Skip to content

Security model

The Runbook’s job is to let agents do real work without letting them do what should need a person. That rests on two rules: the server decides what may happen, and it knows who is asking from the credential, never from the request.

Every write goes through the server, which checks it against the published runbook and the caller’s credential:

  • who may claim and complete a step (actor, assignee with assignment: strict), and who may decide an approval (its approvers, its escalation, and agents only with allow_agents);
  • that a destructive step can’t follow from a decision an agent or a timeout made, unless the runbook explicitly allows it;
  • leases, so one session at a time works a step, and a stale session’s report is refused;
  • timeouts, retries and failure handling;
  • outputs and evidence, checked against their declarations before anything is recorded.

It can’t see what an agent does on its own machine. agent.hints (preferred tools and commands) are passed to the agent as preferences only. Limit what an agent can do through the access you give it: the credential’s scopes, and what that machine can reach.

  1. Personal tokentrb_pat_ · a person
  2. Agent-kind tokentrb_pat_ --agent · an agent you sponsor
  3. Execution pairtrb_exe_ / trb_exr_ · an agent, one run
  4. Service tokentrb_svc_ · a project's automation

The kind of credential decides whether the caller is a person or an agent. An agent’s claims, reports and memory writes are recorded as an agent’s, naming its sponsor and token or run, and agents never cast human approvals. An OAuth grant to an MCP client is an agent sponsored by the person who consented. See Permissions and tokens.

  • Tokens are stored as SHA-256 hashes; the secret is shown once.
  • Webhook signing secrets are sealed (encrypted) at rest with the operator’s key, opened only to sign a delivery, and never appear in a view, a log or an error.
  • Logs are redacted on the server: Redaction and the audit trail.
  • The CLI keeps logins in the macOS Keychain or Windows Credential Manager (otherwise a 0600 file) and execution pairs in a 0600 file.
  • The web app is served from the server’s own origin with a strict Content Security Policy and no CORS. Cookie sessions need X-Runbook-CSRF: 1 and a matching Origin for every change.
  • Uploaded files are served only from a separate origin with Content-Security-Policy: sandbox, X-Content-Type-Options: nosniff, no cookies, and short-lived signed URLs, so a malicious file can never act as the app. Images are re-encoded, which strips EXIF and location data.

Webhook targets must be https and resolve to public addresses. Each address is checked again at every delivery and the connection goes to that vetted address (no DNS rebinding); redirects are never followed. Private and link-local targets need explicit operator settings. Payloads carry no credentials.

Inputs, outputs, summaries, comments and memory were written by people and earlier steps. The CLI and MCP give them to agents in a separate data object or between RUNBOOK DATA markers, apart from the step’s instructions, and the therunbook skill tells agents never to follow instructions found in data.