Runbook Guard

Runbook Guard is an open-source safety layer for operational automation. It turns a runbook request into a controlled workflow that gathers evidence, builds a typed plan, checks policy, keeps risky work behind approval, executes in dry-run mode by default, verifies postconditions, and writes an audit bundle.

The project is built for teams that need automation around incident response, deployment recovery, database-change review, ticket updates, and infrastructure operations without losing reviewability or traceability.

Author: Eldergenix

What It Does

Runbook Guard provides a repeatable lifecycle for safer operational changes:

1. Accept a structured runbook request.
2. Collect read-only evidence from configured systems.
3. Build a typed change plan with explicit capabilities and risk level.
4. Validate the plan against policy, approvals, and capability budgets.
5. Execute safe actions through adapters, with dry-run enabled by default.
6. Verify requested postconditions after execution.
7. Persist a machine-readable audit bundle with receipts and outcomes.

The result is a clear record of what was requested, what evidence was used, what was planned, what was allowed, what was executed, and whether the expected outcome was verified.

Who It Helps

Runbook Guard is useful for:

• Platform teams that want controlled automation for repeated operations.
• SRE and DevOps teams that need safer incident-response workflows.
• Security teams that require approvals, receipts, and audit trails.
• Engineering teams that want dry-run-first tooling around production-adjacent changes.
• Open-source maintainers who want deterministic examples for pull request, issue, CI, or migration-review workflows.

Current Capabilities

• FastAPI control plane with health, readiness, planning, status, and execution endpoints.
• Typer-based CLI for local validation, planning, execution, status checks, and audit inspection.
• Pydantic contracts for requests, evidence, plans, approvals, receipts, postconditions, and audit bundles.
• Policy engine for capability allowlists, denied capabilities, risk checks, approval thresholds, and rate or budget limits.
• Separate read and write adapter boundaries.
• Dry-run receipts for write operations.
• File-backed audit bundle storage with hashing, optional signing, and chained audit metadata.
• In-memory and SQLite workflow storage options.
• Deterministic example workflows for incident remediation, flaky CI review, and database migration review.
• Local quality, type-check, test, and security gates.

Repository Layout

src/runbook_guard/        Python package
src/runbook_guard/api/    FastAPI routes, dependencies, and error handling
src/runbook_guard/cli.py  Command-line interface
src/runbook_guard/core/   Workflow state machine and orchestration
src/runbook_guard/schemas Typed request, plan, receipt, and audit models
src/runbook_guard/policies Policy checks, approvals, auth, and budgets
src/runbook_guard/tools/  Read and write adapter interfaces
src/runbook_guard/storage Workflow and audit storage
examples/                 Runnable request examples and expected outputs
tests/                    Unit and integration tests
configs/                  Example policy, rules, and observability config
infra/                    Local Docker and compose assets
tools/                    Quality and security helper scripts

Requirements

• Python 3.12 or newer
• uv recommended for dependency management
• Docker only if you want to use the Docker-based sandbox or container build

Install

Clone the repository:

git clone https://github.com/Eldergenix/autonomous-agent-runbook-guard.git
cd autonomous-agent-runbook-guard

Install all development extras with uv:

uv sync --extra dev --extra agent --extra observability --extra evals --extra sandbox

Or install with pip:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,agent,observability,evals,sandbox]"

Run the CLI

Print the effective local settings:

uv run runbook-guard doctor

Validate an example request:

uv run runbook-guard validate examples/incident_to_pr/request.json

Plan a workflow without executing it:

uv run runbook-guard plan examples/incident_to_pr/request.json

Execute an example workflow in dry-run mode with approval supplied at the CLI:

uv run runbook-guard execute \
  --input examples/incident_to_pr/request.json \
  --approved \
  --approver local-operator

List audit bundles:

uv run runbook-guard audit-list

Show an audit bundle by workflow ID:

uv run runbook-guard audit-show <workflow-id>

The Makefile also includes shortcuts:

make doctor
make example-plan
make example-execute

Run the API

Start the local API server:

make serve

The API runs at:

• Base URL: http://localhost:8080
• Swagger UI: http://localhost:8080/docs
• OpenAPI schema: http://localhost:8080/openapi.json

Plan a runbook request:

curl -s \
  -X POST http://localhost:8080/v1/runbooks/plan \
  -H "Content-Type: application/json" \
  --data @examples/incident_to_pr/request.json

Execute a request inline:

curl -s \
  -X POST http://localhost:8080/v1/runbooks/execute-inline \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "request_id": "incident-to-pr",
      "title": "Investigate failed deploy and prepare remediation",
      "objective": "Collect deployment evidence and stage the minimal safe remediation.",
      "summary": "Use read-only evidence first, then prepare a dry-run write receipt.",
      "target_systems": ["github", "ci", "kubernetes"],
      "requested_read_capabilities": ["github.read", "ci.read", "docs.read"],
      "requested_write_capabilities": ["github.pull_request.create"],
      "risk_level": "medium",
      "requester": "platform-operator",
      "dry_run": true,
      "postconditions": [
        {
          "id": "draft-pr-receipt",
          "description": "A draft pull request receipt exists.",
          "required": true,
          "verifier": "receipt"
        }
      ]
    },
    "approved": true,
    "approver": "api-operator"
  }'

Check a workflow status:

curl -s http://localhost:8080/v1/runbooks/<workflow-id>/status

Example Workflows

The examples/ directory includes ready-to-run requests:

• examples/incident_to_pr/request.json collects incident evidence and prepares a safe remediation pull request receipt.
• examples/flaky_ci_fix/request.json reviews flaky CI evidence and stages a safe patch workflow.
• examples/db_migration_review/request.json reviews database migration risk while keeping mutation steps behind approval and dry-run behavior.

Each example is deterministic, local-first, and designed to show the full request-to-audit lifecycle.

Configuration

Configuration is environment-driven through the Settings model in src/runbook_guard/config.py. Common settings include:

• RUNBOOK_GUARD_APP_NAME
• RUNBOOK_GUARD_ENVIRONMENT
• RUNBOOK_GUARD_LOG_LEVEL
• RUNBOOK_GUARD_PROJECT_ROOT
• RUNBOOK_GUARD_AUDIT_DIR
• RUNBOOK_GUARD_POLICY_CONFIG
• RUNBOOK_GUARD_APPROVAL_CONFIG
• RUNBOOK_GUARD_SIGNING_KEY

Example policy and observability files live under configs/.

Audit Bundles

Audit bundles are first-class outputs. A bundle records:

• Original runbook request
• Evidence gathered before execution
• Typed change plan
• Approval status and approver identity
• Execution receipts
• Postcondition verification results
• Final workflow status
• Content hash, optional signature, and chain hash metadata

This makes each run easier to inspect, store, diff, or forward to a review system.

Safety Model

Runbook Guard is designed around several safety defaults:

• Read-only evidence collection happens before write execution.
• Write actions are routed through separate adapters.
• Dry-run mode is enabled by default on requests.
• Higher-risk actions can require approval before execution.
• Capability policy can allow, deny, or budget tool access.
• Postconditions are checked after execution.
• Every workflow can produce audit receipts.

The default implementation is local-first and intentionally conservative so it can be extended without granting broad production permissions by accident.

Development Checks

Run the full local verification set:

make quality
make security
make test

Individual checks:

make verify-repo
make lint
make typecheck
make test

Build the package:

make build

Build the local container image:

make docker-build

Project Status

Runbook Guard is an alpha project with runnable CLI and API flows, typed contracts, policy checks, adapter seams, storage options, example workflows, and test coverage. Some external integrations are scaffolded or local-first and are intended to be replaced with deployment-specific adapters.

License

Apache-2.0. See LICENSE.