# perf/nuisance — edge nuisance-block (my.knownelement.com)

Runbook for the founder-directed hostile-source block (#796, #787 Option B).
Ops knowledge lives here (runs beside code); the durable audit trail is
Redmine #796 + Discourse t/298.

## How it works

- Enforcement is **Cloudron-native**: the blocklist setting
  (`firewall_blocklist`) drives ipset `cloudron_blocklist`, referenced by the
  INPUT-side `CLOUDRON` chain and FORWARD-side `DOCKER-USER`. Cloudron
  re-applies it at boot — no custom firewall persistence to maintain.
- Detection is **dual**:
  - `nuisance-sweep.sh` (workstation, daily 09:00 automation): scans Haraka
    spamhaus-DENY sources, adds new ones (>=3 denials/24h, cap 64/run) via
    the blocklist API, prints every change for the daily report.
  - `nuisance-detect.sh` + `nuisance-detect.timer` (host, 07:15 daily, no
    secrets): writes ranked candidates to
    `/home/yellowtent/platformdata/nuisance/candidates.txt` — cross-check
    that detection runs even if the LLM automation misses a day.

## View current blocks

- Panel: **my.knownelement.com → Network → IP block list**
- API: `GET https://my.knownelement.com/api/v1/network/blocklist`
- Kernel: `ipset list cloudron_blocklist` (members = what is actually dropped)

## Unblock something

1. Add the IP/CIDR to `allowlist.txt` (repo) — the sweep will never re-add it.
2. Remove it from the live setting: GET the blocklist, delete the line, POST
   the remainder (POST /api/v1/network/blocklist, body
   `{"blocklist": "<full text>"}`). Takes effect immediately.
3. Update `blocklist.txt` (repo) and note why in Redmine #796.
4. Verify: `ipset test cloudron_blocklist <ip>` must FAIL after removal.

## Files

| file | role |
|------|------|
| `nuisance-sweep.sh` | daily auto-block sweep (workstation, automation-driven) |
| `nuisance-detect.sh` | host-side candidate scan (no secrets) |
| `nuisance-detect.{service,timer}` | systemd arming for the detector |
| `blocklist.txt` | git SoR mirror of the live blocklist |
| `allowlist.txt` | never-block overrides (always wins) |

## Known limits (v1)

- IPv4 only. IPv6 sources are logged by Haraka but not blocked.
- The sweep only ever blocks IPs our own mail server already DENIED on
  Spamhaus evidence — a listed-but-legit sender is unaffected in practice
  (it could not deliver anyway). If a shared IP needs unblocking, follow the
  procedure above.