Deepsleuth

Deepsleuth — 细读小字内容

Deepsleuth 是一款确定性、无需大模型的 MCP 服务安全扫描器。 它会审计服务声称的内容，更重要的是，审计它实际做了什么。

大多数 MCP 扫描器只读取声明的清单（tools/list 中的名称、 描述和架构）。它们从不启动服务、从不调用工具、从不读取响应、 从不读取实现源码，也从不跨调用进行推理，因此在结构上无法发现整类攻击。

Deepsleuth 能发现这些问题。 它是一个与前端无关的单一检测核心， 包含两个前端：

• 前端 A — 内联 MCP 网关／代理（主要组件）。 一个透明代理，对 Agent 来说是 MCP 服务，对一个下游服务来说则是 MCP 客户端。它会在启动时审计工具描述，在每次 tools/call 前执行门控，并在返回每个响应前进行扫描。还包含用于离线评分的无头 proxy-eval 模式。
• 前端 B — 批处理／沙盒扫描器。 一个预检审计器，会在 Docker 沙盒中启动服务，通过合成调用和植入的金丝雀主动诱发行为，并生成发现结果。它也是离线评分工具。

两个前端都在同一个 Context 上运行相同的检测器——每个检测器只需编写一次，即可在两者中使用。

绝不用大模型。

完全确定：解析、静态 AST 和污点／数据流分析、归一化正则／令牌启发式分析、Unicode／编码／熵分析、结构差异分析，以及带插桩的沙盒动态执行。相同输入 → 字节级完全相同的发现结果。 离线运行（除连接 Docker 守护程序外，不进行网络外连）。不使用威胁情报源。

---

安装

Python 3.11+。无需安装第三方依赖——扫描器自身通过 stdio 与 MCP 通信，因此可安装在受外部管理的环境（PEP 668）中。

pip install security-scanner-deepsleuth-mcp                             # published on PyPI
# or from source:
pip install git+https://github.com/DeepSleuth/deepsleuth-mcp.git   # zero required dependencies
deepsleuth --help
# or straight from the source tree:
python -m deepsleuth --help

PyPI 发行包名为 security-scanner-deepsleuth-mcp（说明其用途并体现品牌）；工具、代码库和 MCP 服务均名为 deepsleuth。该包会安装 deepsleuth 控制台命令，以及一个以发行包自身名称命名的别名脚本，因此 uvx security-scanner-deepsleuth-mcp 可为注册表客户端启动该服务。

Deepsleuth 本身就是 MCP 服务，因此 Agent 可以直接使用它进行扫描：

{"mcpServers": {"deepsleuth": {"command": "python", "args": ["-m", "deepsleuth.mcp_server"]}}}

工具：list_detectors、check_listing、scan_target。

安装为 Agent 插件

该代码库是符合规范的 Agent Plugins 软件包 （plugin.json + mcp.json，规范版本 1.0.0）：任何兼容的客户端都可以直接从代码库安装，并获得 deepsleuth MCP 服务和 audit-mcp-server 技能。stdio 入口（bin/deepsleuth-mcp）只需要 python3.11+——扫描器不需要任何第三方依赖：

{"type": "stdio", "command": "./bin/deepsleuth-mcp"}

动态层（前端 B 和 proxy-eval）需要 Docker CLI + 守护程序。没有 Docker 时，扫描器会平稳降级：静态／清单检测器仍会运行，并报告跳过的动态覆盖范围（绝不会崩溃）。

运行

# Frontend B — batch/sandbox scanner (also the offline scoring harness)
python -m deepsleuth scan <target> [--no-dynamic] [--json out.json] [--timeout N] [--reference-listing tools.json]

# Frontend A — inline MCP gateway/proxy (the gate); speaks MCP on stdio to the agent
python -m deepsleuth proxy <target> [--policy policy.yaml] [--fail-closed] [--log run.jsonl]

# Frontend A headless — drive a deterministic call plan through the proxy, emit the findings JSON
python -m deepsleuth proxy-eval <target> [--json out.json] [--timeout N] [--policy p]

# list every registered detector
python -m deepsleuth detectors

<target> 可以是服务目录（包含 mcp.json 和／或源代码）、mcp.json 启动规范，或原始 stdio 启动命令（例如 "python3 server.py"）。scan 在未发现问题时以 0 退出；一旦发现的问题达到 --fail-severity（默认为 high），则以非零值退出。

--allow-unsandboxed 会在不使用 Docker 的情况下运行动态分析层——仅用于你自己信任的测试样例，切勿用于不可信的服务。

--reference-listing tools.json 可提供另一个服务的工具列表（包含 {name, description, inputSchema} 条目的 JSON 数组，或带有 tools 键的对象），这样无需启动第二个服务，跨服务名称比较也能针对该列表进行。同一比较也会自动应用于一个 mcp.json 中的多个条目，以及同一目录中找到的多个服务入口模块。

将代理接入 Agent

将 MCP 客户端指向代理，而不是实际服务；代理会在下游启动实际服务：

{ "mcpServers": {
    "guarded-fs": {
      "command": "python", "args": ["-m", "deepsleuth", "proxy",
        "/path/to/real-server", "--policy", "policy.example.yaml", "--log", "gate.jsonl"]
    } } }

试用捆绑的测试样例

python -m deepsleuth scan tests/fixtures/injection --no-dynamic          # source taint + hint violation
python -m deepsleuth scan tests/fixtures/poisoned  --no-dynamic          # poisoned descriptions
python -m deepsleuth scan tests/fixtures/supplychain --no-dynamic        # install-time hook + typosquat
python -m deepsleuth proxy-eval tests/fixtures/runtime --allow-unsandboxed  # response injection + cross-call leak, with gate decisions
python tests/run_all.py                                                    # unit + e2e tests (no pytest needed)

覆盖范围

证据位置 — deepsleuth 会检测全部八类证据位置，尤其擅长检测纯清单扫描器会漏掉的五类：

证据位置	纯清单扫描器能检测到吗？	deepsleuth
description、name、schema	能	✅ 规范化机制规则 + 混淆检测
source	不能	✅ AST 污点分析、提示与行为比对、rug-pull 门控、身份验证／审计
runtime-response	不能	✅ 响应注入 + 金丝雀／凭据泄露扫描
multi-call-state	不能	✅ 跨调用金丝雀泄露、重新列出差异、响应差异
server-identity	很少	✅ 握手与配置／软件包身份比对
install-time-script	不能	✅ npm／pip 安装钩子 + 拼写仿冒分析

机制类别： tool-poisoning、agent-config-poisoning、 tool-shadowing、prompt-injection、credential-exposure、command-injection、 path-traversal、ssrf、data-exfiltration、confused-deputy、 auth-misconfiguration、denial-of-service、excessive-privilege、 supply-chain、information-disclosure、client-side-vulnerability、other。

每项发现都会通过固定的发现结果架构验证，包含顶层 evidence_location 和 confidence；通过代理生成的发现还会将门控判定记录在 raw.gate_decision 中。请参阅 DETECTORS.md，其中逐一介绍检测器及其已知盲点；另请参阅 ARCHITECTURE.md，了解各层如何配合，以及如何添加检测器。

已知限制（v1）

• 源代码分析以 Python 为主。 Node／TS 服务支持清单分析、安装钩子分析和动态分析，但 v1 中只有 Python 支持源代码污点分析（JS 仅进行轻量级正则分析）。
• 污点分析仅限过程内。 对模块中辅助函数／类之间的流转仅作近似处理，不会完整跟踪。
• 代理恰好代理一个下游服务（v1 的范围；已为多服务命名空间设计好结构，但尚未实现）。
• 在线代理的 elicitation 往返交互和下游发起请求的转发仅尽力而为。 proxy-eval 会全面测试所有门控／审计／差异／响应逻辑，离线评估器也会据此评分。
• 不使用 Docker 时，会跳过动态检测器（会报告跳过，不会静默处理）。

参与贡献

欢迎贡献——请参阅 CONTRIBUTING.md。 发现安全问题？请遵循 SECURITY.md。

---

已列入官方 MCP Registry：

mcp-name: io.github.DeepSleuth/deepsleuth