Stanch

The dead-man's switch that acts. Stanch stops the bleeding when no one answers.

v0.1 shipped detection, invariants and alerting; v0.2 adds the "acts": first-class acknowledgment and autonomous stop-playbook execution on missed ACK. See Status.

Services increasingly run themselves — agents, automations, pipelines, AI-operated workflows. When one of them goes wrong at 3 a.m., your monitoring stack tells you. Nothing guarantees the bleeding stops if you don't answer.

To stanch is to stop a flow — of blood, of loss. That is the entire product. Alerting assumes a human wakes up; Stanch assumes the human might not — and holds a small set of pre-approved emergency actions that can only ever make the system safer: turn a flag off, pause a lane, go read-only, quarantine, restart once. If a critical alert is not acknowledged in time, Stanch executes the most conservative pre-approved action. That's it. It cannot "fix" anything — by design.

The model comes from fail-stop semantics in distributed systems: on failure, stop rather than act incorrectly.

Everything below is exercised by the test suite (226 tests) and the demo compose.

• External dead-man heartbeat. Your services check in (POST /api/v1/heartbeat, scoped tokens, fail-closed); Stanch runs outside them, so it notices when they can't speak for themselves.
• Business-invariant watchers. Not just "is the process up" — versioned YAML rules over heartbeat metadata (staleness, meta_threshold), shadow-capable, for invariants like payouts per hour must not exceed X or no completed orders for N minutes during business hours.
• Pluggable alert channels. Telegram and WhatsApp (direct Meta Graph API, template mode for business-initiated alerts outside the 24h window) behind a single channel interface.
• Anti-fatigue pipeline. Dedupe by fingerprint, per-rule cooldowns, auto-resolve on recovery, optional per-severity re-notification of open alerts.
• Stop-only playbooks, declared as code. Containment actions are a closed set, pre-approved in code, reviewed via git, and restricted to STOP semantics by construction: disable a feature flag, pause a lane, switch read-only, quarantine an entity, one restart. Stanch can never start, transfer, delete, or touch DNS — enforced by type and by negative test.
• Playbook execution engine. A shadow-first runtime for the stop set: pluggable executors (webhook family included — one operator-controlled URL per action kind), action_log written before and after every real execution, and shadow mode that logs what would have run without touching anything.
• Missed-ACK autonomy. A P0 with no human acknowledgment within the configured window ⇒ the most conservative pre-approved action of its rule runs, automatically. One autonomy decision per alert (re-armed only after resolve), enforcement opt-in per rule — everything else stays shadow.
• Acknowledgment tracking. First-class ACK on alerts — an authenticated endpoint (idempotent, coherent 404/409) plus /ack commands and replies straight from the Telegram ops chat; WhatsApp acks via the endpoint (its template contract has no buttons — documented).
• Append-only audit trail. Every observation, alert, and recorded action is appended to action_log; nothing is rewritten.
• Self-monitoring. Watch-the-watcher pings to a healthchecks.io-compatible URL, plus a daily health summary.

1. The hand only knows how to stop. Every automated action reduces exposure; none can create new risk.
2. Deterministic action path. No model, no heuristic, no "probably" between detection and containment.
3. Human primacy. Playbooks are approved by humans in advance, as code, via git. The dashboard can acknowledge and silence — it can never edit rules.
4. Shadow-first adoption. Run observe-only until you trust it; enforcement is opt-in per rule.
5. Fail-stop over fail-operational. When in doubt, stop the smallest thing that stanches the loss.

Prerequisites: Docker with the Compose v2 plugin (docker compose, not docker-compose), make, and curl. No .env needed — the demo ships with safe defaults.

git clone https://github.com/getstanch/stanch
cd stanch
docker compose up --build

This boots Stanch plus a small demo service that heartbeats every 10 s and exposes its own control endpoint. It runs in the foreground — open a second terminal for the next commands (or add -d). Wait until the demo service has checked in once (~15 s after boot; make demo-status shows heartbeats_delivered ≥ 1). Don't worry about racing it: make demo-incident refuses to run before that first check-in, so you can't silently break the demo. Then trigger the whole loop:

make demo-incident   # stops the demo service's heartbeat — nothing else
make demo-status     # watch: P0 alert (~30 s) → no ACK (60 s) → lane paused → audit trail

Missed heartbeat → P0 alert → no acknowledgment within the window → Stanch POSTs the pre-approved pause action to the demo service's control endpoint → the lane shows paused and the dossier carries the full action_started/action_finished trail. To watch a human win the race instead, run make demo-ack before the window closes — it grabs the open alert's id, acks it, and the hand stands down. Example configuration lives in examples/, fully commented.

Early — v0.1.0, APIs unstable. Stanch was designed by a founder-engineer to guard a real five-city transportation platform (~400,000 rides/month); the staged, shadow-first rollout on that operation is in progress, and this README will state plainly what has and hasn't run in production as that progresses. No inflated claims: what you read here is what is true today. v0.1 shipped detection, invariants, alerting and the audit trail; v0.2 (unreleased, on main) adds the acknowledgment flow, the playbook execution engine and missed-ACK autonomy — every capability listed above is proven by the test suite before it is listed.

Stanch is not a metrics platform (bring Prometheus/Grafana), not an incident manager (bring PagerDuty/Opsgenie if you like — Stanch coexists), and not an auto-healer. It deliberately cannot repair, scale, roll back, or "try something." It stops things. That constraint is the product.

• Hardened playbook executors for common stacks (feature-flag providers, queue pauses, DB read-only)
• More alert channels; acknowledgment via inline replies
• Invariant-rule library with real-world examples
• Post-incident report generation (read-only analyst)

Issues and PRs welcome — especially real-world invariant rules and containment executors. See CONTRIBUTING.md. Security reports: see SECURITY.md (please do not open public issues for vulnerabilities).

Apache-2.0. © Marcos Rodrigues Gomes Junior.