M24 — Guided tour, setup checklist and tunnel controls

Status: accepted.

1. Goal

A first-time owner understands, from the dashboard alone, what each part of SuckerPot does, where the data comes from and what is left to set up. The VPN tab gets the two controls the owner missed after a tunnel restart: “Check now” and “Reconnect”.

2. Guided tour (web only)

• A welcome dialog opens on the first login of each account (state kept in localStorage, keyed by username; nothing sensitive). It can be replayed at any time from a ”?” button in the top bar (“Take the tour”).
• 7 short steps, each one sentence plus a small flow diagram or illustration, with Back / Next / Skip and a step indicator. Keyboard and screen-reader friendly.
  1. What SuckerPot is: fake services that attackers find on the internet, nothing real behind.
  2. Daily reading: Today, then Attacks → a session’s story and replay.
  3. Campaigns, Tools (scripts, malware, infrastructure) and Trends: how sessions are grouped.
  4. Payloads: sensors only record URLs; the collector fetches them through the VPN into a quarantine; the network-less analyzer reads them (type, hashes, YARA, deobfuscation, C2); nothing is ever executed.
  5. Anonymous egress: only the vpn service reaches the internet; the gate pauses every outbound lookup when the tunnel or its exit looks wrong; the kill switch.
  6. Abuse reports: contacts found over RDAP through the VPN, drafts the owner reviews and sends from their own mailbox; the stack never sends mail; the identity guard.
  7. Alerts: rules, channels, digests; sent through the VPN. The last step shows the setup checklist (section 3).
• A ”?” help popover on every page header: two or three sentences on what the page shows, where its data comes from and one useful action. Texts live in one module (web/src/lib/help.ts) so they can be reviewed together.

3. Setup checklist

GET /api/v1/setup/status (admin only) returns a list of items: {id, state: "ok" | "todo" | "warning" | "off", detail, href}. Items, computed from real state:

id	ok when
sensors	every sensor has sent an event in the last 24 h (else warning, listing the silent ones)
vpn	the ingest egress gate is open
collector	COLLECTOR_ENABLED is true and the collector gate is open (off when disabled)
reporting_settings	every Settings → Reporting wording field is filled
self_address	a manual (or confirmed) self address exists
abuse_worker	ABUSE_REPORTS_ENABLED is true (off otherwise)
alerts	at least one alert channel is configured (off otherwise)
provider_keys	AbuseIPDB / GreyNoise keys set (off when not, with what they add)

The checklist appears in the tour’s last step and as a card in Settings → General. The host firewall cannot be seen from inside the stack: the card names just egress-check instead.

4. Tunnel controls

• Faster recovery. While the gate is closed, ingest and the collector re-check every 20 s (backing off to the normal interval after 10 failures), instead of waiting the full interval.
• Check now. POST /api/v1/settings/vpn/check (admin, CSRF, no password, rate-limited to one per 10 s) inserts a row in egress_check_requests (migration 0021: id, requested_at, requested_by, done_at; api SELECT/INSERT, ingest SELECT/UPDATE(done_at)). Ingest polls the table every 5 s and wakes its gate; the collector’s gate follows within its fast retry.
• Reconnect. POST /api/v1/settings/vpn/reconnect (admin, password again, at most one per 60 s) writes /vpn-config/restart (a timestamp). The vpn entrypoint watches that file too and restarts the container when it changes, exactly as for a new wg.env. Audit action vpn.reconnect. Nothing else in the file is read.