Skip to content

About

Turn Markdown runbooks into agent-executable steps: read-only diagnostics run automatically, changes require human approval. Ships as an MCP server.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

8 Commits

Folders and files

Repository files navigation

runbook-agent

Turn Markdown runbooks into executable steps: read-only diagnostics run automatically, anything that changes state waits for a human to approve that exact step. Works as a command-line tool and as an MCP server.

Status: first working version (0.1.0). Parsing, command classification, dry-run, approval-gated execution, the audit log, a stdio MCP server and user-defined allowlist rules (--rules FILE) all work today. See Limitations for what does not.

Safety model

The tool is built so that the dangerous path is the one that takes effort.

  • Dry-run by default. run and serve execute nothing unless you pass --execute.
  • Allowlist, not blocklist. A command auto-runs only if every part of it is a known inspection command (df, kubectl get, journalctl, ...) used without flags that write. Unknown commands are treated the same as mutating ones.
  • No shell for auto-run commands. Read-only commands are executed directly as argument lists. Anything that would need a shell to interpret ($VAR, $(...), globs, redirection, sudo, environment assignments, multi-line scripts) is never auto-run.
  • Approval is per step and explicit. A mutating step runs only when a human names it (--approve 3), types yes at an interactive prompt, or records a one-time approval for the MCP server. A blocked or failed change stops the runbook.
  • The agent cannot approve itself. The MCP server has no approval tool. Approvals are recorded out of band, are single-use, expire after 15 minutes and are bound to the exact command text, so editing the step voids them.
  • Everything is logged. Each command, its classification, the reason, who approved it, exit code and output go to a JSON Lines audit log.

Install

pip install git+https://github.com/narayana006/runbook-agent

Python 3.10 or newer. No dependencies outside the standard library.

Quick start

Clone the repo for the example runbooks, then dry-run one. Nothing is executed:

$ runbook-agent run examples/runbooks/disk-full.md
Disk full on a checkout-api node (disk-full.md): 7 steps, mode: DRY RUN (nothing is executed; pass --execute to run)

[1] Confirm which filesystem is full.
    $ df -h
      dry-run: read-only, would run automatically

[2] Find the pods on the affected node and check for restarts.
    $ kubectl get pods -n shop -o wide
      dry-run: read-only, would run automatically
    $ kubectl describe node worker-07.example.com
      dry-run: read-only, would run automatically

[3] Look for a log flood in the last few minutes.
    $ kubectl logs -n shop deploy/checkout-api --since=10m | grep -c ERROR
      dry-run: read-only, would run automatically

[4] Check how much space old journal entries are using.
    $ journalctl --disk-usage
      dry-run: read-only, would run automatically

[5] Trim the journal to free space quickly.
    $ sudo journalctl --vacuum-size=500M
      dry-run: mutating, needs approval (runs with elevated privileges (sudo))

[6] If a single pod is flooding the logs, restart the deployment.
    $ kubectl rollout restart -n shop deploy/checkout-api
      dry-run: mutating, needs approval (kubectl rollout restart is not a read-only subcommand)
    $ kubectl rollout status -n shop deploy/checkout-api
      dry-run: read-only, would run automatically

[7] Confirm disk usage is back under the alert threshold.
    $ df -h
      dry-run: read-only, would run automatically

Result: dry-run. 0 command(s) executed, 2 step(s) need approval.

examples/runbooks/hello.md only uses echo, uname, tr, sort and cat, so it is safe to execute for real. With --execute the diagnostics run and the tool stops at the first change (exit code 3):

$ runbook-agent run examples/runbooks/hello.md --execute
Hello runbook (hello.md): 4 steps, mode: EXECUTE

[1] Print the kernel name.
    $ uname -s
      auto-run: exit 0 in 12 ms
      | Darwin

[2] Pipes between read-only commands are fine.
    $ echo "three two one" | tr " " "\n" | sort
      auto-run: exit 0 in 21 ms
      | one
      | three
      | two

[3] Write a marker file (redirection writes to disk, so this needs approval).
    $ echo "runbook-agent was here" > runbook-agent-demo.txt
      BLOCKED: mutating, not approved (redirects output to a file)

Result: awaiting-approval. 2 command(s) executed, 1 step(s) need approval, audit log: runbook-audit.jsonl.
Stopped before step 3. Review it, then re-run with --approve 3 (or --interactive).

Approve that one step and the run completes:

$ runbook-agent run examples/runbooks/hello.md --execute --approve 3 --approver dana
Hello runbook (hello.md): 4 steps, mode: EXECUTE

[1] Print the kernel name.
    $ uname -s
      auto-run: exit 0 in 32 ms
      | Darwin

[2] Pipes between read-only commands are fine.
    $ echo "three two one" | tr " " "\n" | sort
      auto-run: exit 0 in 69 ms
      | one
      | three
      | two

[3] Write a marker file (redirection writes to disk, so this needs approval).
    $ echo "runbook-agent was here" > runbook-agent-demo.txt
      approved-run approved by dana: exit 0 in 57 ms

[4] Read the marker file back.
    $ cat runbook-agent-demo.txt
      auto-run: exit 0 in 16 ms
      | runbook-agent was here

Result: completed. 4 command(s) executed, 1 step(s) need approval, audit log: runbook-audit.jsonl.

The matching audit log entry for step 3:

{"ts": "2026-11-11T02:00:36+00:00", "runbook": "hello.md", "step": 3, "title": "Write a marker file (redirection writes to disk, so this needs approval).", "command": "echo \"runbook-agent was here\" > runbook-agent-demo.txt", "classification": "mutating", "reason": "redirects output to a file", "action": "approved-run", "approved_by": "dana", "exit_code": 0, "duration_ms": 57, "output": ""}

How runbooks are read

  • Each fenced code block tagged bash, sh, shell, zsh or console is one step. Untagged blocks and other languages are ignored, so sample output and YAML snippets never become commands.
  • The step title is the nearest prose line above the block (usually the numbered list item), falling back to the section heading.
  • Each line of a block is one command. Comment lines are dropped and trailing-backslash continuations are joined. In console blocks only $ lines are commands.
  • A block containing a heredoc or shell control flow (for, if, while, ...) is kept whole as one script, which always needs approval.

Commands

Command What it does
runbook-agent parse FILE [--json] List steps and show how every command is classified, with the reason.
runbook-agent run FILE Dry-run. Add --execute to run read-only steps and stop at the first unapproved change.
runbook-agent run FILE --execute --approve N Also run mutating step N. Repeat --approve for more steps. --interactive prompts on the terminal instead and requires typing yes.
runbook-agent approve FILE N Record a one-time approval of step N for the MCP server (prompts for yes; --yes skips the prompt).
runbook-agent serve DIR [--execute] Serve the *.md runbooks in DIR as an MCP server over stdio.

parse, run and serve also take --rules FILE to load extra allowlist rules.

Other options: --log PATH (audit log; defaults to runbook-audit.jsonl when --execute is given, no log is written for a dry run unless you ask), --timeout SECONDS per command (default 30), --approver NAME (recorded in the log, defaults to the current user), --state-dir DIR (where approvals are stored, default .runbook-agent).

Exit codes for run: 0 dry-run finished or runbook completed, 1 an approved change failed, 3 stopped waiting for approval.

Classification

Three labels: read-only runs automatically; mutating (recognised as changing state) and unknown (not recognised, or needs a shell) both wait for approval.

Read-only today: common inspection commands (cat, ls, grep, head, tail, df, du, ps, dig, ping, jq, stat, ...), find without -delete/-exec, sort without -o, journalctl without maintenance flags, curl for plain GET/HEAD with no upload or output-file flags, and the read subcommands of kubectl (get, describe, logs, top, rollout status, ...), git, docker, systemctl, helm and aws (describe-*, list-*, get-*, s3 ls). Commands that would print secrets (kubectl get secret, aws ... get-secret-value) need approval. Pipes and &&, ||, ; between read-only commands are allowed. The full table is in src/runbook_agent/classifier.py.

Custom allowlist rules

Pass a JSON file with --rules to teach the classifier about your own read-only tools, or to make it stricter. The file is only read when you name it; nothing is picked up automatically from the current directory, so a rules file inside a cloned repository cannot loosen the checks on its own. examples/rules.json:

{
  "allow": {
    "gcloud": {
      "subcommands": ["compute instances list", "compute instances describe", "config list", "container clusters list"],
      "deny_long": ["--log-http"],
      "value_flags": ["--project", "--zone", "--region", "--format"]
    },
    "kubectl": { "subcommands": ["get-contexts"] },
    "uname": { "deny_short": "n" }
  },
  "deny": ["ping"]
}
$ runbook-agent parse examples/runbooks/gcp-vm.md --rules examples/rules.json
GCE VM is unreachable (gcp-vm.md): 4 steps

[1] Check which project the CLI is pointed at.  (read-only, line 5)
    $ gcloud config list
      -> read-only: only read-only commands, no shell features

[2] List instances in the zone.  (read-only, line 11)
    $ gcloud --project shop-prod compute instances list --zone europe-west1-b
      -> read-only: only read-only commands, no shell features

[3] Check the VM answers on the network.  (unknown, line 17)
    $ ping -c 3 10.0.0.12
      -> unknown: ping is not on the read-only allowlist

[4] Reset the VM.  (mutating, line 23)
    $ gcloud --project shop-prod compute instances reset web-1 --zone europe-west1-b
      -> mutating: gcloud compute instances is not a read-only subcommand

Without --rules, steps 1, 2 and 4 are all unknown (gcloud is not built in) and step 3 is read-only.

How the file is applied:

  • allow maps a program name to a rule. Fields: subcommands (allowed subcommand prefixes such as "compute instances list"; leave it out to allow any arguments), deny_short (single-letter flags that write, e.g. "of"), deny_long (long flags that write; "--out" also blocks --out=x and --output), value_flags (global flags that take a value, skipped when finding the subcommand), max_positional, prefixes and skip_words (operation-word matching, as the built-in aws rule uses).
  • A new program gets exactly the rule you write.
  • A built-in program can only be extended: listed subcommands, deny_short, deny_long and value_flags are added to the built-in ones, and the built-in restrictions (secret checks, write flags) stay. prefixes, max_positional and skip_words cannot be changed for built-ins, and adding subcommands to a built-in that already allows any arguments (such as cat) is rejected.
  • deny removes programs from the allowlist, so they wait for approval.
  • Refused outright: names that are paths or contain shell characters, and programs that run other commands (sh, bash, env, xargs, sudo, timeout, watch, python, awk, sed, ssh, ...). Unknown fields, wrong types and a program listed in both allow and deny are errors too. A bad file stops the tool (exit 1) with a message naming the problem; it never falls back to the built-in rules silently.

MCP server

runbook-agent serve ./runbooks            # dry-run: run_step reports what it would do
runbook-agent serve ./runbooks --execute  # read-only steps run; changes need approval

The server speaks JSON-RPC 2.0 over stdio (one message per line) and offers three tools:

  • list_runbooks: runbooks in the directory with step counts.
  • get_runbook: steps, commands and classifications for one runbook.
  • run_step: run one step. A mutating step returns "status": "blocked" with the command a human should run:
This step changes state and has not been approved. Ask a human to run: runbook-agent approve /srv/runbooks/hello.md 3

After a person runs runbook-agent approve ... in the same working directory as the server (or with the same --state-dir), the next run_step call for that step executes once and the approval is consumed.

To register it with an MCP client, point the client at the command runbook-agent with arguments serve /path/to/runbooks.

Features

  • Parse Markdown runbooks into structured steps
  • Classify steps as read-only vs mutating (allowlist; unknown commands need approval)
  • Auto-run diagnostics, require approval for changes (dry-run by default)
  • Full audit log of what ran and why (JSON Lines)
  • MCP server so any agent client can use it (stdio transport, tools only)
  • User-defined allowlist rules from a JSON config file (--rules)
  • Redaction of secrets in captured output
  • Variables and parameters passed into runbook steps
  • HTTP transport for the MCP server

Limitations

  • A read-only command the built-in allowlist does not know (for example gcloud ... list) needs approval unless you add it with --rules. Rules files are JSON only (no YAML or TOML), and there is no way to set a default rules file other than passing --rules every time.
  • A rule you add is trusted as written. If you allow a subcommand that can write, or a program whose flags can run other commands, it will be auto-run.
  • "Read-only" means "does not change state", not "harmless to disclose". cat will happily print a sensitive file, and captured output (first 4000 characters per command) is written to the audit log unredacted.
  • A GET request can still trigger side effects on a badly designed endpoint. curl GETs are treated as read-only.
  • Commands are found through PATH. If PATH contains a hostile df, it will be run.
  • Because auto-run commands do not go through a shell, diagnostics that use variables, globs or 2>&1 are classified unknown and wait for approval even when they are harmless.
  • Following commands (tail -f, kubectl logs -f, ping without -c) are stopped by the per-command timeout rather than detected up front.
  • The approval store is a file. It stops an agent that only talks to the MCP server; it is not a security boundary against a process that already has shell access to the same machine.
  • run executes steps strictly in order with no branching; "if X then do Y" prose is not interpreted.
  • The MCP server implements initialize, ping, tools/list and tools/call only, and has been tested with scripted JSON-RPC messages rather than against a specific client.

Development

git clone https://github.com/narayana006/runbook-agent
cd runbook-agent
pip install -e ".[test]"
pytest

The test suite only ever executes harmless commands (echo, tr, sleep); everything else goes through fake runners.

Contributing

Issues and pull requests are welcome. The most useful contributions are classifier cases: a command that was auto-run and should not have been (please report these first), or a common read-only diagnostic that is needlessly gated. Include the exact command line.

Author

Built and maintained by Narayana Vemburaj.

License

MIT

About

Turn Markdown runbooks into agent-executable steps: read-only diagnostics run automatically, changes require human approval. Ships as an MCP server.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages