Metadata-Version: 2.4
Name: agent-security-contract
Version: 0.3.1
Summary: Fail-closed security contract for AI agents and MCP tool calls
Author-email: Andrey Lesnikov <52860508+justrunme@users.noreply.github.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://justrunme.com/cases/agent-security-contract/
Project-URL: Repository, https://github.com/justrunme/agent-security-contract
Project-URL: Documentation, https://github.com/justrunme/agent-security-contract#readme
Project-URL: Changelog, https://github.com/justrunme/agent-security-contract/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/justrunme/agent-security-contract/issues
Project-URL: Research, https://justrunme.com/research/fail-closed-authorization-ai-agents/
Project-URL: Preprint, https://doi.org/10.5281/zenodo.24075886
Project-URL: Book, https://justrunme.com/book/
Project-URL: Live demo, https://huggingface.co/spaces/justrunme/agent-security-contract
Project-URL: Author, https://justrunme.com/
Project-URL: ORCID, https://orcid.org/0009-0004-7583-4314
Keywords: ai-agents,mcp,model-context-protocol,authorization,fail-closed,agent-security,policy-enforcement,llm-security,tool-calling,prompt-injection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: mcp<2.0.0,>=1.0.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: hypothesis>=6.100.0; extra == "test"
Provides-Extra: dev
Requires-Dist: agent-security-contract[test]; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Dynamic: license-file

# agent-security-contract

<!-- mcp-name: io.github.justrunme/agent-security-contract -->

[![CI](https://github.com/justrunme/agent-security-contract/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/justrunme/agent-security-contract/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/justrunme/agent-security-contract/blob/main/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`](https://github.com/justrunme/agent-security-contract/blob/main/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](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)](https://genai.owasp.org/resource/agent-control-standard-acs/) (published 2026-09-01) — middleware hooks and runtime Guardian dispositions; ASC maps to Instrument [`toolCallRequest`](https://genai-security-project.github.io/agent-control-standard/docs/spec/instrument/hooks/) with `ALLOW` / `DENY` / `ASK`
- [OWASP Agentic AI / Agentic Applications Top 10](https://genai.owasp.org/initiatives/agentic-security-initiative/) — risk taxonomy for scenario mapping
- [OWASP MCP security cheat sheets](https://genai.owasp.org/resources/?e-filter-3b7adda-resource-item=cheat-sheets) — MCP hardening guidance
- [OWASP Agent Security Regression Harness](https://github.com/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](https://www.promptfoo.dev/) (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+.

```bash
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

```yaml
- 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`](https://github.com/justrunme/agent-security-contract/blob/main/docs/INTEGRATION.md). On sidecar/client timeout, fail closed (`BLOCK`); `asc.client.evaluate_remote()` does this for you.

```bash
python -m asc.sidecar --policy policy/demo-agent.policy.yaml --port 8788
```

## MCP server

ASC exposes its policy engine as a [Model Context Protocol](https://modelcontextprotocol.io/) server. MCP clients (Claude Desktop, Cursor, etc.) can call ASC tools to enforce security contracts before executing tool calls.

### Install

```bash
pip install agent-security-contract
```

Or from source:

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

```json
{
  "mcpServers": {
    "agent-security-contract": {
      "command": "asc-mcp"
    }
  }
}
```

### Configure for Cursor

Add to Cursor MCP settings (Settings → Features → MCP Servers):

```json
{
  "mcpServers": {
    "agent-security-contract": {
      "command": "asc-mcp"
    }
  }
}
```

### Run standalone (stdio)

```bash
asc-mcp
```

### Run as streamable HTTP server

```bash
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`](https://github.com/justrunme/agent-security-contract/blob/main/examples/external-auth/README.md). Integration evidence: [`docs/EVIDENCE-EXTERNAL-AUTH.md`](https://github.com/justrunme/agent-security-contract/blob/main/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`](https://github.com/justrunme/agent-security-contract/blob/main/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`](https://github.com/justrunme/agent-security-contract/blob/main/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`](https://github.com/justrunme/agent-security-contract/blob/main/docs/UPSTREAM.md).

## Development

```bash
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](https://justrunme.com/cases/agent-security-contract/)
- [Agent security on Kubernetes](https://justrunme.com/agent-security/)
- [MCP security checklist for Kubernetes](https://justrunme.com/guides/mcp-security-checklist-kubernetes/)
- [OWASP Agentic Top 10 on Kubernetes](https://justrunme.com/guides/owasp-agentic-top-10-kubernetes/)
- [AI agent audit trail](https://justrunme.com/guides/ai-agent-audit-trail/)

## Research and book

The preprint [Fail-Closed Authorization for Tool-Using AI Agents: A Capability Contract and Case Study](https://doi.org/10.5281/zenodo.24075886) (Andrey Lesnikov, Zenodo, 2026) describes the contract and its evaluation. Additional context and analysis: [Fail-Closed Authorization for AI Agents](https://justrunme.com/research/fail-closed-authorization-ai-agents/).

The book [*Prove It Before Production: Evidence-Driven Infrastructure Engineering for Kubernetes and AI*](https://justrunme.com/book/) ([Amazon author page](https://www.amazon.com/author/justrunme)) 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](https://huggingface.co/spaces/justrunme/agent-security-contract)

## 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](https://justrunme.com/) • [GitHub](https://github.com/justrunme) • [ORCID](https://orcid.org/0009-0004-7583-4314)

## Security

See [SECURITY.md](https://github.com/justrunme/agent-security-contract/blob/main/SECURITY.md).
