# ToolTrust Scanner **Category:** πŸ’» Developer Tools **Repository:** https://github.com/AgentSafe-AI/tooltrust-scanner **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/tooltrust-scanner ## Description Scans MCP servers for prompt injection, data exfiltration, and privilege escalation. ## Claude Desktop Quick Installation Heuristic fallback β€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "tooltrust-scanner": { "command": "npx", "args": ["-y","tooltrust-scanner"] } } ``` ## Documentation & README

ToolTrust

ToolTrust Scanner

Static security scanner for MCP tool definitions
Trust grades (A–F) before your agent calls a tool β€” run as an MCP server, CLI, or CI check.

CI Security Go Report Card License: MIT GitHub stars

--- Every MCP tool your agent calls is an attack surface β€” prompt injection, data exfiltration, privilege escalation, supply-chain backdoors. ToolTrust scans tool definitions *before* your agent trusts them and assigns a trust grade (A–F) so you know the risk. ToolTrust is an **MCP Server** and a **CLI/CI tool** β€” not a host, gateway, or runtime proxy. Coverage is expanding beyond today’s MCP-focused workflows; **skills** and additional agent tool formats are on the roadmap.

Browse the live ToolTrust Directory β€” trust grades and scan-backed reports before you install.

ToolTrust Directory UI

MCP demo: run a full config scan from your agent.

![ToolTrust MCP demo](docs/mcp-demo.gif) ## Scan your setup in 30 seconds Add ToolTrust as an MCP server and let your agent audit its own tools (stdio transport β€” no network listener; your host launches it as a subprocess): ```json { "mcpServers": { "tooltrust": { "command": "npx", "args": ["-y", "tooltrust-mcp"] } } } ``` Then ask your agent: *"Run tooltrust_scan_config"* It reads your MCP config, connects to each server in parallel, scans every tool, and returns a risk report with grades and enforcement decisions β€” all in seconds. Or use the CLI: ```bash curl -sfL https://raw.githubusercontent.com/AgentSafe-AI/tooltrust-scanner/main/install.sh | bash tooltrust-scanner scan --server "npx -y @modelcontextprotocol/server-filesystem /tmp" ``` ## Example snapshot (research cohort) The public **[ToolTrust Directory](https://www.tooltrust.dev/)** holds **current** grades and aggregates as scanning scales. One published research pass illustrates the shape of the problem β€” **207 MCP servers**, **3,235** tools β€” not an exhaustive count of everything we scan today: | Metric | Count | |--------|-------| | MCP servers in cohort | 207 | | Individual tools analyzed | 3,235 | | Total security findings | 3,613 | | Servers with at least one finding | 145 (70%) | | Servers with a clean Grade A | 22 (10%) | | Servers with arbitrary code execution | 16 | **Only 10% of servers in that cohort had a clean Grade A.** See **[tooltrust.dev](https://www.tooltrust.dev/)** for up-to-date directory-wide results (and use this table only as a labeled snapshot). ## πŸ” What it catches ToolTrust runs **16** static tool-definition rules in this repo (**AS-001–AS-011**, **AS-013–AS-017**) plus **2** source-scan rules for embedded MCP implementations (**AS-018**, **AS-019**). **AS-012** (tool drift) is evaluated in the **[ToolTrust Directory](https://github.com/AgentSafe-AI/tooltrust-directory)** when new scan results are compared to previous runs. | ID | Severity | Detects | |----|:--------:|---------| | πŸ›‘οΈ **AS‑001** | `Critical` | **Tool Poisoning** β€” Adversarial prompts hidden in tool descriptions (`ignore previous instructions`, ``) | | πŸ”‘ **AS‑002** | `High`/`Low` | **Permission Surface** β€” `exec`, `network`, `db`, `fs` beyond stated purpose; over-broad input schema | | πŸ“ **AS‑003** | `High` | **Scope Mismatch** β€” Tool name contradicts its permissions (e.g. `read_config` with `exec`) | | πŸ“¦ **AS‑004** | `High`/`Critical` | **Supply Chain CVEs** β€” Known CVEs in bundled dependencies via [OSV](https://osv.dev) | | πŸ”“ **AS‑005** | `High` | **Privilege Escalation** β€” `admin`/`:write` OAuth scopes; `sudo`/`impersonate` in descriptions | | ⚑ **AS‑006** | `Critical` | **Arbitrary Code Execution** β€” `evaluate_script`, `_evaluate` suffix, `execute javascript`, `page.evaluate()` patterns | | ℹ️ **AS‑007** | `Info` | **Insufficient Tool Data** β€” Tool lacks a valid description or schema | | 🚨 **AS‑008** | `Critical` | **Known Compromised Package** β€” Offline embedded blacklist of confirmed supply-chain attacks (LiteLLM 1.82.7/1.82.8, Trivy v0.69.4-v0.69.6, Langflow <1.9.0, Axios 1.14.1/0.30.4). Zero-latency, no network required. | | πŸ”€ **AS‑009** | `Medium` | **Typosquatting** β€” Tool name within edit-distance 2 of a well-known MCP tool, suggesting impersonation | | πŸ—οΈ **AS‑010** | `Medium` | **Secret Handling** β€” Input params accepting API keys/passwords; credentials logged insecurely | | ⚑ **AS‑011** | `Low` | **DoS Resilience** β€” No rate-limit, timeout, or retry config on network/exec tools | | πŸ”„ **AS‑012** | `High` | **Rug-Pull** β€” Tool set changed between scans of the same version without a version bump *(directory pipeline only)* | | πŸ‘₯ **AS‑013** | `High`/`Medium` | **Tool Shadowing** β€” Duplicate or near-duplicate tool name hijacks calls intended for a trusted tool | | ℹ️ **AS‑014** | `Info` | **Dependency Inventory Unavailable** β€” MCP server exposed neither `metadata.dependencies` nor a `repo_url`, so supply-chain coverage is limited and must be treated as incomplete | | ⚠️ **AS‑015** | `Medium`/`High` | **Suspicious NPM Lifecycle Script** β€” npm dependency publishes `preinstall` / `postinstall` / similar install-time scripts; severity rises for remote-fetch or inline-execution patterns | | 🚨 **AS‑016** | `Critical` | **Suspicious NPM IOC Dependency** β€” published npm metadata or install-time scripts reference a known malicious IOC package, domain, URL, or reviewed script pattern such as `plain-crypto-js`, even if the top-level package name is new | | ⚠️ **AS‑017** | `Medium` | **Suspicious Data Exfiltration Description** β€” tool description explicitly suggests sending user data, content, or conversation history to external / remote endpoints, without classifying it as prompt injection | | ℹ️ **AS‑018** | `Info` | **Embedded MCP Server Detected** β€” source-level MCP SDK usage was found, but tools could not be enumerated from a manifest or live handshake, so manual review is still required | | πŸ”“ **AS‑019** | `High` | **Unauthenticated MCP Route Exposure** β€” embedded MCP HTTP routes expose the same handler without equivalent authentication middleware | Full rule details: [docs/RULES.md](docs/RULES.md) ## How it works 1. **Parse** β€” Connects to a live MCP server (or reads a JSON file) and extracts every tool definition 2. **Analyze** β€” Runs tool-definition rules against each tool's name, description, schema, and permissions; source scans add embedded MCP implementation checks 3. **Grade** β€” Assigns a numeric risk score and letter grade (A–F) per tool 4. **Enforce** β€” Maps each grade to a gateway policy: `ALLOW`, `REQUIRE_APPROVAL`, or `BLOCK` Pure static analysis. No LLM calls. No data leaves your machine (except optional CVE lookups). Runs in milliseconds. Deterministic and reproducible. ## Install ```bash # One-line install (macOS / Linux) curl -sfL https://raw.githubusercontent.com/AgentSafe-AI/tooltrust-scanner/main/install.sh | bash # Go go install github.com/AgentSafe-AI/tooltrust-scanner/cmd/tooltrust-scanner@latest # npx (no install needed) npx -y tooltrust-mcp ``` ## MCP tools When running as an MCP server, ToolTrust exposes these tools to your agent: | Tool | What it does | Data access | |------|-------------|-------------| | `tooltrust_scan_config` | Scan all MCP servers in your `.mcp.json` or `~/.claude.json` | Reads local config; spawns each server as subprocess | | `tooltrust_scan_server` | Launch and scan a specific MCP server by command | Runs user-supplied command as subprocess (stdio) | | `tooltrust_scanner_scan` | Scan a raw JSON blob of tool definitions | In-memory only; no subprocess or network | | `tooltrust_lookup` | Look up a server's trust grade from the ToolTrust Directory | Network request to ToolTrust Directory API | | `tooltrust_list_rules` | List all built-in security rules | Local catalog only | ## CI / GitHub Actions Block risky MCP servers in your pipeline: ```yaml - name: Audit MCP Server uses: AgentSafe-AI/tooltrust-scanner@main with: server: "npx -y @modelcontextprotocol/server-filesystem /tmp" fail-on: "approval" ``` ## Deployment and security For deployment, use the install paths in [Install](#install) or the workflow example in [CI / GitHub Actions](#ci--github-actions). For vulnerability reporting and disclosure policy, see [docs/SECURITY.md](docs/SECURITY.md). ## Scan-before-install gate Never add an untrusted MCP server to your config again: ```bash # Scans the server, then auto-installs if Grade A/B, prompts on C/D, blocks on F tooltrust-scanner gate @modelcontextprotocol/server-memory -- /tmp # Replace `claude mcp add` with a scanned install alias mcp-add='tooltrust-scanner gate' ``` Full gate options and pre-commit hook setup: [docs/USAGE.md](docs/USAGE.md) ## Add a trust badge to your project If your MCP server passes ToolTrust, let people know: ```markdown [![ToolTrust Grade A](https://img.shields.io/badge/ToolTrust-Grade%20A-brightgreen)](https://www.tooltrust.dev/) ``` > [![ToolTrust Grade A](https://img.shields.io/badge/ToolTrust-Grade%20A-brightgreen)](https://www.tooltrust.dev/) --- > **Supply-chain alert:** ToolTrust detects and blocks confirmed compromised packages including LiteLLM v1.82.7/8 (TeamPCP backdoor), Trivy v0.69.4–v0.69.6, and Langflow < 1.9.0. If you encounter a Grade F with rule AS-008, remove the package immediately and rotate all credentials. --- [Usage guide](docs/USAGE.md) Β· [Developer guide](docs/DEVELOPER.md) Β· [Contributing](docs/CONTRIBUTING.md) Β· [Deployment & security](#deployment-and-security) Β· [Changelog](CHANGELOG.md) Β· [Security](docs/SECURITY.md) Β· [License: MIT](LICENSE)