bigpickle/sigil
0
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
sigil/docs/PROD_RUNBOOK.md
leora df1ed31bdb Fix R11: pin cryptography; add prod runbook for seal + anchor 
Add requirements.txt (cryptography>=43.0.0,<45) and docs/PROD_RUNBOOK.md
requiring SIGIL_SEAL_PASS and SIGIL_ANCHOR on separate storage. Document
info findings R9/R12/R13 in DESIGN; leave R10 domain separation as a
versioned follow-up (not backward-safe).
2026-10-06 06:28:01 +08:00

2.1 KiB
Raw Blame History

Sigil production runbook

Short checklist before Sigil guards anything real. Library-only today — do not enable platform glue until an integration review covers session minting.

Required environment

Variable Purpose Notes
SIGIL_DB Path to the store file Prefer a dedicated volume; backups are sensitive (roster + audit).
SIGIL_SEAL_PASS AES-256-GCM seal passphrase Required in prod. ≥12 chars. Without it the DB file is cleartext on disk. Seal-on still uses a plaintext 0600 working copy while the process is open — not SQLCipher.
SIGIL_ANCHOR Off-box signed tip path Required in prod. Must be on storage separate from SIGIL_DB (different volume/host). Every checkpoint publishes here; verify_external_anchors / verify-chain must alert on failure.

Optional: agent private keys stay off the platform host whenever possible; checkpoint signer key preferably offline.

Ops loop

  1. Open with seal + anchor configured (CLI respects the env vars above).
  2. Periodically run chain verify and external-anchor verify; page on failure.
  3. After permanent revoke (compromise): bootstrap + enrol_rekey, then reinstate. Reinstate alone does not restore a wiped key.
  4. Single writer process until a shared rate-limit store exists (in-process quotas multiply across processes).

Integration sharp edges (do not ignore)

  • Never mint issue_agent_session from a client-supplied name or header. Only after a verified challenge-response. Prefer keeping that helper internal to verified paths.
  • Human view codes are ~40 bits; keep TTL short; never log raw codes (already hashed in audit).
  • Challenge signatures today sign the raw nonce (no domain separation). Changing the signed payload needs a coordinated version bump — tracked as a follow-up, not a silent break.

Deferred

  • SQLCipher / page-level encryption for multi-tenant co-resident hosts.
  • Domain-separated challenge payloads (sigil-challenge-v1 prefix) — backward-incompatible without a protocol version.
  • Shared cross-process rate limiter.