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.
Manager and sensor link¶
| 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.