netbox-toolkit-plugin 0.1.0__py3-none-any.whl

netbox_toolkit/__init__.py

@@ -0,0 +1,30 @@
+from netbox.plugins import PluginConfig
+
+class ToolkitConfig(PluginConfig):
+    name = 'netbox_toolkit_plugin'
+    verbose_name = 'Netbox Command Toolkit Plugin'
+    description = 'NetBox plugin for running pre-defined commands on network devices'
+    version = '0.1.0'
+    author = 'Andy Norwood'
+    base_url = 'toolkit'
+
+    # Database migrations
+    required_settings = []
+    
+    # Default plugin settings
+    default_settings = {
+        'rate_limiting_enabled': True,
+        'device_command_limit': 10,
+        'time_window_minutes': 5,
+        'bypass_users': [],
+        'bypass_groups': [],
+        'debug_logging': False,  # Enable debug logging for this plugin
+    }
+    
+    # Middleware
+    middleware = []
+    
+    # Django apps to load when plugin is activated
+    django_apps = []
+
+config = ToolkitConfig

netbox_toolkit/admin.py

@@ -0,0 +1,16 @@
+from django.contrib import admin
+from netbox.admin import NetBoxModelAdmin
+from .models import Command, CommandLog
+
+@admin.register(Command)
+class CommandAdmin(NetBoxModelAdmin):
+    list_display = ('name', 'platform', 'command_type', 'description')
+    list_filter = ('platform', 'command_type')
+    search_fields = ('name', 'command', 'description')
+
+@admin.register(CommandLog)
+class CommandLogAdmin(NetBoxModelAdmin):
+    list_display = ('command', 'device', 'username', 'execution_time')
+    list_filter = ('command', 'device', 'username', 'execution_time')
+    search_fields = ('command__name', 'device__name', 'username', 'output')
+    readonly_fields = ('output', 'execution_time')

netbox_toolkit/api/mixins.py

@@ -0,0 +1,54 @@
+"""
+Common mixins and utilities for NetBox Toolkit API views
+"""
+from rest_framework.response import Response
+from django.contrib.contenttypes.models import ContentType
+from users.models import ObjectPermission
+
+
+class APIResponseMixin:
+    """Mixin to add consistent API response headers"""
+    
+    def finalize_response(self, request, response, *args, **kwargs):
+        """Add custom headers to all responses"""
+        response = super().finalize_response(request, response, *args, **kwargs)
+        
+        # Add API version header
+        response['X-NetBox-Toolkit-API-Version'] = '1.0'
+        
+        return response
+
+
+class PermissionCheckMixin:
+    """Mixin for NetBox ObjectPermission checking"""
+    
+    def _user_has_action_permission(self, user, obj, action):
+        """Check if user has permission for a specific action on an object using NetBox's ObjectPermission system"""
+        # Get content type for the object
+        content_type = ContentType.objects.get_for_model(obj)
+        
+        # Check if user has any ObjectPermissions with the required action
+        user_permissions = ObjectPermission.objects.filter(
+            object_types__in=[content_type],
+            actions__contains=[action],
+            enabled=True
+        )
+        
+        # Check if user is assigned to any groups with this permission
+        user_groups = user.groups.all()
+        for permission in user_permissions:
+            # Check if permission applies to user or user's groups
+            if (permission.users.filter(id=user.id).exists() or 
+                permission.groups.filter(id__in=user_groups.values_list('id', flat=True)).exists()):
+                
+                # If there are constraints, evaluate them
+                if permission.constraints:
+                    # Create a queryset with the constraints and check if the object matches
+                    queryset = content_type.model_class().objects.filter(**permission.constraints)
+                    if queryset.filter(id=obj.id).exists():
+                        return True
+                else:
+                    # No constraints means permission applies to all objects of this type
+                    return True
+        
+        return False

netbox_toolkit/api/schemas.py

@@ -0,0 +1,234 @@
+"""
+OpenAPI schema definitions for NetBox Toolkit API
+"""
+from drf_spectacular.utils import extend_schema, OpenApiResponse
+
+
+# Command ViewSet Schemas
+COMMAND_LIST_SCHEMA = extend_schema(
+    summary="List commands",
+    description="Retrieve a list of all commands available in the system.",
+    tags=["Commands"]
+)
+
+COMMAND_RETRIEVE_SCHEMA = extend_schema(
+    summary="Retrieve command",
+    description="Retrieve details of a specific command.",
+    tags=["Commands"]
+)
+
+COMMAND_CREATE_SCHEMA = extend_schema(
+    summary="Create command",
+    description="Create a new command.",
+    tags=["Commands"]
+)
+
+COMMAND_UPDATE_SCHEMA = extend_schema(
+    summary="Update command",
+    description="Update an existing command.",
+    tags=["Commands"]
+)
+
+COMMAND_PARTIAL_UPDATE_SCHEMA = extend_schema(
+    summary="Partial update command",
+    description="Partially update an existing command.",
+    tags=["Commands"]
+)
+
+COMMAND_DESTROY_SCHEMA = extend_schema(
+    summary="Delete command",
+    description="Delete a command.",
+    tags=["Commands"]
+)
+
+COMMAND_EXECUTE_SCHEMA = extend_schema(
+    summary="Execute command on device",
+    description="Execute a specific command on a target device with authentication credentials.",
+    tags=["Commands"],
+    responses={
+        200: OpenApiResponse(
+            description="Command executed successfully",
+            examples=[
+                {
+                    "success": True,
+                    "output": "interface status output...",
+                    "error_message": None,
+                    "execution_time": 1.23,
+                    "command": {
+                        "id": 1,
+                        "name": "show interfaces",
+                        "command_type": "show"
+                    },
+                    "device": {
+                        "id": 1,
+                        "name": "switch01.example.com"
+                    },
+                    "syntax_error": {
+                        "detected": False
+                    },
+                    "parsed_output": {
+                        "success": True,
+                        "method": "textfsm",
+                        "data": [{"interface": "GigabitEthernet1/0/1", "status": "up"}]
+                    }
+                }
+            ]
+        ),
+        400: OpenApiResponse(
+            description="Bad request - validation errors or command execution failed"
+        ),
+        403: OpenApiResponse(
+            description="Forbidden - insufficient permissions"
+        ),
+        404: OpenApiResponse(
+            description="Not found - command or device not found"
+        ),
+        429: OpenApiResponse(
+            description="Too many requests - rate limit exceeded"
+        )
+    }
+)
+
+COMMAND_BULK_EXECUTE_SCHEMA = extend_schema(
+    summary="Bulk execute commands",
+    description="Execute multiple commands on multiple devices in a single API call.",
+    tags=["Commands"],
+    request={
+        "type": "object",
+        "properties": {
+            "executions": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "command_id": {"type": "integer"},
+                        "device_id": {"type": "integer"},
+                        "username": {"type": "string"},
+                        "password": {"type": "string", "format": "password"}
+                    },
+                    "required": ["command_id", "device_id", "username", "password"]
+                }
+            }
+        },
+        "required": ["executions"]
+    },
+    responses={
+        200: OpenApiResponse(
+            description="Bulk execution completed",
+            examples=[
+                {
+                    "results": [
+                        {"execution_id": 1, "success": True, "command_log_id": 123},
+                        {"execution_id": 2, "success": False, "error": "Permission denied"}
+                    ],
+                    "summary": {
+                        "total": 2,
+                        "successful": 1,
+                        "failed": 1
+                    }
+                }
+            ]
+        )
+    }
+)
+
+# Command Log ViewSet Schemas
+COMMAND_LOG_LIST_SCHEMA = extend_schema(
+    summary="List command logs",
+    description="Retrieve a list of command execution logs with filtering and search capabilities.",
+    tags=["Command Logs"]
+)
+
+COMMAND_LOG_RETRIEVE_SCHEMA = extend_schema(
+    summary="Retrieve command log",
+    description="Retrieve details of a specific command execution log.",
+    tags=["Command Logs"]
+)
+
+COMMAND_LOG_CREATE_SCHEMA = extend_schema(
+    summary="Create command log",
+    description="Create a new command execution log entry.",
+    tags=["Command Logs"]
+)
+
+COMMAND_LOG_UPDATE_SCHEMA = extend_schema(
+    summary="Update command log",
+    description="Update an existing command log entry.",
+    tags=["Command Logs"]
+)
+
+COMMAND_LOG_PARTIAL_UPDATE_SCHEMA = extend_schema(
+    summary="Partial update command log",
+    description="Partially update an existing command log entry.",
+    tags=["Command Logs"]
+)
+
+COMMAND_LOG_DESTROY_SCHEMA = extend_schema(
+    summary="Delete command log",
+    description="Delete a command log entry.",
+    tags=["Command Logs"]
+)
+
+COMMAND_LOG_STATISTICS_SCHEMA = extend_schema(
+    summary="Get command log statistics",
+    description="Retrieve statistics about command execution logs including success rates and common errors.",
+    tags=["Command Logs"],
+    responses={
+        200: OpenApiResponse(
+            description="Statistics retrieved successfully",
+            examples=[
+                {
+                    "total_logs": 1000,
+                    "success_rate": 85.5,
+                    "last_24h": {
+                        "total": 50,
+                        "successful": 45,
+                        "failed": 5
+                    },
+                    "top_commands": [
+                        {"command_name": "show interfaces", "count": 150},
+                        {"command_name": "show version", "count": 120}
+                    ],
+                    "common_errors": [
+                        {"error": "Connection timeout", "count": 10},
+                        {"error": "Invalid command", "count": 5}
+                    ]
+                }
+            ]
+        )
+    }
+)
+
+from drf_spectacular.utils import OpenApiParameter
+
+COMMAND_LOG_EXPORT_SCHEMA = extend_schema(
+    summary="Export command logs",
+    description="Export command logs in various formats (CSV, JSON).",
+    tags=["Command Logs"],
+    parameters=[
+        OpenApiParameter(
+            name='format',
+            description='Export format',
+            required=False,
+            type=str,
+            enum=['csv', 'json'],
+            default='json'
+        ),
+        OpenApiParameter(
+            name='start_date',
+            description='Start date for export (YYYY-MM-DD)',
+            required=False,
+            type=str
+        ),
+        OpenApiParameter(
+            name='end_date',
+            description='End date for export (YYYY-MM-DD)',
+            required=False,
+            type=str
+        ),
+    ],
+    responses={
+        200: OpenApiResponse(description="Export data"),
+        400: OpenApiResponse(description="Invalid parameters")
+    }
+)

netbox_toolkit/api/serializers.py

@@ -0,0 +1,158 @@
+from rest_framework import serializers
+from netbox.api.serializers import NetBoxModelSerializer, WritableNestedSerializer
+from dcim.api.serializers import PlatformSerializer, DeviceSerializer
+from ..models import Command, CommandLog
+
+class CommandExecutionSerializer(serializers.Serializer):
+    """Serializer for command execution input validation"""
+    device_id = serializers.IntegerField(
+        help_text="ID of the device to execute the command on"
+    )
+    username = serializers.CharField(
+        max_length=100,
+        help_text="Username for device authentication",
+        trim_whitespace=True
+    )
+    password = serializers.CharField(
+        max_length=255,
+        style={'input_type': 'password'},
+        help_text="Password for device authentication",
+        trim_whitespace=False
+    )
+    timeout = serializers.IntegerField(
+        required=False,
+        default=30,
+        min_value=5,
+        max_value=300,
+        help_text="Command execution timeout in seconds (5-300)"
+    )
+    
+    def validate_device_id(self, value):
+        """Validate that the device exists and has required attributes"""
+        from dcim.models import Device
+        try:
+            device = Device.objects.get(id=value)
+            if not device.platform:
+                raise serializers.ValidationError(
+                    "Device must have a platform assigned for command execution"
+                )
+            if not device.primary_ip:
+                raise serializers.ValidationError(
+                    "Device must have a primary IP address for command execution"
+                )
+            return value
+        except Device.DoesNotExist:
+            raise serializers.ValidationError("Device not found")
+    
+    def validate(self, data):
+        """Cross-field validation and object retrieval"""
+        from dcim.models import Device
+        
+        # Get the actual device object for use in views
+        device = Device.objects.get(id=data['device_id'])
+        data['device'] = device
+        
+        return data
+    
+    def validate_username(self, value):
+        """Validate username format"""
+        if not value.strip():
+            raise serializers.ValidationError("Username cannot be empty")
+        if len(value.strip()) < 2:
+            raise serializers.ValidationError("Username must be at least 2 characters")
+        return value.strip()
+    
+    def validate_password(self, value):
+        """Validate password"""
+        if not value:
+            raise serializers.ValidationError("Password cannot be empty")
+        if len(value) < 3:
+            raise serializers.ValidationError("Password must be at least 3 characters")
+        return value
+
+class NestedCommandSerializer(WritableNestedSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name='plugins-api:netbox_toolkit-api:command-detail'
+    )
+
+    class Meta:
+        model = Command
+        fields = ('id', 'url', 'name', 'display')
+
+class CommandSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name='plugins-api:netbox_toolkit-api:command-detail'
+    )
+    platform = PlatformSerializer(nested=True)
+
+    class Meta:
+        model = Command
+        fields = (
+            'id', 'url', 'display', 'name', 'command', 'description', 
+            'platform', 'command_type',
+            'tags', 'custom_fields', 'created', 'last_updated'
+        )
+        brief_fields = ('id', 'url', 'display', 'name', 'command_type', 'platform')
+
+class CommandLogSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name='plugins-api:netbox_toolkit-api:commandlog-detail'
+    )
+    command = NestedCommandSerializer()
+    device = DeviceSerializer(nested=True)
+
+    class Meta:
+        model = CommandLog
+        fields = (
+            'id', 'url', 'display', 'command', 'device', 'output', 
+            'username', 'execution_time', 'success', 'error_message', 'execution_duration',
+            'parsed_data', 'parsing_success', 'parsing_template',
+            'created', 'last_updated'
+        )
+        brief_fields = ('id', 'url', 'display', 'command', 'device', 'username', 'execution_time', 'success')
+
+class BulkCommandExecutionSerializer(serializers.Serializer):
+    """Serializer for bulk command execution validation"""
+    command_id = serializers.IntegerField(
+        help_text="ID of the command to execute"
+    )
+    device_id = serializers.IntegerField(
+        help_text="ID of the device to execute the command on"
+    )
+    username = serializers.CharField(
+        max_length=100,
+        help_text="Username for device authentication"
+    )
+    password = serializers.CharField(
+        max_length=255,
+        style={'input_type': 'password'},
+        help_text="Password for device authentication"
+    )
+    timeout = serializers.IntegerField(
+        required=False,
+        default=30,
+        min_value=5,
+        max_value=300,
+        help_text="Command execution timeout in seconds"
+    )
+    
+    def validate_command_id(self, value):
+        """Validate that the command exists"""
+        try:
+            Command.objects.get(id=value)
+            return value
+        except Command.DoesNotExist:
+            raise serializers.ValidationError("Command not found")
+    
+    def validate_device_id(self, value):
+        """Validate that the device exists"""
+        from dcim.models import Device
+        try:
+            device = Device.objects.get(id=value)
+            if not device.platform:
+                raise serializers.ValidationError(
+                    "Device must have a platform assigned"
+                )
+            return value
+        except Device.DoesNotExist:
+            raise serializers.ValidationError("Device not found")

netbox_toolkit/api/urls.py

@@ -0,0 +1,10 @@
+from netbox.api.routers import NetBoxRouter
+from .views import CommandViewSet, CommandLogViewSet
+
+app_name = 'netbox_toolkit'
+
+router = NetBoxRouter()
+router.register('commands', CommandViewSet)
+router.register('command-logs', CommandLogViewSet)
+
+urlpatterns = router.urls

netbox_toolkit/api/views/__init__.py

@@ -0,0 +1,10 @@
+"""
+Import all viewsets for easier access
+"""
+from .commands import CommandViewSet
+from .command_logs import CommandLogViewSet
+
+__all__ = [
+    'CommandViewSet',
+    'CommandLogViewSet',
+]

netbox_toolkit/api/views/command_logs.py

@@ -0,0 +1,170 @@
+"""
+API ViewSet for CommandLog resources
+"""
+from rest_framework import status
+from rest_framework.decorators import action
+from rest_framework.response import Response
+from django.utils import timezone
+from datetime import timedelta
+from django.db.models import Count, Q
+from django.http import HttpResponse
+from drf_spectacular.utils import extend_schema_view
+from netbox.api.viewsets import NetBoxModelViewSet
+
+from ... import models, filtersets
+from ..serializers import CommandLogSerializer
+from ..mixins import APIResponseMixin
+from ..schemas import (
+    COMMAND_LOG_LIST_SCHEMA,
+    COMMAND_LOG_RETRIEVE_SCHEMA,
+    COMMAND_LOG_CREATE_SCHEMA,
+    COMMAND_LOG_UPDATE_SCHEMA,
+    COMMAND_LOG_PARTIAL_UPDATE_SCHEMA,
+    COMMAND_LOG_DESTROY_SCHEMA,
+    COMMAND_LOG_STATISTICS_SCHEMA,
+    COMMAND_LOG_EXPORT_SCHEMA,
+)
+
+
+@extend_schema_view(
+    list=COMMAND_LOG_LIST_SCHEMA,
+    retrieve=COMMAND_LOG_RETRIEVE_SCHEMA,
+    create=COMMAND_LOG_CREATE_SCHEMA,
+    update=COMMAND_LOG_UPDATE_SCHEMA,
+    partial_update=COMMAND_LOG_PARTIAL_UPDATE_SCHEMA,
+    destroy=COMMAND_LOG_DESTROY_SCHEMA,
+)
+class CommandLogViewSet(NetBoxModelViewSet, APIResponseMixin):
+    queryset = models.CommandLog.objects.all()
+    serializer_class = CommandLogSerializer
+    filterset_class = filtersets.CommandLogFilterSet
+    # NetBox automatically handles object-based permissions - no need for explicit permission_classes
+    
+    def get_queryset(self):
+        """NetBox will automatically filter based on user's ObjectPermissions"""
+        return super().get_queryset()
+    
+    @COMMAND_LOG_STATISTICS_SCHEMA
+    @action(detail=False, methods=['get'], url_path='statistics')
+    def statistics(self, request):
+        """Get command execution statistics"""
+        queryset = self.get_queryset()
+        
+        # Basic stats
+        total_logs = queryset.count()
+        successful_logs = queryset.filter(success=True).count()
+        success_rate = (successful_logs / total_logs * 100) if total_logs > 0 else 0
+        
+        # Last 24 hours stats
+        last_24h = timezone.now() - timedelta(hours=24)
+        recent_logs = queryset.filter(created__gte=last_24h)
+        recent_total = recent_logs.count()
+        recent_successful = recent_logs.filter(success=True).count()
+        recent_failed = recent_total - recent_successful
+        
+        # Top commands
+        top_commands = (
+            queryset.values('command__name')
+            .annotate(count=Count('command'))
+            .order_by('-count')[:10]
+        )
+        
+        # Common errors (non-empty error messages)
+        common_errors = (
+            queryset.filter(~Q(error_message=''), ~Q(error_message__isnull=True))
+            .values('error_message')
+            .annotate(count=Count('error_message'))
+            .order_by('-count')[:10]
+        )
+        
+        return Response({
+            'total_logs': total_logs,
+            'success_rate': round(success_rate, 2),
+            'last_24h': {
+                'total': recent_total,
+                'successful': recent_successful,
+                'failed': recent_failed
+            },
+            'top_commands': [
+                {'command_name': item['command__name'], 'count': item['count']}
+                for item in top_commands
+            ],
+            'common_errors': [
+                {'error': item['error_message'][:100], 'count': item['count']}
+                for item in common_errors
+            ]
+        })
+    
+    @COMMAND_LOG_EXPORT_SCHEMA
+    @action(detail=False, methods=['get'], url_path='export')
+    def export(self, request):
+        """Export command logs"""
+        import csv
+        from datetime import datetime
+        
+        export_format = request.query_params.get('format', 'json')
+        start_date = request.query_params.get('start_date')
+        end_date = request.query_params.get('end_date')
+        
+        queryset = self.get_queryset()
+        
+        # Apply date filters if provided
+        if start_date:
+            try:
+                start_date = datetime.strptime(start_date, '%Y-%m-%d').date()
+                queryset = queryset.filter(created__date__gte=start_date)
+            except ValueError:
+                return Response(
+                    {'error': 'Invalid start_date format. Use YYYY-MM-DD.'},
+                    status=status.HTTP_400_BAD_REQUEST
+                )
+        
+        if end_date:
+            try:
+                end_date = datetime.strptime(end_date, '%Y-%m-%d').date()
+                queryset = queryset.filter(created__date__lte=end_date)
+            except ValueError:
+                return Response(
+                    {'error': 'Invalid end_date format. Use YYYY-MM-DD.'},
+                    status=status.HTTP_400_BAD_REQUEST
+                )
+        
+        # Limit export size for performance
+        if queryset.count() > 10000:
+            return Response(
+                {'error': 'Export too large. Please use date filters to reduce size.'},
+                status=status.HTTP_400_BAD_REQUEST
+            )
+        
+        if export_format == 'csv':
+            # CSV export
+            response = HttpResponse(content_type='text/csv')
+            response['Content-Disposition'] = 'attachment; filename="command_logs.csv"'
+            
+            writer = csv.writer(response)
+            writer.writerow([
+                'ID', 'Command', 'Device', 'User', 'Success', 
+                'Created', 'Execution Time', 'Error Message'
+            ])
+            
+            for log in queryset.select_related('command', 'device', 'user'):
+                writer.writerow([
+                    log.id,
+                    log.command.name,
+                    log.device.name,
+                    log.user.username if log.user else 'Unknown',
+                    log.success,
+                    log.created.isoformat(),
+                    log.execution_time,
+                    log.error_message or ''
+                ])
+            
+            return response
+        
+        else:
+            # JSON export
+            serializer = self.get_serializer(queryset, many=True)
+            return Response({
+                'count': queryset.count(),
+                'results': serializer.data
+            })