safe-runbook-mcp: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents working in this repository.

Goal

Keep safe-runbook-mcp small, auditable, and secure by default. An agent may select a reviewed runbook; it must never gain a general-purpose shell through this project.

Branch workflow

• Never push directly to main or develop.
• Branch from develop using feature/<name>, fix/<name>, or docs/<name>.
• Open a pull request into develop; promote tested releases from develop to main.
• Keep commits focused and use Conventional Commit messages.

Non-negotiable safety rules

• Execution stays disabled by default.
• Never add an arbitrary command, shell script, eval, exec, or shell: true path.
• Every executable must pass the exact allowlist.
• Variables must be schema-validated and occupy a complete argv item.
• Resolve and confine every working directory with real paths; test symlink escapes.
• Mutating and destructive plans require approval bound to the exact plan hash.
• Approval tokens are created out-of-band, expire quickly, and never appear in logs.
• Preserve timeout, output-size limits, environment minimization, and secret redaction.
• stdout belongs to MCP protocol traffic; write server diagnostics to stderr.

Runbook review

For each new runbook, verify its risk level, executable, fixed arguments, variable patterns, working directory, timeout, failure behavior, and least-privilege requirements. Prefer several narrow runbooks over one flexible runbook.

Required checks

Run before opening a pull request:

npm run check
npm run typecheck
npm test
npm run build
docker build -t safe-runbook-mcp .

Add regression tests for security-boundary changes. Do not weaken a failing safety test to make CI pass.