shadow-mcp 0.1.0__tar.gz

shadow_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      # All deps (incl. the mcp-audits + mcp-trust grading engines) now resolve
+      # from PyPI, so a plain sync installs the full grading path. The engine-backed
+      # tests run for real here — config-only scans with no live targets. (The one
+      # real-spawn connected test is gated behind SHADOW_MCP_RUN_CONNECT and stays
+      # skipped.)
+      - name: Install
+        run: uv sync
+
+      - name: Lint
+        run: uv run --no-sync ruff check .
+
+      - name: Test
+        run: uv run --no-sync pytest

shadow_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read   # checkout needs read on this (private) repo
+      id-token: write  # OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.11"
+
+      # Gate the release on the test suite: a broken tag must not publish. The
+      # grading engines resolve from PyPI now, so the full suite (engine-backed
+      # tests included) runs as the gate.
+      - name: Test gate
+        run: uv run pytest -q
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

shadow_mcp-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+# shadow-mcp is a published library: consumers (and `uvx`) resolve deps fresh
+# from PyPI, so we don't pin a lock. The old committed lock encoded editable
+# local path-sources (../MCPAudit) that only resolved on one machine anyway.
+uv.lock
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.DS_Store
+# never commit a captured inventory of a real machine
+/out/
+*.inventory.json

shadow_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: shadow-mcp
+Version: 0.1.0
+Summary: Discover and risk-grade the MCP servers actually present on this machine. Local-first shadow-MCP inventory.
+Author: Saagar Patel
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: mcp-audits>=2.2.3
+Requires-Dist: mcp-trust>=0.1.0
+Requires-Dist: mcp<2,>=1.27.0
+Requires-Dist: pydantic>=2
+Requires-Dist: rich>=13
+Description-Content-Type: text/markdown
+
+# shadow-mcp
+<!-- mcp-name: io.github.saagpatel/shadow-mcp -->
+
+Discover and risk-grade the MCP servers actually present on **this** machine.
+
+Most MCP security tooling assumes you already have a list of servers to audit.
+On a real developer machine you don't: servers are scattered across Claude Code,
+Codex, Claude Desktop, project-local `.mcp.json` files, DXT extensions, and live
+processes that bind no port. shadow-mcp finds them first, then grades them.
+
+This is the local-first answer to **OWASP MCP09:2025 — Shadow MCP Servers**.
+
+## What it does
+
+```
+discover  ->  inventory  ->  risk-grade  ->  report
+```
+
+1. **Discover** (read-only) every place an MCP server is declared or running:
+   Claude Code (`~/.claude.json`, user + project scope), `claude mcp list`
+   (catches remote + plugin servers no file contains), Codex
+   (`~/.codex/config.toml` + profiles), project `.mcp.json`, Claude Desktop
+   config + DXT extension manifests, and the live process table.
+2. **Inventory**: merge sightings into one entry per logical server, even when a
+   server appears under different names across hosts (`personal-ops` vs
+   `personal_ops`), tracking every provenance.
+3. **Risk-grade** by **delegating** to the existing engines rather than
+   reimplementing them:
+   - [MCPAudit](../MCPAudit) for a 0-10 capability composite + injection findings
+   - [mcp-trust](../mcp-trust) for an authoritative A-F danger grade (when known)
+   - a thin local layer for the config-shaped OWASP dimensions the engines under-cover
+     (secrets/MCP01, supply-chain provenance/MCP04, transport exposure/MCP07).
+4. **Report**: a ranked terminal table, a machine-readable JSON inventory, or
+   markdown — plus a **Shadow & attention** section for the deltas that matter
+   (running-but-unconfigured, broad blast radius, capable-but-ungraded).
+
+The risk model and its OWASP mapping live in [docs/risk-model.md](docs/risk-model.md).
+
+## Install
+
+```bash
+uv sync                 # installs deps incl. MCPAudit as a local editable engine
+```
+
+shadow-mcp grades against your local checkouts of MCPAudit (`../MCPAudit`) and
+mcp-trust (`../mcp-trust/registry.db`). Override with `SHADOW_MCP_MCPTRUST_DB`
+or `--registry-db`.
+
+## Use
+
+```bash
+uv run shadow-mcp scan                      # full pipeline, terminal report
+uv run shadow-mcp scan --json out.json      # machine-readable inventory
+uv run shadow-mcp scan --format markdown    # markdown report
+uv run shadow-mcp discover                  # inventory only, no grading
+uv run shadow-mcp sources                   # per-collector counts
+uv run shadow-mcp grade-missing             # A-F for servers the registry hasn't scanned
+uv run shadow-mcp deep-scan cost-tracker    # connect to a server, grade its real tools
+```
+
+Useful flags: `--no-processes` (skip the live process scan), `--no-cli` (skip
+`claude mcp list`), `--no-mcpaudit` (inventory + mcp-trust only), `--home PATH`
+(point discovery at a fixture tree).
+
+### Static vs connected grading
+
+By default grading is **static** (config-only): no server is spawned, so grades
+reflect what's visible in the config. That's safe but coarse — a server's real
+capability only shows once you connect and list its tools.
+
+`shadow-mcp scan --connect` (or `deep-scan [names...]`) **spawns** each stdio
+server and enumerates its real tools, delegating to MCPAudit's connected engine
+for a capability grade that actually differentiates (a filesystem server jumps
+from a static `A` to a connected `D`). This is **opt-in** because connecting
+executes the server; remote endpoints are never spawned (that's the network-scan
+tier), and a server that needs real secrets to start falls back to its static
+grade.
+
+## Development
+
+```bash
+uv sync                       # dev tools + grading engines (the default groups)
+uv run pytest                 # full suite (61 + engine-backed tests)
+uv run ruff check .           # lint
+```
+
+The grading engines are an optional `engines` dependency-group, resolved to your
+local checkouts of `../MCPAudit` and `../mcp-trust` via `[tool.uv.sources]`. The
+tool degrades to discovery-only without them (engine-backed tests skip cleanly),
+so CI installs without them:
+
+```bash
+uv sync --no-group engines    # discovery + local OWASP layer only (what CI runs)
+```
+
+## Safety
+
+- **Read-only discovery.** Collectors parse configs and list processes; nothing
+  they find is ever mutated. (`--connect`/`deep-scan` is the one path that
+  *executes* servers, and only when you explicitly ask.)
+- **Secrets stay out.** We record env variable *names* (to flag secret-bearing
+  servers per MCP01) but never their values. A captured inventory still contains
+  real local paths and hostnames, so treat `*.inventory.json` as private (it is
+  git-ignored by default).
+
+## Use as an MCP server
+
+shadow-mcp can serve its own inventory tools as an MCP server so an agent can
+query your local MCP surface without leaving the conversation.
+
+### Tools
+
+| Tool | Description |
+|---|---|
+| `scan_local` | Full pipeline (discover → inventory → grade → report). Returns JSON. |
+| `discover_local` | Inventory every MCP server without grading. Returns JSON. |
+| `deep_scan` | Grade only the named servers (static, no spawning). Accepts `names: list[str]`. Returns JSON. |
+| `list_sources` | Per-collector source counts from a discover run. Returns JSON. |
+
+### Run the server
+
+```bash
+# directly from a local checkout
+shadow-mcp mcp-serve
+
+# via uvx (once published to PyPI)
+uvx shadow-mcp mcp-serve
+```
+
+**LOCAL only.** The MCP server never connects to hosted MCP endpoints — all
+grading is static (config-based). `connect=False` is enforced unconditionally;
+no server is ever spawned from an MCP tool call.
+
+## Scope
+
+This is the **local-first** tool: it inventories one machine from its configs
+and processes. A later network-scan expansion (probing hosts/ports for remote
+MCP endpoints, org-wide fleet inventory, typosquat-distance provenance checks)
+is deliberately out of scope here — see the bottom of `docs/risk-model.md` and
+the project notes for what that would add.

shadow_mcp-0.1.0/README.md

@@ -0,0 +1,140 @@
+# shadow-mcp
+<!-- mcp-name: io.github.saagpatel/shadow-mcp -->
+
+Discover and risk-grade the MCP servers actually present on **this** machine.
+
+Most MCP security tooling assumes you already have a list of servers to audit.
+On a real developer machine you don't: servers are scattered across Claude Code,
+Codex, Claude Desktop, project-local `.mcp.json` files, DXT extensions, and live
+processes that bind no port. shadow-mcp finds them first, then grades them.
+
+This is the local-first answer to **OWASP MCP09:2025 — Shadow MCP Servers**.
+
+## What it does
+
+```
+discover  ->  inventory  ->  risk-grade  ->  report
+```
+
+1. **Discover** (read-only) every place an MCP server is declared or running:
+   Claude Code (`~/.claude.json`, user + project scope), `claude mcp list`
+   (catches remote + plugin servers no file contains), Codex
+   (`~/.codex/config.toml` + profiles), project `.mcp.json`, Claude Desktop
+   config + DXT extension manifests, and the live process table.
+2. **Inventory**: merge sightings into one entry per logical server, even when a
+   server appears under different names across hosts (`personal-ops` vs
+   `personal_ops`), tracking every provenance.
+3. **Risk-grade** by **delegating** to the existing engines rather than
+   reimplementing them:
+   - [MCPAudit](../MCPAudit) for a 0-10 capability composite + injection findings
+   - [mcp-trust](../mcp-trust) for an authoritative A-F danger grade (when known)
+   - a thin local layer for the config-shaped OWASP dimensions the engines under-cover
+     (secrets/MCP01, supply-chain provenance/MCP04, transport exposure/MCP07).
+4. **Report**: a ranked terminal table, a machine-readable JSON inventory, or
+   markdown — plus a **Shadow & attention** section for the deltas that matter
+   (running-but-unconfigured, broad blast radius, capable-but-ungraded).
+
+The risk model and its OWASP mapping live in [docs/risk-model.md](docs/risk-model.md).
+
+## Install
+
+```bash
+uv sync                 # installs deps incl. MCPAudit as a local editable engine
+```
+
+shadow-mcp grades against your local checkouts of MCPAudit (`../MCPAudit`) and
+mcp-trust (`../mcp-trust/registry.db`). Override with `SHADOW_MCP_MCPTRUST_DB`
+or `--registry-db`.
+
+## Use
+
+```bash
+uv run shadow-mcp scan                      # full pipeline, terminal report
+uv run shadow-mcp scan --json out.json      # machine-readable inventory
+uv run shadow-mcp scan --format markdown    # markdown report
+uv run shadow-mcp discover                  # inventory only, no grading
+uv run shadow-mcp sources                   # per-collector counts
+uv run shadow-mcp grade-missing             # A-F for servers the registry hasn't scanned
+uv run shadow-mcp deep-scan cost-tracker    # connect to a server, grade its real tools
+```
+
+Useful flags: `--no-processes` (skip the live process scan), `--no-cli` (skip
+`claude mcp list`), `--no-mcpaudit` (inventory + mcp-trust only), `--home PATH`
+(point discovery at a fixture tree).
+
+### Static vs connected grading
+
+By default grading is **static** (config-only): no server is spawned, so grades
+reflect what's visible in the config. That's safe but coarse — a server's real
+capability only shows once you connect and list its tools.
+
+`shadow-mcp scan --connect` (or `deep-scan [names...]`) **spawns** each stdio
+server and enumerates its real tools, delegating to MCPAudit's connected engine
+for a capability grade that actually differentiates (a filesystem server jumps
+from a static `A` to a connected `D`). This is **opt-in** because connecting
+executes the server; remote endpoints are never spawned (that's the network-scan
+tier), and a server that needs real secrets to start falls back to its static
+grade.
+
+## Development
+
+```bash
+uv sync                       # dev tools + grading engines (the default groups)
+uv run pytest                 # full suite (61 + engine-backed tests)
+uv run ruff check .           # lint
+```
+
+The grading engines are an optional `engines` dependency-group, resolved to your
+local checkouts of `../MCPAudit` and `../mcp-trust` via `[tool.uv.sources]`. The
+tool degrades to discovery-only without them (engine-backed tests skip cleanly),
+so CI installs without them:
+
+```bash
+uv sync --no-group engines    # discovery + local OWASP layer only (what CI runs)
+```
+
+## Safety
+
+- **Read-only discovery.** Collectors parse configs and list processes; nothing
+  they find is ever mutated. (`--connect`/`deep-scan` is the one path that
+  *executes* servers, and only when you explicitly ask.)
+- **Secrets stay out.** We record env variable *names* (to flag secret-bearing
+  servers per MCP01) but never their values. A captured inventory still contains
+  real local paths and hostnames, so treat `*.inventory.json` as private (it is
+  git-ignored by default).
+
+## Use as an MCP server
+
+shadow-mcp can serve its own inventory tools as an MCP server so an agent can
+query your local MCP surface without leaving the conversation.
+
+### Tools
+
+| Tool | Description |
+|---|---|
+| `scan_local` | Full pipeline (discover → inventory → grade → report). Returns JSON. |
+| `discover_local` | Inventory every MCP server without grading. Returns JSON. |
+| `deep_scan` | Grade only the named servers (static, no spawning). Accepts `names: list[str]`. Returns JSON. |
+| `list_sources` | Per-collector source counts from a discover run. Returns JSON. |
+
+### Run the server
+
+```bash
+# directly from a local checkout
+shadow-mcp mcp-serve
+
+# via uvx (once published to PyPI)
+uvx shadow-mcp mcp-serve
+```
+
+**LOCAL only.** The MCP server never connects to hosted MCP endpoints — all
+grading is static (config-based). `connect=False` is enforced unconditionally;
+no server is ever spawned from an MCP tool call.
+
+## Scope
+
+This is the **local-first** tool: it inventories one machine from its configs
+and processes. A later network-scan expansion (probing hosts/ports for remote
+MCP endpoints, org-wide fleet inventory, typosquat-distance provenance checks)
+is deliberately out of scope here — see the bottom of `docs/risk-model.md` and
+the project notes for what that would add.

shadow_mcp-0.1.0/docs/future-network-scan.md

@@ -0,0 +1,48 @@
+# Future: the network-scan expansion
+
+shadow-mcp is deliberately **local-first**. It inventories one machine by reading
+its configs and process table, and it is immediately useful and dogfoodable for
+exactly that. This note records what a later **network-scan** tier would add, so
+the boundary is a decision and not an accident. None of this is built yet.
+
+## What local-first already covers
+
+- Every config host on this machine (Claude Code, Codex, Claude Desktop, DXT,
+  project `.mcp.json`) plus the live process table.
+- Per-server capability grade (MCPAudit), A-F danger grade (mcp-trust), and the
+  config-shaped OWASP layer: secrets (MCP01), transport exposure (MCP07),
+  blast radius and shadow deltas (MCP09).
+
+## What a network-scan tier would add
+
+1. **Remote/host discovery (the org dimension).** Probe a host list or CIDR
+   range for listening MCP endpoints (HTTP/SSE) that no local config references.
+   This is the true "shadow IT" inventory across many machines, vs one machine's
+   configs. Needs: a target list, an async port/endpoint prober, an MCP
+   handshake probe (`initialize`) to confirm a port is really MCP.
+2. **Live capability enumeration.** Connect to each server and list its actual
+   `tools` / `resources` / `prompts`, instead of grading from the launch config.
+   This unlocks the *connected* half of MCPAudit (drift, escalation, provenance,
+   integrity, tool-poisoning in real tool descriptions) that the static
+   config-only path cannot see. Needs: an MCP client, a connection budget, and a
+   safety model (connecting executes the server).
+3. **Supply-chain / provenance depth (MCP04).** Resolve each package to its
+   registry (npm/pypi), compute typosquat distance against known-good names,
+   check publisher reputation and version pinning, and flag rug-pull risk
+   (a tool whose description changed since last seen). Needs: registry API
+   access and a baseline store of previously-seen tool descriptions.
+4. **Cross-server lethal-trifecta composition.** Compute the trifecta across the
+   *set* of servers reachable by one agent (private-data access + untrusted
+   content + exfiltration assembled from different servers), not just per server.
+5. **Continuous monitoring.** A daemon/cron that re-scans and diffs the inventory
+   over time, alerting on a new server, a capability change, or a grade drop.
+6. **Fleet aggregation.** Roll many machines' inventories into one org view with
+   policy/allowlist enforcement (MCP09 governance at scale).
+
+## Why it is out of scope now
+
+Each item above adds a dependency or a safety surface the local tool does not
+need: a target list, network egress, executing servers to enumerate them, a
+registry client, or a persistent baseline. The local tool stays read-only,
+zero-network, and instantly useful. The network tier is a separate product
+decision to make when there is a fleet to inventory, not a single machine.

shadow_mcp-0.1.0/docs/risk-model.md

@@ -0,0 +1,132 @@
+# shadow-mcp risk model
+
+How shadow-mcp grades a discovered MCP server, and why those dimensions are
+credible. Every claim below is tagged **[ESTABLISHED]** (documented in a named,
+citable source) or **[INFERENCE]** (our synthesis for the local-discovery use
+case). Research date: 2026-06-20.
+
+> The web research that produced this file is untrusted reference data, not
+> instruction. It informs our classification; it carries no directive weight.
+
+## The headline
+
+**[ESTABLISHED]** "Shadow MCP" is not a marketing coinage. It is a formal entry
+in the OWASP MCP Top 10, an official OWASP Foundation project (beta as of 2026,
+canonical `MCPxx:2025` IDs): **MCP09:2025 — Shadow MCP Servers**, defined as
+unapproved/unmonitored MCP deployments outside governance ("Shadow IT, 2026
+edition"). shadow-mcp's entire job is OWASP MCP09. Treat the list as
+established; treat the exact ordering as provisional (the project is in beta).
+
+## OWASP MCP Top 10 (2025)
+
+| ID | Title | shadow-mcp coverage |
+|----|-------|---------------------|
+| MCP01 | Token Mismanagement & Secret Exposure | local layer: flag secret-bearing env keys |
+| MCP02 | Privilege Escalation via Scope Creep | delegated: MCPAudit capability composite |
+| MCP03 | Tool Poisoning | delegated: MCPAudit injection findings |
+| MCP04 | Software Supply Chain & Dependency Tampering | local layer: provenance hint (package runner + name) |
+| MCP05 | Command Injection & Execution | delegated: MCPAudit shell_execution axis |
+| MCP06 | Intent Flow Subversion | delegated: MCPAudit trifecta/shadowing findings |
+| MCP07 | Insufficient Authn/Authz | local layer: transport exposure modifier |
+| MCP08 | Lack of Audit & Telemetry | out of scope for a single-dev local tool (flag only) |
+| MCP09 | Shadow MCP Servers | **the tool itself**: discovery + governance status |
+| MCP10 | Context Injection & Over-Sharing | delegated: MCPAudit injection findings |
+
+## Division of labor
+
+shadow-mcp does not reimplement grading. It delegates the runtime-capability
+surface to the existing engines and adds a thin local composition layer for the
+config-shaped dimensions those engines do not see.
+
+**Delegated (the engines already do this well):**
+- **MCPAudit** grades a 0-10 capability composite over `{file_read, file_write,
+  network, shell_execution, destructive, exfiltration}` plus injection / SSRF /
+  trifecta findings. Covers MCP02, MCP03, MCP05, MCP06, MCP10 and the capability
+  half of the lethal trifecta. **[ESTABLISHED]**
+- **mcp-trust** gives an A-F danger grade weighting shell + file access highest.
+  Authoritative letter grade when the server is in its registry. **[ESTABLISHED]**
+
+**Local composition layer (what the engines under-cover, and what a local tool
+is best placed to inspect):**
+1. **Secret / token handling (MCP01).** **[INFERENCE]** The engines grade tool
+   *capability*, not launch *config*. shadow-mcp reads the server's declared env
+   var **names** (never values) and flags secret-bearing keys. OWASP ranks this #1.
+2. **Provenance / supply chain (MCP04).** **[INFERENCE]** Neither engine grades
+   where the package came from. shadow-mcp records the package-runner + package
+   name as a provenance hint (a full typosquat-distance check is future work; see
+   the network-scan expansion note).
+3. **Transport exposure (MCP07).** **[INFERENCE]** stdio (local-only, pipe-attached)
+   vs HTTP/SSE (network-reachable, confused-deputy + session-hijack surface)
+   materially changes blast radius. Used as a risk modifier, not a base score.
+4. **Governance / inventory status (MCP09).** **[ESTABLISHED]** the category;
+   **[INFERENCE]** that it should be surfaced explicitly. shadow-mcp reports
+   blast radius (how many hosts declare a server) and the shadow deltas
+   (running-but-unconfigured, configured-everywhere, capable-but-ungraded).
+
+## The lethal trifecta
+
+**[ESTABLISHED]** Origin: Simon Willison, 2025-06-16. A system is acutely
+dangerous when it simultaneously has private-data access + untrusted-content
+exposure + an exfiltration channel. **[INFERENCE]** For shadow-mcp the important
+adaptation is that the trifecta is frequently assembled across *several* servers
+on one client, not within one server. MCPAudit emits per-server trifecta
+findings; composing the trifecta across the installed set is future work.
+
+## How the band is computed
+
+The sortable band (critical / high / medium / low / unknown) is derived from the
+MCPAudit composite as the base, then adjusted:
+- base: composite >= 7 critical, >= 5 high, >= 3.5 medium, > 0 low, else unknown
+- mcp-trust grade of F or D raises the band by one step (authoritative danger signal)
+- an HTTP/SSE transport raises a low/medium band by one step (MCP07 exposure)
+- the assessment's `reasons` cite the OWASP ID behind each contribution
+
+This keeps the numeric grade delegated and explainable while letting the local
+layer (secrets, transport, provenance, governance) shape the final verdict with
+cited justification.
+
+## Registry vs computed A-F grades
+
+mcp-trust only stores grades for servers someone has already scanned and seeded
+(a handful). Every other discovered server gets a **computed** A-F letter: we
+feed MCPAudit's static dimensions into mcp-trust's own `grade()` (its danger
+weighting + critical cap), so the letter comes from mcp-trust's logic, not a
+reimplementation, and without writing to its database. Computed grades are
+marked with a trailing `~` and flagged `computed: true`.
+
+**Honest caveat (the transparency axis).** A computed grade is derived from
+*static config only* (no connection, no live tool enumeration), so for stdio
+servers launched via wrappers/npx, MCPAudit sees little and most letters land at
+**A**. Per mcp-trust's own transparency model, that is `transparency: low` —
+"cannot verify safe", **not** "verified safe". So a computed `A~` means "no
+capability risk detectable from config alone." The **band** (not the letter)
+carries the differentiated signal, because the band folds in the local OWASP
+layer (transport/MCP07, secrets/MCP01, blast radius/MCP09).
+
+**Connected grading (`--connect` / `deep-scan`).** To populate the capability
+dimensions for real, shadow-mcp can spawn a stdio server and enumerate its tools,
+delegating to MCPAudit's connected engine. This moves a server off the static
+`A` floor (a filesystem server connected-grades to `D`), so the computed letter
+becomes meaningful. It is opt-in because connecting executes the server; remote
+endpoints are never spawned (that is the network-scan tier), and a server that
+needs real secrets to start falls back to its static grade. A connected grade is
+flagged `connected: true` with the tool count in its reason line.
+
+## Scale context (vendor-sourced, treat as directional)
+
+**[ESTABLISHED, vendor-sourced]** Wallarm 2026 reported 315 MCP-related vulns in
+2025; Palo Alto Unit 42 reported a 78.3% attack-success rate against one
+compromised server among five connected; CVE-2025-49596 (CVSS 9.4) was
+unauthenticated RCE via MCP Inspector. Much of the scale framing comes from
+vendors selling MCP-security products, so treat specific percentages as
+directional rather than precise.
+
+## Citations
+
+- OWASP MCP Top 10: https://owasp.org/www-project-mcp-top-10/
+- OWASP MCP09 Shadow MCP Servers: https://owasp.org/www-project-mcp-top-10/2025/MCP09-2025%E2%80%93Shadow-MCP-Servers
+- OWASP MCP Security Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/MCP_Security_Cheat_Sheet.html
+- Lethal trifecta (Willison, 2025-06-16): https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/
+- MCP Spec security best practices (2025-06-18): https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices
+- Invariant Labs, tool poisoning: https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks
+- Mend.io, Shadow MCP: https://www.mend.io/blog/shadow-mcp-unauthorized-ai-connectivity-in-your-codebase/

shadow_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "shadow-mcp"
+version = "0.1.0"
+description = "Discover and risk-grade the MCP servers actually present on this machine. Local-first shadow-MCP inventory."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Saagar Patel" }]
+dependencies = [
+    "pydantic>=2",
+    "rich>=13",
+    "mcp>=1.27.0,<2",
+    # Grading engines, resolved from PyPI. mcp-audits provides the static
+    # capability analyzer (mcp_audit.api.scan_config_only_dict); mcp-trust
+    # provides the A-F danger-grade logic (mcp_trust.core.grading.grade). Both
+    # are imported lazily (try/except ImportError) so a partial install degrades
+    # to discovery-only rather than crashing — but a normal `uvx shadow-mcp`
+    # install pulls them from PyPI and grades fully. The mcp cap stays <2 so a
+    # fresh uvx resolve can't pull a v2 alpha that breaks the FastMCP API.
+    "mcp-audits>=2.2.3",
+    "mcp-trust>=0.1.0",
+]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+shadow-mcp = "shadow_mcp.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shadow_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+# Test fixtures reproduce real `ps`/CLI output lines verbatim; wrapping them
+# would corrupt the data under test.
+"tests/**" = ["E501"]

shadow_mcp-0.1.0/server.json

@@ -0,0 +1,22 @@
+{
+	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+	"name": "io.github.saagpatel/shadow-mcp",
+	"title": "shadow-mcp",
+	"description": "Local MCP server that inventories and risk-grades MCP servers configured on this machine.",
+	"repository": {
+		"url": "https://github.com/saagpatel/shadow-mcp",
+		"source": "github"
+	},
+	"version": "0.1.0",
+	"packages": [
+		{
+			"registryType": "pypi",
+			"registryBaseUrl": "https://pypi.org",
+			"identifier": "shadow-mcp",
+			"version": "0.1.0",
+			"runtimeHint": "uvx",
+			"transport": { "type": "stdio" },
+			"packageArguments": [{ "type": "positional", "value": "mcp-serve" }]
+		}
+	]
+}

shadow_mcp-0.1.0/src/shadow_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""shadow-mcp: discover and risk-grade the MCP servers present on this machine.
+
+Discovery is strictly read-only: collectors parse configs and list processes,
+and never mutate anything they find. Risk-grading delegates to the existing
+engines (MCPAudit for a 0-10 capability composite, mcp-trust for an A-F danger
+grade) rather than reimplementing them.
+"""
+
+__version__ = "0.1.0"