概述与快速开始

项目简介

decoy-scan 是一款面向 MCP（Model Context Protocol）服务器配置的安全扫描器，定位为「零依赖、零配置、零账号」的轻量级命令行工具。它能够在攻击者之前发现 MCP 配置中的潜在风险：包括高危工具、提示词注入、跨服务器毒化流（toxic flows）、敏感环境变量泄露以及已知的供应链漏洞。资料来源：package.json:1-5 与 README.md:1-15。

工具通过 bin/cli.mjs 暴露 CLI 入口 decoy-scan，同时通过 index.mjs 暴露完整的库 API（例如 scan、classifyTool、detectPoisoning、discoverConfigs、probeServer 等）。package.json 明确声明 "type": "module"、"engines.node": ">=18.0.0"，且没有任何运行时依赖——这意味着扫描器本身不会通过 npm install 引入供应链风险。资料来源：package.json:7-58。

支持的宿主与运行环境

decoy-scan 自动发现并扫描本机已安装的主流 AI 客户端 MCP 配置，覆盖 7 个宿主：Claude Desktop、Cursor、Windsurf、VS Code、Claude Code、Zed、Cline。配置路径在 macOS、Windows、Linux 上均做了平台适配。资料来源：README.md:17-30 与 AGENTS.md:1-15。

扫描器与每个被发现的 MCP 服务器执行标准的 MCP 握手流程：initialize → notifications/initialized → tools/list，每个服务器设有 15 秒超时，完成后即终止子进程。资料来源：AGENTS.md:1-15。

核心检查能力

下表概述了扫描器覆盖的主要检查类别，详细逻辑由 RISK_PATTERNS、POISONING_PATTERNS 及各类分析函数实现。资料来源：README.md:1-30 与 AGENTS.md:1-20。

快速开始

通过 npx 直接运行是最低门槛的体验方式，无需全局安装：

npx decoy-scan                # 扫描本机所有 MCP 配置
npx decoy-scan --no-probe     # 仅扫描配置文件，不真正 spawn 服务器
npx decoy-scan --no-advisories # 跳过远程公告库查询
npx decoy-scan --policy=no-critical,no-poisoning  # CI/CD 策略门禁
npx decoy-scan --json         # 输出结构化 JSON
npx decoy-scan --sarif        # 输出 SARIF（用于 GitHub Security 标签页）
npx decoy-scan --verbose      # 显示包括 low 在内的全部工具

对于希望理解具体发现的用户，扫描器提供了 explain 子命令，可针对严重等级、发现类别、投毒类型或具体工具名生成结构化解释，并支持 --json 输出以便代理消费。资料来源：README.md:1-25 与 AGENTS.md:1-30。

decoy-scan explain critical
decoy-scan explain prompt-override
decoy-scan explain evaluate_script
decoy-scan explain list

GitHub Action 集成

action.yml 提供了一个 Composite Action，便于在 CI 流水线中嵌入扫描。典型用法只需两步：检出代码后调用 decoy-run/decoy-scan@v1，即可将 SARIF 上传至 GitHub Security 标签页。资料来源：action.yml:1-40。

# .github/workflows/mcp-security.yml
name: MCP Security
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: decoy-run/decoy-scan@v1

可配置输入包括：policy（默认 no-critical,no-poisoning）、sarif（默认 true）、report（上传到 Decoy Guard 仪表板）、token（Decoy API Token）、verbose。资料来源：action.yml:1-25。

退出码与社区动态

decoy-scan 沿用简洁的三段式退出码约定，便于 CI 策略门禁使用：

退出码同时会出现在 --json 与 --brief 输出中的 exitCode 字段，方便智能体直接分支判断而无需重新推导严重度计数。资料来源：AGENTS.md:1-25。

社区方面，最新 v0.5.8 起，扫描输出末尾新增了一行 GitHub star 引导，与 decoy-tripwire、decoy-redteam 的尾部交互保持一致；这是面向同时使用多个 Decoy CLI 的用户的统一体验。资料来源：CHANGELOG.md。

安全策略与许可

若在 decoy-scan 自身发现安全漏洞，请通过 [email protected] 负责任地披露，避免公开 Issue。SECURITY.md 中声明：当前仅 0.4.x 版本获得官方支持，更早版本不再维护。资料来源：SECURITY.md:1-30。项目以 MIT 协议开源。资料来源：package.json:54-58。

See Also

• Library API Reference — scan、classifyTool、detectPoisoning 等导出函数详解
• CLI Reference — 完整命令行参数与子命令手册
• Explain Subcommand — explain 的内部数据模型与扩展方法
• GitHub Action — 在 CI 中执行策略门禁
• Policy Rules — 自定义 --policy 规则的语义与组合

检测引擎与风险分析

概览

decoy-scan 的检测引擎是一套无运行时依赖（zero-dependency）的 ES Module 库，针对 MCP（Model Context Protocol）服务器配置与运行时报文执行静态与动态分析，覆盖工具风险、提示注入、毒性数据流、敏感凭据暴露、供应链公告以及生产就绪度等维度。资料来源：package.json:1-15 显示包以 index.mjs 为入口，exports 字段仅暴露根模块，并通过 bin/cli.mjs 提供 CLI。

引擎按职责拆分为多个内部模块：

数据流

flowchart LR
  A[MCP 配置文件] --> B[discoverConfigs]
  B --> C[probeServer]
  C --> D[classifyTool]
  C --> E[detectPoisoning]
  C --> F[analyzeServerCommand]
  C --> G[analyzeEnvExposure]
  C --> H[analyzeReadiness]
  D --> I[mapToOwasp]
  E --> I
  F --> I
  G --> I
  H --> I
  I --> J[JSON / SARIF / --brief]

风险分层与工具分类

工具风险分为四档：critical（关键）、high（高）、medium（中）、low（低）。critical 涵盖「可执行代码、修改数据或造成不可逆变更」的工具，例如 execute_command、write_file。资料来源：AGENTS.md:explain 章节

classifyTool 同时依据工具名称和描述进行匹配。RISK_PATTERNS 收录了诸如 ^execute[_-]?(script|code|js|javascript|python|sql)$、^run[_-]?(script|code|js|javascript|python|sql)$ 等正则；关键动词（execute、run、evaluate、spawn、fetch）在缺乏描述时也会触发 critical 或 high 评级。资料来源：CHANGELOG.md:0.5.2

检测模块

提示注入检测

detectPoisoning 扫描工具描述，匹配 POISONING_PATTERNS 中的 37 条正则，覆盖 20 类攻击类别。CONTRIBUTING.md 给出了模式结构：

{
  pattern: /regex/i,
  type: "category-name",
  severity: "critical",
  description: "Human-readable"
}

新增模式后需将其 type 同步登记到 OWASP_MAP。资料来源：CONTRIBUTING.md:Poisoning detection patterns

毒性流分析

引擎识别两类跨服务器攻击链：TF001（cross-server data leak）与 TF002（destructive attack chains），用于发现「无害读工具 → 危险外发/执行工具」的危险组合。资料来源：README.md:toxic flow analysis

环境变量暴露

analyzeEnvExposure 识别 12 类敏感凭据（API key、token、密码、数据库连接串、云凭据等）通过 env 字段传递给 MCP 服务器。资料来源：AGENTS.md:Library Exports

就绪度

analyzeReadiness 检查生产环境部署合理性：缺少描述、缺少 schema、缺少必填字段、作用域过宽、危险工具缺少安全提示。资料来源：CONTRIBUTING.md:Adding Readiness Checks

供应链公告

checkAdvisories 与 matchAdvisories 从 Decoy API 拉取公告数据库（40+ 已知存在漏洞的 MCP 包），与已发现服务器的包名做匹配。资料来源：README.md:supply chain advisories

OWASP 映射

mapToOwasp 将所有发现归类到 OWASP Agentic Top 10：ASI01（提示注入）、ASI02（不安全工具使用）、ASI03（身份与权限滥用）、ASI05（不安全代码执行）。资料来源：README.md:OWASP mapping

库 API 概览

import {
  scan, classifyTool, detectPoisoning,
  analyzeServerCommand, analyzeEnvExposure, analyzeReadiness,
  discoverConfigs, probeServer,
  checkAdvisories, matchAdvisories,
  toSarif, mapToOwasp
} from 'decoy-scan';

scan 是顶层编排函数，整合发现、探测、分类、检查四个阶段；toSarif 将结果转换为 SARIF 2.1.0 格式以便 GitHub Security / VS Code 消费。资料来源：AGENTS.md:Library Exports

See Also

• CLI 使用与策略门禁（--policy、--sarif、--report）
• GitHub Action 集成
• decoy-tripwire —— 受损代理检测诱饵
• decoy-redteam —— 自主红队框架
• Decoy Guard 仪表盘与合规报告

CLI、输出格式与 CI/CD 集成

decoy-scan 是一个零依赖、零配置的安全扫描器，用于在 Claude Desktop、Cursor、Windsurf、VS Code、Claude Code、Zed 和 Cline 等 MCP 客户端的配置中发现风险工具、可疑服务器与已知漏洞包。本页聚焦于 CLI 使用方式、输出格式、退出码语义，以及在 CI/CD 中以 GitHub Action 或裸命令形式集成扫描器的方法。package.json 将其声明为 ES Module，主入口为 index.mjs，可执行文件为 bin/cli.mjs，运行时要求 Node.js >=18.0.0。

CLI 入口与常用选项

CLI 由 bin/cli.mjs 启动（参见 package.json 的 bin 字段）。最常用的运行方式是在项目根目录执行 npx decoy-scan，它会自动发现本机的 MCP 配置文件，并按需探测每个服务器。可用的核心选项如下表所示。

资料来源：README.md、AGENTS.md。

输出格式：JSON、SARIF 与 `--brief`

扫描器原生支持三种机器可读的输出格式。--brief 是面向代理与 CI 流水线的极简摘要：传入后即隐含 --json，字段包括 servers（被扫描的服务器数量）、critical/high/medium/low（按风险等级的工具计数）、poisoned（被检测出提示注入的工具数）、status（pass/warn/fail）以及与进程退出码一致的 exitCode（资料来源：AGENTS.md）。--json 给出完整结构化结果，包含每个服务器的 findings 数组、summary 块、advisories 与 owasp 映射，可用于二次处理。--sarif 生成 SARIF 2.1.0，配合 github/codeql-action/upload-sarif@v3 上传到 GitHub Security 标签页。

CHANGELOG 中提到 v0.5.x 修复了一个管道截断问题：--sarif 与 --json 在通过管道传递给 jq 等命令时可能丢失末尾字节，根因是 process.exit() 在 stdout 排空前杀掉了 Node 进程；修复后 CLI 会等待管道冲刷再退出（资料来源：CHANGELOG.md）。这是 CI 集成中最常被踩到的坑之一。

退出码与策略门禁

CLI 以三个退出码概括结果严重性：0 表示未发现 critical 或 high 级问题；1 表示存在 high 级风险；2 表示存在 critical 级风险或工具被检测出提示注入（资料来源：AGENTS.md、README.md）。--policy 选项将这一机制具象化为可组合的规则集：

资料来源：README.md。

GitHub Action 与 `explain` 子命令

仓库根目录的 action.yml 把上述能力打包成单步 Action。核心 inputs 包括 policy（默认 no-critical,no-poisoning）、sarif（默认 true，自动上传到 Security 标签页）、report、token 与 verbose。Action 内部会执行 npx decoy-scan --policy=...，把退出码透传给 GITHUB_STEP_SUMMARY，并在 SARIF 可用时调用 github/codeql-action/upload-sarif@v3 以 decoy-scan 分类上传。

explain 子命令（v0.5.0 引入）为代理与终端用户提供结构化的"为什么被标记"解释。它接受 severity tier、finding category、poisoning type 或 tool name 作为 target，并支持 --json 输出；result.kind 可能是 tier/category/poisoning/tool，所有解释都从 RISK_PATTERNS 与 POISONING_PATTERNS 中实时解析，避免与扫描器逻辑漂移（资料来源：AGENTS.md、CHANGELOG.md）。

终端输出与社区反馈

v0.5.8（社区上下文提及的版本）之后，每次扫描输出末尾会附加一行 GitHub star 提示，与 decoy-tripwire 和 decoy-redteam 的收尾保持一致，方便同时使用多个 Decoy CLI 的用户。后续的 v0.8.1 把这条收尾行从通用仪表板链接改为与本次扫描结果绑定的"findings-aware"提示，例如 3 findings — keep them past this terminal:，并附一行说明仪表板提供历史与 diff 能力（资料来源：CHANGELOG.md）。

flowchart LR
  A[push / PR] --> B[decoy-scan Action]
  B --> C{npx decoy-scan --policy}
  C -- exit 0 --> D[✅ Step Summary]
  C -- exit ≥ 1 --> E[🚨 Step Summary]
  B --> F[--sarif]
  F --> G[GitHub Security tab]

常见失败模式

• 管道截断：如上所述，在 decoy-scan --sarif | jq 场景下务必使用修复后的版本（≥ 0.5.x 修复版）。
• 未显式退出码判断：--policy 是 CI 友好的判据，但裸跑时退出码 0/1/2 同样可作为 PR 检查条件（资料来源：README.md）。
• 误以为没有 SARIF：Action 默认开启 sarif: true，若不希望结果出现在 Security 标签页，需在 workflow 中显式 with: sarif: 'false'。
• 跨平台差异：CI 中通常运行 Linux，配置路径与 macOS/Windows 不同，建议在 CI 中显式指定配置目录或使用 --no-probe 仅做配置审计（资料来源：CONTRIBUTING.md）。

See Also

• index.mjs 库 API 与 MCP 握手
• CHANGELOG
• Decoy Scan 文档
• OWASP Top 10 for Agentic Applications 2026

供应链、技能与可扩展性

概述

decoy-scan 是一款面向 MCP（Model Context Protocol）服务器配置的零依赖安全扫描器。其设计目标不仅是发现单个工具的风险，更涵盖了供应链安全、技能（Skills）扫描以及面向开发者与 CI 流水线的可扩展性三个维度。本页围绕这三类能力，梳理其检查范围、配置方式与扩展接入点。

资料来源：README.md | package.json

供应链安全公告

扫描器内置「Decoy Advisory Database」交叉检查能力，针对 40 余个已知存在漏洞的 MCP 包做供应链层面的命中比对。CLI 通过 --no-advisories 可跳过该检查；通过 --report 可将结果上报到 Decoy Guard 仪表盘，从而获得持续更新的威胁情报。

资料来源：README.md | AGENTS.md

Claude Code 技能扫描

从检查清单可见，扫描器把 Claude Code 的 Skills 也纳入了风险面：会在技能定义中检测提示词注入、硬编码密钥与可疑 URL。调用方式是在常规扫描命令后追加 --skills 即可启用；结合 --verbose 可看到所有低风险工具与被忽略的细节。该能力与 v0.5.0 引入的 explain 子命令协同，让用户既能看到「命中了什么」，也能即时理解「为什么命中」。

npx decoy-scan --skills
npx decoy-scan explain prompt-override
npx decoy-scan explain tool-description --json

资料来源：README.md | CHANGELOG.md

库 API 与可扩展性

decoy-scan 同时提供 CLI 与 库（ES Module）两种使用方式。package.json 中 type: "module"、main: "index.mjs"、零依赖与 engines.node >= 18.0.0 共同决定了它以纯 ESM 形态对外暴露。库导出包含扫描主流程与可单独复用的分析器，便于在自定义流水线中嵌入。

flowchart LR
  A[index.mjs<br/>库入口] --> B[scan]
  A --> C[classifyTool]
  A --> D[detectPoisoning]
  A --> E[analyzeServerCommand]
  A --> F[analyzeEnvExposure]
  A --> G[analyzeReadiness]
  A --> H[discoverConfigs]
  A --> I[probeServer]
  A --> J[checkAdvisories]
  B --> K[bin/cli.mjs<br/>CLI 入口]
  K --> L[GitHub Action<br/>action.yml]

关键设计原则：只读——扫描器从不修改任何 MCP 配置文件；零依赖、零构建——npm install 后即可直接 node bin/cli.mjs 运行。这两点共同保证了在 CI、临时容器、本地开发机等任意环境中都可复现。

资料来源：AGENTS.md | package.json | CHANGELOG.md

策略与 CI/CD 集成

action.yml 将上述能力封装为可一步接入的 GitHub Action。policy 输入默认 no-critical,no-poisoning，并支持 no-high、no-toxic-flows、no-secrets、require-tripwires、max-critical=N、max-high=N 等规则；sarif 输出可直接进入 GitHub Security 标签页，report + token 则把结果写入 Decoy Guard 仪表盘。Action 暴露 exit-code、sarif-file、summary 三个 outputs，便于下游作业继续编排。

退出码遵循统一约定：0 干净、1 存在高风险、2 存在严重风险或工具投毒，CI 可直接据此判断流水线成败。

资料来源：action.yml | README.md | AGENTS.md | SECURITY.md

社区与版本说明

社区最近反馈集中在输出格式的一致性上：v0.5.8 之后，扫描尾部会追加一行统一的 GitHub Star 提示，与 decoy-tripwire、decoy-redteam 保持一致，便于同时使用多个 Decoy CLI 的用户识别。安全披露通过 [email protected] 接收，目前仅 0.4.x 系列在支持窗口内，建议在生产环境锁定该主版本并持续升级补丁。

资料来源：CHANGELOG.md | SECURITY.md

参见

• CHANGELOG.md — 版本变更记录
• README.md — 人类用户文档
• AGENTS.md — 面向 AI Agent 的接口说明
• action.yml — GitHub Action 定义
• SECURITY.md — 漏洞披露策略

Pitfall Log / 踩坑日志

项目：decoy-run/decoy-scan

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/decoy-run/decoy-scan | host_targets=mcp_host, claude_code, claude, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/decoy-run/decoy-scan | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/decoy-run/decoy-scan | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/decoy-run/decoy-scan | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/decoy-run/decoy-scan | release_recency=unknown