agent-capmap 0.1.0__py3-none-any.whl

agent_capmap-0.1.0.dist-info/METADATA

@@ -0,0 +1,295 @@
+Metadata-Version: 2.5
+Name: agent-capmap
+Version: 0.1.0
+Summary: Inventory the MCP tools reachable by AI agents and flag dangerous capability combinations with policy-as-code.
+Project-URL: Homepage, https://github.com/NKwolv/agent-capmap
+Project-URL: Documentation, https://github.com/NKwolv/agent-capmap#readme
+Project-URL: Issues, https://github.com/NKwolv/agent-capmap/issues
+Project-URL: Changelog, https://github.com/NKwolv/agent-capmap/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/NKwolv/agent-capmap/security/policy
+Author: NKwolv
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,mcp,model-context-protocol,sarif,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=1.11
+Requires-Dist: certifi>=2026.10.19
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: dev
+Requires-Dist: bandit>=1.8; extra == 'dev'
+Requires-Dist: cyclonedx-bom>=7.5; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-jsonschema; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Requires-Dist: uv>=0.13.4; extra == 'dev'
+Requires-Dist: virtualenv>=21.14.9; extra == 'dev'
+Requires-Dist: zizmor>=1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-capmap
+
+**Find out what your AI agents can actually do, and which combinations of their tools
+an attacker could abuse.**
+
+AI assistants such as Claude Desktop, Cursor, VS Code and Claude Code get their powers
+from MCP servers: read files, browse the web, send email, run shell commands. Each tool
+can look harmless on its own. The danger is usually the combination: an agent that can
+read private data, read attacker-written content (a web page, an issue, an email), and
+send data out can be talked into leaking that data. That is the "lethal trifecta".
+
+agent-capmap inventories every MCP server and tool reachable by each agent, classifies
+what each tool can do, and applies policy-as-code rules to the **combination** of tools
+per agent. Findings come with evidence and can gate CI through SARIF and exit codes.
+
+> **Status: pre-release (0.1.0).** All features below work. The classifier's accuracy
+> has not been benchmarked yet; see [Accuracy](#accuracy).
+
+## Install
+
+Requires Python 3.11+.
+
+```sh
+pipx install agent-capmap        # or: uv tool install agent-capmap
+```
+
+Releases are built and published by GitHub Actions with PyPI trusted publishing, so
+each file on PyPI carries an attestation linking it to the workflow run that built it.
+
+For a fully hash-pinned install, with the exact dependency versions CI tests, install
+from a clone instead:
+
+```sh
+git clone https://github.com/NKwolv/agent-capmap
+cd agent-capmap
+python -m venv .venv
+. .venv/bin/activate            # Windows PowerShell: .venv\Scripts\Activate.ps1
+pip install --require-hashes -r requirements/runtime.lock
+pip install --no-deps .
+```
+
+> **Locked-down Windows machines:** if your organization's policy (Device Guard,
+> AppLocker, Smart App Control) blocks `agentcapmap.exe` or `pipx.exe`, run the tool
+> through Python instead, which is the same program. If you installed with
+> `pip install agent-capmap`, run `python -m agentcapmap scan --user`. If you installed
+> with pipx, the package lives in pipx's own environment, so plain `python` will not
+> find it: use that environment's interpreter (`python -m pipx environment --value
+> PIPX_LOCAL_VENVS` shows the folder):
+> `<venvs>\agent-capmap\Scripts\python.exe -m agentcapmap scan --user`. Do not try to
+> bypass the policy; ask your administrator to allow the launcher if you want it.
+
+> **Windows:** if `pip install` fails with "No such file or directory" deep inside
+> `site-packages`, the path is too long for Windows' 260-character limit. Clone to a
+> short path (for example `C:\src\agent-capmap`) or enable long path support.
+
+## Quickstart (5 minutes, no API key)
+
+```sh
+# 1. See findings on a ready-made inventory of five example agents
+#    (from a clone, use examples/demo/inventory.json directly)
+curl -fsSLO https://raw.githubusercontent.com/NKwolv/agent-capmap/main/examples/demo/inventory.json
+agentcapmap evaluate inventory.json --format markdown
+
+# 2. List the MCP servers configured on your own machine (reads files only)
+agentcapmap scan --user
+```
+
+On Windows PowerShell, use `curl.exe` instead of `curl`.
+
+Step 1 should report 2 critical, 2 high and 1 medium finding. Step 2 lists your
+servers with every secret redacted, without starting anything.
+
+## Example output
+
+```markdown
+### 1. `CAP-001` | Critical
+
+`Lethal trifecta: the agent can read private data, ingest attacker-controlled content,
+and send data externally, so injected instructions can exfiltrate data.`
+
+- **Agent:** `generic:fixtures/trifecta/mcp.json` at `fixtures/trifecta/mcp.json:3`
+- **Tools:** `github/get_file_contents`, `github/list_issues`, `mailer/send_email`
+
+| Server | Tool | Matched | Evidence |
+|---|---|---|---|
+| `github` | `get_file_contents` | `data_access=private_read` | `contents of a file from a private or public repository` |
+| `github` | `list_issues` | `untrusted_input=true` | `including issues opened by anyone` |
+| `mailer` | `send_email` | `egress=external` | `Send an email to any recipient address` |
+```
+
+(Abridged from the real output of step 1.)
+
+## How it works
+
+```
+config files ──► discover ──► enumerate ──► classify ──► policy ──► report
+                 (read only)  (initialize +  (LLM tags    (YAML      (JSON, Markdown,
+                              tools/list)    6 axes)      rules)     SARIF, exit code)
+```
+
+1. **Discover** MCP configs: Claude Desktop, Cursor, VS Code (`.vscode/mcp.json`,
+   `settings.json`), Claude Code (`.mcp.json`, and with `--user` your `~/.claude.json`
+   user and per-project servers, including permission rules) and generic `mcp.json`.
+   Secrets are redacted everywhere.
+2. **Enumerate** (`--enumerate`): start each server and ask only for its tool list.
+   Tools are never called.
+3. **Classify** (`--classify`): an LLM tags each tool on six axes and flags tool
+   descriptions that try to manipulate the model. Results are cached and validated
+   against a JSON schema.
+4. **Evaluate** (`--evaluate`): deterministic rules decide what is dangerous. The LLM
+   never makes risk decisions.
+5. **Report**: JSON, Markdown, or SARIF for GitHub code scanning; `--fail-on` sets the
+   exit code.
+
+### Full scan of your own setup (needs an API key)
+
+```sh
+export ANTHROPIC_API_KEY=<YOUR_API_KEY>          # PowerShell: $env:ANTHROPIC_API_KEY = "..."
+agentcapmap scan --user --enumerate --classify --evaluate --format markdown -o report.md
+```
+
+`--enumerate` **runs the server commands in your configs**: only use it on configs you
+trust. To try the whole pipeline on two known servers first, see
+[`examples/live-trifecta`](https://github.com/NKwolv/agent-capmap/blob/main/examples/README.md).
+
+## Capability taxonomy
+
+| Axis | Values | Question |
+|---|---|---|
+| `data_access` | none, private_read, secrets_read | What non-public data can it read? |
+| `untrusted_input` | false, true | Does it return content strangers can write? |
+| `egress` | none, internal, external | Can it send data somewhere an outsider can read? |
+| `mutation` | none, reversible_write, destructive | What can it change or delete? |
+| `execution` | none, sandboxed, host | Does it run code, and where? |
+| `privilege` | none, identity_admin | Does it manage users or permissions? |
+
+Definitions and edge-case rulings: [docs/taxonomy.md](https://github.com/NKwolv/agent-capmap/blob/main/docs/taxonomy.md).
+
+## Policy
+
+The built-in [`policies/default.yaml`](https://github.com/NKwolv/agent-capmap/blob/main/policies/default.yaml) has nine rules:
+
+| ID | Severity | Fires when an agent has |
+|---|---|---|
+| CAP-001 | critical | private data + untrusted input + external egress (lethal trifecta) |
+| CAP-002 | critical | untrusted input + host code execution |
+| CAP-003 | high | a destructive or host-execution tool with no approval gate |
+| CAP-004 | high | secrets access + external egress |
+| CAP-005 | high | a remote server with no authentication exposing capabilities |
+| CAP-006 | high | tool definitions that changed since the baseline (rug pull) |
+| CAP-007 | medium | a server not pinned to an exact version, or from an unvetted source |
+| CAP-008 | high | a tool description that tries to instruct the model (tool poisoning) |
+| CAP-009 | medium | the same tool name on two servers (shadowing) |
+
+Write your own rules in the same format and pass `--policy my-policy.yaml`:
+
+```yaml
+- id: ACME-001
+  severity: high
+  when_server: {remote: true}
+  when_agent_has_any:
+    - privilege: identity_admin
+  message: Remote servers must not manage identities.
+```
+
+Conditions: `when_agent_has_all`, `when_agent_has_any`, `when_server`,
+`when_hash_changed`, `when_tool_name_shadowed`. The format is defined by
+[`schemas/policy.schema.json`](https://github.com/NKwolv/agent-capmap/blob/main/schemas/policy.schema.json). Rug-pull detection:
+
+```sh
+agentcapmap baseline create inventory.json -o baseline.json   # once, after review
+agentcapmap evaluate new-inventory.json --baseline baseline.json
+```
+
+To see what changed between two runs (for example `main` versus a pull request), save
+each `evaluate` output and compare them:
+
+```sh
+agentcapmap diff before.json after.json --format markdown
+agentcapmap diff before.json after.json --fail-on high --fail-on-new-capability
+```
+
+`diff` lists new and resolved findings and capabilities an agent gained or lost.
+`--fail-on` looks at new findings only, so existing, already-accepted findings do not
+fail the build; `--fail-on-new-capability` fails when an agent gains any capability.
+
+## CI and GitHub code scanning
+
+```sh
+agentcapmap evaluate inventory.json --format sarif -o agentcapmap.sarif --fail-on high
+```
+
+Exit codes: `0` passed, `1` findings at or above `--fail-on`, `2` usage or input error.
+The repository is also a GitHub Action: see [docs/github-action.md](https://github.com/NKwolv/agent-capmap/blob/main/docs/github-action.md)
+and the [example workflow](https://github.com/NKwolv/agent-capmap/blob/main/docs/examples/agentcapmap.yml). By default the Action reads
+configs only, which is safe for pull requests from forks.
+
+## Accuracy
+
+The classifier is evaluated against hand-labeled tools from real MCP servers (see
+[`eval/`](https://github.com/NKwolv/agent-capmap/blob/main/eval/README.md)). **No accuracy numbers are published yet.** The 381 labels
+(28 servers) were drafted by one AI model and then reviewed by another AI model at the
+maintainer's request; no person has independently reviewed them yet. A model grading a
+model can overstate accuracy, so numbers will be quoted here only after a person has
+reviewed the labels and the run is frozen (`python eval/run_eval.py`). The same labels
+also power classification without an API key for these known tools; see
+[Limitations](#limitations).
+
+## Limitations
+
+- **Descriptions, not behavior.** Tools are classified by what their definitions say. A
+  tool that lies about itself will be mis-tagged; agent-capmap never calls tools.
+- **Classifier errors.** Tags can be wrong, especially for vague descriptions. Every
+  tag carries a confidence and an evidence phrase; phrases not found in the definition
+  are marked unverified.
+- **Approval gates are mostly invisible.** Claude Code's permission settings are read
+  (so its default "ask before each MCP call" counts as a gate), but most other clients do
+  not record this, and CAP-003 treats "unknown" as "no gate" by default.
+- **Enumeration runs code.** Starting servers executes the configured commands. A
+  started server can also read its parent's environment on Linux.
+- **Coverage.** Config formats evolve; Windsurf is not read yet. MCP servers that do not
+  live in config files (Claude Code plugins, claude.ai connectors, IDE built-in servers,
+  managed settings) are not seen. WebSocket servers are listed but not enumerated.
+  Token scopes are not visible.
+- **Reference labels are AI-reviewed.** For 381 tools from 28 well-known servers, the
+  classifier answers from bundled labels (matched by exact definition hash) instead of
+  calling a model, so no API key is needed. Those labels were reviewed by an AI model, not
+  yet by a person, and a wrong label is returned with full confidence; any change to a
+  tool's definition falls back to the cache or the LLM. Treat them as a convenience.
+- **Not assessed is not safe.** Servers that could not be enumerated and tools that
+  could not be classified are listed under `not_assessed`, never assumed safe.
+
+## Safety
+
+Secrets from configs are redacted in all output and logs. Enumeration sends only
+`initialize` and `tools/list`, with a minimal environment for launched servers, no
+credential-forwarding redirects, and size limits on everything a server returns.
+Reports render untrusted text inertly. See [SECURITY.md](https://github.com/NKwolv/agent-capmap/blob/main/SECURITY.md) and the
+[threat model](https://github.com/NKwolv/agent-capmap/blob/main/docs/threat-model.md).
+
+## Documentation
+
+- [Capability taxonomy](https://github.com/NKwolv/agent-capmap/blob/main/docs/taxonomy.md)
+- [Threat model](https://github.com/NKwolv/agent-capmap/blob/main/docs/threat-model.md): attacks covered, OWASP / MITRE ATLAS mapping
+- [GitHub Action](https://github.com/NKwolv/agent-capmap/blob/main/docs/github-action.md)
+- [Comparison with Snyk Agent Scan (mcp-scan)](https://github.com/NKwolv/agent-capmap/blob/main/docs/vs-mcp-scan.md)
+- [Examples](https://github.com/NKwolv/agent-capmap/blob/main/examples/README.md) · [Evaluation](https://github.com/NKwolv/agent-capmap/blob/main/eval/README.md) · [POC checklist](https://github.com/NKwolv/agent-capmap/blob/main/docs/poc-checklist.md)
+- [Contributing](https://github.com/NKwolv/agent-capmap/blob/main/CONTRIBUTING.md) · [Security policy](https://github.com/NKwolv/agent-capmap/blob/main/SECURITY.md) · [Changelog](https://github.com/NKwolv/agent-capmap/blob/main/CHANGELOG.md)
+
+## License
+
+MIT. See [LICENSE](https://github.com/NKwolv/agent-capmap/blob/main/LICENSE).

agent_capmap-0.1.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+agentcapmap/__init__.py,sha256=obKLf0ZZ_1JxejXRMSVoQyyXCUUVpKnpg70raMECb8s,92
+agentcapmap/__main__.py,sha256=7ZDXsBQ0WkuCXfmY-_jkFHDuEhAWAJluGZqddbGItYo,63
+agentcapmap/baseline.py,sha256=wUD1fRL40fCcSgfI1PnyXQJeM0yhv-WZw6u1woUkURo,4676
+agentcapmap/cli.py,sha256=OdRJN5_ROn5U9q9ZstDxSIY--o-JGIrgOn5TIfMmDV0,14835
+agentcapmap/diff.py,sha256=XU51_reeUwDgwz14hP3-I2HWaA7B94L6gaWO2khxads,3964
+agentcapmap/evaluation.py,sha256=uxHDh65c9wnVZgsEAXKPdlmuPwG4DCYJLr2iTNs-pbM,17200
+agentcapmap/findings.py,sha256=lZX41bb-ffGlijX64PA_mOa7yzDsvFwZZajLrDMzHrU,3503
+agentcapmap/limits.py,sha256=OE1d4VkXY5ceN_F7wOnUBROS9RzJo4jLVnTkh4wmYYc,1231
+agentcapmap/models.py,sha256=74ZlxchqRzm6m_SNiVmpnSr05dB3v9kT2xtKVHq9Sbg,5931
+agentcapmap/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentcapmap/redact.py,sha256=ZAjJVoDZ1rGIjGhwWCi32XWkGtKU4Zl6NUAF8yq4aes,9507
+agentcapmap/taxonomy.py,sha256=Iuw4c_kThiyjrzwHW_O9Yc-7aCOOiZE6K_cyR53O1y4,1869
+agentcapmap/classify/__init__.py,sha256=Mgw5f2loU6FBgpXGWR22LkpykDz0qKEv5OWjNMXnpKs,8606
+agentcapmap/classify/cache.py,sha256=bJzpbNi4LtixN8WsvJOdiZeGftaqihpCB6Vy26soGng,2531
+agentcapmap/classify/prompt.py,sha256=I1kDpKwkdCdOzcF0BpA20LyoHvY3FQBq4_MC0A0CU_c,8682
+agentcapmap/classify/provider.py,sha256=fjGy0VpT_aOhkSvhGaSETaX8Pf-r89OdS_C7mgWHbaA,4878
+agentcapmap/classify/reference.py,sha256=8FXGPrpKZBeviXd-aQfX9jZ2Sqa8SBhPIQHNTE4qE9E,4034
+agentcapmap/classify/reference_labels.json,sha256=EB7LaRAEWrni8azwAYPlHh2oDb881rO_dbwjZ0H6xjk,208335
+agentcapmap/discovery/__init__.py,sha256=a3b4t-otqWLl9XfUOs-SUwZoYMbQ6ttAM4FwsVeegn0,7554
+agentcapmap/discovery/_common.py,sha256=u0WA0IA1023LBsXZnjT-Eao9P2j_X-0l-nV1AwHzjSI,10043
+agentcapmap/discovery/claude_code.py,sha256=Z6AL7a95jAVGIvEN0vyLwtcXRMvrI4OTMppsMCNep-4,10239
+agentcapmap/discovery/claude_desktop.py,sha256=7PsElFL8fD1L4RhxkS7UhZ-euEKYJh48a4rDpfvnLUc,833
+agentcapmap/discovery/cursor.py,sha256=cTMK8hRYi67YnXqOxLcZzD07f6TnQYHVlUPpLXDeUms,1039
+agentcapmap/discovery/mcp_json.py,sha256=aYfWGVHZMtM6miFCYhRax-1RoNRsOcc4Jka-LhI7KWc,936
+agentcapmap/discovery/vscode.py,sha256=eewYklqnyKMOLjYfUnMG4Q1FoW2j3DHw4RaWRC9Ib-Q,2126
+agentcapmap/enumerate/__init__.py,sha256=7891bEb59OuXyu-wJKmrEwXUdREFKVzyHhctycrm8GE,10958
+agentcapmap/enumerate/hashing.py,sha256=5gno5bAiAuvLfKdTx8X4YmKMebkJhlQp0MESmXxb3Zc,1214
+agentcapmap/enumerate/http.py,sha256=Pv3wB1hNZ2Jw2bMO7TxZok4_rzXVVkU8lBg1bKp4q0A,12321
+agentcapmap/enumerate/netguard.py,sha256=Qgi4xYwi1uMu89kRJlKIFk72MW7uq2yISF26M13KknE,2554
+agentcapmap/enumerate/stdio.py,sha256=2Z4Dj7Whun5IB7CrT4OXh6CObb-PBD8WFoW98wN_OE0,10403
+agentcapmap/enumerate/transport.py,sha256=Q55C7k2VnSLgifXGOLbTcTvaFmm6duXczT8lX9zATKI,2771
+agentcapmap/graph/__init__.py,sha256=S7wEDGXrbbE8y93ZhWlHnHnv25PNX7AzOcI4j5OK0CI,10035
+agentcapmap/graph/server_attrs.py,sha256=kxTKBhHjLWIkEz__FCSeMuKBHN-crDgjg_f6DyefJr4,6748
+agentcapmap/policy/__init__.py,sha256=Wgt961Ff76YBcBbmqcLel3Mj9HihrhbEPJVsdCZ0YHI,489
+agentcapmap/policy/engine.py,sha256=S3S_EBI5wS4zxHjWt-XrZ7yDdOzde6SCElENqZcHOqk,8406
+agentcapmap/policy/loader.py,sha256=K2TH0RcDFT_1vextVrcBHbPC17s73DSBjUtcyCErI9c,8033
+agentcapmap/report/__init__.py,sha256=9Dw-xMcpEFbx7_I8C_Y-ITapDubm6SZWVD_bJ6rSXIw,1127
+agentcapmap/report/_text.py,sha256=iGk1PXB6Z_Dwir9nlqFoTVXK9GJsGe0qSsMzJUgcF4g,2099
+agentcapmap/report/markdown.py,sha256=Uo2fZLlJoJWYS7cNDopVyB50aF7-SBZvZth7dEkiRUs,6083
+agentcapmap/report/sarif.py,sha256=lUpOM8UEQ3zaAikyucX_c3P_tbUTZHmuCxDi2hqQVl8,7696
+agentcapmap/policies/default.yaml,sha256=49mVVNkh64uHTrJjBvPozSnoWWdKwmcn08_QzUF8mVY,4325
+agentcapmap/schemas/policy.schema.json,sha256=7UTVJP2QiO54oONKDXp44K7kpVX9o7pg5hvcNkUg8gA,6423
+agentcapmap/schemas/tool-tags.schema.json,sha256=HCiOD69uRap1rVXmflQaUbSdNXMYgwrcNQFzItz91KQ,2171
+agent_capmap-0.1.0.dist-info/METADATA,sha256=qwxAB-bCUuSd7dBoJWPERlA13q40dg1Ni-tQsZyesp4,14678
+agent_capmap-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agent_capmap-0.1.0.dist-info/entry_points.txt,sha256=olKJIQuXulXL9T9E_SdreA0Ggy-Ylq-NbgVynJTfH6Y,53
+agent_capmap-0.1.0.dist-info/licenses/LICENSE,sha256=FnKTHxvCRPab3DyRc6SWm-NbmCvvAfZ7IrvGSMaXhIo,1063
+agent_capmap-0.1.0.dist-info/RECORD,,

agent_capmap-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_capmap-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentcapmap = agentcapmap.cli:main

agent_capmap-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NKwolv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentcapmap/__init__.py

@@ -0,0 +1,3 @@
+"""agent-capmap: map the MCP capabilities reachable by AI agents."""
+
+__version__ = "0.1.0"

agentcapmap/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from agentcapmap.cli import main
+
+sys.exit(main())

agentcapmap/baseline.py

@@ -0,0 +1,125 @@
+"""Baseline pinning of tool definition hashes, for rug-pull detection (CAP-006).
+
+`agentcapmap baseline create` records, per server, the hash of every tool definition.
+Later scans compare against it: a changed, added or removed tool means the server's
+definitions changed after review.
+
+A server is identified by its name, transport and (redacted) launch command or URL, so
+a deliberate config change (e.g. a new pinned version) is a new server, while the same
+config serving different definitions is a change.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints, ValidationError
+
+from agentcapmap.limits import MAX_CONFIG_BYTES, MAX_TOOLS_PER_SERVER, loads_untrusted
+from agentcapmap.models import EnumerationStatus, Inventory, Server
+
+BASELINE_VERSION: Literal[1] = 1
+_MAX_BASELINE_BYTES = 16 * MAX_CONFIG_BYTES
+_MAX_SERVERS = 10_000
+
+Sha256Hex = Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{64}$")]
+ToolName = Annotated[str, StringConstraints(min_length=1, max_length=512)]
+
+
+class BaselineError(ValueError):
+    pass
+
+
+class BaselineServer(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: Annotated[str, StringConstraints(min_length=1, max_length=512)]
+    tools: dict[ToolName, Sha256Hex] = Field(max_length=MAX_TOOLS_PER_SERVER)
+
+
+class Baseline(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    baseline_version: Literal[1] = BASELINE_VERSION
+    servers: dict[Sha256Hex, BaselineServer] = Field(default_factory=dict, max_length=_MAX_SERVERS)
+
+
+class HashDiff(BaseModel):
+    added: list[str] = Field(default_factory=list)
+    removed: list[str] = Field(default_factory=list)
+    changed: list[str] = Field(default_factory=list)
+    # name -> {"baseline": hash, "current": hash} for changed tools
+    hashes: dict[str, dict[str, str]] = Field(default_factory=dict)
+
+    def __bool__(self) -> bool:
+        return bool(self.added or self.removed or self.changed)
+
+
+def server_identity(server: Server) -> str:
+    material = json.dumps(
+        [server.name, server.transport.value, server.command, server.args, server.url],
+        separators=(",", ":"),
+        ensure_ascii=False,
+    )
+    return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+
+def _current_tools(server: Server) -> dict[str, str] | None:
+    enumeration = server.enumeration
+    if enumeration is None or enumeration.status is not EnumerationStatus.OK:
+        return None
+    return {tool.name: tool.definition_hash for tool in enumeration.tools}
+
+
+def create_baseline(inventory: Inventory) -> Baseline:
+    """Pin every successfully enumerated, enabled server in the inventory."""
+    baseline = Baseline()
+    for agent in inventory.agents:
+        for server in agent.servers:
+            tools = _current_tools(server)
+            if server.disabled or tools is None:
+                continue
+            baseline.servers[server_identity(server)] = BaselineServer(
+                name=server.name, tools=dict(sorted(tools.items()))
+            )
+    baseline.servers = dict(sorted(baseline.servers.items()))
+    return baseline
+
+
+def load_baseline(path: Path) -> Baseline:
+    try:
+        size = path.stat().st_size
+        raw = path.read_bytes() if size <= _MAX_BASELINE_BYTES else b""
+    except OSError as exc:
+        raise BaselineError(f"cannot read baseline: {exc.strerror}") from None
+    if size > _MAX_BASELINE_BYTES:
+        raise BaselineError(f"baseline file larger than {_MAX_BASELINE_BYTES} bytes")
+    try:
+        data = loads_untrusted(raw)
+    except ValueError as exc:
+        raise BaselineError(f"baseline is not valid JSON: {exc}") from None
+    try:
+        return Baseline.model_validate(data, strict=True)
+    except ValidationError as exc:
+        raise BaselineError(
+            f"baseline does not match the expected format ({exc.error_count()} error(s))"
+        ) from None
+
+
+def diff_server(baseline: Baseline, server: Server) -> HashDiff | None:
+    """None when the server is not in the baseline or could not be enumerated now."""
+    pinned = baseline.servers.get(server_identity(server))
+    current = _current_tools(server)
+    if pinned is None or current is None:
+        return None
+    before, after = pinned.tools, current
+    changed = sorted(n for n in before.keys() & after.keys() if before[n] != after[n])
+    return HashDiff(
+        added=sorted(after.keys() - before.keys()),
+        removed=sorted(before.keys() - after.keys()),
+        changed=changed,
+        hashes={n: {"baseline": before[n], "current": after[n]} for n in changed},
+    )