rpotctl CLI reference¶
rpotctl is the deployment tool inside the ReD-Pot image. The installer uses it to create the persona, baits,
certificates and compose file. Most administrators never call it directly: use install.sh
for anything that changes an install, because the installer also updates the firewall, the systemd unit,
INSTALL-INFO.txt and the login banner.
Changing commands
init, baits, tls --renew, compose, add-sensor and remove-sensor rewrite parts of a deployment. On a
production manager, use install.sh (add-decoy, remove-decoy, set-access, reset-token) instead. Back up
/opt/redpot/manager first if you do use them.
How to run it¶
Commands that take -d DIR work on the manager directory, mounted into a throw-away container:
slots and export read the live database, so they run inside the console container:
python3 rpotctl.py --help and python3 rpotctl.py <command> --help list the options.
Commands¶
roles¶
Lists the decoy roles from the role catalog (roles/*.json).
init¶
Creates a new deployment in a directory: persona, baits, certificates, rpot.json. Used by the installer and the lab.
| Option | Meaning |
|---|---|
-d, --dir DIR |
deployment directory (required) |
--domain DOMAIN |
AD/DNS domain (required) |
--profile |
bank, generic, government, hotel or it (default generic) |
--web-theme |
webmail (default), helpdesk or intranet |
--sensor SPEC |
a decoy; repeat up to 3 times. Host mode: HOSTNAME=role@IP%IFACE; bridge lab: HOSTNAME=role[@IP] |
--net-mode |
host (production: each decoy on its interface's own IP) or bridge (isolated Docker lab, default) |
--subnet, --console-ip |
bridge lab only: the lab network and the manager's address on it |
--ui-port, --sensor-port |
host ports of the web UI (default 8740) and sensor API (default 8741) |
--public-ip, --mgmt-ip |
static public IP; management interface IP (UI and sensor API are published only there) |
--canary-url |
URL clients use to reach the console for bait-document beacons |
--allow CIDR |
scanner allow-list entry (repeatable) |
--internal CIDR |
extra internal network, for example your own public range (repeatable) |
--site-name, --site-lat, --site-lon |
site location on the world map |
--force |
overwrite an existing deployment |
baits¶
ctl baits -d DIR plans the baits for the current decoy set. Existing honeytokens are kept; crumbs for new decoys are
added. Restart the containers afterwards.
tls¶
ctl tls -d DIR shows the manager certificate (subject, issuer, SANs, SHA-256 fingerprint). --renew re-issues it and
re-keys the local decoys. Remote sensors pin the old fingerprint and must join again with a new join string.
compose¶
ctl compose -d DIR [--image IMAGE] [--ui-bind IP] writes the Docker Compose file for the deployment.
show¶
ctl show -d DIR prints the persona, the decoys and every honeytoken in plaintext (user, password, where it is
valid, where it is planted). Treat the output as secret.
add-sensor / remove-sensor¶
ctl add-sensor -d DIR --sensor SPEC and ctl remove-sensor -d DIR --name NAME add or remove a local decoy. The
installer's add-decoy and remove-decoy call these and also handle the firewall, SSH and the self-test.
wall-url¶
ctl wall-url -d DIR [--base URL] [--rotate] prints the read-only kiosk link. --rotate issues a new token and
invalidates old links. install.sh reset-token --wall does the same and restarts what is needed.
geoip¶
ctl geoip -d DIR [--city] downloads the DB-IP Lite country and ASN databases (about 18 MB). --city also fetches the
city database (about 130 MB) for precise map points. Lookups are offline afterwards. install.sh geoip is the usual way.
site¶
ctl site -d DIR --name NAME --lat LAT --lon LON sets where decoys on private addresses are drawn on the world map.
Restart the manager afterwards.
sudo docker run --rm --user 0 -v /opt/redpot/manager:/d rpot:1.0.1 ctl site -d /d --name "Yerevan HQ" --lat 40.18 --lon 44.51
sudo ls -ln /opt/redpot/manager/rpot.json # check owner and mode, see below
sudo systemctl restart redpot
Keep rpot.json readable by the console
Commands that save rpot.json write a new file with mode 0600, owned by the user that ran them (root with
--user 0). The console container runs as uid 10001 and reads rpot.json. If ls -ln shows another owner than
the one the file had before (on a standard install, uid 10001), restore it, for example
sudo chown 10001:10001 /opt/redpot/manager/rpot.json, before restarting.
slots¶
rpotctl.py slots --db DB --config CONFIG prints the decoy slot counts as one JSON line:
{"max": 3, "used": ..., "local": ..., "remote": ..., "pending": ...}.
export¶
rpotctl.py export --db DB --config CONFIG --from YYYY-MM-DD --to YYYY-MM-DD writes the JSON export of incidents and
alert records for those UTC days to standard output. Exit code 2 = bad range, 3 = too large. See
Export.