Skip to content

Honeywatch

Honeywatch

Run your own SSH honeypot and watch what the internet does to it.

What It Is

Honeywatch is an SSH honeypot with an analytics pipeline attached. A Cowrie honeypot answers SSH pretending to be a neglected CentOS box. An ingestor tails Cowrie's JSON event log into PostgreSQL. A read-only Flask API serves aggregates over that data, and a Vue dashboard turns them into a world map, an activity heatmap, credential leaderboards and per-session replays.

The whole thing is five containers on one Docker network. Simplest configuration would include the following:

  1. Clone the repo onto a VPS or a spare machine;
  2. Give the port 22 to the honeypot;
  3. Keep the dashboard bound to loopback;
  4. Look at it through a tunnel.

A public instance runs at honey.piotrkrzysztof.dev.

How It Fits Together

graph TB
    subgraph capture [Capture]
        direction LR
        ATT[Attacker] -->|SSH| COW[cowrie]
        COW -->|JSON events| LOG[(cowrie-logs volume)]
    end
    subgraph store [Store]
        direction LR
        ING[ingestor] -->|writes| PG[(postgres)]
    end
    subgraph serve [Serve]
        direction LR
        YOU[Your browser] --> DASH[dashboard: nginx + Vue]
        DASH -->|GET /api/v1| API[api: Flask + gunicorn]
    end
    LOG -->|tail| ING
    API -->|reads| PG

    style COW fill:#ffe082,color:#000
    style LOG fill:#e8f5e9,color:#1b5e20
    style ING fill:#a5d6a7,color:#1b5e20
    style PG fill:#b39ddb,color:#311b92
    style API fill:#90caf9,color:#0d47a1
    style DASH fill:#c5cae9,color:#1a237e

Cowrie and the ingestor never talk directly. They share a volume, and the ingestor tails cowrie.json out of it.

Where to Start

  • Quick Start

    Bring the five containers up on your laptop and see the dashboard

    Quick Start

  • Deploy the Stack

    Put it on a real machine: what to publish, what to keep on loopback

    Deploy the Stack

  • How It Works

    The pipeline in detail: event parsing, schema, geolocation, redaction

    How It Works

  • REST API

    Every endpoint, plus the self-hosted Swagger UI and ReDoc

    REST API

What It Captures

Login attempts, the commands attackers type, hashes of anything they download, SSH client versions and key-exchange fingerprints, offered public keys, and port-forward requests. Everything else Cowrie emits is dropped.

The API is read-only and never returns a source IP address. Addresses are kept in the database for geolocation and counting distinct sources, nothing more.

You are collecting other people's data

A honeypot records credentials people type and binaries they upload. Whether that is fine where you live is your call to make before you expose it.

License and Attributions

Honeywatch is MIT licensed. Cowrie is a separate upstream project with its own license.

This product includes GeoLite Data created by MaxMind, available from maxmind.com. Country boundaries are made with Natural Earth.