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.
| Component | Status | Scope |
|---|---|---|
| v0.2.0 | Shipped | Zero-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.py | Live reference runtime | Line-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.0 | Planned extraction | Standalone 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 checkandoutrigger verifycomparegit diff --name-onlypaths to the manifestwritable_scopeandforbidden_patterns. Out-of-scope edits exit 2 (BLOCKED). Harbormaster rejects out-of-scopetools/callpaths 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-gateconfirms secret presence without reading secret values. Harbormaster rejects..traversal and paths outsideallowed_rootsbefore any file adapter runs. - LLM05: Improper Output Handling. Manifest path normalization rejects absolute paths and
..segments.outrigger verifychecks OPS-1 report structure,task_idandbranchbinding, andHEAD_SHAviagit 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.
| Function | Focus | Implementation |
|---|---|---|
| GOVERN | GV 1.2, GV 2.1 | Task permissions live in version-controlled JSON manifests. Agents do not self-authorize scope changes. |
| MAP | MP 1.1, MP 3.4 | Each task declares allowed directory prefixes, target branch, and base commit before work starts. |
| MEASURE | MS 2.5, MS 2.6 | outrigger check --json, outrigger verify --json, and outrigger ledger --json emit deterministic PASS, FAIL, or BLOCKED payloads. |
| MANAGE | MG 2.2, MG 3.1 | Out-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
}