🛡️ Cinch

Contain your AI agents before they reach production.

MCP server + cross-harness skills for building and operating AI agents safely.

The model proposes; the architecture authorizes and enforces.

Grounded in NIST AI RMF · CISA Secure AI Development · OWASP LLM & Agentic · MITRE ATLAS · CUSTODY · LASM · Google SAIF · DORA 2025

AI agents can read data, invoke tools, execute code, call APIs, and initiate business processes. When they go wrong — through prompt injection, excessive autonomy, credential theft, or model error — the consequences are only as severe as the environment allows. Cinch gives you the enforceable controls, protocols, and runtime queries to keep that environment contained.

✨ What's inside

Related MCP server: AWS SRA Verify MCP Server

🖥️ The assessment console

▶ Try the hosted console — no install required.

One page, two modes: a landing page for the project, and a live containment assessment dashboard. It is not a static mockup — it loads a real assessment result pack and renders the analysis: letter grade, insights, ranked recommendations, and a phased action plan. Mark a control Enforced / Gap / N-A and every one of those re-derives instantly.

Where the results come from

Two ways to produce them, one engine grading both:

1. Probe a running agent — cinch collect observes the real deployment and emits an evidence bundle; cinch verify grades it. This is the primary path.

2. Review by hand — cinch assess grades a state file a reviewer filled in (or the console session they clicked through).

The grade itself is computed once and shown everywhere: src/cinch/assess.py for the CLI and CI, the dashboard for the browser, both reading their rules — severity weights, grade bands, critical-gap and completeness caps, remediation phases — from docs-site/data/rubric.json. Change a rule there and both follow.

# review by hand
cinch assess --state examples/assessment-state.json            # grade + insights + action plan
cinch assess --state examples/assessment-state.json --out pack.json
cinch console --assessment pack.json                            # open the dashboard on it
cinch assess --state pack.json --fail-on critical               # gate a release (exit 2)

A state file is just what a reviewer decided (see examples/assessment-state.json):

{
  "deployment": "checkout-agent-prod",
  "status":   { "AC-001": "pass", "AC-006": "fail", "AC-014": "na" },
  "evidence": { "AC-006": "retrieval output concatenated into the system turn" }
}

🔎 Assess a running agent

Nobody wants to hand-answer 117 controls. cinch collect observes the deployment and answers what it can prove, in the agent's own environment.

# 1. probe the agent — out of band, as an operator/sidecar/CI identity
cinch collect --host --pid $AGENT_PID \
              --project /srv/checkout-agent \
              --deployment checkout-agent-prod \
              --sign-cmd 'cosign sign-blob -' \
              --out evidence.json

# 2. grade the evidence
cinch verify --evidence evidence.json --out pack.json --fail-on critical

# 3. look at it
cinch console --assessment pack.json

What each probe family observes

Host findings are also mapped onto the containment controls that assert the same thing (AE-005 egress → AC-019 exfiltration), labelled derived: so the chain stays visible.

Probes also abstain when the target is the wrong kind of thing: supply-chain and documentation controls (SBOM, dependency scanning, provenance, threat model) report unknown unless the directory is actually a build tree — a build manifest, a CI workflow, or a repository. Reporting "no SBOM" about a config directory would be confidently wrong.

Three statuses, and why unknown matters

pass demonstrably enforced · fail demonstrably not · unknown the probe could not tell.

unknown is never a pass — and never a fail either. A probe on macOS with no /proc, without CAP_NET_ADMIN, or with no manifest to read says so and leaves the control unreviewed — it costs completeness instead of quietly earning credit. Keyword hits in config are reported as leads to confirm, not as proof a limit is enforced at runtime. Every observation keeps the raw evidence it was derived from, so you can check the probe's reasoning instead of trusting it. Secret names are recorded; secret values never are.

Self-audit is detected, not assumed away

protocols/evidence-collect.md is blunt about this: an agent auditing its own host is both auditor and audited, and a compromised or simply mistaken agent can report every control as enforced.

So collection records who collected what, where and when — and when the collector is the audited party, the bundle is stamped provenance.self_attested: true. Three ways that is detected: the inspected PID is the collector's own; the inspected PID is an ancestor of the collector (the agent spawned it, so it inherits the agent's identity and authority); or the request arrived over MCP, where the requester is an agent by definition. That becomes a critical finding in the assessment, is shown as a red self-attested banner in the console, and is never counted as assurance. Independent evidence means cinch collect run out of band under its own identity, signed with --sign-cmd using a key the agent cannot reach.

Behavioural probing sends adversarial input to a live system, so it refuses to run without --authorized naming the target.

As MCP tools

An auditing agent can drive the same flow:

Bundles collected through MCP are marked self-attested by construction — the requester is an agent. Use them to find problems fast; use an out-of-band signed run when the grade has to mean something.

Three ways to get results into the dashboard:

Exports round-trip: an exported pack feeds straight back into cinch assess --state or the Load assessment button, so re-assessments diff cleanly.

How the grade works. The score is severity-weighted (critical ×3, high ×2, medium/low ×1) over the controls you actually answered. Grade bands run A–F, and two kinds of cap can only ever lower the result — the pack always says which cap fired and why:

That last one exists because of a real failure: probing a live Claude Code harness resolved 3 of 117 controls, all passing, and the first version graded it A (Contained). A score computed over three controls says nothing about the other 114. Coverage is part of the verdict, not a footnote.

Serve it yourself

The console reads its catalog with fetch('data/full.json'), so it must be served over HTTP — opening the file directly with file:// makes that fetch fail and falls back to a small offline subset. cinch console does it for you:

pip install cinch-ai-security
cinch console                  # serves on http://127.0.0.1:8787 and opens your browser

cinch console --port 9000      # pick another port
cinch console --no-browser     # headless / remote-friendly
cinch console --host 0.0.0.0   # expose on your LAN (read-only, but consider who can reach it)

The server is read-only, GET/HEAD only, bound to 127.0.0.1 by default, and rooted at the console directory. Assessment state lives in the browser only — nothing is uploaded anywhere.

From a source checkout, the same page is served straight from docs-site/:

git clone https://github.com/nirhalfon/cinch-ai-security.git
cd cinch-ai-security && pip install -e .
python scripts/build_docs_json.py   # regenerate the catalog bundle after editing any YAML
cinch console

Turn a session into evidence

1. Assess the controls that apply to your deployment (Control library → expand → Enforced / Gap / N-A, plus an evidence note).

2. Read Insights & plan — the grade, what is actually wrong, and what to do in what order.

3. Export evidence → Download all — three artifacts:

   • JSON — the full result pack: summary + grade, coverage, insights, ranked recommendations, action plan, and every control with status and evidence. Commit it, diff the next run, gate CI with cinch assess --fail-on critical.

   • CSV — the gap register, one row per control, with remediation phase and rank, for tickets and trackers.

   • PDF — printable report: grade and why it was capped, insights, action plan, recommendations, CUSTODY coverage, open gaps, NIST AI RMF crosswalk.

🚀 Quick start for AI agents

You are an AI agent reading this repo. This section is for you. Three commands and one config block get you operational.

1. Install

pip install cinch-ai-security
# or, from source:
git clone https://github.com/nirhalfon/cinch-ai-security.git
cd cinch-ai-security && pip install -e .

2. Wire it into your MCP client

Add this to your MCP config (Claude Desktop, Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "cinch": {
      "command": "cinch",
      "args": ["serve"]
    }
  }
}

3. Query the controls you need

Your tools (all return JSON):

Checklist ID prefixes: AC agent-containment · AE agent-environment · HE harness-engineering · RT red-team · SC supply-chain · SH system-hardening.

30-second smoke test

cinch serve &            # start the MCP server on stdio
# then call checklist_list from your MCP client, or:
python -c "from cinch.loader import list_checklists; [print(c['name'], c['item_count']) for c in list_checklists()]"

CLI reference

Use as a skill (Hermes / Claude / OpenClaw / NanoClaw)

# Hermes skill
cp -r skills/ai-harness-review ~/.hermes/skills/

# Claude Code — drop into your project root; it auto-loads
cp cross-harness/claude/CLAUDE.md /your/project/CLAUDE.md

# OpenClaw / NanoClaw — see cross-harness/openclaw/ and cross-harness/nanoclaw/

🧭 Philosophy

1. The model proposes; the architecture authorizes and enforces. Prompts are not a security boundary.

2. An AI agent can be manipulated, compromised, or wrong. Its environment must prevent a bad decision from becoming an unrestricted system action.

3. Functional correctness ≠ security. 47.5% of AI-generated code may be functionally correct, but only 8.25% is also secure (ICLR 2026 vibe-coding benchmark).

4. Capability accretion is the core risk. Agents silently gain practical authority through inherited credentials, trust relationships, tool access, and delegation chains.

5. Defense in depth maps to architecture layers. A control at one layer does not detect an attack at another (LASM principle).

📚 Project structure

cinch/
├── src/cinch/                      # MCP server (SDK 2.0)
│   ├── server.py                   # 9 tool definitions + CLI (serve / console / collect / verify / assess)
│   ├── probes/                     # observe a running agent
│   │   ├── host.py                 # AE-001..AE-011 from /proc, cgroups, netfilter, mountinfo
│   │   ├── project.py              # MCP grants, manifests, CI, pinning, secrets (HE/SC/AC)
│   │   └── behaviour.py            # injection / leakage / tool / rate probes (authorization-gated)
│   ├── collect.py                  # evidence bundle: provenance, self-audit detection, signing
│   ├── verify.py                   # bundle → graded assessment (unknown never becomes a pass)
│   ├── assess.py                   # assessment engine: score, grade, insights, recommendations, plan
│   ├── console.py                  # localhost static server for the assessment console
│   └── loader.py                   # YAML checklist/protocol/mapping loader (path-traversal-safe)
├── checklists/                     # 6 checklists · 117 controls
│   ├── agent-containment.yaml      # CUSTODY-based agent containment (AC)
│   ├── agent-environment.yaml      # host/container controls, out-of-band audited (AE)
│   ├── harness-engineering.yaml    # AI dev harness safeguards (HE)
│   ├── system-hardening.yaml       # OS/infra hardening for AI workloads (SH)
│   ├── red-team.yaml               # AI red team engagement checklist (RT)
│   └── supply-chain.yaml           # AI supply chain security (SC)
├── protocols/                      # 5 how-to procedures
│   ├── agent-deployment.md
│   ├── evidence-collect.md         # out-of-band signed-JSON host evidence for AE controls
│   ├── incident-response.md
│   ├── red-team-engagement.md
│   └── harness-setup.md
├── skills/                         # 3 Hermes skills
│   ├── ai-harness-review/SKILL.md
│   ├── agent-audit/SKILL.md        # + separation-of-duties / --self-audit rule
│   └── ai-red-team/SKILL.md
├── mappings/                       # 5 framework crosswalks
│   ├── nist-rmf-crosswalk.yaml
│   ├── owasp-llm-crosswalk.yaml
│   ├── atlas-crosswalk.yaml
│   ├── custody-crosswalk.yaml
│   └── lasm-crosswalk.yaml
├── cross-harness/                  # agent platform configs
│   ├── claude/CLAUDE.md
│   ├── openclaw/agent-config.yaml
│   └── nanoclaw/agent-config.yaml
├── templates/                      # 4 review/policy/ADR templates
├── docs/                           # threat-model, research-references, design-rationale
├── marketing/                      # announcement copy (kept out of docs/ — docs/ is bundled)
├── docs-site/                      # the console
│   ├── index.html                  # landing page + assessment dashboard (one file)
│   └── data/
│       ├── full.json               # generated control catalog
│       ├── rubric.json             # scoring rules — shared with src/cinch/assess.py
│       └── assessment.json         # generated result pack the console opens on
├── examples/assessment-state.json  # worked assessment state (input to `cinch assess`)
├── scripts/
│   ├── build_docs_json.py          # deterministic full.json generator (run on every source change)
│   ├── build_assessment.py         # regenerate docs-site/data/assessment.json
│   └── migrate_schema.py           # one-time Schema B → canonical Schema A migration
├── tests/                          # pytest: loader, server, console, assessment engine, probes
└── .github/
    ├── dependabot.yml              # weekly pip + github-actions updates
    └── workflows/
        ├── validate.yaml           # CI: YAML, imports, ruff, bandit, pip-audit, content gate, pytest, full.json sync
        ├── security-scan.yml       # CodeQL, semgrep, dependency-review, gitleaks, SBOM
        └── pages.yml               # deploy the console to GitHub Pages

🔬 Research grounding

🤝 Contributing

See CONTRIBUTING.md. Every checklist item, protocol step, and mapping must cite a source. After any source change, regenerate both generated files — CI verifies they are in sync:

python scripts/build_docs_json.py    # docs-site/data/full.json     (control catalog)
python scripts/build_assessment.py   # docs-site/data/assessment.json (result pack the console opens on)

🔒 Security

See SECURITY.md for vulnerability reporting. This project dogfoods its own controls — the repo itself is scanned with CodeQL, semgrep, bandit, pip-audit, and gitleaks on every push.

📄 License

CC BY 4.0 — free to share and adapt with attribution.