/projects/runbookguard
An open-source safety layer that turns a runbook request into a controlled workflow — read-only evidence, a typed plan, policy and approval gates, dry-run-by-default execution, postcondition checks, and a hashed audit bundle.
Operational automation can be dangerous when runbooks jump straight from request to execution. Production teams need evidence, risk checks, approvals, dry runs, postconditions, and audit bundles.
Runbook Guard turns each runbook request into a controlled workflow: evidence collection, typed planning, policy gates, approval checks, dry-run write adapters, postcondition verification, and hashed audit output.
The workflow must make operational safety practical: operators need CLI and API access, policies need typed contracts, and write actions must be testable before execution.
The project frames runbook automation as a safety layer, not a convenience wrapper. Every potentially risky step is represented as data that can be approved, replayed, or audited.
This demonstrates Stefan's operational governance expertise across FastAPI, Typer CLIs, Pydantic contracts, dry-run adapters, approval systems, and incident-safe automation design.
Runbook Guard is production automation with a safety lifecycle. It shows how to let agents assist operations without jumping straight from natural language to irreversible writes.
The runbook path moves through evidence collection, typed planning, policy gates, approval, dry-run execution, postcondition checks, and audit output. Each state has a purpose.
Risk thresholds, allowlists, denylists, and budgets are deterministic controls. They keep safety out of the prompt and inside contracts that operators can inspect.
Write adapters default to dry-run receipts so operators can see intended effects before mutations happen. This is essential for infrastructure and incident workflows.
A hashed audit bundle records request, evidence, plan, approval, receipts, and verification. That makes runbook execution explainable after the incident window closes.
Keeps the control plane approachable for SRE and platform automation scripts.
Provides typed HTTP endpoints for plan, status, execute, health, and readiness.
Gives operators a CLI that mirrors the API without duplicating command parsing.
Makes runbook requests, plans, receipts, approvals, and audit bundles explicit contracts.
Stores workflow state locally with almost no operational overhead.
Packages the guardrail service for repeatable local and deployment checks.
Keeps Python dependency resolution and command startup fast for operator workflows.
Accepts plan, execute, status, health, and readiness calls.
Runs validate, plan, execute, audit-list, and audit-show from the terminal.
Rejects malformed requests before they enter the state machine.
Pulls read-only evidence before any write action can be planned.
Applies allowlists, denylists, risk thresholds, and budget limits.
Holds higher-risk plans until a named human approves them.
Keep mutations behind a separate seam and emit receipts by default.
Confirm the intended outcome before the run is marked verified.
Seals request, evidence, plan, approvals, receipts, and verification into a reviewable record.