🐍 Django Framework

AI-WAF Django Installation Guide

This guide helps you properly install AI-WAF in your Django project to avoid common setup errors.

Common Error Fix:

RuntimeError: Model class aiwaf.models.FeatureSample doesn't declare an explicit app_label and isn't in an application in INSTALLED_APPS.

Solution: Follow the complete installation steps below.

Step 1: Install AI-WAF

pip install aiwaf

Step 2: Configure Django Settings

Required: Add to INSTALLED_APPS

INSTALLED_APPS = [
    # ... your existing apps ...
    'aiwaf',  # AI-WAF (REQUIRED - must be in INSTALLED_APPS)
]
                

Required: Basic Configuration

# AI-WAF Configuration
AIWAF_ACCESS_LOG = "/var/log/nginx/access.log"  # Path to your access log
                

Required: Add Middleware

MIDDLEWARE = [
    # ... your existing middleware ...
    
    # AI-WAF Protection Middleware (add these line by line)
    'aiwaf.middleware.IPAndKeywordBlockMiddleware',
    'aiwaf.middleware.HeaderValidationMiddleware', 
    'aiwaf.middleware.RateLimitMiddleware',
    'aiwaf.middleware.AIAnomalyMiddleware',
    'aiwaf.middleware.HoneypotTimingMiddleware',
    'aiwaf.middleware.UUIDTamperMiddleware',
    
    # Optional: AI-WAF Request Logger
    'aiwaf.middleware_logger.AIWAFLoggerMiddleware',
]

Middleware Order Explanation:
• HeaderValidationMiddleware: Should be first among AI-WAF middlewares for early bot detection
• IPAndKeywordBlockMiddleware: Core IP and keyword blocking
• RateLimitMiddleware: Rate limiting protection
• AIAnomalyMiddleware: AI-based anomaly detection
• HoneypotTimingMiddleware: Form timing analysis
• UUIDTamperMiddleware: UUID tampering detection
• AIWAFLoggerMiddleware: Request logging (optional, can be last)

Step 3: Database Setup

# Create migrations
python manage.py makemigrations aiwaf

# Apply migrations
python manage.py migrate
                

All data is stored in Django models for real-time performance.

Step 4: Test Installation

# Test the installation
python manage.py check

# Add a test IP exemption
python manage.py add_ipexemption 127.0.0.1 --reason "Testing"

# Check AI-WAF status
python manage.py aiwaf_logging --status
                

🔧 Step 5: Optional Configuration

Enable Built-in Request Logger

# settings.py
AIWAF_MIDDLEWARE_LOGGING = True
                

Exempt Paths

# settings.py
AIWAF_EXEMPT_PATHS = [
    "/favicon.ico",
    "/robots.txt",
    "/static/",
    "/media/",
    "/health/",
    "/api/webhooks/",
]
                

AI Settings

# settings.py
AIWAF_AI_CONTAMINATION = 0.05  # AI sensitivity (5%)
AIWAF_MIN_FORM_TIME = 1.0      # Honeypot timing
AIWAF_RATE_MAX = 20            # Rate limiting
                

Header Validation Settings

# settings.py - HTTP Header Bot Detection Configuration

# Enable/disable header validation (default: True)
AIWAF_HEADER_VALIDATION_ENABLED = True

# Minimum header quality score (default: 5, range: 0-11)
AIWAF_MIN_HEADER_QUALITY = 5

# Block requests with suspicious User-Agent patterns (default: True)
AIWAF_BLOCK_SUSPICIOUS_USER_AGENTS = True

# Allow legitimate bots (Google, Bing, etc.) even with low scores (default: True)
AIWAF_ALLOW_LEGITIMATE_BOTS = True

# Log blocked header validation requests (default: True)
AIWAF_LOG_HEADER_BLOCKS = True

# Custom suspicious User-Agent patterns (regex)
AIWAF_CUSTOM_SUSPICIOUS_PATTERNS = [
    r'wordpress',
    r'scanner',
    r'exploit',
    # Add your patterns here
]

# Whitelist additional legitimate bot User-Agents
AIWAF_LEGITIMATE_BOT_PATTERNS = [
    r'MyCustomBot/1.0',
    r'LegitimateScanner',
    # Add your patterns here  
]
                

Step 6: Start Training

# Train the AI model (after some traffic)
python manage.py detect_and_train
                

Troubleshooting

Error: Model not in INSTALLED_APPS
Problem: AI-WAF models can't be loaded.

Solutions:
1. Add 'aiwaf' to INSTALLED_APPS (required)
2. Run python manage.py migrate if using models
3. Use CSV mode: AIWAF_STORAGE_MODE = "csv"

Error: No module named 'aiwaf'
Problem: AI-WAF not installed properly.

Solution:
pip install aiwaf or pip install --upgrade aiwaf

Error: Access log not found
Problem: AIWAF_ACCESS_LOG points to non-existent file.

Solutions:
1. Fix log path in settings
2. Enable middleware logger: AIWAF_MIDDLEWARE_LOGGING = True

Verification Checklist

☐ aiwaf added to INSTALLED_APPS
☐ AIWAF_ACCESS_LOG configured
☐ Middleware added to MIDDLEWARE
☐ Migrations run: python manage.py migrate aiwaf
☐ python manage.py check passes
☐ Test command works: python manage.py add_exemption 127.0.0.1

🏃‍♂️ Quick Start (Minimal Setup)

# settings.py - Minimal configuration

INSTALLED_APPS = [
    # ... existing apps ...
    'aiwaf',  # Required
]

MIDDLEWARE = [
    # ... existing middleware ...
    'aiwaf.middleware.HeaderValidationMiddleware',   # Bot detection (recommended first)
    'aiwaf.middleware.IPAndKeywordBlockMiddleware',  # Basic protection
]

# Choose one:
AIWAF_ACCESS_LOG = "/var/log/nginx/access.log"  # Use server logs
# OR
AIWAF_MIDDLEWARE_LOGGING = True  # Use built-in logger

# Optional: Configure header validation
AIWAF_MIN_HEADER_QUALITY = 5  # Block requests with low header quality
                

# Run migrations (if using models)
python manage.py migrate

# Start protecting!
python manage.py runserver
                

That's it! AI-WAF is now protecting your Django application.

📚 Next Steps:
• Learn about middleware components
• Check management commands