Skip to main content

agent-security-contract

CI License

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

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 (default true); 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: true on the call or the verdict is REQUIRE_APPROVAL; destructive paths that resolve to a parent/root still BLOCK
  • 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/DEFER dispositions 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.

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)

Source distribution for agent-security-contract 0.3.0
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)

Table of built distributions (wheels) for agent-security-contract 0.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page