# agent-sec-mcp

**Authorized-use agent-security MCP server.** Deterministic, no-LLM MCP server
for auditing AI-agent supply-chain and agent-facing surfaces that the operator
is **authorized to test**. Fills the "Agent / Supply-Chain Security" category
missing from offensive-security MCP catalogs.

## Hard authorization gate
Any tool that touches a **network target** refuses to run unless the target is
in an explicit `authorized_hosts` allowlist (per-call) or the `ENGAGEMENT_SCOPE`
env var. Local read-only auditing of a skill bundle you provide needs no scope.

```
# touch a network target? you must declare scope:
export ENGAGEMENT_SCOPE="192.168.1.0/24,my-box.example.com"
# or pass authorized_hosts to the tool per call
```
Without it: `probe_agent_endpoint`/`enumerate_mcp_surface` return `AUTHZ_DENIED`.

## Tools
| Tool | Scope required | What it does |
|---|---|---|
| `audit_agent_skill` | none (local) | Audit a skill/plugin/prompt bundle vs **8 supply-chain attack patterns** (R1 injection, R2 exfil, R3 secrets, R4 dangerous cmds, R5 obfuscation, R6 untrusted fetch, R7 cred access, R8 priv-esc) with line-level evidence |
| `scan_secrets` | none (local) | Secrets detection on a local path (GitHub tokens, API keys, AWS, private keys, passwords) |
| `probe_agent_endpoint` | **YES** | Read-only HTTP recon of an agent endpoint: status, headers (server/x-powered-by/sts/set-cookie/www-auth), TLS |
| `enumerate_mcp_surface` | **YES** | Discover declared tools/schema of an MCP endpoint (initialize/tools.list, read-only) |
| `verify_claim_evidence` | none | Evidence-gated claim check — is a claimed action actually verified? (FACT/INFERENCE/REFUTED/UNVERIFIED; DO-NOT-REPORT gate) |
| `list_rules` | none | List the 8 supply-chain audit patterns |

## Run
```
# stdio (Claude Desktop / MCP clients)
python3 mcp_server.py

# streamable HTTP
python3 mcp_server.py --http 8102
# health: GET http://127.0.0.1:8102/healthz

# deterministic self-test (CI)
python3 mcp_server.py --self-test
```

Protocol: JSON-RPC 2.0 over stdio; `initialize` / `tools/list` / `tools/call` / `ping`.

## Determinism & trust
- **No LLM, no network exfil, pure stdlib.** The 8-pattern audit engine is the
  same deterministic ruleset used by `mcp-skill-sec`; secret/heuristic scanning
  is gitleaks-style token regex.
- Reads only what you point it at; writes nothing except stdout.
- Ships with an E2E-tested authorization gate so network-facing tools are
  denied unless scope is declared — no "scan anything" foot-gun.

## Install (once published)
```
pip install agent-sec-mcp        # PyPI
# or
uv tool install git+https://github.com/sudo-ai-git/agent-sec-mcp
```

## License & provenance
MIT. Written by `sudo-ai-git`. Authorized security-testing tool — use it only on
systems you own or have written permission to test.