honeydj 0.1.0

Self-hosted Django honeypot and attacker intelligence platform

HoneyDjango

Self-hosted Django honeypot and attacker intelligence platform. Serves decoy endpoints (/.env, /wp-admin/, canary tokens, …), captures and enriches every hit via Celery (GeoIP, JA3/User-Agent fingerprinting, threat feeds), builds attacker profiles, and shows it all live in the Django admin — real-time map, alert rules with Slack/email/webhook notifiers, and CSV/JSON/STIX export.

Requirements

• Python 3.11+
• PostgreSQL (models use ArrayField; JSONB for payloads)
• Redis (Channels layer + Celery broker)

Install

pip install honeydj            # host project already has a Postgres driver
pip install "honeydj[postgres]"  # or bring psycopg 3 along

Quickstart (~5 minutes)

1. Settings — at the end of your settings.py:

from honeydj.contrib.quickstart import apply_honeydj_settings

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "honeydj.honeypot.middleware.HoneyMiddleware",  # right after SecurityMiddleware
    # ... the rest of your middleware ...
]

REDIS_URL = "redis://localhost:6379/0"  # optional; defaults derive from this
apply_honeydj_settings(globals())

The helper appends the honeydj apps (plus unfold and channels) to INSTALLED_APPS and fills in Channels/Celery/honeydj defaults without overwriting anything you already set. Your DATABASES must point at PostgreSQL.

2. URLs — decoys go at the site root, last, so they never shadow real routes and their attack paths look authentic:

urlpatterns = [
    # ... your real routes ...
    path("intel/dashboard/", include("honeydj.dashboard.urls", namespace="dashboard")),
    path("api/events/", include("honeydj.events.urls", namespace="events")),
    path("api/feeds/", include("honeydj.feeds.urls", namespace="feeds")),
    path("", include("honeydj.honeypot.urls", namespace="honeypot")),  # keep last
]

Mount the dashboard behind a non-obvious prefix — it shares the admin's auth.

3. Migrate and run:

python manage.py migrate
python manage.py seed_decoy_routes        # optional starter decoys
celery -A yourproject worker -Q default,enrichment,alerts -l info
celery -A yourproject beat -l info        # hourly threat-feed purge

The live map needs an ASGI server (Daphne/Uvicorn) with a ProtocolTypeRouter routing honeydj.events.routing.websocket_urlpatterns — see config/asgi.py for a working example. Everything else works under plain WSGI.

GeoIP (optional)

The GeoLite2 database is not distributable on PyPI. Download GeoLite2-City.mmdb from MaxMind (free account) and set GEOIP_PATH to its directory. Without it, events are simply captured without geo data.

Configuration

apply_honeydj_settings documents every setting it touches. The ones you'll most likely override: GEOIP_PATH, ABUSEIPDB_API_KEY, VIRUSTOTAL_API_KEY (feed adapters self-disable while empty), ALERT_REFIRE_WINDOW_SECONDS, and ADMIN_BASE_URL (absolute base URL used to build clickable links in alerts).

Development

This repo doubles as the dev/demo project (config/ holds the harness — it is not part of the PyPI package):

cp .env.example .env
docker compose up
docker compose run --rm web pytest

Lint and types: ruff check . && mypy . (config lives in pyproject.toml).

Releasing

CI (.github/workflows/ci.yml) runs ruff, mypy, and pytest with a coverage gate on every push and PR. Publishing (.github/workflows/publish.yml) triggers only on tags matching v*.*.*:

# bump __version__ in honeydj/__init__.py (single source of truth), then:
git tag v0.1.0 && git push origin v0.1.0

Requires a PYPI_API_TOKEN repository secret (PyPI → Account settings → API tokens; use __token__ scoped to this project after the first upload).

License

MIT — see LICENSE.