Skip to content

Architecture

A ReD-Pot deployment has one manager and up to three decoys (Community Edition). Decoys run either on the manager server itself (local decoys) or on other servers (remote sensors).

flowchart LR
    subgraph DL1["Decoy LAN A"]
        A1["Attacker"]
    end
    subgraph DL2["Decoy LAN B (other VLAN or office)"]
        A2["Attacker"]
    end
    subgraph M["Manager server"]
        direction TB
        D1["Local decoy<br/>(host network, eth1 IP)"]
        CON["Console container<br/>web UI :random<br/>sensor API :random<br/>SQLite"]
        FW["Host firewall<br/>firewall.sh"]
    end
    subgraph R["Sensor server"]
        direction TB
        D2["Decoy"] -- "Unix socket" --> RL["Relay sidecar"]
    end
    ADM["Admin browser<br/>(management network)"]
    A1 --> D1
    A2 --> D2
    D1 -- "events (HTTPS)" --> CON
    RL -- "HTTPS, pinned certificate,<br/>one kept-alive connection" --> CON
    ADM -- "HTTPS, allow-listed" --> CON
    CON --> LOG["alerts.json / events.json"]

Components

Component What it does
Installer (install.sh, Python standard library only) Installs the manager or a sensor, adds and removes decoys, changes allow-lists, updates, uninstalls, exports. See Installer reference.
Manager console One container with the Flask web UI and the sensor API, each on its own random HTTPS port. Stores events, incidents and alert records in SQLite (WAL). Scores events, builds incidents and writes alerts.json.
Decoy One container per decoy, running only the protocol emulators of its role. Production decoys run in the host network and bind the IP of their own interface.
Relay (remote sensors only) Sidecar container. The decoy hands events to it over a Unix socket, and only the relay talks to the manager.
Host firewall (firewall.sh) Generated by the installer, applied by the redpot systemd service at every start. Decoy-interface policy, admin allow-lists, decoy egress guard, TTL 128 for Windows decoys. See Ports and firewall.
rpotctl Deployment CLI inside the image: persona, baits, TLS, compose file, slots, export. See rpotctl CLI reference.

Everything runs from one Docker image, ghcr.io/redsidesecurity/red-pot:<version> (about 280 MB), or rpot:<version> when built locally.

Property Behaviour
Transport HTTPS (TLS 1.2 or 1.3) on its own random port. The web UI uses a different random port.
Trust The manager certificate is pinned by its SHA-256 fingerprint, which is part of the join string. A different certificate is refused. There is no CA to compromise.
Enrollment A one-time join token (valid 24 hours) is exchanged for a per-sensor key. The manager stores only the key's hash. Revoke disables a key at once.
Least data A sensor receives its identity, the persona and a hashed honeytoken index. No plaintext bait passwords, bait locations or admin secrets. The domain controller decoy additionally holds the Kerberos keys of the bait accounts valid on it, so it can issue tickets and verify NTLM.
Anti-spoofing Events are stamped with the authenticated sensor name, so a hijacked sensor cannot report as another one.
Efficiency One kept-alive TLS connection, heartbeats every 25 to 35 seconds with random jitter, gzip-compressed batches: about 0.6 kbit/s idle, about 5 MB per day.
Live sync Each heartbeat returns a configuration version. When a new sensor enrolls, sensors pull the new honeytoken index, so a credential stolen at one site is recognised at every site.
Liveness The manager checks every 30 seconds. More than 2 minutes of silence opens an L4 "possible tampering" incident.
Clocks Sensor clocks are not trusted. A timestamp more than 15 minutes old or more than 5 minutes in the future is replaced by the manager's time; the original is kept as sensor_ts.

When the manager is unreachable

A sensor retries the batch in flight in memory for up to 60 seconds, so a manager restart loses nothing. After that, events are written only to a local log on the sensor, undelivered-<NAME>.jsonl (mode 0600, capped at 50 MB by default) and are not sent later. When the sensor reconnects, it sends one note with the number of undelivered events and the first and last timestamp, shown on that decoy's incident.

Enterprise feature: available in ReD-Pot Enterprise

Offline spool and replay. In ReD-Pot Enterprise a sensor buffers events on disk while the manager is unreachable and replays them when the link is back, so no events are lost during an outage.

About ReD-Pot Enterprise · Compare editions · Contact us for a licence

Data and storage

What Where (manager)
Configuration (secret) /opt/redpot/manager/rpot.json
Install summary (root only) /opt/redpot/manager/INSTALL-INFO.txt
Database (SQLite) Docker volume redpot_console-data, /var/lib/rpot/rpot.db inside the console container
Alert and event logs /opt/redpot/manager/logs/alerts.json, events.json
Bait files /opt/redpot/manager/baits/
Manager certificate /opt/redpot/manager/tls/
Remote sensor /opt/redpot/sensor/

See Configuration file and Logs.