README
¶
ToolTrust Scanner
Scan MCP servers for prompt injection, data exfiltration, and privilege escalation before your AI agent blindly trusts them.
[Insert Terminal GIF Here]
🚀 Quick Start
Install via Homebrew:
brew install AgentSafe-AI/tooltrust-scanner/tooltrust-scanner
(Alternatively, use go install github.com/AgentSafe-AI/tooltrust-scanner/cmd/tooltrust-scanner@latest)
💻 Usage
Scan an MCP server directly by spinning it up:
tooltrust-scanner scan --server "npx -y @modelcontextprotocol/server-filesystem /tmp"
🔍 What it catches
ToolTrust intercepts tool definitions before execution and blocks threats at the source.
| ID | Detects |
|---|---|
| 🛡️ AS‑001 | Prompt poisoning (ignore previous instructions, system:) |
| 🔑 AS‑002 | Excessive permissions (exec, network, db, fs beyond stated purpose) |
| 📐 AS‑003 | Scope mismatch (e.g. read_config secretly holding exec) |
| 📦 AS‑004 | Supply chain vulnerabilities (CVEs in dependencies via OSV) |
| 🔓 AS‑005 | Privilege escalation (admin OAuth scopes, sudo keywords) |
| ⚡ AS‑006 | Arbitrary code execution (evaluate_script, execute javascript) |
| ℹ️ AS‑007 | Insufficient tool data (missing description or schema) |
| 🗝️ AS‑010 | Insecure secret handling (params accepting keys/passwords) |
| ⚡ AS‑011 | DoS resilience (missing rate-limits or timeouts) |
🤝 GitHub Actions
Integrate into your CI/CD to block high-risk tools automatically:
- name: Audit MCP Server
uses: AgentSafe-AI/tooltrust-scanner@main
with:
server: "npx -y @modelcontextprotocol/server-filesystem /tmp"
fail-on: "approval"
🤖 AI Agent Integration (Claude Desktop / Cursor)
Give your AI agent the ability to self-scan other MCP servers by adding ToolTrust to your mcp.json or claude_desktop_config.json:
{
"mcpServers": {
"tooltrust": {
"command": "npx",
"args": ["-y", "tooltrust-mcp"]
}
}
}
This exposes tooltrust_scan_server and tooltrust_lookup to your AI, allowing it to evaluate external tools before trusting them!
Developer guide · Contributing · Changelog · Security · License: MIT © 2026 AgentSafe-AI
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
tooltrust-mcp
command
Package main provides the ToolTrust Scanner MCP Server — the meta-scanner.
|
Package main provides the ToolTrust Scanner MCP Server — the meta-scanner. |
|
tooltrust-scanner
command
|
|
|
internal
|
|
|
pkg
|
|
|
adapter
Package adapter defines the protocol-agnostic Adapter interface and the registry used to select the correct adapter at runtime.
|
Package adapter defines the protocol-agnostic Adapter interface and the registry used to select the correct adapter at runtime. |
|
adapter/mcp
Package mcp provides an Adapter that parses MCP tools/list responses.
|
Package mcp provides an Adapter that parses MCP tools/list responses. |
|
adapter/openai
Package openai provides an Adapter for the OpenAI Function Calling format.
|
Package openai provides an Adapter for the OpenAI Function Calling format. |
|
adapter/skills
Package skills provides an Adapter for Markdown-based AI Skills format.
|
Package skills provides an Adapter for Markdown-based AI Skills format. |
|
analyzer
Package analyzer provides the scanning engine that runs a set of checkers over a UnifiedTool and produces a RiskScore.
|
Package analyzer provides the scanning engine that runs a set of checkers over a UnifiedTool and produces a RiskScore. |
|
gateway
Package gateway derives enforcement policies from analyzer RiskScore values.
|
Package gateway derives enforcement policies from analyzer RiskScore values. |
|
sandbox
Package sandbox defines the interface for executing tools in an isolated environment.
|
Package sandbox defines the interface for executing tools in an isolated environment. |
|
storage
Package storage persists ToolTrust Scanner results to a SQLite database.
|
Package storage persists ToolTrust Scanner results to a SQLite database. |