Assay
About
The firewall for MCP tool calls. Block unsafe calls, audit every decision, replay anything. Deterministic policy enforcement with replayable evidence bundles.
Details
- Author
- rul1an
- Categories
- Developer Tools, Security
Jump to
Setup
Install Assay in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/rul1an/assay
Follow the installation instructions in the repository README, then restart your MCP client.
The open, recomputable evidence profile for privileged MCP tool actions.
Assay records what a privileged tool call decided, what was observed, and what stays unproven, so a reviewer can replay the claim offline instead of trusting the agent's account of itself. Enforcement is deterministic and fail-closed, and the enforcing proxy is the reference producer rather than the contract itself. Kernel-level (eBPF/LSM) observation on Linux is an optional stronger vantage. CI-native, no backend, bounded by design.
Quickstart·How it works·See it work·MCP example·OWASP MCP Top 10·Discussions
Agents got real tool access through MCP — and tool poisoning, rug pulls, and confused-deputy OAuth came with it. Most tools scan a server or filter a prompt. Assay sits at the tool-call boundary and does three things, in order.
One golden path:therelease-pinned agent journeyrecords the nine driven CLI/MCP steps and their exit/stdout contracts. Its protected-action fixture lives inexamples/privileged-action-gate/.
- Enforce.A deterministic, fail-closed gate decides everytools/callbefore it runs, with the precise reason for each allow or deny. On Linux it adds real kernel enforcement — an eBPF/LSM IPv4/TCP connect-egress block and a Landlock TCP-connect port allowlist, both opt-in and fail-closed. A policy it cannot express exactly is refused, never half-applied.
- Prove.Each decision and observed effect becomes an offline-verifiable, tamper-evident evidence bundle: the verdict, the pre-call establish journey, and declared-vs-observed conformance — all reviewable in CI, with no hosted backend.
- Stay honest.Every claim carries its basis (verified,self_reported,inferred,absent), and a gate refuses to let a claim exceed what was observed. A tool returning "success" is the provider's assertion, never proof. Assay ships no single safety score and never claims more than it can prove.
cargo install assay-cli --version 5.4.0 --locked mkdir -p /tmp/assay-demo && echo "safe content" > /tmp/assay-demo/safe.txt assay mcp wrap --policy examples/mcp-quickstart/policy.yaml \ -- npx @modelcontextprotocol/server-filesystem /tmp/assay-demo
✅ ALLOW read_file path=/tmp/assay-demo/safe.txt reason=policy_allow ❌ DENY read_file path=/tmp/outside-demo.txt reason=path_constraint_violation ❌ DENY exec cmd=ls reason=tool_denied
Project manifests are shipped for Claude Code and Cursor; Codex uses the equivalent TOML entry documented in theeditor MCP recipe.assay mcp config-pathsupports Claude and Cursor only. Python SDK:pip install assay-it. CI:GitHub Action. No hosted backend and no API keys for core flows. New to the threat model? TheOWASP MCP Top 10 mappinglays out, per risk, what Assay covers and what it deliberately does not.
Agent ──► Assay ──► MCP Server ├─ ✅ ALLOW / ❌ DENY (policy, with reason) ├─► 📋 Evidence bundle (offline-verifiable) └─► 📊 Trust Basis → Trust Card → SARIF / CI
Current release:v5.4.0.CHANGELOG.mdand release notes remain the authority for released behavior; merged changes after the tag areUnreleased, and crates.io publication is separate from merge state.
Yesif you already have eval output, runtime decisions, inventory artifacts, or MCP tool-call tests, and you want a small reviewable CI artifact instead of a dashboard — bounded auditability, not a scalar trust badge.
Not yetif you need Assay to judge model correctness for you, want a hosted dashboard as the product, or want a compliance claim rather than a bounded evidence boundary. Assay is not a trust-score engine, a generic eval dashboard, or a hosted observability product — seewhat it is and is not.
An agent tries a privileged action —github.add_deploy_key— through the enforcing proxy, decided per callbefore it forwards, offline against a local mock (no real credentials):
cd examples/privileged-action-gate && ./run.sh
A deny is fail-closed caution, not a verdict on intent; an allow is the decision to forward, never proof the action happened. Declared-vs-observed conformance is recordedbesidethe verdict, never as a gate. Full walkthrough:privileged-action-gate.
The workflow stays small: import or record a bounded outcome, bundle and verify it, compiletrust-basis.json, gate the Trust Basis diff. Assay doesn't make the upstream tool the source of truth; it makes the evidence boundary inspectable. For privileged tool actions, the MCP proxy records eachtools/callas a structuredtool-decision surface— keeping the asserted-versus-verified line honest.
version: "2.0" name: "my-policy" tools: allow: ["read_file", "list_dir"] deny: ["exec", "shell", "write_file"] schemas: read_file: type: object properties: path: { type: string, pattern: "^/app/.*" } required: ["path"]
assay init --from-trace trace.jsonlgenerates the runtime-observation policy used by the trace-generation flow (files,network, andprocesses); it is not an MCP authorization policy. Migrate a legacy MCPconstraints:policy withassay policy migrate. SeePolicy Files.
- MCP Quickstart·Editor MCP recipe— policy-enforcing MCP in Cursor / Claude Code / Codex
- MCP 2025/2026 protocol-era parity— pinnedresultTypeand interim-result compatibility corpus
- Coding-agent governance·OpenTelemetry & Langfuse— observed runs → evidence
- Evidence Receipts in Action— Promptfoo / OpenFeature / CycloneDX receipt families
- CI Guide·Evidence Store(S3 / B2 / MinIO)
- OWASP MCP Top 10 mapping·Security experiments
- Positioning:ADR-033·RFC-005
Trust claims use explicit epistemology, not a single safety score:verified(direct evidence or offline verification),self_reported(emitted without independent corroboration),inferred(bounded, documented rules),absent(no trustworthy evidence). Assay ships no aggregate trust score orsafe/unsafebadge as the main output — see[ADR-033.
…
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
