OPS-1

Outrigger Protocol

Deterministic Git diff scope gates, OPS-1 manifest verification, and credential-leak checks for autonomous coding workflows. Zero external packages. Python 3.12 standard library only.

OPS-1 overview

An OPS-1 task manifest names the files and tools an agent may touch. After the agent runs, outrigger check and outrigger verify compare the Git diff and the Hub Report to that manifest. Out-of-scope edits fail the run. Unsafe paths and credential leaks fail the run. The gate is fail-closed.

Exit code 0 is PASS. Exit code 1 is FAIL for structural errors, secret leaks, report binding mismatches, or unsafe .. paths. Exit code 2 is BLOCKED for out-of-scope file modifications. Both non-zero codes fail CI.

Outrigger is an application-level policy boundary. It does not replace OS sandboxes, containers, or kernel isolation.

Shipped vs. planned boundary

v0.2.0 is the shipped CLI and GitHub Action. Harbormaster mcp_server.py is the live stdio containment reference. v0.3.0 extracts that proxy into Outrigger.

ComponentStatusScope
v0.2.0ShippedZero-dependency Python 3.12 stdlib CLI (outrigger check, outrigger verify, 40/40 tests) and composite GitHub Action. Fail-closed Git diff and OPS-1 manifest scope gates. Application-level policy boundary only. Not an OS or kernel sandbox.
Harbormaster mcp_server.pyLive reference runtimeLine-delimited JSON-RPC 2.0 stdio path containment via ensure_within_scope. Rejects path traversal with JSON-RPC error -32602. 719 tests passing.
v0.3.0Planned extractionStandalone extraction of Harbormaster MCP stdio security proxy into Outrigger Protocol. Initial module staged on main as src/outrigger_protocol/proxy.py.

OWASP Top 10 for LLMs

Outrigger v0.2.0 and the Harbormaster ensure_within_scope gate address three categories in the OWASP Top 10 for LLM Applications.

  • LLM06: Excessive Agency. outrigger check and outrigger verify compare git diff --name-only paths to the manifest writable_scope and forbidden_patterns. Out-of-scope edits exit 2 (BLOCKED). Harbormaster rejects out-of-scope tools/call paths with -32602 before the tool runs.
  • LLM02: Sensitive Information Disclosure. find_leaks() scans reports and manifests for known token formats and PEM private-key headers, exiting 1 (FAIL) on a match. outrigger auth-gate confirms secret presence without reading secret values. Harbormaster rejects .. traversal and paths outside allowed_roots before any file adapter runs.
  • LLM05: Improper Output Handling. Manifest path normalization rejects absolute paths and .. segments. outrigger verify checks OPS-1 report structure, task_id and branch binding, and HEAD_SHA via git cat-file -e. Malformed MCP path inputs return -32602 instead of executing.

NIST AI RMF

Alignment to NIST AI Risk Management Framework 1.0 functions for declared authority, bounded tasks, measurable gates, and fail-closed response.

FunctionFocusImplementation
GOVERNGV 1.2, GV 2.1Task permissions live in version-controlled JSON manifests. Agents do not self-authorize scope changes.
MAPMP 1.1, MP 3.4Each task declares allowed directory prefixes, target branch, and base commit before work starts.
MEASUREMS 2.5, MS 2.6outrigger check --json, outrigger verify --json, and outrigger ledger --json emit deterministic PASS, FAIL, or BLOCKED payloads.
MANAGEMG 2.2, MG 3.1Out-of-scope diffs fail CI with non-zero exit codes. Out-of-scope MCP stdio tool calls are dropped before execution with -32602.

30-second outrigger verify trace

This self-contained check uses Python 3.12 standard library only. An unsafe parent-traversal scope entry fails closed with exit code 1.

python -c '
import json, pathlib, tempfile
from cli import outrigger

with tempfile.TemporaryDirectory() as tmp:
    p = pathlib.Path(tmp)
    manifest = {
        "protocol": "OPS-1", "task_id": "TASK-001", "objective": "Scope test",
        "writable_scope": ["../etc/passwd"], "branch": "main",
        "acceptance_criteria": [], "validation_commands": ["git diff --name-only HEAD~1 HEAD"],
        "forbidden_actions": [], "handoff_path": ".outrigger/report.md"
    }
    (p / "manifest.json").write_text(json.dumps(manifest), encoding="utf-8")
    (p / "report.md").write_text(pathlib.Path(".outrigger/report.md").read_text(encoding="utf-8"), encoding="utf-8")
    code = outrigger.main(["verify", str(p / "report.md"), "--manifest", str(p / "manifest.json"), "--json"])
    raise SystemExit(code)
'

Output:

{
  "status": "FAIL",
  "violations": [
    "unsafe repository-relative path: ../etc/passwd"
  ],
  "exit_code": 1
}

When a valid manifest restricts writable_scope to ["src/"] and the Git diff includes an out-of-scope edit such as SPEC.md, verify and check reject with exit code 2:

{
  "status": "BLOCKED",
  "violations": [
    "outside writable scope: SPEC.md"
  ],
  "exit_code": 2
}

Source and threat model