occasio

Requirements

• Node.js ≥ 18
• Claude Code (npm install -g @anthropic-ai/claude-code) — or any agent that respects ANTHROPIC_BASE_URL
• Python 3 (optional) — required for the independent verifier and LAO context trimming
• sigstore-python (optional) — adds the cryptographic Sigstore step to the Python verifier

---

Quickstart

Requires Node.js ≥ 18. Works on Windows, macOS, Linux.

npm install -g @occasiolabs/occasio   # Install
occasio doctor                          # Verify setup (Node, claude CLI, port, profile)
occasio policy init                     # Write ~/.occasio/policy.yml (dev-default)
occasio register                        # Add 'claude' shell alias (one-time)
claude "read package.json and tell me the version"

After the alias is registered, every claude invocation routes through Occasio transparently. Audit-chain rows accumulate at ~/.occasio/pipeline-events.jsonl.

Inspect the run:

occasio status                  # Session totals
occasio replay --detail         # Run-level audit
occasio audit verify            # Re-walk the hash chain end-to-end
occasio anomalies               # Run EDR detectors over the last 15 minutes
occasio attest --run-id <uuid>  # Build a behavioral attestation for one session
occasio explain <event-id>      # Why was this blocked? — the matched policy rule + how to unblock

---

Demos

• EDR defense-in-depth — real Claude Code attacking a denied path under your policy, all blocks held, EDR fires HIGH ×100–×1000 over baseline. Reproducible in <2 minutes.
• Reference Pipeline — PR with AI-agent → GitHub Action signs attestation via Sigstore keyless → Check Run on the PR → independent verification offline.
• Cross-protocol governance — the same deny_paths rule producing identical BLOCK rows under Claude Code's HTTP proxy and the MCP server.

---

Reference

• spec/agent-attestation/v1/README.md — predicate type specification
• schemas/agent-attestation-v1.json — authoritative JSON Schema
• docs/AUDIT.md — audit-chain row schema and canonical-serialisation rules
• docs/compliance-mapping.md — SOC 2 Common-Criteria mapping
• docs/python-verifier.md — independent Python verifier
• docs/edr-demo.md — defense-in-depth walkthrough
• docs/reference-pipeline.md — end-to-end CI pipeline
• integrations/attest-action/ — GitHub Action that signs + posts a Check Run
• integrations/attest-view/ — static browser viewer for attestation files

---

Evidence workflow

Produce one file an auditor or CI receives and checks in a single command:

occasio attest --run-id <uuid> --sign          # behavioral attestation (Sigstore optional)
occasio bundle --run <uuid> --out run.occasio.json   # pack attestation + chain slice + policy + manifest
occasio verify run.occasio.json                 # 6 offline checks; exit ≠ 0 on tamper

verify checks the schema, the manifest hashes, the chain slice integrity, the policy binding, the git-state vs chain cross-check, and the Sigstore signature when present — all against data embedded in the file (never the producer's machine). The run is bound to the concrete code it touched via git_state rows (HEAD + diff hash + changed files). Signing is optional; an unsigned bundle still verifies everything else. Bundles embed absolute producer paths — an internal-audit artifact; review before sharing publicly. → docs/VERIFY.md

Policy workflow

~/.occasio/policy.yml governs the Occasio-controlled path: secret handling, deny_paths/allow_paths, custom deny_patterns, per-round limits, and tool routing. Approve it and pin against drift:

occasio policy init                              # starter policy.yml
occasio policy validate                          # lint before you rely on it
occasio policy lock --sign --out policy.lock.json   # record the approved policy
occasio policy diff --since policy.lock.json     # CI gate: exit 1 if the policy drifted

→ docs/POLICY.md

Dashboard vs. Eyes

Both run as local browser UIs but answer different questions:

Both live on 127.0.0.1 only. No CORS, no auth, no external network.

---