🪤 Dead Man's Switch

A heartbeat watchdog that fires when you go silent — now a full handler toolkit.

"If I don't check in by tomorrow, the package ships itself."

What is it?

The Dead Man's Switch is the oldest trick in the espionage playbook, turned into a command-line toolkit. You arm it with a TTL (time-to-live). You stamp a heartbeat — a proof of life. If the heartbeat goes stale — if you're taken, you're cut off, or your cron just breaks — the switch escalates and fires its payload.

v0.2.0 grows the prop into the whole apparatus around it: a deterministic engine with a grace/warning phase, a tamper-evident event log, signed heartbeats and cancel tokens, proof-of-life challenges with a covert duress flag, Shamir secret sharing for the disarm key, quorum cancel approval, escalation policies, delivery channels with retry, a contact roster, a scenario simulator, handler reporting, and pre-flight checklists.

A natural fit for:

• Novel research — the scene where the captured hero can't touch the file and the countdown is real.
• Automation safety — if a scheduled task stops reporting, get an alert.
• Personal failsafes — a check-in ritual that escalates when it breaks.

Features

• ⏱️ Heartbeat with configurable TTL and grace/warning phase
• 🔫 Six payload types: print, webhook, email, command, file, notify
• 🧾 Tamper-evident event log (SHA-256 hash chain)
• 🔐 Signed heartbeats & cancel tokens (HMAC, replay-protected)
• 🧠 Proof-of-life challenges with a covert duress answer
• 🗝️ Shamir secret sharing to split the disarm key among trusted parties
• 👥 Quorum cancel — M-of-N approvals before a cancel is honored
• 📈 Escalation policies — remind → alert → release on a schedule
• 📡 Delivery channels with retry queue (file + loopback UDP)
• 🧪 Scenario simulator — replay beat patterns on a deterministic clock
• 📋 Handler reporting — status, timeline, post-mortem, runbook, debrief
• ✅ Pre-flight checklists and config auditing
• 🕯️ Digital legacy planner — staged, gated release of assets
• 📦 Zero runtime dependencies, pure Python standard library

Install

pip install deadman-switch

From source:

git clone https://github.com/AnonymoDGH/deadman-switch
cd deadman-switch
pip install -e .

Quickstart

# 1. Arm it — 60 seconds of silence means fire
dms arm --ttl 60 --payload '{"type": "command", "command": "echo released the files"}'

# 2. Prove you're alive
dms heartbeat

# 3. How much slack is left?
dms status
# [+] Alive. Last beat 3s ago, 57s of slack left.

# 4. Block until the switch fires
dms watch

CLI reference

All commands accept --config <path> to point at a different config file.

Payloads

{ "type": "webhook", "url": "https://example.com/hook", "data": "{\"op\":\"release\"}" }
{ "type": "email", "from": "agent@example.com", "to": "control@example.com",
  "subject": "SILENCE", "message": "The package is loose.",
  "smtp_host": "smtp.example.com", "smtp_user": "u", "smtp_pass": "p" }
{ "type": "command", "command": "python notify.py --urgent" }
{ "type": "file", "path": "release.txt", "message": "..." }
{ "type": "notify", "label": "trusted-contact" }

The handler toolkit (v0.2.0)

The package is organized as small, testable modules you can compose:

Example: simulate a silence scenario

dms simulate --scenario silence --ttl 60 --duration 300 \
             --beat-interval 30 --silence-from 60
# scenario:     silence
# final state:  fired
# fired:        yes

Example: split the disarm key

dms split "my-disarm-key" -n 3 -k 2 --out-dir ./shares
dms combine ./shares/share-1.txt ./shares/share-3.txt

How it works

Tests

pip install pytest
pytest

The suite is fully deterministic: the engine runs on an injected FixedClock, network tests use loopback UDP, and there are no external services.

License

MIT — a fiction research prop. Use it on systems you own, and keep the fireworks in the novel where they belong.