django-honeyguard Documentation

django-honeyguard is a Django application that provides honeypot security mechanisms to detect and log bot attacks on fake admin login pages. It implements timing-based attack detection, hidden field honeypots, and comprehensive logging.

Features

  • Hidden Honeypot Fields: Detect bots by monitoring hidden form fields that humans shouldn’t fill

  • Timing Attack Detection: Identify suspiciously fast or slow form submissions

  • Multiple CMS Support: Fake login pages for Django admin and WordPress

  • Comprehensive Logging: Database, console, and email logging of all attacks

  • Risk Assessment: Automatic calculation of risk scores for each attack

  • Admin Interface: Enhanced Django admin with filters, actions, and analytics

  • Configuration Validation: Early detection of configuration errors at startup

Quick Start

  1. Install the package:

pip install django-honeyguard

  1. Add to your INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_honeyguard",
]

  1. Configure in your settings.py:

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

  1. Include URLs (option A) or use views directly (option B):

# Option A: Include all URLs
urlpatterns = [
    path("", include("django_honeyguard.urls")),
]

# Option B: Use individual views directly
from django_honeyguard.views import FakeDjangoAdminView
urlpatterns = [
    path("admin/", FakeDjangoAdminView.as_view()),
]

  1. Run migrations:

python manage.py migrate

Contents

Running Documentation Locally

  1. Create a virtual environment and install requirements:

    python -m venv .venv && source .venv/bin/activate pip install -r docs/requirements.txt

  2. Build HTML docs:

    cd docs && make html

  3. Open docs/_build/html/index.html in your browser.

Indices and tables