Skip to content

Security Decorators Overview

DjangoAPI Guard's security decorators allow you to apply fine-grained security controls to individual views, complementing the global middleware protection. This gives you the flexibility to customize security policies on a per-endpoint basis.

What are Security Decorators?

Security decorators are Python decorators that you can apply to your Django view functions to add specific security measures. They work alongside the global DjangoAPIGuard middleware to provide layered protection.

from djangoapi_guard import SecurityConfig
from djangoapi_guard import SecurityDecorator
from django.http import JsonResponse

config = SecurityConfig()
guard_deco = SecurityDecorator(config)

def public_endpoint(request):
    return JsonResponse({"message": "This uses global security settings"})

@guard_deco.rate_limit(requests=5, window=300)
@guard_deco.require_ip(whitelist=["10.0.0.0/8"])
def restricted_endpoint(request):
    return JsonResponse({"message": "This has additional route-specific restrictions"})

Key Features

  • Route-Level Controls: Apply security rules to specific endpoints
  • Override Global Settings: Route decorators can override global middleware settings
  • Stacking Support: Combine multiple decorators for comprehensive protection
  • Behavioral Analysis: Monitor endpoint usage patterns and detect anomalies
  • Content Filtering: Control request types and sizes per endpoint
  • Time-Based Access: Restrict access to specific time windows

Decorator Categories

. Access Control

Control who can access your endpoints based on IP, geography, and cloud providers.

@guard_deco.require_ip(whitelist=["192.168.1.0/24"])
@guard_deco.block_countries(["CN", "RU"])
@guard_deco.block_clouds(["AWS", "GCP"])
def sensitive_endpoint(request):
    return JsonResponse({"data": "restricted"})

. Authentication & Authorization

Enforce authentication requirements and secure headers.

@guard_deco.require_https()
@guard_deco.require_auth(type="bearer")
@guard_deco.api_key_auth(header_name="X-API-Key")
def authenticated_endpoint(request):
    return JsonResponse({"data": "authenticated"})

. Rate Limiting

Apply custom rate limits to specific endpoints.

@guard_deco.rate_limit(requests=10, window=300)  # 10 requests per 5 minutes
@guard_deco.geo_rate_limit({"US": (100, 3600), "CN": (5, 3600)})
def limited_endpoint(request):
    return JsonResponse({"data": "rate limited"})

. Behavioral Analysis

Monitor and analyze user behavior patterns.

@guard_deco.usage_monitor(max_calls=50, window=3600, action="ban")
@guard_deco.return_monitor("win", max_occurrences=3, window=86400, action="alert")
def game_endpoint(request):
    return JsonResponse({"result": "win", "reward": "rare_item"})

. Content Filtering

Control request content and format.

@guard_deco.content_type_filter(["application/json"])
@guard_deco.max_request_size(1024 * 1024)  # 1MB limit
@guard_deco.require_referrer(["myapp.com"])
def upload_endpoint(request):
    return JsonResponse({"status": "uploaded"})

. Advanced Features

Time-based controls and sophisticated detection mechanisms.

@guard_deco.time_window("09:00", "17:00", "UTC")  # Business hours only
@guard_deco.suspicious_detection(enabled=True)
@guard_deco.honeypot_detection(["bot_trap", "hidden_field"])
def advanced_endpoint(request):
    return JsonResponse({"data": "advanced protection"})

Basic Setup

. Initialize the Decorator

from djangoapi_guard import SecurityConfig
from djangoapi_guard import SecurityDecorator
from djangoapi_guard.middleware import DjangoAPIGuard

config = SecurityConfig(
    enable_ip_banning=True,
    enable_rate_limiting=True,
    rate_limit=100,
    rate_limit_window=3600
)

# Create decorator instance
guard_deco = SecurityDecorator(config)

. Apply Decorators to Views

from django.http import JsonResponse

@guard_deco.require_https()
@guard_deco.rate_limit(requests=5, window=300)    # Stricter limit for login
@guard_deco.suspicious_detection(enabled=True)
def login(request):
    # Login logic here
    return JsonResponse({"token": "jwt_token"})

@guard_deco.require_ip(whitelist=["10.0.0.0/8"])  # Internal network only
@guard_deco.require_auth(type="bearer")
@guard_deco.time_window("09:00", "17:00", "UTC")  # Business hours
def admin_panel(request):
    return JsonResponse({"message": "Admin access granted"})

Configuration Priority

Security settings are applied in this order (highest to lowest priority):

  1. Decorator Settings - Route-specific configurations
  2. Global Middleware Settings - Application-wide defaults
  3. Built-in Defaults - Library defaults

Best Practices

. Logical Decorator Order

Apply decorators from most specific to most general:

@guard_deco.require_https()                         # Security requirement
@guard_deco.require_auth(type="bearer")             # Authentication
@guard_deco.require_ip(whitelist=["10.0.0.0/8"])    # Access control
@guard_deco.rate_limit(requests=5, window=3600)     # Rate limiting
@guard_deco.suspicious_detection(enabled=True)      # Monitoring
def admin_endpoint(request):
    return JsonResponse({"status": "admin action"})

Next Steps

For complete API reference, see the Security Decorators API Documentation.