Assay

Policy-as-code for MCP agents: enforce what a tool call can do, prove what it did, and stay honest about what you can't.
A deterministic, fail-closed policy gate for MCP tool calls, with real kernel-level (eBPF/LSM) enforcement on Linux and offline-verifiable evidence. CI-native, no backend, bounded by design.

Quickstart · How it works · See it work · MCP example · CI guide · OWASP MCP Top 10 · Discussions

In 2026 agents got real tool access through MCP, and the attacks came with it: tool poisoning, rug pulls, confused-deputy OAuth, dozens of CVEs in the first months alone. Most tools scan a server or filter a prompt. Assay sits at the tool-call boundary and does three things, in order.

Enforce, prove, stay honest

• Enforce. A deterministic, fail-closed policy gate decides every MCP tools/call before it runs, with the precise reason for each allow or deny. On Linux it adds real kernel-level enforcement: a proven IPv4/TCP connect-egress block (eBPF/LSM) 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. Every decision and observed effect becomes an offline-verifiable, tamper-evident evidence bundle, alongside pinned per-call carriers: the verdict, the pre-call establish journey, and declared-vs-observed tool-annotation conformance. All reviewable in CI, with no hosted backend.
• Stay honest. Each claim carries its basis (verified, self_reported, inferred, or absent), and a gate refuses to let a claim exceed what was actually observed. A tool returning "success" is the provider's assertion, never proof, until evidence confirms it. Assay ships no single safety score and never claims more than it can prove.

Try it in 30 seconds

cargo install assay-cli

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

Wire it into Cursor, Claude Code, or Codex in one line with assay mcp config-path <editor>. New to the threat model? Start with the OWASP MCP Top 10 mapping, which lays out, per risk, what Assay covers and what it deliberately does not.

Use Assay if you already have machine-readable AI outcomes or agent tool-call tests and want a small reviewable artifact boundary in CI.

Start with the path that matches what you already have:

The core workflow is intentionally small: import or record a bounded outcome, bundle and verify it, compile trust-basis.json, then gate the Trust Basis diff. Assay does not make the upstream tool the source of truth; it makes the evidence boundary inspectable.

For observed runtime evidence specifically, the same boundary discipline runs end to end: a coverage descriptor declares what the capture can and cannot support, claim-class cells record each claim as claim_strength x claim_basis, and a gate refuses to let a claim exceed what was observed. See the coverage-honesty walkthrough and the claim-class semantics.

For privileged tool actions specifically, the MCP proxy records each observed tools/call as a structured tool-decision (assay.tool_decision_surface.v0): the privileged in-application actions kernel and network enforcement cannot see, such as a deploy key added or a workspace member invited. Rule-based classifiers tag the action and project a target with sensitive ids hashed and raw arguments never stored, and the shape keeps the asserted-versus-verified line honest: a tool returning success is the provider's assertion, never proof, until independently checked audit evidence confirms it. See tool-decision surface and credential-scope.

Trust Basis Gate
Status: OK
Bundles verified: 1
Regressed claims: 0

Assay is not a trust-score engine, a generic eval dashboard, or a hosted observability product. See What Assay is and is not for the boundary.

Is This For Me?

Yes, if you:

• already have eval output, runtime decisions, inventory artifacts, or MCP tool-call tests
• want a CI review artifact instead of a dashboard-only result
• need bounded auditability, not a scalar trust badge

Not yet, if you:

• need Assay to judge model correctness or policy quality for you
• want a hosted dashboard as the primary product
• want a compliance claim instead of a bounded evidence boundary

Install

cargo install assay-cli

CI: GitHub Action. Python SDK: pip install assay-it.

No hosted backend. No API keys for core flows. Deterministic: same input, same decision.

v3.21.0 runtime enforcement (Linux): assay sandbox --enforce-net enforces a TCP-connect port allowlist with Landlock, a second kernel route beside the connect4/eBPF egress path, denying any TCP connect to a non-allowlisted port. It records the outcome in a separate assay.enforcement_health.v1 artifact, and --probe-enforcement adds a per-run real-block check (a denied connect blocked with EACCES, the harness listener never reached). Enforcement is opt-in and fail-closed: a network policy it cannot express as an explicit port allowlist is refused rather than partially applied, and a requested health artifact that cannot be written is an error, never a silent absence. It is bounded by design and makes no IP/CIDR, hostname, UDP, or QUIC claim. See CHANGELOG.md for the full release notes.

What ships today

Repository truth: release notes and CHANGELOG.md remain the authority for what is actually public. main may carry release-prep commits before a tag is cut; crates.io publication is separate from repository merge state.

  Agent ──► Assay ──► MCP Server
              │
              ├─ ✅ ALLOW / ❌ DENY  (policy)
              ├─► 📋 Evidence bundle (verifiable)
              └─► 📊 Trust Basis → Trust Card → SARIF / CI

CLI: MCP runtime commands live under assay mcp. Use assay mcp --help, assay mcp wrap …, assay mcp discover, assay mcp kill, or follow the MCP Quickstart.

A boundary, not a category. “MCP firewall” describes the control plane; trust compilation describes the outcome: reviewable claims backed by evidence. See ADR-033 and RFC-005.

See It Work

An agent tries a privileged action — github.add_deploy_key — through the enforcing proxy. Assay decides per call before it forwards and writes a replayable evidence record. One command, offline, against a local mock (no real credentials, no real GitHub call):

cd examples/privileged-action-gate && ./run.sh

❌ DENY   github.add_deploy_key  reason=no_declared_allowance
❌ DENY   github.add_deploy_key  reason=credential_scope_insufficient
❌ DENY   github.add_deploy_key  reason=manifest_drifted_since_approval
✅ ALLOW  github.add_deploy_key  reason=allow
✅ ALLOW  github.add_deploy_key  reason=allow  + conformance: mismatched (declared_read_only_observed_mutating)  [separate, non-gating]

A deny is fail-closed caution, not a verdict on intent; an allow is the decision to forward, never proof the action happened. The last line is separate evidence — the tool declared itself read-only while the observed call was mutating — recorded beside the verdict, never a gate. Full walkthrough: examples/privileged-action-gate/.

A simpler first example

cargo install assay-cli

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
✅ ALLOW  list_dir   path=/tmp/assay-demo/           reason=policy_allow
❌ DENY   read_file  path=/tmp/outside-demo.txt      reason=path_constraint_violation
❌ DENY   exec       cmd=ls                          reason=tool_denied

Inspect the audit artifact:

assay evidence show demo/fixtures/bundle.tar.gz

The bundle is tamper-evident and cryptographically verifiable. Signed mandate events can include an Ed25519-backed authorization trail for high-risk actions.

Trust artifacts from a verified bundle

After a bundle verifies, compile the claim artifact:

# Machine-readable claim basis (deterministic, claim-first)
assay trust-basis generate demo/fixtures/bundle.tar.gz > trust-basis.json

trust-basis.json is the canonical output for CI and review. Claim id values are stable across runs; consumers should key by id, not row count or order. It is not a scalar trust score.

The current claim-visible receipt families are Promptfoo assertion-component results, OpenFeature boolean EvaluationDetails, and CycloneDX ML-BOM model components. See the receipt-family matrix, the three-family note, and Evidence Receipts in Action.

assay trust-card generate demo/fixtures/bundle.tar.gz --out-dir ./trust-out
# -> trust-out/trustcard.json , trust-out/trustcard.md , trust-out/trustcard.html

Add to Cursor in 30 Seconds

Assay ships a helper that finds your local Cursor MCP config path and prints a ready-to-paste entry:

assay mcp config-path cursor

It generates JSON like:

{
  "filesystem-secure": {
    "command": "assay",
    "args": [
      "mcp",
      "wrap",
      "--policy",
      "/path/to/policy.yaml",
      "--",
      "npx",
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/Users/you"
    ]
  }
}

The same wrapped command works in other MCP clients (Claude Code, Codex) — see the editor MCP recipe and MCP Quick Start.

Policy Is Simple

version: "2.0"
name: "my-policy"

tools:
  allow: ["read_file", "list_dir"]
  deny: ["exec", "shell", "write_file"]

schemas:
  read_file:
    type: object
    additionalProperties: false
    properties:
      path:
        type: string
        pattern: "^/app/.*"
        minLength: 1
    required: ["path"]

Legacy constraints: policies still work. Use assay policy migrate for the v2 JSON Schema form, or assay init --from-trace trace.jsonl to generate from observed behavior.

See Policy Files.

assay trace ingest-otel \
  --input otel-export.jsonl \
  --db .eval/eval.db \
  --out-trace traces/otel.v2.jsonl

Add to CI

# .github/workflows/assay.yml
name: Assay Gate
on: [push, pull_request]
permissions:
  contents: read
  security-events: write
jobs:
  assay:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Rul1an/assay-action@v2

PRs that violate policy get blocked; SARIF can surface in the Security tab.

Why Assay

Learn More

• Promptfoo JSONL to Evidence Receipts — smallest adoption path for existing eval artifacts
• OpenFeature EvaluationDetails to CI Review Artifact — runtime decision receipt path
• CycloneDX ML-BOM Model to Inventory Receipt — model inventory/provenance receipt path
• MCP Quickstart — filesystem server walkthrough
• Coding-agent governance — run an agent under the sandbox, get a verifiable record
• Editor MCP recipe — policy-enforcing MCP in Claude Code, Cursor, Codex
• Policy Files — YAML schema for assay mcp wrap
• OpenTelemetry & Langfuse — traces → replay and evidence
• CI Guide — GitHub Action
• Evidence Store — S3, B2, MinIO
• ADR-033: Trust compiler positioning
• RFC-005: Trust compiler MVP & Trust Card

Internal: Assay-Runner

Assay-Runner is an internal measured-run subsystem used by Assay's delegated Linux/eBPF acceptance path. It is not a standalone product. As of Phase 2D, the runner candidate is split into extraction-ready Rust crates (assay-runner-schema, assay-runner-core, assay-runner-linux) — all publish = false — plus the runner-fixtures/ package tree (Node fixture marked "private": true; Python fixture has no distribution surface). Everything stays inside this repository.

• Assay-Runner reference index — internal contracts, boundary map, slice history
• Measured-run proof-bundle walkthrough — read-only walkthrough for maintainers evaluating standalone use cases
• Phase 2D consolidation audit — current burn-in criteria; the extraction question is closed until the criteria are observed and at least one concrete external use case appears

No release commitment. No timeline. No external demand has been measured.

Research, mappings & experiments

Bounded context: numbers below support mapping and experiments, not a product “security score.”

• OWASP MCP Top 10 Mapping — how Assay relates to each risk category (coverage is not a scalar guarantee).
• Third-party survey: popular MCP servers often show weak defaults — Assay adds policy + evidence; see discussion in the mapping doc.
• Security experiments — attack vectors and harness notes (methodology matters more than headline counts).
• MCP tool evidence-binding quickstart — synthetic description→call→effect binding with bounded claims. Experiment-scoped; not a poisoning detector, and distinct from the supported MCP policy quickstart above.

Contributing

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

See CONTRIBUTING.md. Discussions: GitHub Discussions — seed topics for pinned threads live in docs/community/DISCUSSIONS.md.

License

MIT