Metadata-Version: 2.4
Name: honeydj
Version: 0.2.0
Summary: Self-hosted Django honeypot and attacker intelligence platform
Project-URL: Homepage, https://github.com/bistasulove/honeydj
Project-URL: Repository, https://github.com/bistasulove/honeydj
Project-URL: Documentation, https://github.com/bistasulove/honeydj#readme
Project-URL: Bug Tracker, https://github.com/bistasulove/honeydj/issues
Author: Sulav Raj Bista
License: MIT
License-File: LICENSE
Keywords: django,honeypot,intrusion-detection,security
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: celery<6.0,>=5.4
Requires-Dist: channels-redis<5.0,>=4.2
Requires-Dist: channels<5.0,>=4.2
Requires-Dist: django<6.0,>=5.2
Requires-Dist: maxminddb<3.0,>=2.6
Requires-Dist: requests<3.0,>=2.31
Requires-Dist: stix2<4.0,>=3.0
Provides-Extra: dev
Requires-Dist: factory-boy>=3.3; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest-django>=4.9; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4.0,>=3.2; extra == 'postgres'
Description-Content-Type: text/markdown

# HoneyDjango

Self-hosted Django honeypot and attacker intelligence platform.

[![PyPI](https://img.shields.io/pypi/v/honeydj)](https://pypi.org/project/honeydj/)
[![Python versions](https://img.shields.io/pypi/pyversions/honeydj)](https://pypi.org/project/honeydj/)
[![Django versions](https://img.shields.io/pypi/frameworkversions/django/honeydj)](https://pypi.org/project/honeydj/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![CI](https://github.com/bistasulove/honeydj/actions/workflows/ci.yml/badge.svg)](https://github.com/bistasulove/honeydj/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-bistasulove.github.io%2Fhoneydj-blue)](https://bistasulove.github.io/honeydj/)

HoneyDjango turns the paths attackers already probe on your site — `/.env`,
`/wp-admin/`, `/administrator/` — into an early-warning system. It serves
convincing fake responses, records every request in full, and builds a live
picture of who is attacking you, from where, and with which techniques.
Everything runs on your own infrastructure: Django, PostgreSQL, Redis, and
Celery, with no required external services.

![HoneyDjango dashboard showing live attack map and event stream](docs/img/dashboard.gif)

## Features

- **Captures** the full request — method, path, query string, headers, body —
  in under 5&nbsp;ms of middleware time, deferring all slow work to Celery.
- **Serves** decoy endpoints and single-use canary-token URLs that return
  realistic fake content and never 404.
- **Enriches** every event asynchronously with GeoIP location and AbuseIPDB /
  VirusTotal reputation data, through a pluggable feed-adapter interface.
- **Classifies** attack techniques from paths and payloads: SQL injection,
  XSS, path traversal, Log4Shell/Shellshock probes, scanner tooling.
- **Fingerprints** clients with JA3 TLS hashes and User-Agent scanner
  classification.
- **Builds** a persistent per-IP attacker profile with a 0–100 threat score
  and technique tags.
- **Alerts** through Slack, email, or generic webhooks, with per-attacker mute
  windows so a scan burst fires once, not five hundred times.
- **Exports** events and attacker indicators as CSV, JSON, or STIX 2.1 bundles
  for your SIEM or threat-intelligence platform.

## Quick install (Docker Compose)

Runs the full stack — PostgreSQL 16, Redis 7, Daphne, Celery worker and beat —
with migrations applied automatically:

```bash
git clone https://github.com/bistasulove/honeydj.git && cd honeydj
cp .env.example .env
docker compose up
```

Then open http://localhost:8000/admin/ and run
`python manage.py simulate_scanner` to watch the pipeline light up.

## Adding to an existing Django project

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

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

```python
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 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:

```python
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
]
```

**3. Migrate and run:**

```bash
python manage.py migrate
python manage.py seed_decoy_routes
celery -A yourproject worker -Q default,enrichment,alerts -l info
```

The live map needs an ASGI server (Daphne/Uvicorn) routing
`honeydj.events.routing.websocket_urlpatterns`; everything else works under
plain WSGI. GeoIP databases and threat-feed API keys are optional — see the
[quickstart guide](https://bistasulove.github.io/honeydj/quickstart/) for the
full walkthrough.

## How it works

1. **An attacker hits a decoy endpoint.** `DecoyRoute` rows (exact paths or
   regexes) define what gets trapped; seeded defaults cover `/.env`,
   `/wp-admin/`, fake admin logins, and a fake debug API.
2. **`HoneyMiddleware` captures the full request in under 5&nbsp;ms.** The
   event — headers, body, query string — is stored and a convincing fake
   response is returned. No network I/O happens in the request path.
3. **Celery enriches the event.** GeoIP lookup, threat-feed reputation
   (AbuseIPDB, VirusTotal), TTP classification, JA3/User-Agent
   fingerprinting, attacker-profile scoring, and alert-rule evaluation all
   run asynchronously on dedicated queues.
4. **The dashboard updates live via WebSocket.** Django Channels pushes each
   enriched event to the attack map and event stream the moment enrichment
   finishes.

## Screenshots

![Real-time dashboard with event stream, stats, and live attack map](docs/img/dashboard-full.png)

![Leaflet attack map plotting enriched attacker locations as they arrive](docs/img/attack-map.png)

![Attacker profile in the admin: threat score, technique tags, and event history](docs/img/attacker-profile.png)

## Documentation

Full documentation — quickstart, decoy routes, alert rules, threat feeds,
canary tokens, architecture — lives at
**[bistasulove.github.io/honeydj](https://bistasulove.github.io/honeydj/)**.

## Contributing

Contributions are welcome, and the extension seams are deliberately small:
a new decoy type, threat-feed adapter, or alert notifier each lands as one
focused class plus tests. [CONTRIBUTING.md](CONTRIBUTING.md) has concrete
copy-this-file guides for all three, plus development setup and the code
style rules CI enforces (ruff, mypy strict, 80%+ coverage).

## License

[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

MIT — see [LICENSE](LICENSE).
