| name | relay-healthcheck |
| description | Pull, read, and act on the relay's daily health + intrusion report (the systemd timer runs the check and auto-remediates the safe subset; this pulls the secret-free report on demand). Triages FAIL/WARN lines, distinguishes auto-remediated drift from ATTENTION-REQUIRED intrusion, and re-baselines after an intentional change. Use when the user asks "is the relay healthy / safe", "check for attacks/intrusion", "pull the health report", or "re-baseline". |
| allowed-tools | Read, Bash, Agent, TodoWrite |
Relay health & intrusion check
Read CLAUDE.md (invariants + the re-baseline gotcha) and docs/HEALTHCHECK.md (severity model +
auto-remediation scope) first. The report is secret-free by design, so it is safe to display. Set
your own INSTANCE/ZONE/PROJECT for the pull script (defaults are placeholders).
Steps
- Pull the latest report from the laptop:
bash local/healthcheck-pull.sh (exit 2=FAIL, 1=WARN, 0=OK).
- History:
--history; JSON: --json.
- If it reports
NO_REPORT, the timer hasn't run yet — run --update-baseline once, or have the
relay-operator run healthcheck.sh immediately.
- Show the user the OVERALL status + counts, then the REMEDIATION TAKEN and ATTENTION
REQUIRED sections verbatim. Do not paraphrase ATTENTION REQUIRED lines.
- Triage by section:
- OK / WARN-only (e.g. pending updates, cert <30d): report healthy; note any WARN to watch.
- REMEDIATION TAKEN (DOCKER-USER order, INPUT chain, restarted core service): the check already
self-healed hardcoded known-good — confirm the next pull is clean; no human action needed.
- ATTENTION REQUIRED (new SSH key / user / cron /
--allow-cn, unknown listener or container,
auth-failure spike, new gateway api-key): treat as possible intrusion. Do NOT auto-fix. Walk the
user through containment (isolate the VM, inspect journalctl -u ssh, last -aw, authorized_keys,
docker ps -a; rotate CA + revoke device if a rogue CN/key appeared). Only the user authorizes it.
- Re-baseline only for an INTENTIONAL change the user confirms (added a device, rotated a cert,
accepted a package update):
bash local/healthcheck-pull.sh --update-baseline. Never re-baseline to
silence an unexplained diff — that would bless an intrusion.
Delegation
For anything beyond a pull (run the check immediately, inspect intrusion indicators, restore known-good),
delegate to the relay-operator agent. It is report-only on intrusion and never touches
users/keys/cron.
Guardrails
- Reports are secret-free — but never run a reader word +
.env/*.key in one Bash command (hook).
- Never weaken an invariant to make a check pass. A persistent FAIL is a finding, not a nuisance.
