cinch-ai-security 1.1.1

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

🛡️ 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.

117	6	9	5	5	4	3
controls	checklists	MCP tools	crosswalks	protocols	templates	skills

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

	What	Why it matters
📋	6 checklists (117 controls)	Enforceable, framework-mapped YAML — not advice, controls
🔎	Probes (host · project · behaviour)	Assess a running agent: inspect its process, its deployment, and how it behaves under attack
📡	MCP server (9 tools)	Any MCP-compatible agent queries controls at runtime — and can collect + verify evidence
🖥️	Assessment console	Grade a deployment, get insights + a phased action plan, export JSON/CSV/PDF
🧠	3 skills	Drop-in Hermes skill definitions for security reviews & red-teaming
📐	5 protocols	Step-by-step deployment, incident-response, and evidence collection
🔗	5 mappings	Crosswalks: NIST AI RMF · OWASP LLM · MITRE ATLAS · CUSTODY · LASM
📄	4 templates	Security review, risk assessment, agent policy, deployment ADR

---

🖥️ 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.

View	What you get
Overview	Grade, containment score, top insights, "do now" queue, open-gap feed, per-checklist counts
Insights & plan	Grade + why it was capped, ranked findings, one recommendation per gap (do this → verify like this), remediation phased Now / Next / Later with exit criteria
Assessment	Walk the checklist control by control, attach evidence as you go
Control library	All 117 controls across 6 checklists — searchable, filterable, assessable inline
Threat model	LASM 7×4 attack-surface grid derived live from the catalog's layer mapping
Framework coverage	NIST AI RMF, OWASP, CUSTODY, ATLAS, LASM crosswalks against your answers
Export	JSON (full result pack for CI gating and diffs), CSV (gap register with phase + rank), PDF (grade, insights, action plan, recommendations, crosswalk)

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

Family	Flag	Reads	Controls
Host	--host --pid/--unit	The kernel's view of the agent process: UID and NoNewPrivs, capability sets, AppArmor/SELinux confinement, seccomp filter, netfilter egress policy, network namespace and metadata-API reachability, log forwarding and log ownership, credential-shaped env vars, image digest + SBOM, read-only root, cgroup limits	AE-001–AE-011
Project	--project PATH	The authority the deployment grants: MCP tool grants, container/pod security context, NetworkPolicy egress, committed secret material, dependency pinning and hashes, SBOM, vulnerability scanning, provenance attestation and image signing, CI runner posture, threat model and IR docs	HE-*, SC-*, AC-003/016/018/019/023
Behaviour	--endpoint URL --authorized	How the running agent responds to adversarial input: direct injection, injection smuggled through retrieved content, system-prompt extraction, tool enumeration, rate-limit presence	RT-001/002/005/008/009, AC-005/006/017

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:

Tool	Use it to
evidence_collect	Probe a deployment (host, project_path, endpoint + authorized) → evidence bundle
evidence_verify	Grade a bundle → score, grade, insights, recommendations, action plan

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:

Route	How
Published pack	data/assessment.json next to the page — the hosted console opens on one, regenerated by scripts/build_assessment.py
Served pack	cinch console --assessment pack.json serves any pack from anywhere on disk
Loaded by hand	Load assessment in the console header — accepts an exported pack or a plain state file; ?assessment=<url> also works

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:

Cap	Effect
1 unenforced critical control	grade capped at D
3 or more critical controls	grade capped at F
under 60% completeness	grade capped at C — a high score describes a sample, not the deployment
under 25% completeness	grade I · Insufficient evidence — no letter is claimed at all

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):

Tool	Use it to
evidence_collect	Probe a running deployment (host / project / endpoint) and get an evidence bundle
evidence_verify	Grade an evidence bundle → score, grade, insights, recommendations, action plan
checklist_run	Run a named checklist against a description of your deployment
checklist_list	List the 6 checklists and their item counts
checklist_get	Get a specific control by ID (AC-001, AE-005, …)
protocol_get	Get a step-by-step protocol by name (agent-deployment, evidence-collect, …)
mapping_lookup	Look up controls mapped to a framework (nist-rmf, owasp-llm, atlas, custody, lasm)
threat_search	Find every control that mitigates a given threat — scans threat + control + verification + sources
checklist_diff	Compare two checklists to surface coverage gaps and duplicated controls

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

Command	What it does
cinch serve	Run the MCP server over stdio (the default with no subcommand)
cinch console	Serve the assessment console on localhost (--port, --host, --no-browser, --assessment)
cinch collect	Probe a running agent → evidence bundle (--host, --pid, --unit, --project, --endpoint, --authorized, --sign-cmd, --out)
cinch verify	Grade an evidence bundle (--evidence, --out, --fail-on critical|high|any-gap)
cinch assess	Grade a hand-reviewed state file (--state, --out, --deployment, --fail-on)

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

Source	Coverage
NIST AI RMF 1.0	Risk governance (GOVERN, MAP, MEASURE, MANAGE)
NIST AI 600-1 GenAI Profile	Generative AI-specific risks and controls
CISA Secure AI System Development	Secure AI lifecycle controls
OWASP Top 10 for LLMs	LLM application security risks
OWASP Agentic AI	Agent threat modeling and controls
MITRE ATLAS	Adversarial threat landscape for AI
CUSTODY Framework	Autonomous agent containment
LASM	Layered Attack Surface Model
Google SAIF	Secure AI Framework
CSA AICM	AI Controls Matrix
ETSI SAI	AI cybersecurity standardization
AI Harness Scorecard	Engineering safeguards for AI-assisted dev
DORA 2025	CI/CD practices, stability metrics
SlopCodeBench	Subtle correctness in AI-generated code

🤝 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.