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
Author
Andrey Lesnikov — Senior DevOps & AI Platform Engineer
https://orcid.org/0009-0004-7583-4314
Security
See SECURITY.md.
Metadata
Release files for agent-security-contract 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_security_contract-0.3.0.tar.gz | 45.6 kB | With provenance | Details for agent_security_contract-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_security_contract-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for agent_security_contract-0.3.0-py3-none-any.whl |
Total release size: 83.0 kB
Release files / agent_security_contract-0.3.0.tar.gz
| Download URL | agent_security_contract-0.3.0.tar.gz |
|---|---|
| Size | 45.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ed789ca5b7d34f4b6997fd6773613883ebc7a6eed5dde060e250daefb2225c2c
|
|
BLAKE2b-256 checksum How to use checksums |
6c300baf0785a3b76e6a60f09a2d719edb4dca48a1db3ad53a09ca3e6e7c04e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logRelease files / agent_security_contract-0.3.0-py3-none-any.whl
| Download URL | agent_security_contract-0.3.0-py3-none-any.whl |
|---|---|
| Size | 37.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bea74284f79e5d3c28bd9a5faa33c1188b9f28ddf6a5a1b6b3f4ab1c2fa0cb27
|
|
BLAKE2b-256 checksum How to use checksums |
f5e3ff7f03047193e170bbe92f0377bd8b49ce829b9bd4072bf3a6f7d32c8a10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logSecurity for agent-security-contract 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_security_contract-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.