NetBox Toolkit Plugin

The NetBox Toolkit plugin allows you to run command execution directly from NetBox device pages or via the API. Features command variables, command history, encrypted credential storage with token authentication for API, and comprehensive logging options.

⚠️ EARLY DEVELOPMENT WARNING ⚠️ This plugin is in very early development and not recommended for production use. There will be bugs and possible incomplete functionality. Use at your own risk! If you do, give some feedback in Discussions

📋 Feature Overview

• 🔧 Command Creation: Define platform-specific commands (show/config types) with variables
• ⚡ Command Execution: Run commands from device pages via "Toolkit" tab or REST API
• 📄 Raw Output: View complete, unfiltered command responses
• 🔍 Parsed Output: Automatic JSON parsing using textFSM templates
• 📊 Command Logs: Complete execution history with timestamps
• 🔐 Secure Credentials: Encrypted storage with credential tokens via API, or on-the-fly entry in the GUI (no storage required)
• 📊 Statistics Dashboard: Execution analytics, success rates, and performance metrics
• 🚀 Bulk Operations: Execute multiple commands across multiple devices via API
• 🐛 Debug Logging: Optional detailed logging for troubleshooting

Built with:

• Scrapli: Primary network device connection library (SSH/Telnet/NETCONF)
• Scrapli Community: Extended platform support for network devices
• Netmiko: Fallback SSH client for enhanced device compatibility
• TextFSM: Structured data parsing for command outputs

Security Architecture:

• Credential Token System: Secure API execution using credential tokens (no password transmission)
• Fernet Encryption: AES-128 CBC + HMAC-SHA256 for credential encryption
• Argon2id: Secure key derivation and token hashing with pepper-based authentication
• Encrypted Storage: Device credentials encrypted with unique keys per set
• User Isolation: Credential tokens bound to specific users
• No Credential Transmission: Passwords never sent in API calls
• Secure Audit Trail: Operations logged with sanitized data (credentials excluded from change logs)

🛠️ Developed With:

📚 Essential Guides

🚀 Getting Started

• 📦 Plugin Installation - Install the plugin in your NetBox environment
• 🔄 Plugin Upgrade - Upgrade to newer versions
• ⚙️ Plugin Configuration - Configure plugin settings and options
• 🔐 Permissions Creation - Set up user access and permissions
• 📋 Command Creation - Create platform-specific commands with variables
• 🔑 Device Credentials - Secure credential storage and token management
• 📝 Logging Guide - Enable logging for troubleshooting

🔌 API Integration

• 📖 API Overview - REST API capabilities and features
• 🔑 Authentication & Permissions - API authentication with credential tokens
• ⚡ Commands API - Command execution and management
• 📊 Command Logs API - Access execution history and logs
• � Error Handling - API error responses and troubleshooting
• 🔄 API Workflows - Common API usage patterns
• 🤖 Automation Examples - Scripts and automation scenarios

📋 Configuration Examples

• 📝 Permission Examples - Example permission configurations
• ⚖️ GUI vs API Comparison - Feature comparison between web interface and API

👨‍💻 Development

• 🏗️ Developer Guide - Complete overview for contributors
• 🔧 Development Setup - Set up your development environment

Demo

Demo from older plugin version

Quick Start

Installation:

# 1. Install the plugin
pip install netbox-toolkit-plugin

# 2. Add to NetBox configuration.py
PLUGINS = ['netbox_toolkit_plugin']

# 3. Configure security pepper (REQUIRED)
python3 -c "import secrets; print(secrets.token_urlsafe(48))"  # Generate pepper

PLUGINS_CONFIG = {
    'netbox_toolkit_plugin': {
        'security': {
            'pepper': 'your-generated-pepper-here',
        },
    },
}

# 4. Run migrations and restart
python3 manage.py migrate netbox_toolkit_plugin
python3 manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

Initial Setup (Required):

1. Set up permissions - Grant users access to execute commands
2. Create commands - Define platform-specific commands (e.g., "show version")

Note: Using credential token allows for secure command execution via API without transmitting passwords! 🔒

3. Add credentials (Optional for GUI) - Create credential sets or enter on-the-fly per command (GUI) / Create credential set and copy token (API)

Using the GUI:

1. Navigate to any device page → "Toolkit" tab
2. Select a command, enter variables (if any), choose credentials (or enter on-the-fly), and execute
3. View results with raw or parsed output

Using the API:

Execute commands programmatically:

curl -X POST "https://netbox.example.com/api/plugins/toolkit/commands/17/execute/" \
  -H "Authorization: Token <your-netbox-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "credential_token": "<your-credential-token>"
  }'

📖 Full installation guide: Plugin Installation

Contributing

🚀 Want to Contribute? Get started quickly with the Dev Container setup or use the Contributor Guide for a complete overview of the codebase.

Completed Features:

• ✅ API returns both parsed and raw command output
• ✅ Command variables with NetBox attribute integration (interfaces, VLANs, IPs)
• ✅ Statistics dashboard with execution analytics
• ✅ On-the-fly credential entry (no storage required)
• ✅ Argon2id security with pepper-based authentication
• ✅ Search functionality across commands and logs
• ✅ Platform normalization for connector selection
• ✅ CSV export for parsed command outputs

Future Features:

• ⬜ Diff/Comparison Tools - Compare command outputs over time or between devices
• ⬜ Enhanced Variable Types - Support for more NetBox objects (sites, tenants, device roles, cables, etc.)