Repository avatar
AI Tools
v0.3.1
active

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

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.

ProjectPrimary jobWhen it runsRelation to ASC
ASC (this repo)Fail-closed policy gate + evidence envelopeBefore tool execution / in CI admissionEnforcement oracle
Promptfoo (MCP red teaming)Attack generation & detection findings in CIEval / red-team jobsComplementary detection; does not replace an admission deny
OWASP Agent Security Regression HarnessRegression suite for agent security behaviorsCI regressionComplementary testing; ASC can act as an enforcement profile
LiteLLM / guardrailsRequest/response filtering & provider controlsProxy / runtime pathComplementary 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)

VerdictExit codeACS disposition
ALLOW0ALLOW
BLOCK1DENY
REQUIRE_APPROVAL2ASK

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:

FieldMeaning
schema_versionEnvelope schema (1.0.0)
policy_versionPolicy document version
policy_sha256SHA-256 of the policy file bytes
scenario_idCorpus / caller scenario id
verdict / reasonDecision
trace_idTrace identifier
commit_shaASC_COMMIT_SHA / GITHUB_SHA / unknown (CI sets ASC_COMMIT_SHA to the PR head or push SHA)
timestampUTC ISO-8601
envelope_sha256SHA-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.

Related on justrunme.com

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.

PYPI
agent-security-contract
Install Command
pip install agent-security-contract