agentinel 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. agentinel-0.1.0/.gitignore +28 -0
  2. agentinel-0.1.0/CHANGELOG.md +40 -0
  3. agentinel-0.1.0/LICENSE +21 -0
  4. agentinel-0.1.0/PKG-INFO +250 -0
  5. agentinel-0.1.0/README.md +217 -0
  6. agentinel-0.1.0/fixtures/clean/comms_only_server.py +19 -0
  7. agentinel-0.1.0/fixtures/clean/echo_server.py +30 -0
  8. agentinel-0.1.0/fixtures/clean/fetch_only_server.py +25 -0
  9. agentinel-0.1.0/fixtures/clean/files_only_server.py +25 -0
  10. agentinel-0.1.0/fixtures/real-world/catalog.json +257 -0
  11. agentinel-0.1.0/fixtures/vulnerable/poisoned_server.py +52 -0
  12. agentinel-0.1.0/fixtures/vulnerable/trifecta_server.py +35 -0
  13. agentinel-0.1.0/fixtures/vulnerable/unicode_smuggle_server.py +33 -0
  14. agentinel-0.1.0/pyproject.toml +113 -0
  15. agentinel-0.1.0/src/agentinel/__init__.py +6 -0
  16. agentinel-0.1.0/src/agentinel/cli.py +298 -0
  17. agentinel-0.1.0/src/agentinel/config.py +65 -0
  18. agentinel-0.1.0/src/agentinel/dynamic/__init__.py +16 -0
  19. agentinel-0.1.0/src/agentinel/dynamic/adaptive.py +250 -0
  20. agentinel-0.1.0/src/agentinel/dynamic/harness.py +76 -0
  21. agentinel-0.1.0/src/agentinel/dynamic/llm.py +83 -0
  22. agentinel-0.1.0/src/agentinel/guard/__init__.py +5 -0
  23. agentinel-0.1.0/src/agentinel/guard/__main__.py +3 -0
  24. agentinel-0.1.0/src/agentinel/guard/claude_code.py +164 -0
  25. agentinel-0.1.0/src/agentinel/guard/core.py +277 -0
  26. agentinel-0.1.0/src/agentinel/guard/hook.py +75 -0
  27. agentinel-0.1.0/src/agentinel/guard/policy.py +31 -0
  28. agentinel-0.1.0/src/agentinel/guard/replay.py +128 -0
  29. agentinel-0.1.0/src/agentinel/mcp_client.py +150 -0
  30. agentinel-0.1.0/src/agentinel/models.py +200 -0
  31. agentinel-0.1.0/src/agentinel/prober.py +85 -0
  32. agentinel-0.1.0/src/agentinel/report/__init__.py +0 -0
  33. agentinel-0.1.0/src/agentinel/report/fonts/OFL-JetBrainsMono.txt +93 -0
  34. agentinel-0.1.0/src/agentinel/report/fonts/OFL-SpaceGrotesk.txt +93 -0
  35. agentinel-0.1.0/src/agentinel/report/fonts/jetbrains-mono-latin-500-normal.woff2 +0 -0
  36. agentinel-0.1.0/src/agentinel/report/fonts/jetbrains-mono-latin-700-normal.woff2 +0 -0
  37. agentinel-0.1.0/src/agentinel/report/fonts/space-grotesk-latin-500-normal.woff2 +0 -0
  38. agentinel-0.1.0/src/agentinel/report/fonts/space-grotesk-latin-700-normal.woff2 +0 -0
  39. agentinel-0.1.0/src/agentinel/report/html.py +486 -0
  40. agentinel-0.1.0/src/agentinel/report/sarif.py +93 -0
  41. agentinel-0.1.0/src/agentinel/report/terminal.py +150 -0
  42. agentinel-0.1.0/src/agentinel/scanner.py +63 -0
  43. agentinel-0.1.0/src/agentinel/server.py +77 -0
  44. agentinel-0.1.0/src/agentinel/static/__init__.py +36 -0
  45. agentinel-0.1.0/src/agentinel/static/capabilities.py +176 -0
  46. agentinel-0.1.0/src/agentinel/static/classifier.py +286 -0
  47. agentinel-0.1.0/src/agentinel/static/drift.py +74 -0
  48. agentinel-0.1.0/src/agentinel/static/fleet.py +57 -0
  49. agentinel-0.1.0/src/agentinel/static/llm_classifier.py +54 -0
  50. agentinel-0.1.0/src/agentinel/static/shadowing.py +105 -0
  51. agentinel-0.1.0/src/agentinel/static/tool_poisoning.py +172 -0
  52. agentinel-0.1.0/src/agentinel/static/trifecta.py +96 -0
  53. agentinel-0.1.0/src/agentinel/taxonomy.py +304 -0
  54. agentinel-0.1.0/tests/__init__.py +0 -0
  55. agentinel-0.1.0/tests/test_classifier.py +52 -0
  56. agentinel-0.1.0/tests/test_cli.py +41 -0
  57. agentinel-0.1.0/tests/test_config.py +89 -0
  58. agentinel-0.1.0/tests/test_drift.py +42 -0
  59. agentinel-0.1.0/tests/test_eval.py +80 -0
  60. agentinel-0.1.0/tests/test_guard.py +247 -0
  61. agentinel-0.1.0/tests/test_html.py +43 -0
  62. agentinel-0.1.0/tests/test_llm_classifier.py +24 -0
  63. agentinel-0.1.0/tests/test_probe.py +193 -0
  64. agentinel-0.1.0/tests/test_real_world.py +55 -0
  65. agentinel-0.1.0/tests/test_sarif.py +39 -0
  66. agentinel-0.1.0/tests/test_shadowing.py +37 -0
  67. agentinel-0.1.0/tests/test_static_detectors.py +84 -0
  68. agentinel-0.1.0/tests/test_tool_poisoning.py +43 -0
@@ -0,0 +1,28 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ .eggs/
8
+
9
+ # venv / uv
10
+ .venv/
11
+ .python-version
12
+
13
+ # tooling caches
14
+ .pytest_cache/
15
+ .ruff_cache/
16
+ .mypy_cache/
17
+
18
+ # env / secrets
19
+ .env
20
+ .env.*
21
+
22
+ # OS / editor
23
+ .DS_Store
24
+ .idea/
25
+ .vscode/
26
+
27
+ # agentinel scan output (sample reports live in examples/ and are committed)
28
+ /reports/
@@ -0,0 +1,40 @@
1
+ # Changelog
2
+
3
+ All notable changes to Agentinel are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/), and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [0.1.0] — 2026-11-19
8
+
9
+ First public release, and the first on PyPI (`pip install agentinel`): an open-source auditor for
10
+ MCP servers and agent fleets.
11
+
12
+ ### Added
13
+ - **`agentinel guard`** (research prototype) — a session-aware Rule-of-Two hook for Claude Code
14
+ that asks only when an outbound call carries data read from a sensitive source after untrusted
15
+ input. `guard init` builds a policy from a scan, `guard replay` measures the prompt cost on your
16
+ recorded sessions, and `probe --guard` measures what still leaks. See `docs/guard.md`.
17
+ - **`agentinel scan`** — static Rule-of-Two / lethal-trifecta analysis, per-server **and** across a
18
+ whole fleet, plus tool poisoning, secrets in config, unsafe code-/CLI-command-execution surfaces,
19
+ over-broad permissions, cross-server name shadowing, and rug-pull drift — each mapped to the
20
+ OWASP Agentic Top 10 (2026).
21
+ - **`agentinel probe`** — an experimental, adaptive "attacker-moves-second" prompt-injection probe
22
+ running both goal-hijack and canary-exfiltration objectives. (Unit-tested with a scripted model;
23
+ not yet validated against a live model.)
24
+ - Outputs: rich terminal, JSON, **SARIF** (GitHub code scanning), and a self-contained **HTML dashboard**.
25
+ - **`agentinel-mcp`** — a read-only MCP server exposing a single `assess_tools` tool.
26
+ - A GitHub Action, a Pages-hosted demo, and a **35-server** real-world eval catalog.
27
+ - A capability-surface study of those 35 servers ([RESEARCH.md](RESEARCH.md)), reproducible via
28
+ `scripts/analyze_catalog.py`.
29
+
30
+ ### Fixed (post-audit hardening)
31
+ - Ordinary read + write servers no longer produce a false HIGH lethal-trifecta (write-tool read-gate).
32
+ - camelCase acronyms (e.g. `getAPIKey`) are split correctly for capability matching.
33
+ - Legitimate emoji (U+200D ZWJ) and ordinary tool docs no longer trip tool-poisoning detection.
34
+ - Rug-pull drift now fingerprints tool **annotations**, so a `readOnlyHint`/`destructiveHint` flip is caught.
35
+ - Tool-poisoning now scans **resource and prompt** descriptions, not only tool metadata.
36
+ - `--config` scans inherit and merge the process environment and expand `${VAR}`, so servers that
37
+ declare an API key launch correctly.
38
+ - Shadowing no longer false-fires on "When the user…" plus generic tool names.
39
+
40
+ [0.1.0]: https://github.com/markusweldon/agentinel
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Markus Weldon
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,250 @@
1
+ Metadata-Version: 2.5
2
+ Name: agentinel
3
+ Version: 0.1.0
4
+ Summary: Audit MCP servers and agent fleets for the lethal trifecta, tool poisoning, and leaked secrets, mapped to the OWASP Agentic Top 10 (2026).
5
+ Project-URL: Homepage, https://github.com/markusweldon/agentinel
6
+ Project-URL: Repository, https://github.com/markusweldon/agentinel
7
+ Project-URL: Issues, https://github.com/markusweldon/agentinel/issues
8
+ Project-URL: Changelog, https://github.com/markusweldon/agentinel/blob/main/CHANGELOG.md
9
+ Author: Markus Weldon
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: agentic-ai,ai-security,mcp,model-context-protocol,owasp,prompt-injection,red-team,security
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: Information Technology
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Security
24
+ Requires-Python: >=3.11
25
+ Requires-Dist: anthropic>=0.40
26
+ Requires-Dist: jinja2>=3.1
27
+ Requires-Dist: mcp<2,>=1.20
28
+ Requires-Dist: pydantic>=2.7
29
+ Requires-Dist: rich>=13.7
30
+ Requires-Dist: truststore>=0.8
31
+ Requires-Dist: typer>=0.12
32
+ Description-Content-Type: text/markdown
33
+
34
+ <div align="center">
35
+
36
+ <img alt="Agentinel" src="https://raw.githubusercontent.com/markusweldon/agentinel/main/docs/assets/logo.svg" width="480">
37
+
38
+ </div>
39
+
40
+ <br>
41
+
42
+ <img alt="Agentinel scanning GitHub's MCP server. Five of its tools on the three lethal-trifecta axes: list_issues reads untrusted input (A); get_file_contents and get_secret_scanning_alert read sensitive data (B); push_files reads sensitive data and takes an external action (B and C); create_pull_request reads untrusted input and takes an external action (A and C). The finding: HIGH, lethal trifecta, it reads untrusted issues and PRs, reads private repo data, and can push and merge. ASI02 Tool Misuse, the same exploit class disclosed in the real GitHub MCP attack. The scan is static and read-only and never calls a tool." src="https://raw.githubusercontent.com/markusweldon/agentinel/main/docs/assets/hero.svg" width="100%">
43
+
44
+ > **A sentinel for your AI agents.** Statically audit MCP servers and agent fleets for the **lethal trifecta**, tool poisoning, and leaked secrets — with findings mapped to the **OWASP Agentic Top 10 (2026)**. Plus an experimental adaptive red-team probe.
45
+
46
+ [![CI](https://github.com/markusweldon/agentinel/actions/workflows/ci.yml/badge.svg)](https://github.com/markusweldon/agentinel/actions/workflows/ci.yml)
47
+ [![PyPI](https://img.shields.io/pypi/v/agentinel.svg)](https://pypi.org/project/agentinel/)
48
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
49
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/markusweldon/agentinel/blob/main/LICENSE)
50
+ [![OWASP Agentic Top 10](https://img.shields.io/badge/OWASP-Agentic%20Top%2010%3A2026-red)](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)
51
+
52
+ AI assistants now connect to many MCP servers at once. Individually those servers are usually fine — but **wire enough of them together and you can accidentally hand one agent the "lethal trifecta": access to untrusted content + sensitive data + a way to send data out** — which is all a prompt injection needs to exfiltrate. Agentinel makes that capability surface visible and flags the concrete risks.
53
+
54
+ It builds directly on prior work — Simon Willison's [Lethal Trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/), Meta's [Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/), and the [OWASP Agentic Top 10](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/). It doesn't invent those ideas; it **operationalizes them** as an automatic check, so you don't have to threat-model your agent setup by hand.
55
+
56
+ **`agentinel scan`** (static, no API key, never runs your tools) reports:
57
+ - the **cross-server lethal trifecta** — when no single server is dangerous, but the *combination* you assembled is (the case that's easy to miss);
58
+ - concrete, fixable issues: **tool poisoning** (hidden instructions in a tool's metadata), **leaked secrets** in config, **rug-pull drift** (a tool's definition changing after you approved it), unsafe code-execution surfaces, over-broad permissions, and cross-server name shadowing;
59
+ - a per-tool **capability matrix** (Rule of Two) so you can see exactly where to break the trifecta.
60
+
61
+ <img alt="The cross-server lethal trifecta. Three MCP servers that are each safe alone: web-fetcher (fetch_doc) reads untrusted web pages (A), notes-reader (read_file, list_files) reads your notes (B), and slack-notifier (send_message) posts to Slack (C). One agent connected to all three holds every axis: a prompt injection in a fetched page can make it read your notes and post them to Slack, which no single server could do alone. Agentinel flags this as HIGH, ASI02. To break the trifecta, remove one axis, split the tools across isolated agents, or require approval for the external step." src="https://raw.githubusercontent.com/markusweldon/agentinel/main/docs/assets/trifecta.svg" width="100%">
62
+
63
+ **`agentinel probe`** is an **experimental** adaptive, "attacker-moves-second" red-team that drives a live agent against a server and tries to both hijack its goal and exfiltrate a planted canary. *(The loop is unit-tested with a scripted model; it has not yet been validated against a live model — treat its output as a starting point, not proof.)*
64
+
65
+ Findings map to an OWASP ASI category and export to terminal, JSON, **SARIF** (GitHub code scanning), and a self-contained **HTML dashboard**.
66
+
67
+ ### What it does well
68
+ - **Turns a known threat model into an automatic check.** No hand-reasoning about your agent's capability surface — you get a ranked report, including the *accidental cross-server* trifecta (individually-safe servers that combine into a real risk).
69
+ - **Validated on 35 real MCP servers (184 tools).** It correctly flags GitHub's server as a lethal trifecta — the same exploit class disclosed in the wild — and stays quiet on benign ones. That precision is regression-tested on every commit.
70
+ - **Surfaces concrete, fixable risks** in the servers it scans: tool poisoning, leaked secrets, rug-pull drift, and unsafe code-execution surfaces — each mapped to an OWASP ASI category with remediation.
71
+ - **Open and reproducible.** Free to run, read, and extend — the cross-server/fleet view and the adaptive live-server probe are open for anyone to study, reproduce, and build on.
72
+
73
+ The static `scan` covers the MCP-observable ASI categories (ASI01–05) and is fully tested. The `probe` is **experimental** — its loop is unit-tested but not yet validated against a live model — and it exercises ASI01–02 (goal hijack and canary exfiltration).
74
+
75
+ ---
76
+
77
+ ## 30-second demo — no setup, nothing external
78
+
79
+ ```bash
80
+ git clone https://github.com/markusweldon/agentinel && cd agentinel
81
+ uv sync
82
+ uv run agentinel scan --stdio "python fixtures/vulnerable/poisoned_server.py"
83
+ ```
84
+
85
+ ```
86
+ ╭─────────────────────────────────────╮
87
+ │ Agentinel — MCP security scan │
88
+ │ server: acme-devtools tools: 4 │
89
+ ╰─────────────────────────────────────╯
90
+ Capability matrix (Rule of Two)
91
+ Tool A B C
92
+ acme-devtools:fetch_url ● · ·
93
+ acme-devtools:read_notes · ● ·
94
+ acme-devtools:send_report · · ●
95
+ acme-devtools:run · · ●
96
+
97
+ Severity OWASP Class Target Title
98
+ HIGH ASI01 tool_poisoning acme-devtools:read_notes Hidden instructions in tool metadata
99
+ HIGH ASI02 lethal_trifecta server:acme-devtools Lethal Trifecta / Rule-of-Two violation
100
+ HIGH ASI05 unsafe_code_execution acme-devtools:run Unsafe code/command execution surface
101
+ ...
102
+ 6 findings (5 high, 1 medium) result: FAIL (--fail-on high)
103
+ ```
104
+
105
+ Add `--html report.html` for the dashboard pictured at the top of this README, or `--sarif findings.sarif` for GitHub's Security tab. Sample reports live in [`examples/`](https://github.com/markusweldon/agentinel/blob/main/examples/).
106
+
107
+ > **Viewing the dashboard.** GitHub can't render a committed `.html` inline, so the SVG banner above is the in-page preview. **The interactive dashboards are live at [markusweldon.github.io/agentinel](https://markusweldon.github.io/agentinel/)** — or open `examples/fleet-scan.html` locally.
108
+
109
+ ## Scan your own setup
110
+
111
+ ```bash
112
+ pip install agentinel # or: uv tool install agentinel
113
+ ```
114
+
115
+ Point `--config` at the MCP config your assistant already uses — Agentinel reads it, connects to every server you have installed, and analyzes their real tools as a fleet:
116
+
117
+ ```bash
118
+ agentinel scan --config ~/.cursor/mcp.json --html report.html
119
+ agentinel scan --config "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
120
+ ```
121
+
122
+ **Read-only by design.** A scan asks each server only for its capability list (`initialize` → `list_tools` / `list_resources` / `list_prompts`). It **never calls a tool** — there is no `call_tool` anywhere in the codebase — so nothing is sent, written, deleted, or executed. It reads tool *metadata* and analyzes text. (Starting a server to read its list runs that server's own startup, exactly as your assistant does every launch.)
123
+
124
+ ---
125
+
126
+ ## What this explores
127
+
128
+ Agentinel is an **open research project** into making agent/MCP risk *visible and automatic*. It focuses on two things that are easy to miss in a busy agent setup:
129
+
130
+ - the **accidental cross-server trifecta** — individually-safe servers that combine into a real exfiltration path; and
131
+ - an **adaptive probe aimed at the MCP tool surface** itself, not just the model endpoint.
132
+
133
+ Everything here is open and reproducible: read the detectors, run them against real servers, and extend the taxonomy. It's a starting point for reasoning about agent capability surfaces — not a finished verdict.
134
+
135
+ ## How the signature checks work
136
+
137
+ **Lethal Trifecta / Rule of Two.** Each tool is classified into three axes — **A** ingests untrusted content, **B** touches sensitive data/systems, **C** changes state or communicates externally — from MCP tool annotations (`openWorldHint`, `destructiveHint`, `readOnlyHint`) plus conservative keyword signals. Annotations may only *raise* risk, never clear it (a server's self-declared `readOnlyHint` is attacker-controllable). If a single tool — or the combined fleet — spans all three axes, any prompt injection can chain them into exfiltration. That's [Simon Willison's Lethal Trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) and [Meta's Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/).
138
+
139
+ **Adaptive probe (attacker moves second).** The probe wires the target's tools into a real agent holding a **planted canary secret**, then an *attacker LLM* crafts an injection — delivered through an untrusted-input tool's output (realistic indirect injection) or the user turn. If the agent doesn't leak the canary, the attacker reads the transcript and tries a **stronger, different** payload next round. Success is detected deterministically (canary in a tool call's arguments), so the verdict doesn't depend on a fallible judge. Per ["The Attacker Moves Second"](https://simonwillison.net/2025/Nov/2/new-prompt-injection-papers/): static benchmarks overstate robustness; adaptive attacks don't. Tools are never actually executed.
140
+
141
+ ## OWASP Agentic Top 10 (2026) coverage
142
+
143
+ | ASI | Category | Agentinel checks |
144
+ |---|---|---|
145
+ | ASI01 | Agent Goal Hijack | tool poisoning, adaptive prompt-injection probe |
146
+ | ASI02 | Tool Misuse & Exploitation | Lethal Trifecta (per-server + cross-server), canary-exfiltration probe |
147
+ | ASI03 | Identity & Privilege Abuse | excessive/wildcard permissions, secrets in config |
148
+ | ASI04 | Agentic Supply Chain | tool shadowing, rug-pull / unpinned server |
149
+ | ASI05 | Unexpected Code Execution | unsafe code/command-execution surface |
150
+ | ASI06–ASI10 | Memory poisoning · inter-agent comms · cascading failures · trust exploitation · rogue agents | roadmap |
151
+
152
+ v0.1 focuses on what is observable from MCP servers; the remaining categories (ASI06–ASI10) are on the roadmap. See [THREAT_MODEL.md](https://github.com/markusweldon/agentinel/blob/main/THREAT_MODEL.md) for the full attack-class → ASI mapping.
153
+
154
+ ## Evaluation
155
+
156
+ **Regression guard (own fixtures).** A labeled corpus (`fixtures/`) of deliberately vulnerable and benign-control servers; CI fails if recall drops or a clean control trips a finding:
157
+
158
+ ```bash
159
+ uv run pytest -q -s # [self-eval] recall=100% precision=100% (0 false positives)
160
+ ```
161
+
162
+ That proves the detectors don't regress — but it's Agentinel grading its own homework. The real test is tool definitions it *didn't* write:
163
+
164
+ **Real-world catalog.** [`fixtures/real-world/catalog.json`](https://github.com/markusweldon/agentinel/blob/main/fixtures/real-world/catalog.json) holds the published tool specs of **35 popular MCP servers** (copied from their docs, never executed). A representative slice of the verdicts (full aggregate in [RESEARCH.md](https://github.com/markusweldon/agentinel/blob/main/RESEARCH.md)):
165
+
166
+ | Server | Axes | Verdict |
167
+ |---|:--:|---|
168
+ | **GitHub** | A·B·C | 🔴 lethal trifecta — reads issues/PRs (untrusted), reads private repo + secret alerts, creates/pushes/merges |
169
+ | **Notion** | A·B·C | 🔴 lethal trifecta — reads comments + database (untrusted), writes pages |
170
+ | Puppeteer | A | 🟠 unsafe code execution — `evaluate` runs arbitrary JavaScript |
171
+ | Kubernetes | B·C | 🟠 code execution — `kubectl_generic` runs any command (also near-trifecta) |
172
+ | filesystem | B·C | 🟡 near-trifecta (reads + writes local files) |
173
+ | git | B·C | 🟡 near-trifecta |
174
+ | GitLab | B·C | 🟡 near-trifecta (write-focused — correctly *not* flagged as a full trifecta) |
175
+ | Slack | A·C | 🟡 near-trifecta (reads channel history, posts messages) |
176
+ | Stripe | B·C | 🟡 near-trifecta (financial data + money movement) |
177
+ | Sentry | A | ✅ clean (reads untrusted error content, but only one axis) |
178
+ | Postgres | B | ✅ clean (read-only query — *not* mis-flagged as code execution) |
179
+ | Google Drive | B | ✅ clean |
180
+ | fetch | A | ✅ clean |
181
+ | memory | C | ✅ clean |
182
+ | time | — | ✅ clean |
183
+
184
+ The GitHub verdict matches a [real-world GitHub MCP exploit disclosed in the wild](https://invariantlabs.ai/blog/mcp-github-vulnerability). Just as important is what Agentinel *doesn't* flag: GitLab (write-focused) is near-trifecta not full, Postgres's read-only `query` isn't called code execution, and fetch/time/memory/Sentry/Drive stay quiet — precision the real-world catalog regression-tests on every commit.
185
+
186
+ **Zoomed out** — across 35 popular MCP servers (184 tools), ~46% already span two or more trifecta axes and ~11% expose a code-execution surface. Full aggregate and method in [RESEARCH.md](https://github.com/markusweldon/agentinel/blob/main/RESEARCH.md) (reproduce with `uv run python scripts/analyze_catalog.py`).
187
+
188
+ ## CI / GitHub Action
189
+
190
+ Gate pull requests and upload findings to GitHub code scanning:
191
+
192
+ ```yaml
193
+ - uses: markusweldon/agentinel/.github/actions/agentinel-scan@main
194
+ with:
195
+ stdio: "npx -y @acme/mcp-server@1.4.2"
196
+ fail-on: high
197
+ ```
198
+
199
+ `agentinel scan` exits non-zero when a finding meets `--fail-on`, and `--sarif` output lands in the Security tab.
200
+
201
+ ## Session guard (research prototype)
202
+
203
+ Almost every useful agent holds the lethal trifecta, so "remove a leg" isn't advice anyone takes. The guard tests a different approach: a Claude Code hook that stays silent unless an outbound call is **carrying data the session read from a sensitive source**, after the session has also read untrusted input. It never grants a permission; it can only add a prompt.
204
+
205
+ On a first replay of real Claude Code sessions it asked **2 times in 88 outbound calls**, against 88 for asking before every outbound call. Asking for the whole session after any secret was touched still cost 83. The adaptive probe can now run with the guard on, to measure what gets through.
206
+
207
+ ```bash
208
+ agentinel guard replay # what would it cost on your own sessions? (local only)
209
+ agentinel guard install # prints the hook settings to add
210
+ ```
211
+
212
+ Method, results, what went wrong and the known gaps: [docs/guard.md](https://github.com/markusweldon/agentinel/blob/main/docs/guard.md).
213
+
214
+ ## Run it from inside your assistant
215
+
216
+ Agentinel also ships as an MCP server, so an assistant can audit tool definitions on demand:
217
+
218
+ ```bash
219
+ claude mcp add agentinel -- uvx --from agentinel agentinel-mcp
220
+ ```
221
+
222
+ It exposes one read-only tool, `assess_tools`, that analyzes tool metadata you pass it — it never launches or connects to anything (that footgun is exactly what Agentinel flags). Live scanning stays in the CLI, where a human supplies the target.
223
+
224
+ ## Architecture
225
+
226
+ ```
227
+ src/agentinel/
228
+ ├── mcp_client.py connect (stdio/HTTP) + enumerate tools/resources/prompts
229
+ ├── config.py parse .mcp.json / Cursor / Claude / VS Code configs
230
+ ├── taxonomy.py OWASP ASI01–10, severities, attack classes + metadata
231
+ ├── models.py Pydantic: CapabilityAxes, Finding, Report, ProbeReport
232
+ ├── static/ scan engine: classifier · trifecta · fleet · tool_poisoning · shadowing · capabilities
233
+ ├── dynamic/ probe engine: llm · harness · adaptive (attacker-moves-second)
234
+ ├── report/ terminal (rich) · sarif · html dashboard
235
+ ├── scanner.py static orchestration → Report
236
+ ├── prober.py adaptive probe orchestration → Report
237
+ └── server.py Agentinel's own (read-only) MCP server
238
+ ```
239
+
240
+ ## Ethics
241
+
242
+ The dynamic probe sends adversarial inputs to a running agent. **Only probe MCP servers you own or are explicitly authorized to test.** Agentinel never executes a target's tools and uses a synthetic canary rather than real secrets. See [ETHICS.md](https://github.com/markusweldon/agentinel/blob/main/ETHICS.md).
243
+
244
+ ## Brand
245
+
246
+ The logo and README images are generated by [`docs/brand/build.py`](https://github.com/markusweldon/agentinel/blob/main/docs/brand/build.py). See [docs/brand/README.md](https://github.com/markusweldon/agentinel/blob/main/docs/brand/README.md).
247
+
248
+ ## License
249
+
250
+ MIT — see [LICENSE](https://github.com/markusweldon/agentinel/blob/main/LICENSE).
@@ -0,0 +1,217 @@
1
+ <div align="center">
2
+
3
+ <img alt="Agentinel" src="docs/assets/logo.svg" width="480">
4
+
5
+ </div>
6
+
7
+ <br>
8
+
9
+ <img alt="Agentinel scanning GitHub's MCP server. Five of its tools on the three lethal-trifecta axes: list_issues reads untrusted input (A); get_file_contents and get_secret_scanning_alert read sensitive data (B); push_files reads sensitive data and takes an external action (B and C); create_pull_request reads untrusted input and takes an external action (A and C). The finding: HIGH, lethal trifecta, it reads untrusted issues and PRs, reads private repo data, and can push and merge. ASI02 Tool Misuse, the same exploit class disclosed in the real GitHub MCP attack. The scan is static and read-only and never calls a tool." src="docs/assets/hero.svg" width="100%">
10
+
11
+ > **A sentinel for your AI agents.** Statically audit MCP servers and agent fleets for the **lethal trifecta**, tool poisoning, and leaked secrets — with findings mapped to the **OWASP Agentic Top 10 (2026)**. Plus an experimental adaptive red-team probe.
12
+
13
+ [![CI](https://github.com/markusweldon/agentinel/actions/workflows/ci.yml/badge.svg)](https://github.com/markusweldon/agentinel/actions/workflows/ci.yml)
14
+ [![PyPI](https://img.shields.io/pypi/v/agentinel.svg)](https://pypi.org/project/agentinel/)
15
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
16
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
17
+ [![OWASP Agentic Top 10](https://img.shields.io/badge/OWASP-Agentic%20Top%2010%3A2026-red)](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)
18
+
19
+ AI assistants now connect to many MCP servers at once. Individually those servers are usually fine — but **wire enough of them together and you can accidentally hand one agent the "lethal trifecta": access to untrusted content + sensitive data + a way to send data out** — which is all a prompt injection needs to exfiltrate. Agentinel makes that capability surface visible and flags the concrete risks.
20
+
21
+ It builds directly on prior work — Simon Willison's [Lethal Trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/), Meta's [Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/), and the [OWASP Agentic Top 10](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/). It doesn't invent those ideas; it **operationalizes them** as an automatic check, so you don't have to threat-model your agent setup by hand.
22
+
23
+ **`agentinel scan`** (static, no API key, never runs your tools) reports:
24
+ - the **cross-server lethal trifecta** — when no single server is dangerous, but the *combination* you assembled is (the case that's easy to miss);
25
+ - concrete, fixable issues: **tool poisoning** (hidden instructions in a tool's metadata), **leaked secrets** in config, **rug-pull drift** (a tool's definition changing after you approved it), unsafe code-execution surfaces, over-broad permissions, and cross-server name shadowing;
26
+ - a per-tool **capability matrix** (Rule of Two) so you can see exactly where to break the trifecta.
27
+
28
+ <img alt="The cross-server lethal trifecta. Three MCP servers that are each safe alone: web-fetcher (fetch_doc) reads untrusted web pages (A), notes-reader (read_file, list_files) reads your notes (B), and slack-notifier (send_message) posts to Slack (C). One agent connected to all three holds every axis: a prompt injection in a fetched page can make it read your notes and post them to Slack, which no single server could do alone. Agentinel flags this as HIGH, ASI02. To break the trifecta, remove one axis, split the tools across isolated agents, or require approval for the external step." src="docs/assets/trifecta.svg" width="100%">
29
+
30
+ **`agentinel probe`** is an **experimental** adaptive, "attacker-moves-second" red-team that drives a live agent against a server and tries to both hijack its goal and exfiltrate a planted canary. *(The loop is unit-tested with a scripted model; it has not yet been validated against a live model — treat its output as a starting point, not proof.)*
31
+
32
+ Findings map to an OWASP ASI category and export to terminal, JSON, **SARIF** (GitHub code scanning), and a self-contained **HTML dashboard**.
33
+
34
+ ### What it does well
35
+ - **Turns a known threat model into an automatic check.** No hand-reasoning about your agent's capability surface — you get a ranked report, including the *accidental cross-server* trifecta (individually-safe servers that combine into a real risk).
36
+ - **Validated on 35 real MCP servers (184 tools).** It correctly flags GitHub's server as a lethal trifecta — the same exploit class disclosed in the wild — and stays quiet on benign ones. That precision is regression-tested on every commit.
37
+ - **Surfaces concrete, fixable risks** in the servers it scans: tool poisoning, leaked secrets, rug-pull drift, and unsafe code-execution surfaces — each mapped to an OWASP ASI category with remediation.
38
+ - **Open and reproducible.** Free to run, read, and extend — the cross-server/fleet view and the adaptive live-server probe are open for anyone to study, reproduce, and build on.
39
+
40
+ The static `scan` covers the MCP-observable ASI categories (ASI01–05) and is fully tested. The `probe` is **experimental** — its loop is unit-tested but not yet validated against a live model — and it exercises ASI01–02 (goal hijack and canary exfiltration).
41
+
42
+ ---
43
+
44
+ ## 30-second demo — no setup, nothing external
45
+
46
+ ```bash
47
+ git clone https://github.com/markusweldon/agentinel && cd agentinel
48
+ uv sync
49
+ uv run agentinel scan --stdio "python fixtures/vulnerable/poisoned_server.py"
50
+ ```
51
+
52
+ ```
53
+ ╭─────────────────────────────────────╮
54
+ │ Agentinel — MCP security scan │
55
+ │ server: acme-devtools tools: 4 │
56
+ ╰─────────────────────────────────────╯
57
+ Capability matrix (Rule of Two)
58
+ Tool A B C
59
+ acme-devtools:fetch_url ● · ·
60
+ acme-devtools:read_notes · ● ·
61
+ acme-devtools:send_report · · ●
62
+ acme-devtools:run · · ●
63
+
64
+ Severity OWASP Class Target Title
65
+ HIGH ASI01 tool_poisoning acme-devtools:read_notes Hidden instructions in tool metadata
66
+ HIGH ASI02 lethal_trifecta server:acme-devtools Lethal Trifecta / Rule-of-Two violation
67
+ HIGH ASI05 unsafe_code_execution acme-devtools:run Unsafe code/command execution surface
68
+ ...
69
+ 6 findings (5 high, 1 medium) result: FAIL (--fail-on high)
70
+ ```
71
+
72
+ Add `--html report.html` for the dashboard pictured at the top of this README, or `--sarif findings.sarif` for GitHub's Security tab. Sample reports live in [`examples/`](examples/).
73
+
74
+ > **Viewing the dashboard.** GitHub can't render a committed `.html` inline, so the SVG banner above is the in-page preview. **The interactive dashboards are live at [markusweldon.github.io/agentinel](https://markusweldon.github.io/agentinel/)** — or open `examples/fleet-scan.html` locally.
75
+
76
+ ## Scan your own setup
77
+
78
+ ```bash
79
+ pip install agentinel # or: uv tool install agentinel
80
+ ```
81
+
82
+ Point `--config` at the MCP config your assistant already uses — Agentinel reads it, connects to every server you have installed, and analyzes their real tools as a fleet:
83
+
84
+ ```bash
85
+ agentinel scan --config ~/.cursor/mcp.json --html report.html
86
+ agentinel scan --config "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
87
+ ```
88
+
89
+ **Read-only by design.** A scan asks each server only for its capability list (`initialize` → `list_tools` / `list_resources` / `list_prompts`). It **never calls a tool** — there is no `call_tool` anywhere in the codebase — so nothing is sent, written, deleted, or executed. It reads tool *metadata* and analyzes text. (Starting a server to read its list runs that server's own startup, exactly as your assistant does every launch.)
90
+
91
+ ---
92
+
93
+ ## What this explores
94
+
95
+ Agentinel is an **open research project** into making agent/MCP risk *visible and automatic*. It focuses on two things that are easy to miss in a busy agent setup:
96
+
97
+ - the **accidental cross-server trifecta** — individually-safe servers that combine into a real exfiltration path; and
98
+ - an **adaptive probe aimed at the MCP tool surface** itself, not just the model endpoint.
99
+
100
+ Everything here is open and reproducible: read the detectors, run them against real servers, and extend the taxonomy. It's a starting point for reasoning about agent capability surfaces — not a finished verdict.
101
+
102
+ ## How the signature checks work
103
+
104
+ **Lethal Trifecta / Rule of Two.** Each tool is classified into three axes — **A** ingests untrusted content, **B** touches sensitive data/systems, **C** changes state or communicates externally — from MCP tool annotations (`openWorldHint`, `destructiveHint`, `readOnlyHint`) plus conservative keyword signals. Annotations may only *raise* risk, never clear it (a server's self-declared `readOnlyHint` is attacker-controllable). If a single tool — or the combined fleet — spans all three axes, any prompt injection can chain them into exfiltration. That's [Simon Willison's Lethal Trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) and [Meta's Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/).
105
+
106
+ **Adaptive probe (attacker moves second).** The probe wires the target's tools into a real agent holding a **planted canary secret**, then an *attacker LLM* crafts an injection — delivered through an untrusted-input tool's output (realistic indirect injection) or the user turn. If the agent doesn't leak the canary, the attacker reads the transcript and tries a **stronger, different** payload next round. Success is detected deterministically (canary in a tool call's arguments), so the verdict doesn't depend on a fallible judge. Per ["The Attacker Moves Second"](https://simonwillison.net/2025/Nov/2/new-prompt-injection-papers/): static benchmarks overstate robustness; adaptive attacks don't. Tools are never actually executed.
107
+
108
+ ## OWASP Agentic Top 10 (2026) coverage
109
+
110
+ | ASI | Category | Agentinel checks |
111
+ |---|---|---|
112
+ | ASI01 | Agent Goal Hijack | tool poisoning, adaptive prompt-injection probe |
113
+ | ASI02 | Tool Misuse & Exploitation | Lethal Trifecta (per-server + cross-server), canary-exfiltration probe |
114
+ | ASI03 | Identity & Privilege Abuse | excessive/wildcard permissions, secrets in config |
115
+ | ASI04 | Agentic Supply Chain | tool shadowing, rug-pull / unpinned server |
116
+ | ASI05 | Unexpected Code Execution | unsafe code/command-execution surface |
117
+ | ASI06–ASI10 | Memory poisoning · inter-agent comms · cascading failures · trust exploitation · rogue agents | roadmap |
118
+
119
+ v0.1 focuses on what is observable from MCP servers; the remaining categories (ASI06–ASI10) are on the roadmap. See [THREAT_MODEL.md](THREAT_MODEL.md) for the full attack-class → ASI mapping.
120
+
121
+ ## Evaluation
122
+
123
+ **Regression guard (own fixtures).** A labeled corpus (`fixtures/`) of deliberately vulnerable and benign-control servers; CI fails if recall drops or a clean control trips a finding:
124
+
125
+ ```bash
126
+ uv run pytest -q -s # [self-eval] recall=100% precision=100% (0 false positives)
127
+ ```
128
+
129
+ That proves the detectors don't regress — but it's Agentinel grading its own homework. The real test is tool definitions it *didn't* write:
130
+
131
+ **Real-world catalog.** [`fixtures/real-world/catalog.json`](fixtures/real-world/catalog.json) holds the published tool specs of **35 popular MCP servers** (copied from their docs, never executed). A representative slice of the verdicts (full aggregate in [RESEARCH.md](RESEARCH.md)):
132
+
133
+ | Server | Axes | Verdict |
134
+ |---|:--:|---|
135
+ | **GitHub** | A·B·C | 🔴 lethal trifecta — reads issues/PRs (untrusted), reads private repo + secret alerts, creates/pushes/merges |
136
+ | **Notion** | A·B·C | 🔴 lethal trifecta — reads comments + database (untrusted), writes pages |
137
+ | Puppeteer | A | 🟠 unsafe code execution — `evaluate` runs arbitrary JavaScript |
138
+ | Kubernetes | B·C | 🟠 code execution — `kubectl_generic` runs any command (also near-trifecta) |
139
+ | filesystem | B·C | 🟡 near-trifecta (reads + writes local files) |
140
+ | git | B·C | 🟡 near-trifecta |
141
+ | GitLab | B·C | 🟡 near-trifecta (write-focused — correctly *not* flagged as a full trifecta) |
142
+ | Slack | A·C | 🟡 near-trifecta (reads channel history, posts messages) |
143
+ | Stripe | B·C | 🟡 near-trifecta (financial data + money movement) |
144
+ | Sentry | A | ✅ clean (reads untrusted error content, but only one axis) |
145
+ | Postgres | B | ✅ clean (read-only query — *not* mis-flagged as code execution) |
146
+ | Google Drive | B | ✅ clean |
147
+ | fetch | A | ✅ clean |
148
+ | memory | C | ✅ clean |
149
+ | time | — | ✅ clean |
150
+
151
+ The GitHub verdict matches a [real-world GitHub MCP exploit disclosed in the wild](https://invariantlabs.ai/blog/mcp-github-vulnerability). Just as important is what Agentinel *doesn't* flag: GitLab (write-focused) is near-trifecta not full, Postgres's read-only `query` isn't called code execution, and fetch/time/memory/Sentry/Drive stay quiet — precision the real-world catalog regression-tests on every commit.
152
+
153
+ **Zoomed out** — across 35 popular MCP servers (184 tools), ~46% already span two or more trifecta axes and ~11% expose a code-execution surface. Full aggregate and method in [RESEARCH.md](RESEARCH.md) (reproduce with `uv run python scripts/analyze_catalog.py`).
154
+
155
+ ## CI / GitHub Action
156
+
157
+ Gate pull requests and upload findings to GitHub code scanning:
158
+
159
+ ```yaml
160
+ - uses: markusweldon/agentinel/.github/actions/agentinel-scan@main
161
+ with:
162
+ stdio: "npx -y @acme/mcp-server@1.4.2"
163
+ fail-on: high
164
+ ```
165
+
166
+ `agentinel scan` exits non-zero when a finding meets `--fail-on`, and `--sarif` output lands in the Security tab.
167
+
168
+ ## Session guard (research prototype)
169
+
170
+ Almost every useful agent holds the lethal trifecta, so "remove a leg" isn't advice anyone takes. The guard tests a different approach: a Claude Code hook that stays silent unless an outbound call is **carrying data the session read from a sensitive source**, after the session has also read untrusted input. It never grants a permission; it can only add a prompt.
171
+
172
+ On a first replay of real Claude Code sessions it asked **2 times in 88 outbound calls**, against 88 for asking before every outbound call. Asking for the whole session after any secret was touched still cost 83. The adaptive probe can now run with the guard on, to measure what gets through.
173
+
174
+ ```bash
175
+ agentinel guard replay # what would it cost on your own sessions? (local only)
176
+ agentinel guard install # prints the hook settings to add
177
+ ```
178
+
179
+ Method, results, what went wrong and the known gaps: [docs/guard.md](docs/guard.md).
180
+
181
+ ## Run it from inside your assistant
182
+
183
+ Agentinel also ships as an MCP server, so an assistant can audit tool definitions on demand:
184
+
185
+ ```bash
186
+ claude mcp add agentinel -- uvx --from agentinel agentinel-mcp
187
+ ```
188
+
189
+ It exposes one read-only tool, `assess_tools`, that analyzes tool metadata you pass it — it never launches or connects to anything (that footgun is exactly what Agentinel flags). Live scanning stays in the CLI, where a human supplies the target.
190
+
191
+ ## Architecture
192
+
193
+ ```
194
+ src/agentinel/
195
+ ├── mcp_client.py connect (stdio/HTTP) + enumerate tools/resources/prompts
196
+ ├── config.py parse .mcp.json / Cursor / Claude / VS Code configs
197
+ ├── taxonomy.py OWASP ASI01–10, severities, attack classes + metadata
198
+ ├── models.py Pydantic: CapabilityAxes, Finding, Report, ProbeReport
199
+ ├── static/ scan engine: classifier · trifecta · fleet · tool_poisoning · shadowing · capabilities
200
+ ├── dynamic/ probe engine: llm · harness · adaptive (attacker-moves-second)
201
+ ├── report/ terminal (rich) · sarif · html dashboard
202
+ ├── scanner.py static orchestration → Report
203
+ ├── prober.py adaptive probe orchestration → Report
204
+ └── server.py Agentinel's own (read-only) MCP server
205
+ ```
206
+
207
+ ## Ethics
208
+
209
+ The dynamic probe sends adversarial inputs to a running agent. **Only probe MCP servers you own or are explicitly authorized to test.** Agentinel never executes a target's tools and uses a synthetic canary rather than real secrets. See [ETHICS.md](ETHICS.md).
210
+
211
+ ## Brand
212
+
213
+ The logo and README images are generated by [`docs/brand/build.py`](docs/brand/build.py). See [docs/brand/README.md](docs/brand/README.md).
214
+
215
+ ## License
216
+
217
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,19 @@
1
+ """Benign control: external comms (axis C) only — produces no findings on its own."""
2
+
3
+ import logging
4
+
5
+ logging.getLogger().setLevel(logging.WARNING)
6
+
7
+ from mcp.server.fastmcp import FastMCP # noqa: E402
8
+
9
+ mcp = FastMCP("notifier")
10
+
11
+
12
+ @mcp.tool()
13
+ def send_message(channel: str, text: str) -> str:
14
+ """Send a message to a chat channel."""
15
+ return ""
16
+
17
+
18
+ if __name__ == "__main__":
19
+ mcp.run()
@@ -0,0 +1,30 @@
1
+ """A benign MCP server used as a false-positive control in the eval corpus.
2
+
3
+ Read-only, no sensitive data, no external communication — should produce zero findings.
4
+ """
5
+
6
+ from mcp.server.fastmcp import FastMCP
7
+
8
+ mcp = FastMCP("echo-clean")
9
+
10
+
11
+ @mcp.tool()
12
+ def echo(text: str) -> str:
13
+ """Echo back the provided text unchanged."""
14
+ return text
15
+
16
+
17
+ @mcp.tool()
18
+ def add(a: int, b: int) -> int:
19
+ """Add two integers and return their sum."""
20
+ return a + b
21
+
22
+
23
+ @mcp.tool()
24
+ def word_count(text: str) -> int:
25
+ """Count the number of whitespace-separated words in the given text."""
26
+ return len(text.split())
27
+
28
+
29
+ if __name__ == "__main__":
30
+ mcp.run()
@@ -0,0 +1,25 @@
1
+ """Benign control: pulls external content (axis A) only — should produce zero findings."""
2
+
3
+ import logging
4
+
5
+ logging.getLogger().setLevel(logging.WARNING)
6
+
7
+ from mcp.server.fastmcp import FastMCP # noqa: E402
8
+
9
+ mcp = FastMCP("docs-fetcher")
10
+
11
+
12
+ @mcp.tool()
13
+ def fetch_doc(url: str) -> str:
14
+ """Fetch a public documentation page by URL and return its text."""
15
+ return ""
16
+
17
+
18
+ @mcp.tool()
19
+ def search_docs(query: str) -> str:
20
+ """Look up a topic in the public documentation index."""
21
+ return ""
22
+
23
+
24
+ if __name__ == "__main__":
25
+ mcp.run()