How kiurakku/dracolure works
Purpose and deployment shape
DracoLure is a defensive, HTTP-focused deception honeypot and reusable threat-classification service. It receives probes, serves fabricated decoys, classifies malicious content, maintains per-source risk/quarantine state, and exposes events and metrics. The primary local/full-stack entry point is docker-compose.yml; the application server starts from app/main.py. Edge routing is handled by nginx/default.conf.
Flask sentinel and deception surface
The Python/Flask service is the central control plane and public honeypot surface. A request-wide pre-route sentinel checks quarantine status before application routes execute; quarantined sources receive delayed 403 responses. Non-blocked requests are analyzed and then routed to bait or normal error responses. Deceptive endpoint content is isolated from detection and state logic.
• app/main.py
• app/decoys.py
• app/Dockerfile
Detection and threat-state pipeline
Detection normalizes request material—including encoded forms—and examines path, query, body, and user agent against attack signatures. It produces categories and weighted scores, capped at 100 with severity bands. Threat state aggregates scores over a rolling window per source IP, triggers TTL-based quarantine at the configured threshold, and drives tarpit behavior.
• app/detection.py
• app/threat.py
• app/main.py
Persistence and event boundary
Classified malicious events are persisted to PostgreSQL while the service remains fail-open if the database is unavailable. The relational schema, indexes, and honeypot-event evolution are versioned independently of Python code. This is the durable boundary for attack records, logs, and dashboard-oriented querying.
• app/database.py
• db/init.sql
• db/migrations/003_honeypot_events.sql
Integration and operator APIs
The Flask service exposes /api/v1 as a remote ingestion/verdict interface plus operational stats, event retrieval, and block/unblock controls. API-key enforcement is optional. External applications can submit request metadata via the stdlib Python client or WSGI/ASGI middleware; middleware is fail-open so caller availability does not depend on DracoLure.
• app/api.py
• integrations/python-sdk/dracolure/client.py
• integrations/python-sdk/dracolure/middleware.py
Supporting services and observability
nginx fronts HTTP traffic and routes honeypot versus Go logging traffic. The Go service independently records raw request logs to PostgreSQL. Prometheus scrapes service metrics; provisioned Grafana dashboards visualize categories, severity, scores, and quarantines. A Tkinter desktop console operates against the Flask API rather than directly accessing storage.
• backend/go-service/main.go
• monitoring/prometheus.yml
• monitoring/grafana/dashboards/honeypot-dashboard.json
Polyglot and infrastructure boundaries
The runnable stack uses Python 3.11/Flask, Go 1.21, C++17, PostgreSQL 15, Docker Compose, nginx, Prometheus, and Grafana. The C++ analyzer is a sidecar/demo-oriented log analyzer, separate from the live Flask classification path. Terraform provides optional cloud infrastructure provisioning; CI/CD workflows build, test, containerize, deploy, and apply infrastructure.
• backend/cpp-analyzer/main.cpp
• infrastructure/terraform/main.tf
• .github/workflows/ci-cd.yml
Main entry points: main.py Flask honeypot server · docker-compose.yml Docker Compose stack · main.go Go raw logger · init.sql PostgreSQL
Components 19
Edge & Deception
- Docker Compose stack · Primary local full-stack entry point.
docker-compose.yml - nginx router · Routes honeypot and Go logging traffic.
nginx/default.conf
Flask Control Plane
- Flask honeypot server · Public deception surface and control plane.
app/main.py - Pre-route sentinel · Checks quarantine and tarpits blocked sources.
app/main.py - Threat detection · Normalizes request material and assigns categories, scores, and severity.
app/detection.py - Threat state · Maintains rolling per-IP scores and TTL quarantine.
app/threat.py - Decoy endpoints · Fabricated bait responses isolated from detection logic.
app/decoys.py - Operator & ingestion API · Provides verdicts, events, stats, and block controls under /api/v1.
app/api.py
Data & Observability
- Event persistence · Persists malicious events and fails open on database outage.
app/database.py - PostgreSQL · Stores attack records, logs, and dashboard query data.
db/init.sql - Honeypot event schema
db/migrations/003_honeypot_events.sql - Go raw logger · Independently records raw request logs.
backend/go-service/main.go - Prometheus · Scrapes service metrics.
monitoring/prometheus.yml - Grafana dashboard · Visualizes categories, severity, scores, and quarantines.
monitoring/grafana/dashboards/honeypot-dashboard.json
Clients & Integrations
- Python SDK client · Submits request metadata for remote classification.
integrations/python-sdk/dracolure/client.py - WSGI/ASGI middleware · Fail-open caller-side ingestion integration.
integrations/python-sdk/dracolure/middleware.py
Delivery & Optional Tools
- C++ log analyzer · Separate from the live Flask classification path.
backend/cpp-analyzer/main.cpp - Terraform provisioning · Optional cloud infrastructure provisioning.
infrastructure/terraform/main.tf - CI/CD workflow · Builds, tests, containerizes, deploys, and applies infrastructure.
.github/workflows/ci-cd.yml
Connections 24
- Docker Compose stack → nginx router: starts
- Docker Compose stack → Flask honeypot server: starts
- Docker Compose stack → PostgreSQL: starts
- Docker Compose stack → Go raw logger: starts
- nginx router → Flask honeypot server: honeypot HTTP
- nginx router → Go raw logger: logging traffic
- Flask honeypot server → Pre-route sentinel: pre-route check
- Pre-route sentinel → Threat state: quarantine lookup
- Flask honeypot server → Threat detection: analyzes non-blocked requests
- Threat detection → Threat state: score and category
- Threat state → Pre-route sentinel: quarantine state
- Flask honeypot server → Decoy endpoints: serves bait
- Flask honeypot server → Operator & ingestion API: exposes API
- Threat detection → Event persistence: malicious event
- Event persistence → PostgreSQL: persist events
- Honeypot event schema → PostgreSQL: evolves schema
- Go raw logger → PostgreSQL: raw logs
- Prometheus → Flask honeypot server: scrapes metrics
- Prometheus → Go raw logger: scrapes metrics
- Grafana dashboard → Prometheus: queries metrics
- Python SDK client → Operator & ingestion API: ingestion and verdicts
- WSGI/ASGI middleware → Python SDK client: uses
- CI/CD workflow → Docker Compose stack: containerizes and deploys
- CI/CD workflow → Terraform provisioning: applies infrastructure