Configuration

django-honeyguard can be configured using either a dictionary-style configuration or individual settings. All settings are optional and have sensible defaults.

Configuration Methods

Method 1: Dictionary Configuration

The recommended approach is to use a HONEYGUARD dictionary in your settings.py:

HONEYGUARD = {
    "EMAIL_RECIPIENTS": ["admin@example.com"],
    "EMAIL_SUBJECT_PREFIX": "🚨 Honeypot Alert",
    "ENABLE_CONSOLE_LOGGING": True,
    "LOG_LEVEL": "INFO",
}

Method 2: Individual Settings

You can also use individual HONEYGUARD_* settings:

HONEYGUARD_EMAIL_RECIPIENTS = ["admin@example.com"]
HONEYGUARD_EMAIL_SUBJECT_PREFIX = "🚨 Honeypot Alert"
HONEYGUARD_ENABLE_CONSOLE_LOGGING = True

Note

If both methods are used, the dictionary configuration takes priority over individual settings.

Available Settings

Email Configuration

EMAIL_RECIPIENTS

Type: List[str] Default: [] Description: List of email addresses to receive honeypot alerts.

HONEYGUARD = {
    "EMAIL_RECIPIENTS": [
        "admin@example.com",
        "security@example.com",
    ],
}

If empty, email alerts will be disabled.

EMAIL_SUBJECT_PREFIX

Type: str Default: "🚨 Honeypot Alert" Description: Prefix for email alert subject lines.

HONEYGUARD = {
    "EMAIL_SUBJECT_PREFIX": "[Security Alert]",
}

EMAIL_FROM

Type: str | None Default: None Description: From address for email alerts. If None, uses Django’s DEFAULT_FROM_EMAIL.

HONEYGUARD = {
    "EMAIL_FROM": "security@example.com",
}

EMAIL_FAIL_SILENTLY: Type: bool Default: True Description: If True, email sending errors won’t raise exceptions.

Logging Configuration

ENABLE_CONSOLE_LOGGING

Type: bool Default: True Description: Enable console logging of honeypot triggers.

HONEYGUARD = {
    "ENABLE_CONSOLE_LOGGING": False,  # Disable console logs
}

LOG_LEVEL

Type: str Default: "WARNING" Valid Values: "DEBUG", "INFO", "WARNING", "ERROR" Description: Logging level for console output.

HONEYGUARD = {
    "LOG_LEVEL": "WARNING",  # Only log warnings and errors
}

Timing Attack Detection

TIMING_TOO_FAST_THRESHOLD

Type: float Default: 2.0 Description: Minimum time in seconds considered normal for form submission. Submissions faster than this are flagged.

HONEYGUARD = {
    "TIMING_TOO_FAST_THRESHOLD": 3.0,  # Require at least 3 seconds
}

TIMING_TOO_SLOW_THRESHOLD

Type: float Default: 600.0 Description: Maximum time in seconds before form submission is considered suspiciously slow.

HONEYGUARD = {
    "TIMING_TOO_SLOW_THRESHOLD": 1200.0,  # 20 minutes
}

GET Method Detection

ENABLE_GET_METHOD_DETECTION

Type: bool Default: False Description: If True, GET requests to admin URLs trigger honeypot detection.

HONEYGUARD = {
    "ENABLE_GET_METHOD_DETECTION": False,  # Only detect POST requests
}

Form Field Configuration

MAX_USERNAME_LENGTH: Type: int Default: 150 Description: Maximum length for Django admin username fields.

MAX_PASSWORD_LENGTH: Type: int Default: 128 Description: Maximum length for Django admin password fields.

WORDPRESS_USERNAME_MAX_LENGTH: Type: int Default: 60 Description: Maximum length for WordPress username fields.

WORDPRESS_PASSWORD_MAX_LENGTH: Type: int Default: 255 Description: Maximum length for WordPress password fields.

Error Messages

DJANGO_ERROR_MESSAGE

Type: str Default: "Please enter a correct username and password." Description: Error message shown when Django admin honeypot is triggered.

HONEYGUARD = {
    "DJANGO_ERROR_MESSAGE": "Invalid credentials.",
}

WORDPRESS_ERROR_MESSAGE: Type: str Default: "Invalid username or password." Description: Error message shown when WordPress admin honeypot is triggered.

Configuration Validation

django-honeyguard validates all configuration settings at application startup. Invalid settings will raise django.core.exceptions.ImproperlyConfigured with a clear error message.

Example errors and fixes:

Invalid email recipient:

HONEYGUARD = {
    "EMAIL_RECIPIENTS": "not-a-list",  # ❌ Wrong: should be a list
}

# ✅ Correct:
HONEYGUARD = {
    "EMAIL_RECIPIENTS": ["admin@example.com"],
}

Invalid timing threshold:

HONEYGUARD = {
    "TIMING_TOO_FAST_THRESHOLD": -5,  # ❌ Wrong: must be positive
}

# ✅ Correct:
HONEYGUARD = {
    "TIMING_TOO_FAST_THRESHOLD": 2.0,
}

Invalid log level:

HONEYGUARD = {
    "LOG_LEVEL": "VERBOSE",  # ❌ Wrong: not a valid level
}

# ✅ Correct:
HONEYGUARD = {
    "LOG_LEVEL": "DEBUG",
}

Complete Example

Here’s a complete configuration example for a production environment:

# settings.py
HONEYGUARD = {
    # Email alerts
    "EMAIL_RECIPIENTS": [
        "security@example.com",
        "admin@example.com",
    ],
    "EMAIL_SUBJECT_PREFIX": "[Honeypot Alert]",
    "EMAIL_FROM": "security@example.com",
    "EMAIL_FAIL_SILENTLY": False,  # Raise on email errors in production

    # Logging
    "ENABLE_CONSOLE_LOGGING": True,
    "LOG_LEVEL": "WARNING",

    # Timing detection
    "TIMING_TOO_FAST_THRESHOLD": 2.0,
    "TIMING_TOO_SLOW_THRESHOLD": 600.0,

    # Detection options
    "ENABLE_GET_METHOD_DETECTION": True,

    # Custom messages
    "DJANGO_ERROR_MESSAGE": "Invalid credentials.",
    "WORDPRESS_ERROR_MESSAGE": "Invalid username or password.",
}

# Ensure Django can send emails
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.example.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "security@example.com"
EMAIL_HOST_PASSWORD = "your-password"
DEFAULT_FROM_EMAIL = "security@example.com"