Authentication & Permissions¶

The NetBox Toolkit API integrates with NetBox's built-in authentication and permission system.

Authentication¶

API Token Authentication¶

All API requests require authentication using NetBox's token system:

curl -H "Authorization: Token YOUR_TOKEN_HERE" \
     -H "Content-Type: application/json" \
     https://netbox.example.com/api/plugins/toolkit/commands/

Getting Your API Token¶

Via NetBox Web UI:
Log into NetBox
Go to User → Profile → API Tokens
Create a new token or copy an existing one
Via Django Admin:
Access Django admin interface
Navigate to Auth Token → Tokens
Create or view existing tokens

Permissions¶

The plugin uses NetBox's ObjectPermission system with custom actions for command execution.

Permission Actions¶

Action	Description	Applies To
`view`	View commands and logs	Commands, Command Logs
`add`	Create new commands	Commands
`change`	Modify existing commands	Commands
`delete`	Delete commands	Commands
`execute_show`	Execute show commands	Commands
`execute_config`	Execute configuration commands	Commands

Setting Up Permissions¶

1. Create User Groups¶

# Example: Create groups for different access levels
from django.contrib.auth.models import Group

# Read-only users
readonly_group = Group.objects.create(name='Toolkit Read Only')

# Show command executors
show_executors = Group.objects.create(name='Toolkit Show Commands')

# Full access (show + config commands)
full_access = Group.objects.create(name='Toolkit Full Access')

2. Create Object Permissions¶

from users.models import ObjectPermission
from django.contrib.contenttypes.models import ContentType
from netbox_toolkit.models import Command

# Get content type for Command model
command_ct = ContentType.objects.get_for_model(Command)

# Permission to execute show commands
show_permission = ObjectPermission.objects.create(
    name='Execute Show Commands',
    enabled=True,
    object_types=[command_ct],
    actions=['execute_show'],
    constraints={'command_type': 'show'}  # Only show commands
)
show_permission.groups.add(show_executors)

# Permission to execute config commands
config_permission = ObjectPermission.objects.create(
    name='Execute Config Commands',
    enabled=True,
    object_types=[command_ct],
    actions=['execute_config'],
    constraints={'command_type': 'config'}  # Only config commands
)
config_permission.groups.add(full_access)

3. Assign Users to Groups¶

from django.contrib.auth.models import User

# Assign user to show executors group
user = User.objects.get(username='john_doe')
user.groups.add(show_executors)

Permission Constraints¶

You can restrict permissions using constraints:

Platform-Specific Permissions¶

# Only allow execution on Cisco IOS devices
ios_permission = ObjectPermission.objects.create(
    name='Execute on Cisco IOS Only',
    enabled=True,
    object_types=[command_ct],
    actions=['execute_show'],
    constraints={'platform__slug': 'cisco_ios'}
)

Command-Specific Permissions¶

# Only allow specific commands
version_permission = ObjectPermission.objects.create(
    name='Execute Version Commands Only',
    enabled=True,
    object_types=[command_ct],
    actions=['execute_show'],
    constraints={'name__icontains': 'version'}
)

Rate Limiting & Bypass¶

Rate Limiting Permissions¶

Users and groups can bypass rate limiting through plugin configuration:

# In NetBox configuration.py
PLUGINS_CONFIG = {
    'netbox_toolkit': {
        'rate_limiting_enabled': True,
        'device_command_limit': 10,
        'time_window_minutes': 5,
        'bypass_users': ['admin', 'automation_user'],
        'bypass_groups': ['Toolkit Admins', 'Automation Systems'],
    }
}

Checking Rate Limit Status¶

Rate limiting information is included in permission checks and API responses.

Common Permission Scenarios¶

Scenario 1: Network Operators (Show Commands Only)¶

# Create group
operators = Group.objects.create(name='Network Operators')

# Create permission for show commands
show_perm = ObjectPermission.objects.create(
    name='Network Operators - Show Commands',
    enabled=True,
    object_types=[command_ct],
    actions=['view', 'execute_show'],
    constraints={'command_type': 'show'}
)
show_perm.groups.add(operators)

Scenario 2: Network Engineers (Full Access)¶

# Create group
engineers = Group.objects.create(name='Network Engineers')

# Create permission for all commands
full_perm = ObjectPermission.objects.create(
    name='Network Engineers - Full Access',
    enabled=True,
    object_types=[command_ct],
    actions=['view', 'add', 'change', 'delete', 'execute_show', 'execute_config']
)
full_perm.groups.add(engineers)

Scenario 3: Automation Systems¶

# Create group with rate limit bypass
automation = Group.objects.create(name='Automation Systems')

# Full permissions
automation_perm = ObjectPermission.objects.create(
    name='Automation - Full Access',
    enabled=True,
    object_types=[command_ct],
    actions=['view', 'execute_show', 'execute_config']
)
automation_perm.groups.add(automation)

# Add to bypass groups in configuration
PLUGINS_CONFIG = {
    'netbox_toolkit': {
        'bypass_groups': ['Automation Systems'],
    }
}

API Permission Errors¶

Common Error Responses¶

401 Unauthorized¶

{
    "detail": "Authentication credentials were not provided."
}

403 Forbidden¶

{
    "error": "You do not have permission to execute configuration commands"
}

429 Too Many Requests (Rate Limiting)¶

{
    "error": "Rate limit exceeded",
    "details": {
        "reason": "Rate limit exceeded: 10/10 successful commands in last 5 minutes",
        "current_count": 10,
        "limit": 10,
        "time_window_minutes": 5
    }
}

Best Practices¶

Use Groups: Assign permissions to groups rather than individual users
Principle of Least Privilege: Only grant necessary permissions
Use Constraints: Restrict permissions to specific platforms or command types
Rate Limit Bypass: Only grant to trusted automation systems
Regular Audits: Review and audit permissions regularly
Test Permissions: Verify permissions work as expected before deploying