
agent-security-contract
io.github.justrunme/agent-security-contract
Fail-closed security contract for AI agents and MCP tool calls with pre-execution enforcement.
Documentation
agent-security-contract
Fail-closed security contract for AI agents and MCP tool calls.
ASC is a platform gate: given an approved policy and a tool-call trace, it emits a CI-grade evidence envelope with verdict ALLOW | BLOCK | REQUIRE_APPROVAL. It is backed by an executable abuse-case corpus. Numbers in docs/EVIDENCE.md are generated from results/results.json — never hand-typed.
Claims are scoped: metrics and pass/fail statements apply on this corpus of N scenarios only. They do not imply general agent safety.
Maintainer site: https://justrunme.com
Why
Agent and MCP stacks expand the attack surface beyond prompt text: tool misuse, poisoned tool descriptions, argument injection, and unapproved high-impact actions. ASC turns an explicit capability contract into a repeatable pre-execution CI / admission check.
Aligned with (complementary, not a fork):
- OWASP Agent Control Standard (ACS) (published 2026-09-01) — middleware hooks and runtime Guardian dispositions; ASC maps to Instrument
toolCallRequestwithALLOW/DENY/ASK - OWASP Agentic AI / Agentic Applications Top 10 — risk taxonomy for scenario mapping
- OWASP MCP security cheat sheets — MCP hardening guidance
- OWASP Agent Security Regression Harness — regression-oriented agent security testing
Positioning (honest)
ASC’s differentiator is pre-execution ENFORCEMENT, not detection: the gate prevents the tool call (or requires approval) and proves the decision in CI via an evidence envelope.
| Project | Primary job | When it runs | Relation to ASC |
|---|---|---|---|
| ASC (this repo) | Fail-closed policy gate + evidence envelope | Before tool execution / in CI admission | Enforcement oracle |
| Promptfoo (MCP red teaming) | Attack generation & detection findings in CI | Eval / red-team jobs | Complementary detection; does not replace an admission deny |
| OWASP Agent Security Regression Harness | Regression suite for agent security behaviors | CI regression | Complementary testing; ASC can act as an enforcement profile |
| LiteLLM / guardrails | Request/response filtering & provider controls | Proxy / runtime path | Complementary runtime filters; ASC focuses on tool-capability contracts + digest pinning |
Quickstart
Requires Python 3.11+.
python -m pip install -e ".[dev]"
# Evaluate one trace — prints a full evidence envelope with --json
python -m asc check \
--policy policy/demo-agent.policy.yaml \
--trace corpus/scenarios/benign_read_workspace_file.json \
--json
# Verify an envelope (rejects invalid/tampered envelopes)
python -m asc check \
--policy policy/demo-agent.policy.yaml \
--trace corpus/scenarios/benign_read_workspace_file.json \
--json --envelope-out /tmp/env.json
python -m asc verify --envelope /tmp/env.json --policy policy/demo-agent.policy.yaml
# Run the full corpus and refresh evidence
python -m asc corpus \
--policy policy/demo-agent.policy.yaml \
--corpus corpus/scenarios \
--results results/results.json \
--summary results/summary.md \
--evidence docs/EVIDENCE.md
Exit codes (asc check)
| Verdict | Exit code | ACS disposition |
|---|---|---|
ALLOW | 0 | ALLOW |
BLOCK | 1 | DENY |
REQUIRE_APPROVAL | 2 | ASK |
Reusable GitHub Action
- uses: justrunme/agent-security-contract@v0.2.0
with:
policy: policy/demo-agent.policy.yaml
corpus: corpus/scenarios
results: results/results.json
summary: results/summary.md
evidence: docs/EVIDENCE.md
Runtime integration
Call the evaluator before tool execution (library or HTTP sidecar). See docs/INTEGRATION.md. On sidecar/client timeout, fail closed (BLOCK); asc.client.evaluate_remote() does this for you.
python -m asc.sidecar --policy policy/demo-agent.policy.yaml --port 8788
MCP server
ASC exposes its policy engine as a Model Context Protocol server. MCP clients (Claude Desktop, Cursor, etc.) can call ASC tools to enforce security contracts before executing tool calls.
Install
pip install agent-security-contract
Or from source:
python -m pip install -e ".[dev]"
Configure for Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"agent-security-contract": {
"command": "asc-mcp"
}
}
}
Configure for Cursor
Add to Cursor MCP settings (Settings → Features → MCP Servers):
{
"mcpServers": {
"agent-security-contract": {
"command": "asc-mcp"
}
}
}
Run standalone (stdio)
asc-mcp
Run as streamable HTTP server
asc-mcp --transport streamable-http --host 127.0.0.1 --port 8765
Available tools
- check_tool_call: Check a proposed tool call against a policy contract. Returns PASS/BLOCK/REQUIRE_APPROVAL verdict with reasons. Fail-closed: any error yields BLOCK.
- verify_corpus: Run the full abuse-case corpus and return metrics (critical false-ALLOW, benign false-BLOCK rate, pass/fail).
- verify_scenario: Verify a single corpus scenario file against a policy.
- list_policy_tools: List loaded policies, capability catalog, digest, and per-agent tool allowlists.
All tools are read-only (they inspect policy and traces but do not modify state).
External auth on Kubernetes
Envoy ext_authz in front of an MCP server, calling the real ASC decision API (kind + script): examples/external-auth/README.md. Integration evidence: docs/EVIDENCE-EXTERNAL-AUTH.md (on this corpus).
Policy contract
YAML policy (policy/demo-agent.policy.yaml) declares:
- Capability catalog — tool name, description, input schema
- Capability digest —
sha256:over the canonical catalog; must match the approved digest - Per-agent allowlists — which tools an agent may call
- Argument constraints — type, pattern, deny patterns, allowlisted hosts, max length, and per-arg
required(defaulttrue); undeclared args are rejected; omitted optional args are allowed - Path canonicalization — path args are percent-decoded, NUL-checked, slash-collapsed, and
..-resolved before allowlist checks - High-impact tools — require
approved: trueon the call or the verdict isREQUIRE_APPROVAL; destructive paths that resolve to a parent/root stillBLOCK - Rate limits — max calls per trace and per tool
Evidence envelope
Every verdict emits JSON conforming to schemas/evidence-envelope.schema.json:
| Field | Meaning |
|---|---|
schema_version | Envelope schema (1.0.0) |
policy_version | Policy document version |
policy_sha256 | SHA-256 of the policy file bytes |
scenario_id | Corpus / caller scenario id |
verdict / reason | Decision |
trace_id | Trace identifier |
commit_sha | ASC_COMMIT_SHA / GITHUB_SHA / unknown (CI sets ASC_COMMIT_SHA to the PR head or push SHA) |
timestamp | UTC ISO-8601 |
envelope_sha256 | SHA-256 over the canonical JSON of all other fields |
asc verify rejects missing fields, invalid values, disposition/verdict inconsistency, any edit that no longer matches envelope_sha256, and (when --policy is set) a policy_sha256 that differs from the policy file.
envelope_sha256 is an unkeyed integrity digest, not a signature: it catches accidental or naive edits, but someone who can rewrite the file can also recompute it. Treat envelopes as trustworthy only when they come from a CI run you control (for example, the uploaded workflow artifact).
Corpus metrics (generated)
See docs/EVIDENCE.md for the current run. Metrics are always phrased on this corpus of N scenarios.
Positive coverage is first-class: legitimate ALLOW scenarios are at least as numerous as attack scenarios; benign false-BLOCK is reported next to critical false-ALLOW.
Threat-model limits (honest)
ASC evaluates static traces (and pre-execution hook payloads) against a declared policy. It is not:
- a signer: evidence envelopes carry an integrity digest but no signature or attestation yet
- a full ACS wire Guardian (no session audit chain, no
MODIFY/DEFERdispositions yet) - a runtime OS sandbox or network enforcer by itself
- a prompt-injection detector inside the model
- a replacement for identity, secrets, or production change-management controls
- a claim of general agent safety beyond this corpus of N scenarios
Use it as a CI / admission gate alongside runtime controls, Promptfoo-style red teaming, and ACS-compliant Guardians.
Upstream
Possible OWASP upstream contributions: docs/UPSTREAM.md.
Development
python -m pip install -e ".[dev]"
python -m ruff check src tests
python -m pytest --collect-only -q
python -m pytest -q
CI (.github/workflows/ci.yml) runs a clean-install pytest --collect-only gate, lint, unit tests (including fail-closed and envelope negatives), the full corpus, writes results/results.json + markdown summary as artifacts, regenerates docs/EVIDENCE.md, and runs the Envoy external-auth kind quickstart job. Workflow permissions: contents: read; Actions pinned by commit SHA.
Related on justrunme.com
- Agent Security Contract case study
- Agent security on Kubernetes
- MCP security checklist for Kubernetes
- OWASP Agentic Top 10 on Kubernetes
- AI agent audit trail
Research and book
The preprint Fail-Closed Authorization for Tool-Using AI Agents: A Capability Contract and Case Study (Andrey Lesnikov, Zenodo, 2026) describes the contract and its evaluation. Additional context and analysis: Fail-Closed Authorization for AI Agents.
The book Prove It Before Production: Evidence-Driven Infrastructure Engineering for Kubernetes and AI (Amazon author page) is about proving that an infrastructure change is safe before it reaches production: reconstruct live state, rehearse the change, emit an explicit ALLOW / BLOCK / REQUIRE_APPROVAL verdict, and fail closed when evidence is missing (Chapter 7). Part IV (Chapters 11-14) applies the same contracts to AI agents on the control plane, including agent security contracts (Chapter 12), inference budgets and GPU admission.
Live demo: Hugging Face Space
Author
Andrey Lesnikov — Senior DevOps & AI Platform Engineer, independent researcher in fail-closed authorization for AI agents. 3rd place, Cloud Native Rockstar Awards 2026 (Cloud Native Conference 2026, Frankfurt).
Links: justrunme.com • GitHub • ORCID
Security
See SECURITY.md.
agent-security-contractpip install agent-security-contract