{
  "canonical_name": "decoy-run/decoy-scan",
  "compilation_id": "pack_9794e1723776471ca8ab5d4db926031c",
  "created_at": "2026-05-14T06:27:26.423037+00:00",
  "created_by": "project-pack-compiler",
  "feedback": {
    "carrier_selection_notes": [
      "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
      "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
    ],
    "evidence_delta": {
      "confirmed_claims": [
        "identity_anchor_present",
        "capability_and_host_targets_present",
        "install_path_declared_or_better"
      ],
      "missing_required_fields": [],
      "must_verify_forwarded": [
        "Run or inspect `npx decoy-scan` in an isolated environment.",
        "Confirm the project exposes the claimed capability to at least one target host."
      ],
      "quickstart_execution_scope": "allowlisted_sandbox_smoke",
      "sandbox_command": "npx decoy-scan",
      "sandbox_container_image": "node:22-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "deterministic_isolated_install",
      "sandbox_validation_id": "sbx_bca44921f44f421fadc666299b912420"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_6cccd8281bc7d4751569e89a401fa601",
    "canonical_name": "decoy-run/decoy-scan",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/decoy-run/decoy-scan",
    "slug": "decoy-scan",
    "source_packet_id": "phit_12b62813167341809147a778a2899855",
    "source_validation_id": "dval_433a8a227aee446a86b78cc771e0d20b"
  },
  "merchandising": {
    "best_for": "需要安全审查与权限治理能力，并使用 mcp_host的用户",
    "github_forks": 0,
    "github_stars": 1,
    "one_liner_en": "Security scanner for MCP server configurations. Like npm audit, but for your AI agent tool servers. Finds risky tools, input validation gaps, transport vulnerabilities, and over-permissioned capability chains. Open source, zero dependencies.",
    "one_liner_zh": "Security scanner for MCP server configurations. Like npm audit, but for your AI agent tool servers. Finds risky tools, input validation gaps, transport vulnerabilities, and over-permissioned capability chains. Open source, zero dependencies.",
    "primary_category": {
      "category_id": "security-permissions",
      "confidence": "high",
      "name_en": "Security & Permissions",
      "name_zh": "安全审查与权限治理",
      "reason": "matched_keywords:security, permission, risk"
    },
    "target_user": "使用 mcp_host 等宿主 AI 的用户",
    "title_en": "decoy-scan",
    "title_zh": "decoy-scan 能力包",
    "visible_tags": [
      {
        "label_en": "Security & Permissions",
        "label_zh": "安全审查与权限治理",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "product_domain-security-permissions",
        "type": "product_domain"
      },
      {
        "label_en": "Tool Integration",
        "label_zh": "工具接入扩展",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "user_job-tool-integration",
        "type": "user_job"
      },
      {
        "label_en": "Workflow Automation",
        "label_zh": "流程自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-workflow-automation",
        "type": "core_capability"
      },
      {
        "label_en": "Node-based Workflow",
        "label_zh": "节点式流程编排",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "workflow_pattern-node-based-workflow",
        "type": "workflow_pattern"
      },
      {
        "label_en": "Evaluation Suite",
        "label_zh": "评测体系",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "selection_signal-evaluation-suite",
        "type": "selection_signal"
      }
    ]
  },
  "packet_id": "phit_12b62813167341809147a778a2899855",
  "page_model": {
    "artifacts": {
      "artifact_slug": "decoy-scan",
      "files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json",
        "REPO_INSPECTION.md",
        "CAPABILITY_CONTRACT.json",
        "EVIDENCE_INDEX.json",
        "CLAIM_GRAPH.json"
      ],
      "required_files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json"
      ]
    },
    "detail": {
      "capability_source": "Project Hit Packet + DownstreamValidationResult",
      "commands": [
        {
          "command": "npx decoy-scan",
          "label": "Node.js / npx · 官方安装入口",
          "source": "https://github.com/decoy-run/decoy-scan#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "安全审查与权限治理",
        "工具接入扩展",
        "流程自动化",
        "节点式流程编排",
        "评测体系"
      ],
      "eyebrow": "安全审查与权限治理",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要安全审查与权限治理能力，并使用 mcp_host的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "Security scanner for MCP server configurations. Like npm audit, but for your AI agent tool servers. Finds risky tools, input validation gaps, transport vulnerabilities, and over-permissioned capability chains. Open source, zero dependencies."
        },
        {
          "body": "未完成验证前保持审慎。",
          "label": "继续前",
          "value": "publish to Doramagic.ai project surfaces"
        }
      ],
      "guardrail_source": "Boundary & Risk Card",
      "guardrails": [
        {
          "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
          "label": "Check 1",
          "value": "不要把试用当真实运行"
        },
        {
          "body": "mcp_host",
          "label": "Check 2",
          "value": "确认宿主兼容"
        },
        {
          "body": "publish to Doramagic.ai project surfaces",
          "label": "Check 3",
          "value": "先隔离验证"
        }
      ],
      "mode": "mcp_config, recipe, host_instruction, eval, preflight",
      "pitfall_log": {
        "items": [
          {
            "body": "README/documentation is current enough for a first validation pass.",
            "category": "能力坑",
            "evidence": [
              "capability.assumptions | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | README/documentation is current enough for a first validation pass."
            ],
            "severity": "medium",
            "suggested_check": "将假设转成下游验证清单。",
            "title": "能力判断依赖假设",
            "user_impact": "假设不成立时，用户拿不到承诺的能力。"
          },
          {
            "body": "未记录 last_activity_observed。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | last_activity_observed missing"
            ],
            "severity": "medium",
            "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
            "title": "维护活跃度未知",
            "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "downstream_validation.risk_items | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "No sandbox install has been executed yet; downstream must verify before user use.",
            "category": "安全/权限坑",
            "evidence": [
              "risks.safety_notes | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | No sandbox install has been executed yet; downstream must verify before user use."
            ],
            "severity": "medium",
            "suggested_check": "转成明确权限清单和安全审查提示。",
            "title": "存在安全注意事项",
            "user_impact": "用户安装前需要知道权限边界和敏感操作。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "issue_or_pr_quality=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | issue_or_pr_quality=unknown"
            ],
            "severity": "low",
            "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
            "title": "issue/PR 响应质量未知",
            "user_impact": "用户无法判断遇到问题后是否有人维护。"
          },
          {
            "body": "release_recency=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | release_recency=unknown"
            ],
            "severity": "low",
            "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
            "title": "发布节奏不明确",
            "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": 1,
        "forks": 0,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": 1
      },
      "source_url": "https://github.com/decoy-run/decoy-scan",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "Security scanner for MCP server configurations. Like npm audit, but for your AI agent tool servers. Finds risky tools, input validation gaps, transport vulnerabilities, and over-permissioned capability chains. Open source, zero dependencies.",
      "title": "decoy-scan 能力包",
      "trial_prompt": "# decoy-scan - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 decoy-scan 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想检查一个 AI 工具或 Agent 工作流在权限、提示注入和数据泄露上的风险。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Security scanner for MCP server configurations. Like npm audit, but for your AI agent tool servers. Finds risky tools, input validation gaps, transport vulnerabilities, and over-permissioned capability chains. Open source, zero dependencies. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. getting-started：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. cli-usage：命令行工具。围绕“命令行工具”模拟一次用户任务，不展示安装或运行结果。\n4. security-checks：安全检查项目。围绕“安全检查项目”模拟一次用户任务，不展示安装或运行结果。\n5. risk-classification：风险分级系统。围绕“风险分级系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. getting-started\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. cli-usage\n输入：用户提供的“命令行工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. security-checks\n输入：用户提供的“安全检查项目”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. risk-classification\n输入：用户提供的“风险分级系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / getting-started：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / cli-usage：Step 3 必须围绕“命令行工具”形成一个小中间产物，并等待用户确认。\n- Step 4 / security-checks：Step 4 必须围绕“安全检查项目”形成一个小中间产物，并等待用户确认。\n- Step 5 / risk-classification：Step 5 必须围绕“风险分级系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/decoy-run/decoy-scan\n- https://github.com/decoy-run/decoy-scan#readme\n- README.md\n- package.json\n- bin/cli.mjs\n- index.mjs\n- action.yml\n- lib/explain.mjs\n- lib/scan.mjs\n- lib/patterns.mjs\n- lib/tier.mjs\n- lib/owasp.mjs\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 decoy-scan 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
      "voices": [
        {
          "body": "来源平台：github。github/github_release: Decoy Scan - MCP Security for CI/CD（https://github.com/decoy-run/decoy-scan/releases/tag/v1）。这些是项目级外部声音，不作为单独质量证明。",
          "items": [
            {
              "kind": "github_release",
              "source": "github",
              "title": "Decoy Scan - MCP Security for CI/CD",
              "url": "https://github.com/decoy-run/decoy-scan/releases/tag/v1"
            }
          ],
          "status": "已收录 1 条来源",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "安全审查与权限治理",
      "desc": "Security scanner for MCP server configurations. Like npm audit, but for your AI agent tool servers. Finds risky tools, input validation gaps, transport vulnerabilities, and over-permissioned capability chains. Open source, zero dependencies.",
      "effort": "安装已验证",
      "forks": 0,
      "icon": "shield",
      "name": "decoy-scan 能力包",
      "risk": "需复核",
      "slug": "decoy-scan",
      "stars": 1,
      "tags": [
        "安全审查与权限治理",
        "工具接入扩展",
        "流程自动化",
        "节点式流程编排",
        "评测体系"
      ],
      "thumb": "purple",
      "type": "MCP 配置"
    },
    "manual": {
      "markdown": "# https://github.com/decoy-run/decoy-scan 项目说明书\n\n生成时间：2026-05-14 05:23:08 UTC\n\n## 目录\n\n- [项目介绍](#project-introduction)\n- [快速开始](#getting-started)\n- [命令行工具](#cli-usage)\n- [安全检查项目](#security-checks)\n- [风险分级系统](#risk-classification)\n- [提示注入检测](#prompt-injection-detection)\n- [扫描架构](#scanning-architecture)\n- [MCP 主机发现](#mcp-host-discovery)\n- [有毒数据流分析](#toxic-flow-analysis)\n- [GitHub Action 集成](#github-action)\n\n<a id='project-introduction'></a>\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#getting-started), [安全检查项目](#security-checks)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n- [action.yml](https://github.com/decoy-run/decoy-scan/blob/main/action.yml)\n</details>\n\n# 项目介绍\n\n## 概述\n\ndecoy-scan 是一款面向 MCP (Model Context Protocol) 生态的**供应链安全扫描工具**，旨在 Agent 执行工具调用之前发现 MCP 服务器中的安全风险。该项目由 Decoy 团队开发，采用零依赖设计，仅需 Node.js 18+ 即可运行，无需安装任何 npm 包。资料来源：[README.md:1]()\n\ndecoy-scan 的核心价值在于：\n\n- **主动防御**：在攻击者利用漏洞之前识别 MCP 服务器中的危险工具和提示注入\n- **零配置**：开箱即用，自动发现本地 MCP 客户端配置\n- **多平台支持**：覆盖主流 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）\n- **CI/CD 友好**：支持 JSON、SARIF 等结构化输出，便于集成到自动化流水线\n\n资料来源：[README.md:1-3]()\n\n## 核心功能\n\ndecoy-scan 提供全面的 MCP 安全扫描能力，涵盖以下检查维度：\n\n| 检查类别 | 功能描述 |\n|---------|---------|\n| 工具风险分类 | 基于名称和描述将工具分为 critical/high/medium/low 四个风险等级 |\n| 提示注入检测 | 37 种正则模式，覆盖 20 个攻击类别，检测工具描述中的提示注入 |\n| 毒性流分析 | 识别跨服务器数据泄露（TF001）和破坏性攻击链（TF002） |\n| 工具清单哈希 | 追踪工具的增删改，检测扫描间的清单变化 |\n| Skill 扫描 | 检测 Claude Code 中的提示注入、硬编码密钥、可疑 URL |\n| 服务器命令分析 | 检测管道到 shell、内联代码、域名仿冒、临时目录生成 |\n| 环境变量暴露 | 识别传递给服务器的 API 密钥、令牌、敏感凭证 |\n| 供应链告警 | 对接 Decoy 告警数据库，覆盖 40+ 已知漏洞 MCP 包 |\n| 传输安全 | 检查 HTTP 无 TLS、缺失认证、通配符 CORS、公共 SSE |\n| 输入验证 | 验证参数约束、maxLength、开放模式 |\n| 权限范围 | 评估过度授权服务器和危险能力组合 |\n| OWASP 映射 | 将所有发现映射到 ASI01–ASI05（OWASP Agentic Top 10） |\n\n资料来源：[README.md:1]()\n\n### 工具风险等级定义\n\n| 等级 | 含义 | 示例工具 |\n|------|------|---------|\n| Critical | 可执行代码、修改数据或造成不可逆变更 | execute_command, write_file |\n| High | 可读取文件或发起网络请求 | read_file, fetch_url |\n| Medium | 轻度风险，需注意配置 | list_directory |\n| Low | 安全工具，可放心使用 | get_time |\n\n资料来源：[AGENTS.md:1]()\n\n### 提示注入检测类型\n\ndecoy-scan 内置 37 种提示注入检测模式，涵盖以下攻击类别：\n\n- 指令覆盖（Instruction Override）\n- 隐匿（Concealment）\n- 数据外泄（Data Exfiltration）\n- 凭证收割（Credential Harvesting）\n- 强制执行（Coercive Execution）\n- 工具影身（Tool Shadowing）\n- 规避技术（Evasion Techniques）\n\n资料来源：[AGENTS.md:1]()\n\n## 支持的平台\n\ndecoy-scan 支持检测以下 MCP 客户端的配置文件：\n\n| 平台 | 操作系统 | 配置文件路径 |\n|------|---------|-------------|\n| Claude Desktop | macOS / Windows / Linux | 平台相关配置目录 |\n| Cursor | macOS / Windows / Linux | 平台相关配置目录 |\n| Windsurf | macOS / Windows / Linux | 平台相关配置目录 |\n| VS Code | macOS / Windows / Linux | 平台相关配置目录 |\n| Claude Code | macOS / Windows / Linux | 平台相关配置目录 |\n| Zed | macOS / Windows / Linux | 平台相关配置目录 |\n| Cline | macOS / Windows / Linux | 平台相关配置目录 |\n\n配置文件路径根据操作系统自动适配（macOS、Windows、Linux）。\n\n资料来源：[AGENTS.md:1]()\n\n## 技术架构\n\n### 架构概览\n\n```mermaid\ngraph TD\n    A[用户执行 decoy-scan] --> B[发现 MCP 配置]\n    B --> C{配置类型}\n    C -->|项目级| D[扫描 .mcp.json]\n    C -->|用户级| E[扫描各客户端配置]\n    D --> F[探针 MCP 服务器]\n    E --> F\n    F --> G[获取工具列表]\n    G --> H[分类工具风险]\n    G --> I[检测提示注入]\n    G --> J[分析服务器命令]\n    G --> K[检查环境变量]\n    H --> L[生成扫描报告]\n    I --> L\n    J --> L\n    K --> L\n    L --> M[JSON / SARIF / CLI 输出]\n```\n\n### 核心模块结构\n\n根据 CONTRIBUTING.md 的代码结构说明，主逻辑位于 `index.mjs`：\n\n| 模块 | 功能 |\n|------|------|\n| `RISK_PATTERNS` + `classifyTool()` | 基于名称/描述的工具风险分类 |\n| `POISONING_PATTERNS` + `detectPoisoning()` | 工具描述中的提示注入检测 |\n| `analyzeServerCommand()` | 服务器启动命令分析 |\n| `SENSITIVE_ENV_PATTERNS` + `analyzeEnvExposure()` | 环境变量暴露检测 |\n| `analyzeReadiness()` | 生产就绪状态启发式检查 |\n| `OWASP_MAP` + `mapToOwasp()` | OWASP Agentic Top 10 映射 |\n| `HOST_CONFIGS` + `discoverConfigs()` | MCP 客户端配置发现 |\n| `probeServer()` | MCP stdio 探针 |\n| `scan()` | 完整扫描编排器 |\n| `toSarif()` | SARIF 输出生成器 |\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 库模式使用\n\ndecoy-scan 不仅可作为 CLI 工具使用，还提供编程接口：\n\n```javascript\nimport {\n  scan,\n  toSarif,\n  classifyTool,\n  detectPoisoning,\n  analyzeToxicFlows,\n  hashToolManifest,\n  detectManifestChanges,\n  discoverSkills,\n  analyzeSkill,\n} from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.toxicFlows);    // [{ id: \"TF001\", severity: \"critical\", roles: {...} }]\nconsole.log(results.skills);        // [{ name: \"...\", findings: [...] }]\nconsole.log(results.servers[0].manifestHash);  // \"45c4c571f03c78a2\"\n```\n\n资料来源：[README.md:1]()\n\n## 安装与使用\n\n### 快速开始\n\n无需安装，直接使用 npx 运行：\n\n```bash\nnpx decoy-scan                        # 完整扫描\nnpx decoy-scan --json                 # 机器可读输出\nnpx decoy-scan --sarif                # SARIF 2.1.0 格式（适用于 CI/CD）\nnpx decoy-scan explain <target>       # 解释风险等级/类别/工具\nnpx decoy-scan explain <target> --json  # 结构化解释输出\n```\n\n资料来源：[AGENTS.md:1]()\n\n### CLI 选项\n\n| 选项 | 简写 | 描述 |\n|------|------|------|\n| `--json` | `-j` | 输出 JSON 格式 |\n| `--sarif` | - | 输出 SARIF 2.1.0 格式 |\n| `--brief` | - | 输出最小摘要（隐含 `--json`） |\n| `--verbose` | `-v` | 显示所有工具，包括低风险 |\n| `--quiet` | `-q` | 抑制状态输出 |\n| `--version` | `-V` | 打印版本 |\n| `--help` | `-h` | 打印帮助信息 |\n\n资料来源：[AGENTS.md:1]()\n\n### GitHub Actions 集成\n\ndecoy-scan 提供官方 GitHub Action，可直接集成到 CI/CD 流水线：\n\n```yaml\n# .github/workflows/mcp-security.yml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n        with:\n          policy: no-critical,no-poisoning,no-toxic-flows\n          sarif: true\n          report: true\n          token: ${{ secrets.DECOY_TOKEN }}\n```\n\nAction 输入参数：\n\n| 输入 | 默认值 | 描述 |\n|------|--------|------|\n| `policy` | `no-critical,no-poisoning` | 逗号分隔的策略规则 |\n| `sarif` | `true` | 上传 SARIF 到 GitHub Security |\n| `report` | `false` | 上传到 Decoy Guard 仪表板 |\n| `token` | — | Decoy API 令牌 |\n| `verbose` | `false` | 显示所有工具包括低风险 |\n\n策略规则示例：\n\n```\nno-critical          关键工具失败（代码执行、文件写入）\nno-high              高风险工具失败（文件读取、网络）\nno-poisoning         提示注入失败\nno-toxic-flows       跨服务器数据泄露/破坏链失败\nno-secrets           MCP 配置中的密钥暴露失败\nrequire-tripwires    未安装 decoy-tripwire 时失败\nmax-critical=N       关键工具数量限制\n```\n\n资料来源：[README.md:1]()\n\n## 输出格式\n\n### JSON 输出结构\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null,\n    \"findings\": [{\n      \"type\": \"env-exposure\",\n      \"severity\": \"high\",\n      \"description\": \"...\",\n      \"source\": \"env-config\"\n    }]\n  }],\n  \"summary\": {\n    \"total\": 2, \"critical\": 1, \"high\": 1, \"medium\": 0, \"low\": 0, \"poisoned\": 0\n  },\n  \"exitCode\": 1\n}\n```\n\n资料来源：[AGENTS.md:1]()\n\n### SARIF 输出\n\nSARIF 2.1.0 格式输出，适用于 GitHub Security 标签页集成：\n\n```bash\nnpx decoy-scan --sarif\n```\n\n资料来源：[README.md:1]()\n\n### 退出码\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 未发现 critical 或 high 风险问题 |\n| `1` | 发现 high 风险问题 |\n| `2` | 发现 critical 问题、工具污染或毒性流 |\n\n退出码同时作为 `exitCode` 字段出现在 JSON 和 `--brief` 输出中，便于程序化判断。\n\n资料来源：[AGENTS.md:1]()\n\n## 设计原则\n\ndecoy-scan 遵循以下核心设计原则：\n\n1. **零依赖**：仅使用 Node.js 内置模块，不添加任何 npm 包\n2. **无构建步骤**：纯 ES 模块，无需 TypeScript 或打包器\n3. **高性能**：扫描应在数秒内完成，对服务器探针采用激进超时策略\n4. **安全扫描**：仅读取配置，不修改任何文件，及时终止启动的服务器\n5. **Agent 优先**：JSON 和 SARIF 输出必须可被机器解析，AGENTS.md 必须完整\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 版本历史\n\ndecoy-scan 采用语义化版本号，主要版本特性如下：\n\n| 版本 | 日期 | 主要更新 |\n|------|------|---------|\n| 0.7.0 | 2026-05-10 | v2遥测信封、重试+持久队列、首次运行仪表板链接 |\n| 0.6.0 | 2026-05-08 | 毒性流分析 v2、Skill 扫描、仪表板上传 |\n| 0.5.0 | 2026-04-21 | explain 子命令、CLI 输出重构 |\n| 0.2.0 | 2026-03-20 | SSE 传输安全、输入验证、动态诱饵检测 |\n| 0.1.0 | 2026-03-15 | 初始版本发布 |\n\n资料来源：[CHANGELOG.md:1]()\n\n## 开发指南\n\n### 本地开发\n\n```bash\ngit clone https://github.com/decoy-run/decoy-scan\ncd decoy-scan\nnode bin/cli.mjs --help\n```\n\n无需安装依赖，无需构建步骤，仅需 Node.js >= 18。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 测试\n\n运行完整测试套件：\n\n```bash\nnpm test\n```\n\n测试覆盖 CLI 输出、JSON/SARIF 结构、策略门控、毒性流检测、Skill 分析和清单哈希。所有测试通过后方可提交 PR。\n\n手动测试不同输出模式：\n\n```bash\nnode bin/cli.mjs --no-probe              # 仅配置扫描\nnode bin/cli.mjs --no-advisories         # 跳过网络请求\nnode bin/cli.mjs --json                  # 验证 JSON 结构\nnode bin/cli.mjs --sarif                 # 验证 SARIF 结构\nnode bin/cli.mjs --verbose               # 显示所有输出\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 添加新的检测模式\n\n污染检测模式定义在 `index.mjs` 的 `POISONING_PATTERNS` 中：\n\n```javascript\n{\n  pattern: /regex/i,           // 匹配规则\n  type: \"category-name\",       // 发现类型（用于 OWASP 映射）\n  severity: \"critical\",        // critical, high, medium, low\n  description: \"人类可读描述\"    // 输出中显示\n}\n```\n\n添加模式后，若适用，需将 `type` 添加到 `OWASP_MAP`。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 添加新平台支持\n\n在 `HOST_CONFIGS` 中添加新条目：\n\n```javascript\n\"New Client\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"config.json\");\n},\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 安全问题报告\n\n发现安全漏洞请通过电子邮件联系 `agent@decoy.run`，请勿为此项目创建公开 Issue。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n---\n\n<a id='getting-started'></a>\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#project-introduction), [命令行工具](#cli-usage)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [bin/cli.mjs](https://github.com/decoy-run/decoy-scan/blob/main/bin/cli.mjs)\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [action.yml](https://github.com/decoy-run/decoy-scan/blob/main/action.yml)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n</details>\n\n# 快速开始\n\ndecoy-scan 是一个 MCP（Model Context Protocol）供应链安全扫描工具，用于检测 MCP 服务器配置中的安全风险、提示注入和有毒数据流。\n\n## 功能概述\n\n| 功能模块 | 说明 |\n|---------|------|\n| 工具风险分类 | 按名称和描述将工具分类为 critical/high/medium/low |\n| 提示注入检测 | 37 种正则模式覆盖 20 个攻击类别 |\n| 有毒流分析 | 跨服务器数据泄漏（TF001）和破坏性（TF002）攻击链检测 |\n| 工具清单哈希 | 检测扫描间工具的增删改 |\n| 技能扫描 | Claude Code 技能中的提示注入、硬编码密钥、可疑 URL 检测 |\n| 服务器命令分析 | 管道到 shell、内联代码、 typosquatting、临时目录检测 |\n| 环境变量暴露 | API 密钥、令牌、密码、云凭证检测 |\n| 供应链情报 | 40+ 已知漏洞 MCP 包 |\n| 传输安全 | HTTP 无 TLS、缺失认证、泛域 CORS |\n| OWASP 映射 | 所有发现映射到 ASI01-ASI05 |\n\n资料来源：[README.md:37-51]()\n\n## 系统要求\n\n| 要求 | 详情 |\n|-----|------|\n| Node.js 版本 | >= 18 |\n| 依赖 | 零依赖（仅使用 Node.js 内置模块） |\n| 构建步骤 | 无需构建，直接运行 ES 模块 |\n| 支持平台 | macOS, Windows, Linux |\n\n资料来源：[CONTRIBUTING.md:8-10]()\n\n## 基本用法\n\n### 方式一：直接运行（推荐）\n\n```bash\nnpx decoy-scan\n```\n\n无需安装，直接运行。工具会自动扫描本地所有支持的 MCP 客户端配置。\n\n资料来源：[README.md:23-24]()\n\n### 方式二：本地开发\n\n```bash\ngit clone https://github.com/decoy-run/decoy-scan\ncd decoy-scan\nnode bin/cli.mjs --help\n```\n\n资料来源：[CONTRIBUTING.md:4-8]()\n\n## 支持的主机\n\ndecoy-scan 支持以下 7 个 MCP 客户端的配置文件自动发现：\n\n| 主机 | 平台支持 |\n|-----|---------|\n| Claude Desktop | macOS, Windows, Linux |\n| Cursor | macOS, Windows, Linux |\n| Windsurf | macOS, Windows, Linux |\n| VS Code | macOS, Windows, Linux |\n| Claude Code | macOS, Windows, Linux |\n| Zed | macOS, Windows, Linux |\n| Cline | macOS, Windows, Linux |\n\n配置文件路径根据操作系统自动适配（macOS 使用 `~/Library/...`，Windows 使用 `%APPDATA%`，Linux 使用 `~/.config`）。\n\n资料来源：[AGENTS.md:59-61]()\n\n## 扫描工作流\n\n```mermaid\ngraph TD\n    A[启动 decoy-scan] --> B[发现 MCP 服务器配置]\n    B --> C{配置检测}\n    C -->|有配置| D[启动服务器进程]\n    C -->|无配置| E[生成诊断信息]\n    D --> F[通过 stdio 查询工具列表]\n    F --> G[工具风险分类]\n    F --> H[提示注入检测]\n    F --> I[环境变量暴露分析]\n    G --> J[生成扫描报告]\n    H --> J\n    I --> J\n    E --> K[输出 --json / --sarif 格式]\n    J --> K\n```\n\n## CLI 参数参考\n\n### 全局参数\n\n| 参数 | 简写 | 说明 |\n|-----|-----|------|\n| `--json` | `-j` | JSON 结构化输出（机器可读） |\n| `--sarif` | `-s` | SARIF 2.1.0 格式输出（CI/CD 集成） |\n| `--brief` | `-b` | 最小摘要信息 |\n| `--verbose` | `-v` | 显示所有工具包括低风险项 |\n| `--quiet` | `-q` | 静默模式，不输出状态信息 |\n| `--version` | `-V` | 显示版本号 |\n| `--help` | `-h` | 显示帮助信息 |\n\n资料来源：[AGENTS.md:13-18]()\n\n### 扫描控制参数\n\n| 参数 | 说明 |\n|-----|------|\n| `--no-probe` | 仅扫描配置，不探测服务器 |\n| `--no-advisories` | 跳过网络请求（不查询供应链情报） |\n| `--no-telemetry` | 禁用遥测数据收集 |\n| `--verify` | AI 验证扫描结果 |\n\n资料来源：[AGENTS.md:19-26]()\n\n### 策略控制参数\n\n| 参数 | 说明 |\n|-----|------|\n| `--policy <rules>` | 逗号分隔的策略规则 |\n| `--report` | 上报结果到 Decoy Guard 仪表板 |\n\n策略规则包括：`no-critical`、`no-high`、`no-poisoning`、`no-toxic-flows`、`no-secrets`、`require-tripwires`、`max-critical=N`。\n\n资料来源：[README.md:78-82]()\n\n## 输出格式\n\n### 标准输出\n\n默认情况下，decoy-scan 输出人类可读的彩色终端界面：\n\n```\n▸ Discovering MCP servers…\n▸ Running N checks…\n\n✗ filesystem 2 critical\n  Critical: read_file, write_file\n  High: list_directory\n\n✓ claude-desktop passed\n\nN issues found · N critical, N high · N checks passed · Ns\n```\n\n服务器状态徽章：\n- `✗ name N critical` - 发现严重问题\n- `! name poisoned tool` - 检测到提示注入（洋红色）\n- `? name probe failed` - 服务器探测失败\n- `✓ name passed` - 通过扫描\n\n资料来源：[CHANGELOG.md:12-22]()\n\n### JSON 输出\n\n```bash\ndecoy-scan --json\n```\n\n输出结构：\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null,\n    \"findings\": [{\n      \"type\": \"env-exposure\",\n      \"severity\": \"high\",\n      \"description\": \"...\",\n      \"source\": \"env-config\"\n    }]\n  }],\n  \"summary\": {\n    \"total\": 2, \"critical\": 1, \"high\": 1, \"medium\": 0, \"low\": 0,\n    \"poisoned\": 0, \"toxicFlows\": [], \"status\": \"warn\", \"exitCode\": 1\n  }\n}\n```\n\n资料来源：[AGENTS.md:64-93]()\n\n### SARIF 输出\n\n```bash\ndecoy-scan --sarif\n```\n\n生成符合 SARIF 2.1.0 标准的输出，可直接上传到 GitHub Security 选项卡。\n\n资料来源：[README.md:57-58]()\n\n### Brief 输出\n\n```bash\ndecoy-scan --brief\n```\n\n最小摘要格式：\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"medium\": 4,\n  \"low\": 5,\n  \"poisoned\": 0,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n资料来源：[AGENTS.md:100-116]()\n\n## 退出码\n\n| 退出码 | 含义 |\n|-------|------|\n| `0` | 无 critical 或 high 风险问题 |\n| `1` | 发现 high 风险问题 |\n| `2` | 发现 critical 问题、工具中毒或有毒流 |\n\n退出码在 `--json` 和 `--brief` 输出中通过 `exitCode` 字段暴露，便于自动化脚本处理。\n\n资料来源：[AGENTS.md:45-54]()\n\n## GitHub Action 集成\n\n### 基本配置\n\n在 `.github/workflows/mcp-security.yml` 中添加：\n\n```yaml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n```\n\n资料来源：[README.md:60-71]()\n\n### 完整配置示例\n\n```yaml\n- uses: decoy-run/decoy-scan@v1\n  with:\n    policy: no-critical,no-poisoning,no-toxic-flows\n    sarif: true\n    report: true\n    token: ${{ secrets.DECOY_TOKEN }}\n    verbose: false\n```\n\n| 输入参数 | 默认值 | 说明 |\n|---------|-------|------|\n| `policy` | `no-critical,no-poisoning` | 逗号分隔的策略规则 |\n| `sarif` | `true` | 上传 SARIF 到 GitHub Security |\n| `report` | `false` | 上传到 Decoy Guard 仪表板 |\n| `token` | — | Decoy API 令牌 |\n| `verbose` | `false` | 显示所有工具包括低风险 |\n\n资料来源：[README.md:73-80]()\n\n### GitHub Action 输出\n\nAction 提供以下输出供后续步骤使用：\n\n| 输出 | 说明 |\n|-----|------|\n| `exit-code` | 扫描退出码 |\n| `sarif-file` | SARIF 文件路径 |\n| `summary` | 摘要信息 |\n\n资料来源：[action.yml:45-54]()\n\n## explain 子命令\n\n用于解释扫描发现的含义，无需解析完整输出：\n\n```bash\ndecoy-scan explain critical              # 严重等级\ndecoy-scan explain tool-description       # 发现类别\ndecoy-scan explain prompt-override        # 中毒类型\ndecoy-scan explain read_file             # 工具名称\ndecoy-scan explain list                  # 列出所有可解释目标\ndecoy-scan explain <target> --json       # 结构化输出\n```\n\nJSON 输出示例：\n\n```json\n{\n  \"tool\": \"decoy-scan\",\n  \"version\": \"0.5.1\",\n  \"target\": \"critical\",\n  \"result\": {\n    \"kind\": \"tier\",\n    \"key\": \"critical\",\n    \"title\": \"Critical\",\n    \"summary\": \"Can execute code, modify data, or cause irreversible changes.\",\n    \"body\": \"...\",\n    \"examples\": [\"execute_command\", \"write_file\"],\n    \"advice\": \"...\"\n  }\n}\n```\n\n`result.kind` 可能是：`tier`（等级）、`category`（类别）、`poisoning`（中毒类型）、`tool`（工具）。\n\n资料来源：[AGENTS.md:24-49]()\n\n## 库模式使用\n\ndecoy-scan 也可作为 Node.js 模块导入使用：\n\n```javascript\nimport {\n  scan,\n  toSarif,\n  classifyTool,\n  detectPoisoning,\n  analyzeToxicFlows,\n  hashToolManifest,\n  detectManifestChanges,\n  discoverSkills,\n  analyzeSkill,\n} from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.toxicFlows);    // 有毒流分析结果\nconsole.log(results.skills);        // 技能扫描结果\nconsole.log(results.servers[0].manifestHash);  // \"45c4c571f03c78a2\"\n```\n\n资料来源：[README.md:86-97]()\n\n## 扫描检查项速查\n\n| 检查项 | 检测内容 |\n|-------|---------|\n| 工具风险分类 | 按名称和描述评估风险等级 |\n| 提示注入检测 | 指令覆盖、隐藏、凭证窃取、强制执行、工具影子、规避技术 |\n| 有毒流分析 | 跨服务器数据泄漏（TF001）和破坏性攻击链（TF002） |\n| 清单变更追踪 | 工具增删、描述变更的哈希对比 |\n| 服务器命令 | 管道到 shell、内联代码、typosquatting |\n| 环境暴露 | API 密钥、令牌、数据库 URL、云凭证 |\n| 供应链情报 | 40+ 已知漏洞 MCP 包 |\n| 传输安全 | HTTP 明文、缺失认证、公开 SSE |\n| 输入验证 | 无约束参数、缺失长度限制、开放 schema |\n| 权限范围 | 过度特权、危险能力组合 |\n\n资料来源：[README.md:37-51]()\n\n## 下一步\n\n- 查看 [AGENTS.md](AGENTS.md) 了解机器可读输出的详细 schema\n- 查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何扩展检测模式\n- 查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史\n- 访问 [decoy.run 文档](https://decoy.run/docs/scan/overview) 获取完整文档\n\n---\n\n<a id='cli-usage'></a>\n\n## 命令行工具\n\n### 相关页面\n\n相关主题：[快速开始](#getting-started)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [bin/cli.mjs](https://github.com/decoy-run/decoy-scan/blob/main/bin/cli.mjs)\n- [lib/explain.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/explain.mjs)\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [action.yml](https://github.com/decoy-run/decoy-scan/blob/main/action.yml)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n</details>\n\n# 命令行工具\n\n## 概述\n\ndecoy-scan 提供了一个零依赖的 Node.js CLI 工具，用于扫描 MCP（Model Context Protocol）客户端配置中的安全风险。该命令行工具无需安装配置，下载后即可直接运行，支持对 Claude Desktop、Cursor、Windsurf、VS Code、Claude Code、Zed 和 Cline 等多种 MCP 主机进行安全扫描。\n\nCLI 的核心功能包括：工具风险分类、提示注入检测、有毒数据流分析、工具清单哈希追踪、技能扫描、服务器命令分析、环境变量暴露检测、供应链告警以及 OWASP Agentic Top 10 映射。资料来源：[README.md:1-45]()\n\n## 快速开始\n\n```bash\nnpx decoy-scan                        # 完整扫描\nnpx decoy-scan --json                 # 机器可读输出\nnpx decoy-scan --sarif                # SARIF 2.1.0 格式（用于 CI/CD）\nnpx decoy-scan explain <target>       # 解释风险等级/类别/工具名称\n```\n\n该工具要求 Node.js 18 或更高版本，无需预先安装任何依赖包。资料来源：[CONTRIBUTING.md:1-8]()\n\n## 全局选项\n\n| 选项 | 说明 |\n|------|------|\n| `--verbose`, `-v` | 显示所有工具，包括低风险项 |\n| `--quiet`, `-q` | 抑制状态输出 |\n| `--version`, `-V` | 打印版本号 |\n| `--help`, `-h` | 打印帮助信息 |\n\n### 扫描控制选项\n\n| 选项 | 说明 |\n|------|------|\n| `--no-probe` | 仅扫描配置文件，不探测服务器 |\n| `--no-advisories` | 跳过供应链告警检查（避免网络请求） |\n| `--json` | 输出 JSON 格式结果 |\n| `--sarif` | 输出 SARIF 2.1.0 格式结果 |\n| `--brief` | 仅输出摘要信息（隐含 `--json`） |\n\n### 输出控制选项\n\n| 选项 | 说明 |\n|------|------|\n| `--output <file>` | 将结果写入指定文件 |\n| `--no-telemetry` | 禁用遥测数据收集 |\n| `--report` | 上传结果至 Decoy Guard 仪表板 |\n\n资料来源：[AGENTS.md:1-10]()\n\n## 子命令\n\n### `explain` 子命令\n\n`explain` 子命令用于解析扫描结果的含义，无需解析完整的扫描输出。当 AI agent 看到某个发现并需要结构化上下文来采取行动时，此命令非常有用。\n\n```bash\ndecoy-scan explain critical              # 严重性等级\ndecoy-scan explain tool-description      # 发现类别\ndecoy-scan explain prompt-override       # 投毒类型\ndecoy-scan explain read_file             # 工具名称（运行真实分类规则）\ndecoy-scan explain list                  # 枚举所有可解释的目标\ndecoy-scan explain <target> --json       # 结构化输出（推荐用于 agent）\n```\n\n资料来源：[AGENTS.md:20-35]()\n\n#### `explain` 输出格式\n\n`--json` 输出的 JSON 结构如下：\n\n```json\n{\n  \"tool\": \"decoy-scan\",\n  \"version\": \"0.5.1\",\n  \"target\": \"critical\",\n  \"result\": {\n    \"kind\": \"tier\",\n    \"key\": \"critical\",\n    \"title\": \"Critical\",\n    \"summary\": \"Can execute code, modify data, or cause irreversible changes.\",\n    \"body\": \"...\",\n    \"examples\": [\"execute_command\", \"write_file\", \"...\"],\n    \"advice\": \"...\"\n  }\n}\n```\n\n`result.kind` 的值包括：\n\n| kind 值 | 说明 |\n|---------|------|\n| `tier` | 严重性等级（critical、high、medium、low） |\n| `category` | 发现类别（如 env-exposure、missing-description） |\n| `poisoning` | 投毒类型（如 prompt-override、credential-harvesting） |\n| `tool` | 工具名称（包含 risk、reason、matched 等字段） |\n\n资料来源：[AGENTS.md:36-50]()\n\n## 退出码\n\nCLI 通过退出码向调用者传递扫描结果的状态：\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 未发现严重或高风险问题 |\n| `1` | 发现高风险问题 |\n| `2` | 发现严重问题、工具投毒或有毒数据流 |\n\n退出码也会在 `--json` 和 `--brief` 输出的 `exitCode` 字段中暴露，便于 agent 在不重新解析严重性计数的情况下进行分支判断。资料来源：[AGENTS.md:58-68]()\n\n## 输出格式\n\n### JSON 输出架构\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null,\n    \"findings\": [{\n      \"type\": \"env-exposure\",\n      \"severity\": \"high\",\n      \"description\": \"...\",\n      \"source\": \"env-config\"\n    }]\n  }],\n  \"summary\": {\n    \"total\": 2,\n    \"critical\": 1,\n    \"high\": 2,\n    \"medium\": 4,\n    \"low\": 5,\n    \"poisoned\": 0\n  }\n}\n```\n\n资料来源：[AGENTS.md:75-100]()\n\n### `--brief` 输出架构\n\n`--brief` 隐含 `--json`，输出精简的摘要对象：\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"medium\": 4,\n  \"low\": 5,\n  \"poisoned\": 0,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n| 字段 | 说明 |\n|------|------|\n| `servers` | 扫描的非诱饵、非错误服务器数量 |\n| `critical`、`high`、`medium`、`low` | 各风险等级的工具数量 |\n| `poisoned` | 工具投毒发现数量 |\n| `status` | `pass`（清洁）、`warn`（高风险）或 `fail`（严重/投毒/有毒流） |\n| `exitCode` | 进程退出码 |\n\n资料来源：[AGENTS.md:102-125]()\n\n### SARIF 输出\n\n使用 `--sarif` 选项可生成 SARIF 2.1.0 格式的输出，适用于 GitHub Security 标签页集成：\n\n```bash\ndecoy-scan --sarif\nnpx decoy-scan --sarif | jq\n```\n\n资料来源：[README.md:15-18]()\n\n## 工作流程架构\n\n```mermaid\ngraph TD\n    A[用户执行 decoy-scan] --> B[发现 MCP 服务器配置]\n    B --> C{选项解析}\n    C -->|explain| D[解析 explain 子命令]\n    C -->|scan| E[执行安全扫描]\n    D --> F[查询 RISK_PATTERNS]\n    D --> G[查询 POISONING_PATTERNS]\n    F --> H[返回结构化解释]\n    G --> H\n    E --> I[探测 MCP 服务器]\n    I --> J[获取工具列表]\n    J --> K[执行安全分析]\n    K --> L{发现风险?}\n    L -->|是| M[分类风险等级]\n    L -->|否| N[标记为通过]\n    M --> O[生成扫描报告]\n    N --> O\n    O --> P[根据结果设置退出码]\n```\n\n## 支持的主机\n\ndecoy-scan 支持以下 7 个 MCP 主机：\n\n| 主机 | 平台支持 |\n|------|----------|\n| Claude Desktop | macOS, Windows, Linux |\n| Cursor | macOS, Windows, Linux |\n| Windsurf | macOS, Windows, Linux |\n| VS Code | macOS, Windows, Linux |\n| Claude Code | macOS, Windows, Linux |\n| Zed | macOS, Windows, Linux |\n| Cline | macOS, Windows, Linux |\n\n配置文件路径根据操作系统自动适配（macOS、Windows、Linux）。资料来源：[AGENTS.md:70-73]()\n\n## CI/CD 集成\n\n### GitHub Action\n\ndecoy-scan 提供官方 GitHub Action，可用于 CI/CD 流水线：\n\n```yaml\n# .github/workflows/mcp-security.yml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n```\n\n#### Action 输入参数\n\n| 输入 | 默认值 | 说明 |\n|------|--------|------|\n| `policy` | `no-critical,no-poisoning` | 逗号分隔的策略规则 |\n| `sarif` | `true` | 上传 SARIF 至 GitHub Security 标签页 |\n| `report` | `false` | 上传至 Decoy Guard 仪表板 |\n| `token` | — | Decoy API token（用于 `report`） |\n| `verbose` | `false` | 显示所有工具包括低风险项 |\n\n#### 策略规则\n\n```\nno-critical          严重工具（代码执行、文件写入）导致失败\nno-high              高风险工具（文件读取、网络）导致失败\nno-poisoning         工具描述中的提示注入导致失败\nno-toxic-flows       跨服务器数据泄露/破坏链导致失败\nno-secrets           MCP 配置中暴露的密钥导致失败\nrequire-tripwires    未安装 decoy-tripwire 导致失败\nmax-critical=N       允许的严重问题数量\n```\n\n资料来源：[README.md:75-100]()\n\n### CLI 参数与 GitHub Action 输入的映射\n\n```mermaid\ngraph LR\n    A[CLI 参数] --> B[Action 输入]\n    A1[--json] --> B1[sarif=false, brief=true]\n    A2[--verbose] --> B2[verbose=true]\n    A3[--report] --> B3[report=true]\n    A4[--policy] --> B4[policy]\n    A5[--token] --> B5[token]\n```\n\n## 代码结构\n\nCLI 的核心实现在 `index.mjs` 中，各模块职责如下：\n\n| 模块 | 功能 |\n|------|------|\n| `RISK_PATTERNS` + `classifyTool()` | 基于名称/描述的工具风险分类 |\n| `POISONING_PATTERNS` + `detectPoisoning()` | 工具描述中的提示注入检测 |\n| `analyzeServerCommand()` | 服务器启动命令分析 |\n| `SENSITIVE_ENV_PATTERNS` + `analyzeEnvExposure()` | 环境变量暴露检测 |\n| `analyzeReadiness()` | 生产就绪性启发式检查 |\n| `OWASP_MAP` + `mapToOwasp()` | OWASP Agentic Top 10 映射 |\n| `HOST_CONFIGS` + `discoverConfigs()` | MCP 客户端配置发现 |\n| `probeServer()` | MCP stdio 探测 |\n| `scan()` | 完整扫描编排器 |\n| `toSarif()` | SARIF 输出生成器 |\n\n资料来源：[CONTRIBUTING.md:12-30]()\n\n## 扫描类别详解\n\n### 1. 工具风险分类\n\n根据名称模式和描述分析，将每个工具分类为严重/高/中/低风险。关键风险模式包括代码执行、文件写入、网络调用等。资料来源：[CONTRIBUTING.md:20-22]()\n\n### 2. 工具投毒检测\n\n37 种正则表达式模式横跨 20 个攻击类别，检测隐藏在工具描述中的提示注入，包括指令覆盖、隐藏、数据外泄、凭证窃取、强制执行、工具影子和规避技术。资料来源：[CONTRIBUTING.md:22-24]()\n\n### 3. 服务器命令分析\n\n检查启动命令中的管道到 shell、临时目录、内联代码、域名仿冒和网络工具。资料来源：[CONTRIBUTING.md:24-26]()\n\n### 4. 环境变量暴露\n\n标记 12 类敏感凭证，包括 API 密钥、令牌、密码、数据库 URL 和云凭证。资料来源：[CONTRIBUTING.md:26-28]()\n\n### 5. 生产就绪性\n\n检查缺失描述、缺失模式、无必需字段、过度作用域以及无安全提示的危险工具。资料来源：[CONTRIBUTING.md:28-30]()\n\n### 6. 供应链告警\n\n通过 Decoy 告警数据库交叉引用 40+ 个已知易受攻击的 MCP 包。资料来源：[CONTRIBUTING.md:30-32]()\n\n## 设计原则\n\n- **零依赖**：仅使用 Node.js 内置模块，不添加 npm 包。\n- **无需构建**：纯 ES 模块，无 TypeScript，无打包器。\n- **快速**：扫描应在数秒内完成，积极设置服务器超时。\n- **安全**：从不修改配置，仅读取扫描，遇到问题时立即终止。\n- **面向 Agent**：JSON 和 SARIF 输出必须是机器可解析的。资料来源：[CONTRIBUTING.md:50-57]()\n\n## 手动测试模式\n\n```bash\nnode bin/cli.mjs --no-probe              # 仅配置扫描\nnode bin/cli.mjs --no-advisories         # 跳过网络调用\nnode bin/cli.mjs --json                  # 验证 JSON 结构\nnode bin/cli.mjs --sarif                 # 验证 SARIF 结构\nnode bin/cli.mjs --verbose               # 显示所有输出\n```\n\n资料来源：[CONTRIBUTING.md:45-49]()\n\n## 库导出\n\nCLI 的核心功能也可作为库导入使用：\n\n```javascript\nimport {\n  scan,\n  toSarif,\n  classifyTool,\n  detectPoisoning,\n  analyzeToxicFlows,\n  hashToolManifest,\n  detectManifestChanges,\n  discoverSkills,\n  analyzeSkill,\n} from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.toxicFlows);    // [{ id: \"TF001\", severity: \"critical\", roles: {...} }]\nconsole.log(results.skills);        // [{ name: \"...\", findings: [...] }]\nconsole.log(results.servers[0].manifestHash);  // \"45c4c571f03c78a2\"\n```\n\n资料来源：[README.md:25-40]()\n\n## 遥测数据\n\nCLI 默认收集匿名使用统计信息，可通过以下方式禁用：\n\n- 设置环境变量 `DECOY_TELETELRY=0`\n- 使用 `--no-telemetry` 标志\n\n首次运行会显示遥测通知，并缓存于 `~/.decoy/telemetry-notice-shown`。资料来源：[CHANGELOG.md:2026-05-10]()\n\n## 常见使用场景\n\n| 场景 | 命令 |\n|------|------|\n| 快速扫描 | `npx decoy-scan` |\n| CI 集成 | `npx decoy-scan --sarif --no-advisories` |\n| Agent 集成 | `npx decoy-scan --brief --json` |\n| 了解风险 | `npx decoy-scan explain critical` |\n| 详细输出 | `npx decoy-scan --verbose` |\n| 仅配置检查 | `npx decoy-scan --no-probe` |\n\n资料来源：[README.md:10-25]()\n\n---\n\n<a id='security-checks'></a>\n\n## 安全检查项目\n\n### 相关页面\n\n相关主题：[项目介绍](#project-introduction), [风险分级系统](#risk-classification), [提示注入检测](#prompt-injection-detection)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n</details>\n\n# 安全检查项目\n\ndecoy-scan 是一款针对 MCP (Model Context Protocol) 供应链安全的扫描工具，零依赖，基于 Node.js 18+ 运行。本文档详细说明该工具执行的所有安全检查项目及其检测机制。\n\n## 核心安全检查概览\n\ndecoy-scan 实现了 **12 大安全检查类别**，涵盖从工具风险分类到供应链威胁检测的完整攻击面分析。\n\n| 检查类别 | 检测内容 | 严重级别 |\n|----------|----------|----------|\n| 工具风险分类 | 按名称和描述将工具分为 critical/high/medium/low |\n| 提示词注入检测 | 37 种正则模式覆盖 20 个攻击类别 |\n| 有毒数据流分析 | 跨服务器数据泄露和破坏性攻击链 |\n| 工具清单哈希 | 检测工具新增、移除和描述变更 |\n| 技能扫描 | Claude Code 技能中的注入和敏感信息 |\n| 服务器命令分析 | 管道到 shell、内联代码、域名仿冒等 |\n| 环境变量暴露 | API 密钥、令牌、云凭证等 |\n| 供应链预警 | 40+ 已知漏洞 MCP 包 |\n| 传输安全 | HTTP 无 TLS、缺失认证、公开 SSE |\n| 输入验证 | 无约束参数、缺失 maxLength、开放 schema |\n| 权限范围 | 过度授权服务器、危险能力组合 |\n| OWASP 映射 | 每项发现映射到 ASI01-ASI05 |\n\n资料来源：[README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n\n## 工具风险分类体系\n\n### 风险级别定义\n\n工具风险分类是 decoy-scan 的核心检测引擎，通过 `RISK_PATTERNS` 和 `classifyTool()` 函数实现。\n\n```mermaid\ngraph TD\n    A[工具输入] --> B{名称模式匹配}\n    B -->|^execute.*| C[Critical 级别]\n    B -->|^read.*|^write.*| D[High 级别]\n    B -->|^list.*|^search.*| E[Medium 级别]\n    B -->|其他| F[Low 级别]\n    C --> G[可执行代码、修改数据、不可逆变更]\n    D --> H[文件读写、网络访问]\n    E --> I[信息列举]\n    F --> J[安全工具]\n```\n\n资料来源：[CONTRIBUTING.md:1-9]()\n\n### Critical 级别工具模式\n\n以下工具名称模式被直接判定为 **critical** 风险：\n\n| 正则模式 | 匹配示例 | 风险说明 |\n|----------|----------|----------|\n| `^execute[_-]?(script\\|code\\|js\\|javascript\\|python\\|sql)$` | `execute_code`, `execute_python` | 可执行任意代码 |\n| `^evaluate[_-]?(script\\|code)$` | `evaluate_script` | 脚本评估执行 |\n| `^run[_-]?(script\\|code\\|js\\|python\\|sql)$` | `run_javascript` | 代码运行 |\n| `^eval[_-]?(script\\|code)$` | `eval_code` | 直接代码执行 |\n| `^write[_-]?file$` | `write_file` | 文件写入 |\n| `^spawn[_-]?process$` | `spawn_process` | 进程生成 |\n\n资料来源：[CHANGELOG.md:1-20]()\n\n### 分类算法改进\n\n在 v0.5.6 版本中修复了此前版本存在的边界问题：之前版本对每个名称模式都使用了锚点 `^`，导致带有后缀的代码执行名称（如 `evaluate_script`、`execute_python`）被错误分类为 \"low\"。\n\n改进措施包括：\n\n1. 添加了完整的带后缀代码执行模式到 critical 层级\n2. 子串回退机制现在同时对**小写化的名称**运行，使 `evaluate`、`spawn`、`fetch` 等危险动词即使没有提供描述也能正确分类\n\n资料来源：[CHANGELOG.md:1-20]()\n\n## 提示词注入检测\n\n### 攻击类别体系\n\n提示词注入检测通过 `POISONING_PATTERNS` 和 `detectPoisoning()` 函数实现，包含 **37 种正则模式**覆盖 **20 个攻击类别**。\n\n```mermaid\ngraph TD\n    A[工具描述文本] --> B{Poisoning Pattern 匹配}\n    B -->|指令覆盖| C[instruction-override]\n    B -->|隐匿| D[concealment]\n    B -->|数据泄露| E[data-exfiltration]\n    B -->|凭证窃取| F[credential-harvesting]\n    B -->|强制执行| G[coercive-execution]\n    B -->|工具影子| H[tool-shadowing]\n    B -->|规避技术| I[evasion-techniques]\n    C --> J[Critical/High 级别发现]\n    D --> J\n    E --> J\n    F --> J\n    G --> J\n    H --> J\n    I --> J\n```\n\n### 检测模式结构\n\n每个 poisoning 检测模式包含以下字段：\n\n```javascript\n{\n  pattern: /regex/i,           // 匹配规则\n  type: \"category-name\",       // 发现类型（用于 OWASP 映射）\n  severity: \"critical\",        // critical/high/medium/low\n  description: \"Human-readable\" // 人类可读说明\n}\n```\n\n资料来源：[CONTRIBUTING.md:1-20]()\n\n### OWASP Agentic Top 10 映射\n\n所有提示词注入检测结果都会映射到 OWASP Agentic Top 10 for 2026 标准，通过 `OWASP_MAP` 和 `mapToOwasp()` 函数实现。\n\n| 发现类型 | OWASP 映射 | 严重级别 |\n|----------|------------|----------|\n| instruction-override | ASI01 | Critical |\n| credential-harvesting | ASI02 | Critical |\n| data-exfiltration | ASI03 | High |\n| tool-shadowing | ASI04 | High |\n| coercive-execution | ASI05 | Medium |\n\n## 有毒数据流分析\n\n### 攻击链检测\n\n有毒数据流分析检测跨服务器的数据泄露和破坏性攻击链。\n\n```mermaid\ngraph LR\n    A[服务器 A] -->|敏感数据流| B[服务器 B]\n    B -->|外部通信| C[攻击者控制端点]\n    D[服务器 X] -->|破坏操作| E[系统资源]\n    \n    subgraph TF001[数据泄露攻击链]\n        A\n        B\n        C\n    end\n    \n    subgraph TF002[破坏性攻击链]\n        D\n        E\n    end\n```\n\n### 攻击链类型\n\n| ID | 类型 | 说明 |\n|----|------|------|\n| TF001 | 数据泄露 | 跨服务器敏感数据流向外部 |\n| TF002 | 破坏性攻击 | 跨服务器破坏操作链 |\n\n资料来源：[README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n\n## 服务器命令分析\n\n### 检测能力\n\n`analyzeServerCommand()` 函数分析 MCP 服务器的启动命令，检测以下可疑特征：\n\n| 检测类型 | 特征 | 风险 |\n|----------|------|------|\n| 管道到 shell | `| bash`, `| sh` | 命令注入 |\n| 临时目录执行 | `/tmp/`, `/var/tmp/` | 持久化攻击 |\n| 内联代码 | `node -e \"...\"`, `python -c \"...\"` | 混淆执行 |\n| 域名仿冒 | 相似拼写的包名 | typosquatting |\n| 网络工具 | `curl`, `wget`, `nc` | 外部通信 |\n\n资料来源：[CONTRIBUTING.md:1-9]()\n\n## 环境变量暴露检测\n\n### 敏感信息模式\n\n`SENSITIVE_ENV_PATTERNS` 和 `analyzeEnvExposure()` 函数检测 12 类敏感环境变量暴露：\n\n```mermaid\ngraph TD\n    A[MCP 配置] --> B{环境变量分析}\n    B -->|API 密钥| C[API_KEY, OPENAI_API_KEY]\n    B -->|令牌| D[AWS_SECRET, GITHUB_TOKEN]\n    B -->|密码| E[DB_PASSWORD, MYSQL_PWD]\n    B -->|数据库 URL| F[DATABASE_URL]\n    B -->|云凭证| G[AWS_ACCESS_KEY, AZURE_KEY]\n    B -->|其他| H[12 类总计]\n    C --> I[High 级别发现]\n    D --> I\n    E --> I\n    F --> I\n    G --> I\n```\n\n### 暴露类别\n\n| 类别 | 模式示例 | 严重级别 |\n|------|----------|----------|\n| API 密钥 | `*_API_KEY`, `*_SECRET_KEY` | High |\n| 访问令牌 | `*_TOKEN`, `*_ACCESS_TOKEN` | High |\n| 数据库凭证 | `*_PASSWORD`, `*_CREDENTIALS` | Critical |\n| 云服务密钥 | `AWS_*`, `AZURE_*`, `GCP_*` | Critical |\n\n## 生产就绪性检查\n\n### 检查项目\n\n`analyzeReadiness()` 函数实现以下生产就绪性检查：\n\n| 检查项 | 条件 | 严重级别 |\n|--------|------|----------|\n| 缺失描述 | 工具缺少 description 字段 | Medium |\n| 缺失 schema | 工具缺少 inputSchema | Medium |\n| 无必需字段 | 关键参数缺少 required 声明 | Medium |\n| 过度授权 | 权限范围过大 | High |\n| 破坏性工具无安全提示 | 危险操作无 confirm 参数 | Medium |\n\n资料来源：[CONTRIBUTING.md:1-20]()\n\n## 工具清单变更追踪\n\n### 哈希机制\n\ndecoy-scan 通过 `hashToolManifest()` 和 `detectManifestChanges()` 函数追踪工具清单变更：\n\n```mermaid\ngraph LR\n    A[首次扫描] -->|生成哈希| B[工具清单哈希]\n    C[后续扫描] -->|生成哈希| D[工具清单哈希]\n    B --> E{哈希比对}\n    D --> E\n    E -->|哈希变化| F[变更检测]\n    E -->|哈希相同| G[无变更]\n    F --> H[报告变更详情]\n```\n\n### 检测变更类型\n\n| 变更类型 | 说明 |\n|----------|------|\n| 工具新增 | 新增的工具可能引入风险 |\n| 工具移除 | 移除的工具有安全盲区 |\n| 描述变更 | 描述修改可能隐藏恶意行为 |\n\n## 供应链预警集成\n\n### 预警数据库\n\ndecoy-scan 通过供应链预警功能交叉引用 **Decoy 预警数据库**，覆盖 40+ 已知存在漏洞的 MCP 包：\n\n```mermaid\ngraph TD\n    A[扫描的 MCP 包] --> B{Decoy 预警数据库}\n    B -->|已知漏洞| C[高风险警告]\n    B -->|未知| D[通过扫描]\n    C --> E[提供修复建议]\n```\n\n### 检查方式\n\n预警检查默认启用，可通过以下方式跳过：\n\n```bash\nnpx decoy-scan --no-advisories  # 跳过网络调用\n```\n\n## 退出码与状态\n\n### 退出码定义\n\n| 退出码 | 含义 | 触发条件 |\n|--------|------|----------|\n| 0 | 通过 | 无 critical 或 high 风险问题 |\n| 1 | 警告 | 发现 high 风险问题 |\n| 2 | 失败 | 发现 critical 问题、工具投毒或有毒数据流 |\n\n### `--brief` 输出状态\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"medium\": 4,\n  \"low\": 5,\n  \"poisoned\": 0,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n| 状态值 | 含义 |\n|--------|------|\n| `pass` | 清洁无问题 |\n| `warn` | 存在 high 风险 |\n| `fail` | 存在 critical/poisoned/toxic-flows |\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 输出格式\n\n### 支持的输出格式\n\n| 格式 | 用途 | 使用场景 |\n|------|------|----------|\n| 人类可读 | 默认输出 | 终端查看 |\n| `--json` | 机器可读输出 | CI/CD 集成、代理消费 |\n| `--sarif` | SARIF 2.1.0 | GitHub Security 标签 |\n| `--brief` | 摘要输出 | 快速状态检查 |\n\n### JSON 输出结构\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null,\n    \"findings\": [{\n      \"type\": \"env-exposure\",\n      \"severity\": \"high\",\n      \"description\": \"...\",\n      \"source\": \"env-config\"\n    }]\n  }],\n  \"summary\": {\n    \"total\": 2,\n    \"critical\": 1,\n    \"high\": 1,\n    \"medium\": 0,\n    \"low\": 0\n  }\n}\n```\n\n## 架构组件\n\n### 核心模块结构\n\n| 模块 | 职责 | 文件位置 |\n|------|------|----------|\n| `RISK_PATTERNS` | 工具风险分类正则 | index.mjs |\n| `POISONING_PATTERNS` | 提示词注入检测正则 | index.mjs |\n| `SENSITIVE_ENV_PATTERNS` | 环境变量暴露模式 | index.mjs |\n| `OWASP_MAP` | OWASP 映射表 | index.mjs |\n| `HOST_CONFIGS` | MCP 客户端配置发现 | index.mjs |\n| `classifyTool()` | 工具风险分类函数 | index.mjs |\n| `detectPoisoning()` | 投毒检测函数 | index.mjs |\n| `analyzeServerCommand()` | 服务器命令分析 | index.mjs |\n| `analyzeEnvExposure()` | 环境变量暴露分析 | index.mjs |\n| `analyzeReadiness()` | 生产就绪性检查 | index.mjs |\n| `probeServer()` | MCP stdio 探测 | index.mjs |\n| `scan()` | 完整扫描编排 | index.mjs |\n| `toSarif()` | SARIF 输出生成 | index.mjs |\n\n资料来源：[CONTRIBUTING.md:1-15]()\n\n### 扫描流程\n\n```mermaid\ngraph TD\n    A[启动扫描] --> B[发现 MCP 服务器]\n    B --> C[探测服务器工具列表]\n    C --> D[工具风险分类]\n    C --> E[提示词注入检测]\n    C --> F[服务器命令分析]\n    C --> G[环境变量暴露检测]\n    C --> H[生产就绪性检查]\n    D --> I[汇总发现]\n    E --> I\n    F --> I\n    G --> I\n    H --> I\n    I --> J[输出报告]\n    J --> K{退出码判定}\n    K -->|0| L[无问题]\n    K -->|1| M[High 风险]\n    K -->|2| N[Critical/投毒]\n```\n\n## 设计原则\n\ndecoy-scan 的安全检查遵循以下核心设计原则：\n\n1. **零依赖** — 仅使用 Node.js 内置模块，不引入外部包\n2. **零构建** — 原始 ES 模块，无需 TypeScript 或打包工具\n3. **快速** — 扫描应在秒级完成，激进地设置超时\n4. **安全** — 只读扫描，不修改配置，及时终止派生的服务器进程\n5. **代理优先** — JSON 和 SARIF 输出必须机器可解析\n\n资料来源：[CONTRIBUTING.md:1-5]()\n\n## 扩展检测能力\n\n### 添加新的投毒检测模式\n\n在 `POISONING_PATTERNS` 中添加新模式：\n\n```javascript\n{\n  pattern: /new-suspicious-pattern/i,\n  type: \"new-category-name\",\n  severity: \"high\",\n  description: \"Human-readable description\"\n}\n```\n\n添加后需在 `OWASP_MAP` 中注册（如果适用）。\n\n### 添加新的就绪性检查\n\n在 `analyzeReadiness()` 函数中添加：\n\n```javascript\nif (/* condition */) {\n  findings.push({\n    type: \"readiness-check-name\",\n    severity: \"medium\",\n    description: \"What's wrong and why it matters\"\n  });\n}\n```\n\n### 添加新的主机支持\n\n在 `HOST_CONFIGS` 中添加新客户端配置：\n\n```javascript\n\"New Client\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"config.json\");\n}\n```\n\n## 相关文档\n\n- [CLI 使用指南](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md) — 完整的命令行接口文档\n- [贡献指南](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md) — 如何添加新的检测模式\n- [OWASP Agentic Top 10 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) — 安全检查的威胁模型基础\n\n---\n\n<a id='risk-classification'></a>\n\n## 风险分级系统\n\n### 相关页面\n\n相关主题：[安全检查项目](#security-checks), [扫描架构](#scanning-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [lib/tier.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/tier.mjs)\n- [lib/owasp.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/owasp.mjs)\n- [lib/constants.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/constants.mjs)\n</details>\n\n# 风险分级系统\n\ndecoy-scan 的风险分级系统是 MCP 安全扫描的核心组件，负责对 MCP 服务器中的工具进行分类、评级和映射。该系统通过多层检测机制，识别工具的风险等级，并将所有发现映射到行业标准 OWASP Agentic Top 10。\n\n## 系统概述\n\n风险分级系统位于 `index.mjs` 主模块中，核心由以下组件构成：\n\n| 组件 | 位置 | 功能描述 |\n|------|------|----------|\n| `RISK_PATTERNS` | index.mjs | 工具风险模式正则表达式集合 |\n| `classifyTool()` | index.mjs | 工具风险分类核心函数 |\n| `POISONING_PATTERNS` | index.mjs | 提示注入检测模式 |\n| `detectPoisoning()` | index.mjs | 提示注入检测函数 |\n| `OWASP_MAP` | index.mjs | OWASP 映射配置 |\n| `mapToOwasp()` | index.mjs | OWASP 映射转换函数 |\n\n资料来源：[CONTRIBUTING.md:代码结构表]()\n\n## 风险等级架构\n\n系统采用四级风险分类体系，每个等级对应不同的安全影响和处置策略。\n\n### 风险等级定义\n\n| 等级 | 严重性 | 影响范围 | 示例工具 |\n|------|--------|----------|----------|\n| Critical | 关键 | 可执行代码、修改数据、不可逆变更 | execute_command, write_file, eval_code |\n| High | 高 | 文件读取、网络访问、数据外泄风险 | read_file, fetch, spawn |\n| Medium | 中 | 中等权限操作、需关注配置 | write_config, create_resource |\n| Low | 低 | 有限权限、安全风险较低 | read_info, list_items |\n\nCritical 等级工具包括代码执行、文件写入等可能造成不可逆影响的操作。High 等级涵盖文件读取和网络访问等存在数据泄露风险的工具。\n\n资料来源：[AGENTS.md:Exit Codes]()、[index.mjs:RISK_PATTERNS]()\n\n### 分类算法流程\n\n```mermaid\ngraph TD\n    A[工具输入] --> B[提取工具名称]\n    B --> C{名称匹配 Critical 模式}\n    C -->|匹配| D[返回 Critical]\n    C -->|未匹配| E{名称匹配 High 模式}\n    E -->|匹配| F[返回 High]\n    E -->|未匹配| G{名称匹配 Medium 模式}\n    G -->|匹配| H[返回 Medium]\n    G -->|未匹配| I{名称包含高风险关键词}\n    I -->|匹配| J[返回 High]\n    I -->|未匹配| K{描述分析}\n    K --> L{关键词匹配}\n    L -->|匹配| M[返回对应等级]\n    L -->|未匹配| N[返回 Low]\n    \n    style D fill:#ff6b6b\n    style F fill:#ffa500\n    style H fill:#ffd93d\n    style N fill:#6bcb77\n```\n\n`classifyTool()` 函数首先检查工具名称是否匹配预定义的正则表达式模式，若未匹配则回退到描述分析。\n\n资料来源：[CONTRIBUTING.md:RISK_PATTERNS + classifyTool()]()\n\n## 工具名称模式匹配\n\n系统通过 `RISK_PATTERNS` 定义的正则表达式对工具名称进行精确匹配。\n\n### Critical 等级模式\n\n| 模式 | 匹配示例 | 说明 |\n|------|----------|------|\n| `^execute_command$` | execute_command | 命令执行 |\n| `^run_.*` | run_script, run_sql | 带前缀的运行命令 |\n| `^exec_.*` | exec_shell, exec_python | exec 前缀执行 |\n| `^eval[_-]?(script\\|code)$` | eval_script, eval-code | 脚本/代码评估 |\n| `^evaluate[_-]?(script\\|code)$` | evaluate_script | 脚本评估 |\n| `^execute[_-]?(script\\|code\\|js\\|python\\|sql)$` | execute_python, execute_js | 多语言执行 |\n| `^run[_-]?(script\\|code\\|js\\|python\\|sql)$` | run_javascript, run_sql | 多语言运行 |\n\nv0.5.4 版本修复了后缀代码执行名称漏检问题，将正则模式从锚定匹配改为灵活匹配。\n\n资料来源：[CHANGELOG.md:v0.5.4 Fixed]()\n\n### 描述回退机制\n\n当工具名称未匹配任何模式时，`classifyTool()` 会将工具名称小写后进行子字符串匹配，作为回退策略。\n\n```mermaid\ngraph LR\n    A[名称未匹配] --> B[转小写]\n    B --> C{子字符串匹配}\n    C -->|eval| D[可能 High]\n    C -->|spawn| E[可能 High]\n    C -->|fetch| F[可能 High]\n    C -->|无匹配| G[低风险关键词分析]\n```\n\n这一机制确保即使工具名称不符合标准命名约定，只要包含高风险动词也能被正确分类。\n\n## OWASP Agentic Top 10 映射\n\n系统通过 `OWASP_MAP` 将所有发现映射到 OWASP Agentic Top 10 标准。\n\n### 映射配置结构\n\n```javascript\nOWASP_MAP = {\n  \"type-name-1\": \"ASI01\",\n  \"type-name-2\": \"ASI02\",\n  // ...\n}\n```\n\n每个 `POISONING_PATTERNS` 条目的 `type` 字段值会关联到对应的 OWASP 分类标准。\n\n资料来源：[CONTRIBUTING.md:OWASP_MAP + mapToOwasp()]()\n\n### ASI01–ASI05 映射范围\n\n| OWASP 标准 | 映射类型 | 检测内容 |\n|------------|----------|----------|\n| ASI01 | 提示注入相关 | 指令覆盖、隐藏注入 |\n| ASI02 | 凭证窃取相关 | API 密钥、令牌暴露 |\n| ASI03 | 数据外泄相关 | 敏感数据访问 |\n| ASI04 | 权限提升相关 | 过度权限配置 |\n| ASI05 | 工具影子供给 | 恶意工具替换 |\n\n所有发现都会通过 `mapToOwasp()` 函数转换为其对应的 OWASP 分类。\n\n## 提示注入检测模式\n\n`POISONING_PATTERNS` 包含 37 个正则表达式模式，分布在 20 个攻击类别中。\n\n### 攻击类别分类\n\n| 类别 | 严重性 | 描述 |\n|------|--------|------|\n| instruction-override | critical | 指令覆盖攻击 |\n| concealment | critical | 隐藏指令 |\n| credential-harvesting | critical | 凭证收割 |\n| data-exfiltration | critical | 数据外泄 |\n| coercive-execution | high | 强制执行 |\n| tool-shadowing | high | 工具影子 |\n| evasion-techniques | medium | 规避技术 |\n\n每个模式定义包含 `pattern`（正则表达式）、`type`（分类类型）、`severity`（严重等级）和 `description`（描述文本）。\n\n资料来源：[CONTRIBUTING.md:POISONING_PATTERNS]()\n\n### 检测函数工作流程\n\n```mermaid\ngraph TD\n    A[工具描述文本] --> B[遍历 POISONING_PATTERNS]\n    B --> C{正则匹配}\n    C -->|匹配| D[生成 poisoning 发现]\n    C -->|未匹配| E{继续下一模式}\n    E --> B\n    D --> F[聚合同一工具的所有发现]\n    F --> G[返回发现列表]\n    \n    style A fill:#e3f2fd\n    style D fill:#ffcdd2\n    style G fill:#c8e6c9\n```\n\n## 退出码与状态映射\n\n风险分级直接影响程序退出码和扫描状态。\n\n### 退出码定义\n\n| 退出码 | 触发条件 | status 值 |\n|--------|----------|-----------|\n| 0 | 无 critical 或 high 风险问题 | pass |\n| 1 | 发现 high 风险问题 | warn |\n| 2 | 发现 critical 问题、工具中毒或毒性数据流 | fail |\n\n`--json` 和 `--brief` 输出中都包含 `exitCode` 字段，便于程序化处理。\n\n资料来源：[AGENTS.md:Exit Codes]()\n\n### 状态计算逻辑\n\n```mermaid\ngraph TD\n    A[扫描结果] --> B{critical 计数 > 0?}\n    B -->|是| C[status = fail, exitCode = 2]\n    B -->|否| D{poisoned 计数 > 0?}\n    D -->|是| C\n    D -->|否| E{toxicFlows 计数 > 0?}\n    E -->|是| C\n    E -->|否| F{high 计数 > 0?}\n    F -->|是| G[status = warn, exitCode = 1]\n    F -->|否| H[status = pass, exitCode = 0]\n    \n    style C fill:#ff6b6b\n    style G fill:#ffa500\n    style H fill:#6bcb77\n```\n\n## 策略门控\n\n通过命令行 `--policy` 参数可以配置策略规则。\n\n| 策略规则 | 失败条件 |\n|----------|----------|\n| `no-critical` | 存在 critical 工具 |\n| `no-high` | 存在 high 工具 |\n| `no-poisoning` | 检测到提示注入 |\n| `no-toxic-flows` | 存在毒性数据流 |\n| `no-secrets` | 配置中存在暴露的密钥 |\n| `require-tripwires` | 未安装 decoy-tripwire |\n\n策略规则在 CI/CD 环境中用于自动化安全门控。\n\n## explain 子命令\n\n`decoy-scan explain` 提供风险分级的交互式解释功能。\n\n### 支持的查询类型\n\n| kind | 说明 | 示例 |\n|------|------|------|\n| tier | 严重等级 | `explain critical` |\n| category | 发现类别 | `explain tool-description` |\n| poisoning | 中毒类型 | `explain prompt-override` |\n| tool | 工具名称 | `explain read_file` |\n\n`explain` 解析器使用与扫描器相同的 `RISK_PATTERNS` 和 `POISONING_PATTERNS` 数据源，确保解释与实际检测结果一致。\n\n资料来源：[AGENTS.md:explain subcommand]()\n\n### JSON 输出结构\n\n```json\n{\n  \"tool\": \"decoy-scan\",\n  \"version\": \"0.5.1\",\n  \"target\": \"critical\",\n  \"result\": {\n    \"kind\": \"tier\",\n    \"key\": \"critical\",\n    \"title\": \"Critical\",\n    \"summary\": \"Can execute code, modify data, or cause irreversible changes.\",\n    \"body\": \"...\",\n    \"examples\": [\"execute_command\", \"write_file\", \"...\"],\n    \"advice\": \"...\"\n  }\n}\n```\n\n## 库导出接口\n\ndecoy-scan 作为库使用时可直接导入分类功能：\n\n```javascript\nimport {\n  classifyTool,\n  detectPoisoning,\n  mapToOwasp,\n} from 'decoy-scan';\n\nconst risk = classifyTool({ name: \"read_file\", description: \"...\" });\nconst poisoningFindings = detectPoisoning(toolDescription);\nconst owaspCategory = mapToOwasp(findingType);\n```\n\n这使得其他安全工具可以复用 decoy-scan 的风险分级能力。\n\n资料来源：[README.md:Library]()\n\n## 版本演进\n\n| 版本 | 重要变更 |\n|------|----------|\n| v0.1.0 | 初始发布，基础风险分类 |\n| v0.5.4 | 修复后缀代码执行名称漏检，子字符串回退增强 |\n| v0.5.6 | 增强对 evaluate_script、eval_code 等工具的检测 |\n\nCHANGELOG.md 记录了风险分级系统的所有重要变更。\n\n---\n\n<a id='prompt-injection-detection'></a>\n\n## 提示注入检测\n\n### 相关页面\n\n相关主题：[安全检查项目](#security-checks), [有毒数据流分析](#toxic-flow-analysis)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [lib/patterns.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/patterns.mjs)\n- [lib/analyzers.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/analyzers.mjs)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n</details>\n\n# 提示注入检测\n\n## 概述\n\n提示注入检测（Prompt Injection Detection）是 decoy-scan 工具的核心安全功能之一，旨在识别 MCP（Model Context Protocol）服务器工具描述中隐藏的恶意提示注入攻击。该功能通过正则表达式模式匹配技术，分析工具的名称和描述文本，检测 37 种不同的攻击模式，覆盖 20 个攻击类别。\n\n主要职责包括：\n\n- 在工具描述中识别隐藏的指令覆盖攻击\n- 检测伪装和隐蔽性攻击\n- 发现数据泄露和凭证收集企图\n- 识别强制执行和工具影子供给\n- 映射攻击类型至 OWASP Agentic Top 10 标准\n\n资料来源：[README.md:47]()\n\n## 架构设计\n\n### 整体架构\n\n提示注入检测系统位于扫描流程的核心位置，与工具风险分类、毒性流分析和 OWASP 映射等功能紧密协作。\n\n```mermaid\ngraph TD\n    A[MCP Server 工具列表] --> B[detectPoisoning 检测器]\n    B --> C{匹配结果}\n    C -->|有匹配| D[生成 Poisoning Finding]\n    C -->|无匹配| E[标记为安全]\n    D --> F[OWASP 映射]\n    F --> G[风险报告输出]\n    E --> G\n    B --> H[explain 子命令]\n    H --> I[结构化解释 JSON]\n```\n\n### 核心模块关系\n\n| 模块 | 文件位置 | 职责 |\n|------|----------|------|\n| `POISONING_PATTERNS` | `index.mjs` / `lib/patterns.mjs` | 定义所有检测正则表达式模式 |\n| `detectPoisoning()` | `index.mjs` / `lib/analyzers.mjs` | 执行模式匹配和分析逻辑 |\n| `OWASP_MAP` | `index.mjs` | 将攻击类型映射至 OWASP 标准 |\n| `explain` 子命令 | `bin/cli.mjs` | 提供人可读和机器可解析的解释 |\n\n资料来源：[CONTRIBUTING.md:23]()\n\n## 检测模式体系\n\n### 攻击类别总览\n\ndecoy-scan 采用分层分类体系组织检测模式，每个模式包含正则表达式、攻击类型、严重等级和人类可读的描述。\n\n```javascript\n{\n  pattern: /regex/i,           // 正则匹配表达式\n  type: \"category-name\",       // 攻击类型标识\n  severity: \"critical\",        // 严重等级\n  description: \"人类可读描述\"   // 输出展示\n}\n```\n\n资料来源：[CONTRIBUTING.md:42-47]()\n\n### 支持的攻击类别\n\n系统支持检测以下 20 个攻击类别的提示注入模式：\n\n| 类别 | 描述 | 严重等级示例 |\n|------|------|--------------|\n| `instruction-override` | 指令覆盖攻击 | critical |\n| `concealment` | 伪装攻击 | critical/high |\n| `data-exfiltration` | 数据泄露 | critical |\n| `credential-harvesting` | 凭证收集 | critical |\n| `coercive-execution` | 强制执行 | high |\n| `tool-shadowing` | 工具影子 | high |\n| `evasion-techniques` | 规避技术 | medium/high |\n| 其他 13 个类别 | 各类隐蔽攻击 | varying |\n\n资料来源：[README.md:47]()\n\n### 严重等级定义\n\n| 等级 | 含义 | 退出码影响 |\n|------|------|-----------|\n| `critical` | 可执行代码、修改数据或造成不可逆变更 | 退出码 2 |\n| `high` | 高风险操作如文件读取、网络访问 | 退出码 1 |\n| `medium` | 中等风险，需关注 | 无退出码影响 |\n| `low` | 低风险操作 | 无退出码影响 |\n\n资料来源：[AGENTS.md:43-47]()\n\n## 工作流程\n\n### 扫描执行流程\n\n```mermaid\nsequenceDiagram\n    participant Scanner as 扫描器\n    participant Pattern as POISONING_PATTERNS\n    participant Analyzer as 检测引擎\n    participant OWASP as OWASP_MAP\n    participant Output as 输出系统\n\n    Scanner->>Scanner: 发现 MCP 服务器\n    Scanner->>Scanner: 获取工具列表\n    Loop 每个工具\n        Scanner->>Analyzer: 传入工具名称和描述\n        Analyzer->>Pattern: 遍历正则模式\n        Pattern-->>Analyzer: 匹配结果\n        Analyzer->>Analyzer: 分类严重等级\n        Analyzer->>OWASP: 映射攻击类型\n        OWASP-->>Analyzer: ASI 代码\n    end\n    Analyzer-->>Scanner: 检测结果\n    Scanner->>Output: 生成报告\n```\n\n### 输出格式\n\n#### 工具级别输出\n\n每个被检测为存在提示注入的工具包含以下字段：\n\n```json\n{\n  \"name\": \"tool-name\",\n  \"risk\": \"critical\",\n  \"poisoning\": [{\n    \"type\": \"instruction-override\",\n    \"severity\": \"critical\",\n    \"description\": \"发现指令覆盖攻击模式\"\n  }]\n}\n```\n\n#### JSON 完整输出\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"tools\": [{\n      \"name\": \"tool-name\",\n      \"description\": \"...\",\n      \"risk\": \"critical\",\n      \"poisoning\": [...]\n    }]\n  }],\n  \"summary\": {\n    \"poisoned\": 0\n  }\n}\n```\n\n资料来源：[AGENTS.md:59-74]()\n\n## API 与接口\n\n### 库函数导出\n\ndecoy-scan 提供独立的 JavaScript 模块接口，可供其他项目导入使用：\n\n```javascript\nimport {\n  scan,\n  detectPoisoning,\n  classifyTool,\n  analyzeToxicFlows,\n} from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.servers[0].tools[0].poisoning);\n```\n\n### detectPoisoning 函数签名\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `toolName` | string | 工具名称 |\n| `toolDescription` | string | 工具描述文本 |\n| 返回值 | array | 匹配到的 poisoning 对象数组 |\n\n### explain 子命令\n\n用于解析特定发现含义的辅助命令：\n\n```bash\ndecoy-scan explain prompt-override       # 攻击类型说明\ndecoy-scan explain list                  # 列举所有可解释目标\ndecoy-scan explain <target> --json       # 机器可读输出\n```\n\n#### --json 输出结构\n\n```json\n{\n  \"tool\": \"decoy-scan\",\n  \"version\": \"0.5.1\",\n  \"target\": \"instruction-override\",\n  \"result\": {\n    \"kind\": \"poisoning\",\n    \"key\": \"instruction-override\",\n    \"title\": \"指令覆盖\",\n    \"summary\": \"攻击者尝试覆盖原始指令\",\n    \"examples\": [\"...具体示例...\"],\n    \"advice\": \"建议修复措施\"\n  }\n}\n```\n\n资料来源：[AGENTS.md:29-41]()\n\n## 配置与扩展\n\n### 添加新的检测模式\n\n在 `POISONING_PATTERNS` 中添加新模式：\n\n```javascript\n{\n  pattern: /new-malicious-pattern/i,\n  type: \"new-attack-category\",\n  severity: \"high\",\n  description: \"新攻击类型的描述\"\n}\n```\n\n添加后需将 `type` 值注册到 `OWASP_MAP` 中：\n\n```javascript\nconst OWASP_MAP = {\n  // ... 现有映射\n  \"new-attack-category\": \"ASI01\",\n};\n```\n\n资料来源：[CONTRIBUTING.md:35-41]()\n\n### OWASP Agentic Top 10 映射\n\n所有攻击类型均映射至 OWASP Agentic Top 10 标准，便于安全合规报告：\n\n| OWASP 代码 | 攻击类型 |\n|-----------|---------|\n| ASI01 | Agentic 系统提示注入 |\n| ASI02 | 敏感信息泄露 |\n| ASI03 | 工具操作验证不足 |\n| ASI04 | 供应链攻击 |\n| ASI05 | 权限过度授予 |\n\n资料来源：[README.md:56]()\n\n## 输出与报告\n\n### 退出码机制\n\n提示注入检测结果直接影响命令退出码：\n\n| 退出码 | 触发条件 |\n|--------|----------|\n| `0` | 无 critical 或 high 风险问题 |\n| `1` | 发现 high 风险问题 |\n| `2` | 发现 critical 问题、工具污染或毒性流 |\n\n### --brief 摘要输出\n\n最小化摘要对象：\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"poisoned\": 0,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n### SARIF 格式支持\n\n支持 SARIF 2.1.0 标准输出，可上传至 GitHub Security：\n\n```bash\ndecoy-scan --sarif\n```\n\n### 毒性流分析\n\n除了单工具检测外，系统还支持跨服务器数据泄露（TF001）和破坏性（TF002）攻击链分析：\n\n```javascript\nimport { analyzeToxicFlows } from 'decoy-scan';\n\nconst results = await scan();\nconsole.log(results.toxicFlows);\n```\n\n资料来源：[README.md:66-68]()\n\n## 版本变更历史\n\n### 关键版本更新\n\n| 版本 | 日期 | 变更内容 |\n|------|------|---------|\n| 0.1.0 | 2026-03-15 | 初始发布，支持基础提示注入检测 |\n| 0.2.0 | 2026-03-20 | 添加 SSE 传输安全检查和输入验证 |\n| 0.5.0 | 2026-04-21 | 新增 explain 子命令，改进分类逻辑 |\n| 0.5.6 | 2026-04-28 | 修复 classifyTool 对代码执行名称的遗漏 |\n| 0.7.0 | 2026-05-10 | 增强遥测功能，完善 v2 事件信封 |\n\n资料来源：[CHANGELOG.md:1-100]()\n\n## 设计原则\n\n### 零依赖原则\n\n检测引擎完全基于 Node.js 原生能力实现，无外部 npm 依赖：\n\n- 仅使用内置 `RegExp` 模块进行模式匹配\n- 不依赖第三方安全扫描库\n- 确保扫描速度和可靠性\n\n### 无修改原则\n\n所有检测操作均为只读扫描：\n\n- 不修改任何 MCP 配置文件\n- 不修改工具描述或服务器状态\n- 及时终止检测过程中启动的服务器进程\n\n### 快速完成原则\n\n扫描应在数秒内完成：\n\n- 主动超时机制终止响应慢的服务器\n- 高效的正则表达式模式匹配\n- 并行处理多服务器扫描\n\n### Agent 优先原则\n\n所有输出格式优先考虑机器可解析性：\n\n- JSON 输出格式稳定、结构化\n- SARIF 格式符合行业标准\n- `--json` 和 `--brief` 输出包含 `exitCode` 字段便于自动化决策\n\n资料来源：[CONTRIBUTING.md:64-72]()\n\n## 命令行使用\n\n### 基础扫描\n\n```bash\nnpx decoy-scan                        # 完整扫描\nnpx decoy-scan --json                 # 机器可读输出\nnpx decoy-scan --sarif                # SARIF 格式输出\n```\n\n### 详细模式\n\n```bash\nnpx decoy-scan --verbose              # 显示所有工具包括 low 风险\nnpx decoy-scan --no-probe             # 仅配置文件检测\nnpx decoy-scan --no-advisories        # 跳过网络调用\n```\n\n### CI/CD 集成\n\n```yaml\n# .github/workflows/mcp-security.yml\nname: MCP Security\non: [push, pull_request]\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n        with:\n          policy: no-critical,no-poisoning\n          sarif: true\n```\n\n### 策略规则\n\n| 规则 | 描述 |\n|------|------|\n| `no-critical` | 禁止 critical 级别工具 |\n| `no-high` | 禁止 high 级别工具 |\n| `no-poisoning` | 禁止工具描述中的提示注入 |\n| `no-toxic-flows` | 禁止跨服务器数据泄露 |\n| `no-secrets` | 禁止 MCP 配置中的敏感信息 |\n| `require-tripwires` | 要求安装 decoy-tripwire |\n\n资料来源：[README.md:89-96]()\n\n## 局限性说明\n\n### 检测范围限制\n\n- 检测基于正则表达式模式匹配，可能无法识别未知变体攻击\n- 仅分析工具名称和描述文本，不深入分析工具实现逻辑\n- 依赖服务器正确响应工具列表请求\n\n### 误报与漏报\n\n- 高敏感度配置可能导致部分合法工具被标记\n- 混淆或编码的恶意内容可能被遗漏\n- 建议结合人工审查进行最终判断\n\n### 跨语言支持\n\n- 默认检测模式针对英文文本设计\n- 非英文工具描述的检测准确度可能降低\n\n---\n\n如需报告安全问题，请联系 agent@decoy.run。请勿为此项目公开提交安全问题。\n\n---\n\n<a id='scanning-architecture'></a>\n\n## 扫描架构\n\n### 相关页面\n\n相关主题：[MCP 主机发现](#mcp-host-discovery), [风险分级系统](#risk-classification)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [lib/scan.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/scan.mjs)\n- [lib/verify.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/verify.mjs)\n- [lib/probe.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/probe.mjs)\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [bin/cli.mjs](https://github.com/decoy-run/decoy-scan/blob/main/bin/cli.mjs)\n</details>\n\n# 扫描架构\n\n## 概述\n\ndecoy-scan 的扫描架构是一套零依赖的 MCP（Model Context Protocol）安全扫描解决方案，采用纯 Node.js 原生模块实现。该架构通过配置文件发现、服务器探测、工具风险分析、投毒检测、有毒流程分析和供应链审查等多个环节，对本地 MCP 服务器配置进行全面的安全评估。\n\n扫描架构的核心设计原则包括：\n\n- **零依赖**：仅使用 Node.js 内置模块，无需安装任何 npm 包\n- **无构建步骤**：直接运行 ES 模块\n- **快速执行**：对服务器进行激进超时，扫描应在数秒内完成\n- **安全操作**：仅读取配置，从不修改，使用后立即终止生成的服务器进程\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n## 核心模块划分\n\ndecoy-scan 的扫描架构由多个核心模块组成，每个模块负责特定的安全检查功能：\n\n| 模块 | 文件位置 | 核心功能 |\n|------|----------|----------|\n| 扫描编排器 | `lib/scan.mjs` | 协调整个扫描流程 |\n| 服务器探测 | `lib/probe.mjs` | 通过 stdio 协议探测 MCP 服务器 |\n| 策略验证 | `lib/verify.mjs` | 验证扫描结果是否满足策略要求 |\n| 工具分类器 | `index.mjs` | 工具风险等级分类 |\n| 投毒检测器 | `index.mjs` | 检测提示词注入攻击 |\n| 环境分析器 | `index.mjs` | 分析敏感环境变量暴露 |\n| 就绪检查器 | `index.mjs` | 生产环境就绪状态评估 |\n| 配置发现器 | `index.mjs` | 发现本地 MCP 客户端配置 |\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n## 扫描流程架构图\n\n扫描流程采用流水线式的处理架构，从配置发现到最终报告生成依次执行：\n\n```mermaid\ngraph TD\n    A[开始扫描] --> B[发现 MCP 配置]\n    B --> C{发现配置?}\n    C -->|无| D[生成空结果]\n    C -->|有| E[遍历每个服务器配置]\n    E --> F[解析服务器启动命令]\n    F --> G{是否探测服务器}\n    G -->|否| H[跳过探测]\n    G -->|是| I[通过 stdio 探测服务器]\n    I --> J{探测成功?}\n    J -->|失败| K[记录探测失败]\n    J -->|成功| L[获取工具列表]\n    L --> M[执行安全分析]\n    M --> N{分析完成?}\n    N -->|是| O[汇总结果]\n    K --> O\n    H --> O\n    O --> P[生成输出报告]\n    P --> Q[退出]\n    D --> Q\n```\n\n## 配置发现模块\n\n配置发现模块负责定位本地系统中各 MCP 客户端的配置文件。该模块维护了一个 `HOST_CONFIGS` 配置映射，支持以下 MCP 客户端：\n\n- Claude Desktop\n- Cursor\n- Windsurf\n- VS Code\n- Claude Code\n- Zed\n- Cline\n\n配置发现器针对不同操作系统（macOS、Windows、Linux）使用不同的配置文件路径：\n\n```javascript\n\"Claude Desktop\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"config.json\");\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n### 项目级配置支持\n\n除系统级 MCP 客户端配置外，扫描器还支持项目级别的 `.mcp.json` 配置文件。从项目根目录运行时，会自动包含项目级配置扫描。\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 服务器探测模块\n\n探测模块是扫描架构的核心组件之一，负责与 MCP 服务器建立通信并获取其工具列表。\n\n### stdio 协议探测\n\n探测模块通过 stdio 协议与 MCP 服务器交互：\n\n1. 解析服务器启动命令和参数\n2. 生成子进程并启动 MCP 服务器\n3. 发送 JSON-RPC 格式的 `tools/list` 请求\n4. 接收并解析服务器返回的工具列表\n5. 正常终止服务器进程\n\n### 探测超时机制\n\n为保证扫描速度，探测模块采用激进超时策略：\n\n- 探测超时后会立即终止服务器进程\n- 探测失败的服务器会记录错误信息但不影响整体扫描继续\n\n```javascript\n// 超时后立即终止并清理\nkillSpawnedServers();\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n### 探测结果处理\n\n探测结果包含以下信息：\n\n| 字段 | 说明 |\n|------|------|\n| `name` | 服务器名称 |\n| `command` | 启动命令 |\n| `args` | 命令参数 |\n| `tools` | 工具列表（包含名称、描述、输入模式） |\n| `error` | 探测错误信息（如有） |\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 安全分析模块\n\n安全分析模块是扫描架构的核心部分，包含多个子分析器：\n\n### 工具风险分类器\n\n工具风险分类器（`classifyTool`）根据工具名称和描述将工具分为四个风险等级：\n\n| 风险等级 | 说明 | 示例 |\n|----------|------|------|\n| critical | 可执行代码、修改数据或造成不可逆更改 | `execute_command`, `write_file` |\n| high | 读取文件或发起网络请求 | `read_file`, `fetch_url` |\n| medium | 访问系统信息或执行其他操作 | `get_system_info` |\n| low | 低风险工具 | 其他工具 |\n\n分类器使用 `RISK_PATTERNS` 正则表达式模式匹配工具名称，并结合工具描述进行综合判断。\n\n关键风险模式包括：\n\n```javascript\n{\n  pattern: /^execute[_-]?(script|code|js|javascript|python|sql)$/,\n  type: \"critical\",\n  severity: \"critical\"\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n### 投毒检测器\n\n投毒检测器（`detectPoisoning`）使用 37 种正则模式检测工具描述中的提示词注入攻击，涵盖 20 个攻击类别：\n\n- 指令覆盖（instruction override）\n- 隐蔽技术（concealment）\n- 数据泄露（data exfiltration）\n- 凭证收割（credential harvesting）\n- 强制执行（coercive execution）\n- 工具影子（tool shadowing）\n- 规避技术（evasion techniques）\n\n每个投毒模式包含：\n\n```javascript\n{\n  pattern: /regex/i,\n  type: \"category-name\",\n  severity: \"critical\",\n  description: \"Human-readable description\"\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n### 服务器命令分析器\n\n命令分析器（`analyzeServerCommand`）检查服务器启动命令中的可疑特征：\n\n- 管道到 shell（pipe-to-shell）\n- 临时目录执行\n- 内联代码注入\n- 误植域名攻击（typosquatting）\n- 网络工具调用\n\n### 环境变量暴露分析器\n\n环境分析器（`analyzeEnvExposure`）使用 `SENSITIVE_ENV_PATTERNS` 模式检测 12 类敏感凭证暴露：\n\n- API 密钥\n- 访问令牌\n- 密码\n- 数据库连接 URL\n- 云服务凭证\n- 其他敏感环境变量\n\n### 就绪状态检查器\n\n就绪状态检查器（`analyzeReadiness`）评估生产环境部署就绪程度，检查项包括：\n\n- 缺失工具描述\n- 缺失输入模式\n- 缺少必需字段\n- 过度授权的工具范围\n- 破坏性工具缺少安全提示\n\n### OWASP 映射器\n\nOWASP 映射器（`mapToOwasp`）将所有发现映射到 OWASP Agentic Top 10：\n\n- ASI01 - Agentic AI Inventory and Tracking\n- ASI02 - Sensitive Data Exposure\n- ASI03 - Tool Poisoning\n- ASI04 - Agentic AI Hallucinations and Mismanagement\n- ASI05 - Overprivileged Agents and Tools\n\n资料来源：[README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n\n## 有毒流程分析\n\n除单个工具的安全分析外，扫描架构还支持跨服务器的有毒流程分析（`analyzeToxicFlows`）：\n\n| 流程类型 | ID | 严重性 | 说明 |\n|----------|-----|--------|------|\n| 数据泄露 | TF001 | critical | 跨服务器数据泄露攻击链 |\n| 破坏性操作 | TF002 | critical | 跨服务器破坏性操作链 |\n\n有毒流程分析在库模式下可用：\n\n```javascript\nimport { scan, analyzeToxicFlows } from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.toxicFlows);\n```\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 供应链审查\n\n扫描架构包含供应链安全审查功能：\n\n### 已知漏洞包检测\n\n通过 Decoy  advisory 数据库（40+ MCP 包）对配置中的服务器进行已知漏洞匹配。\n\n### 工具清单哈希追踪\n\n工具清单哈希（`hashToolManifest`）功能可以检测工具变更：\n\n- 工具新增\n- 工具移除\n- 工具描述变更\n\n通过 `detectManifestChanges` 函数比较两次扫描之间的工具清单差异。\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 技能扫描\n\n扫描架构支持对 Claude Code 技能进行专项安全扫描（`discoverSkills` 和 `analyzeSkill`）：\n\n- 提示词注入检测\n- 硬编码密钥检测\n- 可疑 URL 检测\n\n```javascript\nimport { scan, discoverSkills, analyzeSkill } from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.skills);\n```\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 策略验证模块\n\n策略验证模块（`lib/verify.mjs`）根据用户定义的策略规则验证扫描结果：\n\n### 策略规则语法\n\n| 规则 | 说明 |\n|------|------|\n| `no-critical` | 不允许关键风险工具 |\n| `no-high` | 不允许高风险工具 |\n| `no-poisoning` | 不允许提示词注入 |\n| `no-toxic-flows` | 不允许有毒流程 |\n| `no-secrets` | 不允许暴露密钥 |\n| `require-tripwires` | 要求安装 decoy-tripwire |\n| `max-critical=N` | 限制关键问题数量 |\n\n策略检查失败会设置相应的退出码。\n\n资料来源：[README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n\n## 输出报告生成\n\n### SARIF 报告\n\nSARIF（Static Analysis Results Interchange Format）是一种结构化的安全报告格式，用于 CI/CD 集成：\n\n```javascript\nimport { scan, toSarif } from 'decoy-scan';\n\nconst results = await scan();\nconst sarif = toSarif(results);\n```\n\nSARIF 输出会包含：\n\n- 规则 ID 和级别\n- 问题位置和描述\n- 建议的修复方案\n- OWASP 映射信息\n\n### 退出码规范\n\n| 退出码 | 含义 |\n|--------|------|\n| 0 | 无关键或高风险问题 |\n| 1 | 发现高风险问题 |\n| 2 | 发现关键问题、工具投毒或策略违规 |\n\n退出码在 `--json` 和 `--brief` 输出的 `exitCode` 字段中也会体现，便于程序化处理。\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## CLI 入口\n\n命令行入口位于 `bin/cli.mjs`，负责：\n\n1. 解析命令行参数\n2. 初始化扫描配置\n3. 调用扫描模块\n4. 格式化输出结果\n5. 处理退出逻辑\n\n### 支持的输出模式\n\n| 模式 | 说明 |\n|------|------|\n| 默认 | 人类可读的彩色输出 |\n| `--json` | 机器可解析的 JSON 格式 |\n| `--sarif` | SARIF 2.1.0 标准格式 |\n| `--brief` | 最小化摘要信息 |\n| `--verbose` | 显示所有工具包括低风险 |\n\n### 可用参数\n\n| 参数 | 说明 |\n|------|------|\n| `--no-probe` | 仅扫描配置，不探测服务器 |\n| `--no-advisories` | 跳过网络请求（供应链审查） |\n| `--quiet` | 静默模式，抑制状态输出 |\n| `--version` | 显示版本信息 |\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 数据流架构图\n\n```mermaid\ngraph LR\n    A[MCP 配置文件] --> B[配置发现器]\n    B --> C[服务器列表]\n    C --> D{探测模式}\n    D -->|探测| E[stdio 探测]\n    D -->|跳过| F[跳过探测]\n    E --> G[工具列表]\n    F --> H[空工具列表]\n    G --> I[安全分析引擎]\n    H --> I\n    I --> J[风险分类结果]\n    I --> K[投毒检测结果]\n    I --> L[环境分析结果]\n    I --> M[就绪检查结果]\n    J --> N[结果汇总]\n    K --> N\n    L --> N\n    M --> N\n    N --> O[策略验证]\n    O --> P{SARIF 格式?}\n    P -->|是| Q[SARIF 报告]\n    P -->|否| R[JSON/文本报告]\n    Q --> S[GitHub Security]\n    R --> T[终端输出]\n```\n\n## 扩展机制\n\n### 添加新的投毒模式\n\n在 `POISONING_PATTERNS` 中添加新模式：\n\n```javascript\n{\n  pattern: /regex/i,\n  type: \"category-name\",\n  severity: \"critical\",\n  description: \"Human-readable description\"\n}\n```\n\n添加后需在 `OWASP_MAP` 中添加对应的映射。\n\n### 添加新的 MCP 客户端支持\n\n在 `HOST_CONFIGS` 中添加新的客户端条目：\n\n```javascript\n\"New Client\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"config.json\");\n}\n```\n\n### 添加新的就绪检查\n\n在 `analyzeReadiness()` 函数中添加检查逻辑：\n\n```javascript\nif (/* condition */) {\n  findings.push({\n    type: \"readiness-check-name\",\n    severity: \"medium\",\n    description: \"What's wrong and why it matters\"\n  });\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n## 性能特性\n\n扫描架构的性能设计目标：\n\n- **快速启动**：无依赖安装，npx 直接运行\n- **快速扫描**：激进超时策略，单个服务器探测有明确时间限制\n- **并行发现**：配置文件发现与初步分析可并行执行\n- **资源高效**：无额外进程开销，服务器进程及时清理\n\n## 安全特性\n\n扫描架构的安全设计原则：\n\n| 特性 | 实现方式 |\n|------|----------|\n| 读取隔离 | 仅读取配置，从不修改 |\n| 进程控制 | 服务器进程用后即删 |\n| 无持久化 | 不在系统留下痕迹 |\n| 隐私保护 | 支持 `--no-telemetry` 禁用遥测 |\n| 安全报告 | 敏感信息脱敏处理 |\n\n## 版本演进\n\n| 版本 | 重大变更 |\n|------|----------|\n| 0.8.0 | v2 遥测信封格式 |\n| 0.7.0 | 供应链 advisories、工具清单哈希追踪 |\n| 0.5.0 | 新增 `explain` 子命令 |\n| 0.2.0 | SSE 传输安全检查、输入验证 |\n| 0.1.0 | 初始版本发布 |\n\n资料来源：[CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n\n---\n\n<a id='mcp-host-discovery'></a>\n\n## MCP 主机发现\n\n### 相关页面\n\n相关主题：[扫描架构](#scanning-architecture), [快速开始](#getting-started)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs) — 包含 `HOST_CONFIGS` 和 `discoverConfigs()` 实现\n- [lib/discovery.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/discovery.mjs) — 主机发现核心逻辑\n- [lib/sarif.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/sarif.mjs) — SARIF 输出格式转换\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md) — Agent 参考文档\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md) — 贡献指南\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md) — 项目说明文档\n</details>\n\n# MCP 主机发现\n\n## 概述\n\nMCP 主机发现是 decoy-scan 工具的核心功能之一，负责自动检测本地机器上所有已配置的 MCP（Model Context Protocol）客户端主机，并收集其 MCP 服务器配置信息。该功能使工具能够对用户环境中的 MCP 生态系统进行全面的安全扫描，无需用户手动指定配置文件路径。\n\ndecoy-scan 采用零依赖设计，完全使用 Node.js 内置模块实现主机发现功能，确保扫描过程快速、轻量且可靠。发现阶段会遍历操作系统特定的配置文件路径，解析 MCP 服务器定义，并准备后续的安全分析工作。\n\n## 支持的 MCP 主机\n\ndecoy-scan 目前支持 **7 种主流 MCP 客户端主机**，覆盖桌面 IDE、代码编辑器、AI 编程工具等多种开发环境。\n\n| 主机名称 | 类型 | 支持平台 | 典型用途 |\n|---------|------|---------|---------|\n| Claude Desktop | AI 助手 | macOS/Windows/Linux | Anthropic Claude 桌面集成 |\n| Cursor | AI 代码编辑器 | macOS/Windows/Linux | AI 驱动的代码补全与生成 |\n| Windsurf | AI 代码编辑器 | macOS/Windows/Linux | Cascade AI 工作流 |\n| VS Code | 代码编辑器 | macOS/Windows/Linux | Microsoft Copilot 集成 |\n| Claude Code | CLI 工具 | macOS/Windows/Linux | 命令行 Claude 交互 |\n| Zed | 代码编辑器 | macOS/Windows/Linux | 高性能 GPU 加速编辑器 |\n| Cline | VS Code 扩展 | macOS/Windows/Linux | AI 自主编程代理 |\n\n资料来源：[AGENTS.md:Supported Hosts (7)]()\n\n## 平台感知配置路径\n\nMCP 主机发现模块的核心设计原则是**平台感知**——根据不同操作系统采用相应的配置文件路径规范。这种设计确保工具在 macOS、Windows 和 Linux 三大主流平台上均能正确发现 MCP 配置。\n\n### 配置路径规范\n\n```mermaid\ngraph TD\n    A[启动扫描] --> B{检测操作系统}\n    B -->|macOS| C[使用 homedir() 路径]\n    B -->|Windows| D[使用 APPDATA 环境变量]\n    B -->|Linux| E[使用 ~/.config 目录]\n    \n    C --> F[调用平台特定路径解析函数]\n    D --> F\n    E --> F\n    \n    F --> G[发现 MCP 服务器配置]\n    G --> H[解析配置文件 JSON]\n    H --> I[提取服务器定义列表]\n```\n\n### 路径发现机制\n\n各平台的标准配置存储位置如下：\n\n| 平台 | 配置目录 | 说明 |\n|-----|---------|------|\n| macOS | `~/Library/Application Support/` | 使用 `homedir()` 获取用户主目录 |\n| Windows | `%APPDATA%` | 使用 `process.env.APPDATA` 环境变量 |\n| Linux | `~/.config/` | 标准 XDG 配置目录规范 |\n\n```javascript\n// 主机配置结构示例 (CONTRIBUTING.md)\n\"New Client\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"to\", \"config.json\");\n},\n```\n\n资料来源：[CONTRIBUTING.md:Adding Host Configs]()\n\n## 发现流程架构\n\nMCP 主机发现模块位于 `lib/discovery.mjs`，是扫描管道的第一个关键环节。整个发现流程分为配置探测、服务器提取、重复数据删除三个主要阶段。\n\n### 完整发现流程\n\n```mermaid\ngraph TD\n    A[MCP 主机发现开始] --> B[遍历 HOST_CONFIGS]\n    B --> C{当前平台匹配?}\n    C -->|是| D[读取配置文件]\n    C -->|否| E[跳过该主机]\n    D --> F{配置文件存在?}\n    F -->|是| G[解析 JSON 配置]\n    F -->|否| E\n    G --> H[提取 servers 数组]\n    H --> I{发现 decoy-tripwire?}\n    I -->|是| J[去重标记]\n    I -->|否| K[添加至待扫描列表]\n    J --> L[跨主机去重]\n    K --> L\n    L --> M[返回已发现服务器列表]\n    \n    E --> B\n```\n\n### 配置文件解析\n\n发现的 MCP 配置文件通常为 JSON 格式，包含服务器的启动命令、参数列表等核心定义：\n\n```json\n{\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"env\": {}\n  }]\n}\n```\n\n解析后的数据将传递给后续的 `probeServer()` 模块进行 MCP stdio 探测。\n\n资料来源：[AGENTS.md:JSON Output Schema]()\n\n## 服务器探测阶段\n\n在主机发现完成后，decoy-scan 对每个已发现的 MCP 服务器执行 stdio 探测，查询其工具列表并进行分析。\n\n### 探测流程\n\n```mermaid\nsequenceDiagram\n    participant 扫描器 as decoy-scan\n    participant 服务器 as MCP Server\n    participant 分析器 as 安全分析引擎\n    \n    扫描器->>服务器: 启动服务器进程 (stdio)\n    扫描器->>服务器: 发送 initialize 请求\n    服务器-->>扫描器: 返回 server info\n    扫描器->>服务器: 发送 tools/list 请求\n    服务器-->>扫描器: 返回工具列表\n    扫描器->>分析器: 传递工具列表\n    分析器->>分析器: 风险分类\n    分析器->>分析器: 投毒检测\n    分析器->>分析器: 准备就绪检查\n    扫描器->>服务器: 终止进程\n```\n\n### 探测超时控制\n\n为确保扫描性能，服务器探测采用**激进超时策略**。如果服务器在规定时间内未响应，探测将被强制终止并记录错误信息。\n\n```javascript\n// 探测失败处理\nif (probeError) {\n  findings.push({\n    type: \"probe-failed\",\n    severity: \"medium\",\n    description: \"服务器探测超时或连接失败\"\n  });\n}\n```\n\n资料来源：[AGENTS.md:JSON Output Schema:error]()\n\n## 输出格式\n\n发现阶段的输出可采用多种格式，便于不同使用场景的消费：\n\n### JSON 格式\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null\n  }]\n}\n```\n\n### SARIF 格式\n\n通过 `--sarif` 参数可输出符合 SARIF 2.1.0 标准的格式，便于集成到 CI/CD 安全扫描流程中：\n\n```yaml\nruns:\n  - results:\n      - ruleId: \"critical-tool\"\n        level: \"error\"\n        message: \"发现高风险工具\"\n```\n\n资料来源：[lib/sarif.mjs]()\n\n## 与其他模块的集成\n\nMCP 主机发现是扫描管道的第一步，后续安全分析依赖于发现阶段提供的数据：\n\n```mermaid\ngraph LR\n    A[MCP 主机发现] --> B[工具风险分类]\n    A --> C[投毒检测]\n    A --> D[服务器命令分析]\n    A --> E[环境变量暴露检测]\n    A --> F[准备就绪检查]\n    A --> G[供应链告警]\n    \n    B --> H[结果聚合]\n    C --> H\n    D --> H\n    E --> H\n    F --> H\n    G --> H\n    \n    H --> I[JSON/SARIF 输出]\n    H --> J[策略检查]\n    J --> K{通过?}\n    K -->|是| L[退出码 0]\n    K -->|否| M[退出码 1/2]\n```\n\n### 各模块依赖关系\n\n| 模块 | 依赖发现数据 | 功能说明 |\n|-----|-------------|---------|\n| 工具风险分类 | ✓ | 基于工具名称和描述进行风险评级 |\n| 投毒检测 | ✓ | 检测工具描述中的提示注入模式 |\n| 服务器命令分析 | ✓ | 检查启动命令的安全性 |\n| 环境变量暴露检测 | ✓ | 扫描配置中的敏感凭证 |\n| 准备就绪检查 | ✓ | 评估生产环境就绪程度 |\n| 供应链告警 | ✓ | 对已知漏洞包进行交叉比对 |\n\n资料来源：[CONTRIBUTING.md:Code Structure]()\n\n## 扩展主机支持\n\ndecoy-scan 支持通过修改 `HOST_CONFIGS` 配置对象来添加新的 MCP 主机支持。\n\n### 添加新主机步骤\n\n1. 在 `index.mjs` 中的 `HOST_CONFIGS` 对象添加新条目\n2. 实现平台感知的路径解析逻辑\n3. 确保配置文件格式符合 MCP 规范\n4. 运行 `npm test` 验证测试通过\n\n### 配置模板\n\n```javascript\nHOST_CONFIGS: {\n  // ... 现有配置\n  \"New MCP Client\": () => {\n    const p = platform();\n    if (p === \"darwin\") {\n      return join(homedir(), \"Library\", \"Application Support\", \"NewClient\", \"config.json\");\n    }\n    if (p === \"win32\") {\n      return join(process.env.APPDATA || \"\", \"NewClient\", \"config.json\");\n    }\n    // Linux\n    return join(homedir(), \".config\", \"newclient\", \"config.json\");\n  }\n}\n```\n\n资料来源：[CONTRIBUTING.md:Adding Host Configs]()\n\n## 错误处理与鲁棒性\n\n主机发现模块具备完善的错误处理机制，确保在各种异常情况下仍能提供有用的诊断信息。\n\n### 常见错误场景\n\n| 错误类型 | 处理方式 | 用户提示 |\n|---------|---------|---------|\n| 配置文件不存在 | 静默跳过 | 无 |\n| JSON 解析失败 | 记录错误 | 显示解析错误详情 |\n| 权限不足 | 捕获异常 | 提示权限问题 |\n| 探测超时 | 强制终止 | 显示 `? probe failed` |\n\n### 探针失败展示\n\n当服务器探测失败时，CLI 输出会显示明确的错误标识：\n\n```\n? filesystem-server probe failed\n  Error: Connection timeout after 5000ms\n```\n\n资料来源：[CHANGELOG.md:0.5.3:Fixed]()\n\n## 设计原则\n\nMCP 主机发现模块遵循 decoy-scan 的核心设计理念：\n\n| 原则 | 实现方式 | 优势 |\n|-----|---------|------|\n| 零依赖 | 纯 Node.js 内置模块 | 无需安装额外包 |\n| 零配置 | 自动探测本机配置 | 开箱即用 |\n| 快速 | 异步 I/O + 超时控制 | 秒级完成扫描 |\n| 安全 | 只读扫描不修改配置 | 不影响用户环境 |\n| Agent 优先 | JSON/SARIF 结构化输出 | 便于自动化集成 |\n\n资料来源：[CONTRIBUTING.md:Design Principles]()\n\n## 命令行使用\n\n主机发现功能通过以下命令行参数进行控制：\n\n| 参数 | 功能 | 说明 |\n|-----|------|------|\n| 无参数 | 全量扫描 | 发现所有主机和服务器 |\n| `--no-probe` | 仅配置发现 | 跳过服务器探测，仅读取配置 |\n| `--no-advisories` | 跳过网络请求 | 跳过供应链告警检查 |\n| `--verbose` | 显示所有工具 | 包括低风险工具 |\n| `--json` | JSON 输出 | 结构化机器可读输出 |\n| `--sarif` | SARIF 输出 | 符合 SARIF 2.1.0 标准 |\n\n```bash\n# 仅发现配置，不探测服务器\nnpx decoy-scan --no-probe\n\n# 跳过供应链告警检查\nnpx decoy-scan --no-advisories\n\n# 详细输出模式\nnpx decoy-scan --verbose\n```\n\n资料来源：[AGENTS.md:CLI Flags]()\n\n## 技术规格\n\n| 规格项 | 值 |\n|-------|-----|\n| 支持平台 | macOS, Windows, Linux |\n| Node.js 最低版本 | 18+ |\n| 依赖数量 | 0 (零依赖) |\n| 配置格式 | JSON |\n| 默认超时 | 5000ms |\n| 并发探测 | 串行执行 |\n\n## 总结\n\nMCP 主机发现是 decoy-scan 实现自动化安全扫描的基础能力，通过平台感知的配置路径解析和结构化的服务器发现机制，为后续的安全分析提供了完整的目标清单。该模块的零依赖设计和只读扫描原则确保了工具的便携性和安全性，使其能够在各种开发环境中无缝集成到 CI/CD 流程中。\n\n---\n\n<a id='toxic-flow-analysis'></a>\n\n## 有毒数据流分析\n\n### 相关页面\n\n相关主题：[提示注入检测](#prompt-injection-detection), [安全检查项目](#security-checks)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [lib/analyzers.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/analyzers.mjs)\n- [lib/scan.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/scan.mjs)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n</details>\n\n# 有毒数据流分析\n\n有毒数据流分析（Tainted Flow Analysis 或 Toxic Flow Analysis）是 decoy-scan 安全扫描器的核心检测模块之一。该模块通过追踪 MCP 服务器之间的数据传递路径，识别潜在的安全威胁链，包括跨服务器数据泄露和破坏性操作链。\n\n## 概述\n\n在 MCP（Model Context Protocol）生态系统中，多个服务器通常协同工作，每个服务器拥有不同的工具和权限。有毒数据流分析模块专门检测以下两类攻击链：\n\n| 攻击类型 | 标识符 | 严重级别 | 描述 |\n|---------|--------|---------|------|\n| 跨服务器数据泄露 | TF001 | Critical | 敏感数据通过多个服务器传递后被不当暴露 |\n| 破坏性攻击链 | TF002 | Critical | 多个工具组合执行导致不可逆的破坏性操作 |\n\n资料来源：[README.md:1]()\n\n## 核心功能\n\n### 攻击链检测机制\n\n有毒数据流分析通过分析工具调用序列和数据传递路径来识别潜在威胁。当扫描器探测 MCP 服务器时，会收集所有可用工具的元数据，包括工具名称、描述和参数模式。然后通过图分析算法构建工具调用依赖图，检测是否存在恶意的数据传递链。\n\n该模块的核心逻辑位于 `lib/analyzers.mjs` 中的 `analyzeToxicFlows` 函数。该函数接收扫描到的服务器列表和工具信息，返回检测到的有毒数据流列表。\n\n### 扫描结果数据结构\n\n扫描完成后，有毒数据流结果通过 `results.toxicFlows` 属性暴露：\n\n```javascript\nimport { scan } from 'decoy-scan';\n\nconst results = await scan();\nconsole.log(results.toxicFlows);\n// 输出格式：\n// [{ id: \"TF001\", severity: \"critical\", roles: {...} }]\n```\n\n每个有毒数据流包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| id | string | 攻击链标识符（如 TF001、TF002） |\n| severity | string | 严重级别（critical/high/medium/low） |\n| roles | object | 涉及的角色和权限信息 |\n\n资料来源：[AGENTS.md:1]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n    A[扫描 MCP 配置] --> B[探测服务器工具列表]\n    B --> C[收集工具元数据]\n    C --> D[构建工具依赖图]\n    D --> E{分析数据传递路径}\n    E -->|检测到 TF001| F[跨服务器数据泄露]\n    E -->|检测到 TF002| G[破坏性攻击链]\n    E -->|未检测到威胁| H[扫描通过]\n    F --> I[生成安全报告]\n    G --> I\n    H --> I\n```\n\n## 策略控制\n\ndecoy-scan 提供了细粒度的策略控制机制，允许用户在 CI/CD 环境中根据安全需求配置扫描行为。\n\n### 策略规则\n\n通过 `--policy` 参数可以配置以下与有毒数据流相关的策略：\n\n```\nno-toxic-flows       Fail on cross-server data leak / destructive chains\n```\n\n资料来源：[README.md:1]()\n\n### 退出码机制\n\n有毒数据流检测结果直接影响扫描器的退出码：\n\n| 退出码 | 含义 |\n|-------|------|\n| 0 | 无 critical 或 high 级别问题 |\n| 1 | 发现 high 级别风险问题 |\n| 2 | 发现 critical 级别问题、工具投毒或有毒数据流 |\n\n资料来源：[AGENTS.md:1]()\n\n## 集成使用\n\n### 作为库函数导入\n\ndecoy-scan 提供了模块化接口，可以直接导入 `analyzeToxicFlows` 函数用于自定义分析场景：\n\n```javascript\nimport {\n  scan,\n  analyzeToxicFlows,\n} from 'decoy-scan';\n\n// 执行完整扫描\nconst results = await scan();\n\n// 仅执行有毒数据流分析\nconst toxicFlows = analyzeToxicFlows(results.servers);\nconsole.log(toxicFlows);\n```\n\n### 完整扫描配置\n\n使用 `scan()` 函数时，可以通过选项对象配置扫描行为：\n\n```javascript\nconst results = await scan({\n  skills: true,           // 包含技能扫描\n  advisories: true,       // 包含供应链告警\n  verbose: false,         // 显示所有工具\n  noProbe: false          // 跳过服务器探测\n});\n```\n\n扫描结果对象包含完整的分析数据：\n\n```javascript\n{\n  servers: [...],        // 服务器列表及工具信息\n  toxicFlows: [...],     // 有毒数据流分析结果\n  skills: [...],         // 技能分析结果\n  summary: {\n    total: 2,\n    critical: 1,\n    high: 2,\n    medium: 4,\n    low: 5,\n    poisoned: 0,\n    status: \"fail\",\n    exitCode: 2\n  }\n}\n```\n\n资料来源：[AGENTS.md:1]()\n\n## GitHub Action 集成\n\n在 CI/CD 流程中使用 decoy-scan 时，可以通过 GitHub Action 启用有毒数据流检测：\n\n```yaml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n        with:\n          policy: no-critical,no-poisoning,no-toxic-flows\n          sarif: true\n```\n\n### Action 输入参数\n\n| 参数 | 默认值 | 说明 |\n|------|-------|------|\n| policy | no-critical,no-poisoning | 策略规则列表 |\n| sarif | true | 上传 SARIF 到 GitHub Security |\n| report | false | 上传到 Decoy Guard 仪表板 |\n| token | — | Decoy API 令牌（用于 report） |\n| verbose | false | 显示所有工具包括低风险 |\n\n资料来源：[README.md:1]()\n\n## 威胁场景示例\n\n### TF001：跨服务器数据泄露\n\n当一个服务器拥有读取敏感文件的能力，而该数据随后被传递给另一个具有网络访问权限的服务器时，就会形成数据泄露攻击链。decoy-scan 会检测这种跨服务器的敏感数据传递模式。\n\n### TF002：破坏性攻击链\n\n当多个工具按特定顺序组合使用时，可能导致文件系统破坏或数据不可逆损失。例如，读取配置 → 修改权限 → 删除文件的连续操作可能被识别为破坏性攻击链。\n\n## 输出格式\n\n### JSON 结构\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [...],\n  \"summary\": {\n    \"total\": 2,\n    \"critical\": 1,\n    \"high\": 2,\n    \"medium\": 4,\n    \"low\": 5,\n    \"poisoned\": 0,\n    \"toxicFlows\": 1,\n    \"status\": \"fail\",\n    \"exitCode\": 2\n  }\n}\n```\n\n### Brief 输出\n\n对于简化的概要输出：\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"medium\": 4,\n  \"low\": 5,\n  \"poisoned\": 0,\n  \"toxicFlows\": 1,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n资料来源：[AGENTS.md:1]()\n\n## 版本历史\n\n有毒数据流分析功能在以下版本中逐步完善：\n\n| 版本 | 更新内容 |\n|------|---------|\n| 0.2.0 | 引入有毒数据流分析模块 |\n| 0.5.0 | 增强分析精度，修复边界情况 |\n| 0.5.8 | 优化性能，减少误报 |\n\n资料来源：[CHANGELOG.md:1]()\n\n## 相关模块\n\n有毒数据流分析与其他安全检测模块协同工作：\n\n| 模块 | 功能 |\n|-----|------|\n| 工具风险分类 | 评估单个工具的风险级别 |\n| 工具投毒检测 | 检测工具描述中的提示注入 |\n| 服务器命令分析 | 检查服务器启动命令的安全性 |\n| 环境变量暴露检测 | 识别敏感凭证的泄露风险 |\n\n所有模块的检测结果统一汇总到 `scan()` 函数的返回结果中，形成完整的安全态势报告。\n\n---\n\n<a id='github-action'></a>\n\n## GitHub Action 集成\n\n### 相关页面\n\n相关主题：[快速开始](#getting-started)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [action.yml](https://github.com/decoy-run/decoy-scan/blob/main/action.yml)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n</details>\n\n# GitHub Action 集成\n\n## 概述\n\ndecoy-scan 提供官方的 GitHub Action，用于在 CI/CD 流水线中自动化扫描 MCP 配置。该 Action 无需安装依赖，一行配置即可将 MCP 安全扫描集成到现有的 GitHub 工作流中，支持策略强制执行和 SARIF 结果上传功能。资料来源：[README.md:52-60]()\n\n## 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 自动发现 | 扫描仓库中的 MCP 配置文件 |\n| 策略强制 | 根据规则失败构建 |\n| SARIF 上传 | 将结果上传至 GitHub Security Tab |\n| 多主机支持 | 支持 Claude Desktop、Cursor、Windsurf、VS Code、Claude Code、Zed、Cline |\n\n## 工作原理\n\n```mermaid\ngraph TD\n    A[触发工作流] --> B[检出代码]\n    B --> C[运行 decoy-scan]\n    C --> D{扫描结果}\n    D -->|通过| E[✅ 成功]\n    D -->|有风险| F[🚨 失败 + 上传 SARIF]\n    D -->|仅 SARIF| G[上传 SARIF]\n    F --> H[GitHub Security Tab]\n    G --> H\n```\n\n## 使用方式\n\n### 基础配置\n\n在 `.github/workflows/mcp-security.yml` 中添加以下内容：\n\n```yaml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n```\n\n资料来源：[README.md:52-66]()\n\n### 完整配置示例\n\n```yaml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n        with:\n          policy: no-critical,no-poisoning,no-toxic-flows\n          sarif: true\n          report: true\n          token: ${{ secrets.DECOY_TOKEN }}\n          verbose: false\n```\n\n## 输入参数\n\n| 参数 | 默认值 | 必填 | 说明 |\n|------|--------|------|------|\n| `policy` | `no-critical,no-poisoning` | 否 | 逗号分隔的策略规则 |\n| `sarif` | `true` | 否 | 上传 SARIF 到 GitHub Security Tab |\n| `report` | `false` | 否 | 上传到 Decoy Guard 仪表板 |\n| `token` | — | 条件 | Decoy API 令牌（仅 `report: true` 时需要） |\n| `verbose` | `false` | 否 | 显示所有工具包括低风险项 |\n\n资料来源：[README.md:68-76]()\n\n## 策略规则\n\n| 规则 | 说明 |\n|------|------|\n| `no-critical` | 遇到关键工具（代码执行、文件写入）时失败 |\n| `no-high` | 遇到高风险工具（文件读取、网络请求）时失败 |\n| `no-poisoning` | 检测到提示词注入时失败 |\n| `no-toxic-flows` | 检测到跨服务器数据泄露或破坏性链时失败 |\n| `no-secrets` | 检测到 MCP 配置中暴露的密钥时失败 |\n| `require-tripwires` | decoy-tripwire 未安装时失败 |\n| `max-critical=N` | 关键工具数量超过阈值时失败 |\n\n## 输出变量\n\nAction 执行后生成以下输出供后续步骤使用：\n\n| 输出 | 说明 |\n|------|------|\n| `exit-code` | 扫描退出码（0=通过, 1=高风险, 2=严重/投毒） |\n| `sarif-file` | 生成的 SARIF 文件路径 |\n| `summary` | 扫描摘要信息 |\n\n```yaml\nsteps:\n  - id: scan\n    uses: decoy-run/decoy-scan@v1\n  - name: 使用结果\n    run: |\n      echo \"Exit code: ${{ steps.scan.outputs.exit-code }}\"\n      echo \"Summary: ${{ steps.scan.outputs.summary }}\"\n```\n\n资料来源：[action.yml:55-60]()\n\n## SARIF 集成\n\n启用 `sarif: true` 后，Action 会自动：\n\n1. 生成 SARIF 2.1.0 格式的扫描报告\n2. 上传到 GitHub Security Tab\n3. 在 Pull Request 中显示安全警告\n\n```yaml\n- name: Upload SARIF to GitHub Security\n  if: always() && inputs.sarif == 'true' && steps.scan.outputs.sarif-file != ''\n  uses: github/codeql-action/upload-sarif@v3\n  with:\n    sarif_file: ${{ steps.scan.outputs.sarif-file }}\n    category: decoy-scan\n  continue-on-error: true\n```\n\n资料来源：[action.yml:68-76]()\n\n## 工作流状态处理\n\n```mermaid\ngraph TD\n    A[decoy-scan 执行] --> B{退出码}\n    B -->|0| C[✅ Clean - 无问题]\n    B -->|1| D[⚠️ Warnings - 高风险问题]\n    B -->|2| E[🚨 Failed - 严重/投毒]\n    C --> F[写入 GITHUB_STEP_SUMMARY]\n    D --> F\n    E --> F\n    F --> G[Exit 1 失败构建]\n```\n\nAction 使用 `set +e` 捕获退出码，不会立即失败 step，确保 SARIF 上传和摘要写入在所有情况下都能执行。资料来源：[action.yml:38-50]()\n\n## GitHub Step Summary\n\nAction 会在 GitHub Actions 运行日志中生成摘要：\n\n```markdown\n## Decoy Scan\n\n✅ **Clean** — no issues found\n```\n\n或\n\n```markdown\n## Decoy Scan\n\n🚨 **Issues found** — N servers scanned, N critical, N high\n\nRun `npx decoy-scan -v` locally for full details.\n```\n\n## 版本管理\n\n| 版本 | 说明 |\n|------|------|\n| `@v1` | 主版本，稳定接口 |\n| `@latest` | 始终指向最新发布 |\n| `@0.x.x` | 指定具体版本 |\n\n建议使用 `@v1` 以接收 bug 修复和安全更新，同时保持接口稳定性。\n\n## 与 decoy-scan CLI 的对比\n\n| 特性 | GitHub Action | CLI |\n|------|--------------|-----|\n| 部署方式 | GitHub 市场 | npx |\n| SARIF 上传 | 内置 | 需手动配置 |\n| 策略强制 | 通过 `policy` 参数 | 通过 `--policy` 参数 |\n| CI 集成 | 原生 | 需编写 YAML |\n| 密钥管理 | GitHub Secrets | 环境变量 |\n\n## 故障排除\n\n### SARIF 未上传\n\n确保 `permissions: security-events: write` 已配置：\n\n```yaml\npermissions:\n  security-events: write\n```\n\n### 构建未失败但有安全问题\n\n检查 `policy` 参数是否包含所需的规则：\n\n```yaml\nwith:\n  policy: no-critical,no-poisoning\n```\n\n### 令牌相关错误\n\n验证 Decoy API 令牌格式正确且未过期：\n\n```yaml\nwith:\n  token: ${{ secrets.DECOY_TOKEN }}\n```\n\n## 相关文档\n\n- [decoy-scan 主文档](https://decoy.run/docs/scan/overview)\n- [OWASP Agentic Top 10 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)\n- [SARIF 规范](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：decoy-run/decoy-scan\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | release_recency=unknown\n\n<!-- canonical_name: decoy-run/decoy-scan; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "decoy-scan",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "github_repo:1185640470",
          "kind": "repo",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/decoy-run/decoy-scan"
        },
        {
          "evidence_id": "art_f5cc6c64e4894efe8a980f3276052a78",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/decoy-run/decoy-scan#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "decoy-scan 说明书",
      "toc": [
        "https://github.com/decoy-run/decoy-scan 项目说明书",
        "目录",
        "项目介绍",
        "概述",
        "核心功能",
        "支持的平台",
        "技术架构",
        "安装与使用",
        "Doramagic 踩坑日志"
      ]
    }
  },
  "quality_gate": {
    "blocking_gaps": [],
    "category_confidence": "medium",
    "compile_status": "ready_for_review",
    "five_assets_present": true,
    "install_sandbox_verified": true,
    "missing_evidence": [],
    "next_action": "publish to Doramagic.ai project surfaces",
    "prompt_preview_boundary_ok": true,
    "publish_status": "publishable",
    "quick_start_verified": true,
    "repo_clone_verified": true,
    "repo_commit": "b50fb324f5f2c79030ef307d48b4758aed1adaa2",
    "repo_inspection_error": null,
    "repo_inspection_files": [
      "package.json",
      "README.md"
    ],
    "repo_inspection_verified": true,
    "review_reasons": [
      "community_discussion_evidence_below_public_threshold"
    ],
    "tag_count_ok": true,
    "unsupported_claims": []
  },
  "schema_version": "0.1",
  "user_assets": {
    "ai_context_pack": {
      "asset_id": "ai_context_pack",
      "filename": "AI_CONTEXT_PACK.md",
      "markdown": "# decoy-scan - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 decoy-scan 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`AGENTS.md`, `README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx decoy-scan` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86 等\n- `npx decoy-scan                     # Full scan with server probing` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx decoy-scan --json              # JSON output (stdout, pipeable to jq)` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx decoy-scan --sarif             # SARIF 2.1.0 for GitHub Security / VS Code` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx decoy-scan --skills            # Also scan Claude Code skills` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx decoy-scan --no-probe          # Config-only (don't spawn servers)` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx decoy-scan --no-advisories     # Skip advisory database check` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx decoy-scan --report            # Upload results to Decoy dashboard` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npx decoy-scan --policy=RULES      # CI/CD policy gate (exit 2 on violation)` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `npx decoy-scan --verbose           # Show all tools including low-risk` 证据：`README.md` Claim：`clm_0012` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`AGENTS.md`, `README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`AGENTS.md`, `README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`AGENTS.md`, `README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0026` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`AGENTS.md`, `README.md` Claim：`clm_0027` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md`, `README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：33\n- 重要文件覆盖：30/33\n- 证据索引条目：30\n- 角色 / Skill 条目：5\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 decoy-scan 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 decoy-scan 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 decoy-scan 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **decoy-scan — Agent Reference**（project_doc）：MCP supply chain security scanner. Zero dependencies. Node.js = 18. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **🚀 Get Started**（project_doc）：Find security risks in your MCP servers before attackers do. Zero dependencies, zero config, zero account required. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Contributing to decoy-scan**（project_doc）：Thanks for your interest in improving MCP security. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Changelog**（project_doc）：All notable changes to this project will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Security Policy**（project_doc）：Version Supported ------- --------- 0.4.x Yes < 0.4 No 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n\n## 证据索引\n\n- 共索引 30 条证据。\n\n- **decoy-scan — Agent Reference**（documentation）：MCP supply chain security scanner. Zero dependencies. Node.js = 18. 证据：`AGENTS.md`\n- **🚀 Get Started**（documentation）：Find security risks in your MCP servers before attackers do. Zero dependencies, zero config, zero account required. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"decoy-scan\", \"version\": \"0.8.0\", \"description\": \"Security scanner for MCP server configurations. Finds risky tools, vulnerable packages, and suspicious servers across Claude Desktop, Cursor, VS Code, and more.\", \"type\": \"module\", \"main\": \"index.mjs\", \"exports\": { \".\": \"./index.mjs\" }, \"bin\": { \"decoy-scan\": \"bin/cli.mjs\" }, \"files\": \"index.mjs\", \"lib/\", \"bin/\" , \"keywords\": \"mcp\", \"security\", \"scanner\", \"supply-chain\", \"ai-agent\", \"vulnerability\", \"prompt-injection\", \"tool-risk\" , \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/decoy-run/decoy-scan\" }, \"homepage\": \"https://decoy.run\", \"bugs\": { \"url\": \"https://github.com/decoy-run/decoy-scan/issues\" }, \"scripts\": { \"tes… 证据：`package.json`\n- **Contributing to decoy-scan**（documentation）：Thanks for your interest in improving MCP security. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Changelog**（documentation）：All notable changes to this project will be documented in this file. 证据：`CHANGELOG.md`\n- **Security Policy**（documentation）：Version Supported ------- --------- 0.4.x Yes < 0.4 No 证据：`SECURITY.md`\n- **.gitignore**（source_file）：node modules/ .DS Store .next/ .env .log 证据：`.gitignore`\n- **Build flags**（source_file）：name: Decoy Scan description: Scan MCP server configurations for security risks — tool poisoning, toxic flows, secrets exposure, and more. author: decoy-run 证据：`action.yml`\n- **!/usr/bin/env node**（source_file）：// decoy-scan CLI — MCP supply chain security scanner 证据：`bin/cli.mjs`\n- **Index**（source_file）：// decoy-scan — MCP supply chain scanner // Public API — re-exports from lib/ modules. 证据：`index.mjs`\n- **Advisories**（source_file）：// Advisory check — fetches vulnerability advisories from the Decoy API. 证据：`lib/advisories.mjs`\n- **Analyzers**（source_file）：// Analysis functions — pure, composable, no side effects. // Each takes a tool/entry/array, returns structured findings. 证据：`lib/analyzers.mjs`\n- **Constants**（source_file）：// Extracted constants — no more magic numbers at 3am 证据：`lib/constants.mjs`\n- **Discovery**（source_file）：// Host config discovery — finds MCP server configurations across IDEs and tools. 证据：`lib/discovery.mjs`\n- **Explain**（source_file）：// Explanations for decoy-scan's classifications. // Sourced from the same rules the scanner uses, so explanations stay in sync. 证据：`lib/explain.mjs`\n- **Install Id**（source_file）：// Install ID — stable, anonymous identifier for this machine. Written to // ~/.decoy/install id on first run. The only stable identifier the CLI sends // to /api/telemetry; on signup the dashboard links it to an account so // pre-signup history is preserved. 证据：`lib/install_id.mjs`\n- **Owasp**（source_file）：// OWASP Agentic Top 10 mapping — finding type → OWASP ID 证据：`lib/owasp.mjs`\n- **Patterns**（source_file）：// Pattern definitions — the data layer. // Pure arrays of regex + metadata. No logic, no side effects. 证据：`lib/patterns.mjs`\n- **Probe**（source_file）：// Server probing — spawns MCP servers and extracts tools via JSON-RPC 2.0. 证据：`lib/probe.mjs`\n- **Sarif**（source_file）：// SARIF 2.1.0 output — exports scan results for GitHub Security tab and other SARIF consumers. 证据：`lib/sarif.mjs`\n- **Scan**（source_file）：// Scan orchestration — wires discovery, probing, analysis, and reporting together. 证据：`lib/scan.mjs`\n- **Skills**（source_file）：// Skill scanning — discovers and analyzes Claude Code skills for injection and secrets. 证据：`lib/skills.mjs`\n- **Telemetry**（source_file）：// Anonymous telemetry client v2 envelope for decoy- CLIs. // // Default: ON. Every event carries: // { schema version: 2, tool, version, installId, accountId?, event, // event id, run id, ts, env: { node, platform, arch, ci, host, locale }, // payload } // // Three durability guarantees: // 1. Retry — 1 retry with 200→800ms backoff on timeout / 5xx. // 2. Persistent queue — on final failure events append to // ~/.decoy/telemetry-queue.jsonl capped 1000, FIFO . The next // CLI run drains the queue first as a batched POST. // 3. Dedup — every event carries a UUID event id, so retries + // queue-drain replays are server-side idempotent. // // Opt-out: DECOY TELEMETRY=0 env var or --no-telemet… 证据：`lib/telemetry.mjs`\n- **Tier**（source_file）：// Plan/tier resolution for the CLI. Looks up a token's plan via /api/billing // and caches the answer at ~/.decoy/tier for 24 hours so each explain call // doesn't take an extra network round-trip. // // Returns one of: \"free\" \"team\" \"business\" \"unknown\". // \"unknown\" means: no token, fetch failed, or response was malformed — // callers should treat unknown as free for gating purposes. 证据：`lib/tier.mjs`\n- **Verify**（source_file）：// Client for the /api/verify endpoint — DeepSec-style AI verification of // scan findings. Requires a free Decoy account claim install id at // app.decoy.run/d/ . Free: 5/account/month. Team: 30/seat/day. // Business: 60/seat/day. // // Returns: // { ok: true, verified: ... , stats: {...}, quota: {...} null } // { ok: false, status, code, message, claimUrl?, upgradeUrl?, quota?, cap? } // // Never throws — caller switches on ok and renders. 证据：`lib/verify.mjs`\n- **Cli.Test**（source_file）：// decoy-scan CLI tests // Run: node --test test/cli.test.mjs 证据：`test/cli.test.mjs`\n- **Probe.Test**（source_file）：// Probe, advisory, SARIF, and poisoning false-positive tests // Run: node --test test/probe.test.mjs 证据：`test/probe.test.mjs`\n- **Telemetry.Test**（source_file）：// Tests for install id + telemetry helpers. // Run: node --test test/telemetry.test.mjs 证据：`test/telemetry.test.mjs`\n- **Unit.Test**（source_file）：// Unit tests for individual modules // Run: node --test test/unit.test.mjs 证据：`test/unit.test.mjs`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`AGENTS.md`, `README.md`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`AGENTS.md`, `README.md`, `package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n  - source_paths: README.md, package.json\n- **快速开始**：importance `high`\n  - source_paths: bin/cli.mjs, index.mjs, action.yml\n- **命令行工具**：importance `high`\n  - source_paths: bin/cli.mjs, lib/explain.mjs\n- **安全检查项目**：importance `high`\n  - source_paths: lib/scan.mjs, lib/patterns.mjs\n- **风险分级系统**：importance `high`\n  - source_paths: lib/tier.mjs, lib/owasp.mjs, lib/constants.mjs\n- **提示注入检测**：importance `high`\n  - source_paths: lib/patterns.mjs, lib/analyzers.mjs\n- **扫描架构**：importance `high`\n  - source_paths: lib/scan.mjs, lib/verify.mjs, lib/probe.mjs\n- **MCP 主机发现**：importance `high`\n  - source_paths: lib/discovery.mjs, lib/sarif.mjs\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `b50fb324f5f2c79030ef307d48b4758aed1adaa2`\n- inspected_files: `package.json`, `README.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
      "summary": "给宿主 AI 的上下文和工作边界。",
      "title": "AI Context Pack / 带给我的 AI"
    },
    "boundary_risk_card": {
      "asset_id": "boundary_risk_card",
      "filename": "BOUNDARY_RISK_CARD.md",
      "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：decoy-run/decoy-scan\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在安全注意事项（medium）：用户安装前需要知道权限边界和敏感操作。 建议检查：转成明确权限清单和安全审查提示。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
      "summary": "安装、权限、验证和推荐前风险。",
      "title": "Boundary & Risk Card / 边界与风险卡"
    },
    "human_manual": {
      "asset_id": "human_manual",
      "filename": "HUMAN_MANUAL.md",
      "markdown": "# https://github.com/decoy-run/decoy-scan 项目说明书\n\n生成时间：2026-05-14 05:23:08 UTC\n\n## 目录\n\n- [项目介绍](#project-introduction)\n- [快速开始](#getting-started)\n- [命令行工具](#cli-usage)\n- [安全检查项目](#security-checks)\n- [风险分级系统](#risk-classification)\n- [提示注入检测](#prompt-injection-detection)\n- [扫描架构](#scanning-architecture)\n- [MCP 主机发现](#mcp-host-discovery)\n- [有毒数据流分析](#toxic-flow-analysis)\n- [GitHub Action 集成](#github-action)\n\n<a id='project-introduction'></a>\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#getting-started), [安全检查项目](#security-checks)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n- [action.yml](https://github.com/decoy-run/decoy-scan/blob/main/action.yml)\n</details>\n\n# 项目介绍\n\n## 概述\n\ndecoy-scan 是一款面向 MCP (Model Context Protocol) 生态的**供应链安全扫描工具**，旨在 Agent 执行工具调用之前发现 MCP 服务器中的安全风险。该项目由 Decoy 团队开发，采用零依赖设计，仅需 Node.js 18+ 即可运行，无需安装任何 npm 包。资料来源：[README.md:1]()\n\ndecoy-scan 的核心价值在于：\n\n- **主动防御**：在攻击者利用漏洞之前识别 MCP 服务器中的危险工具和提示注入\n- **零配置**：开箱即用，自动发现本地 MCP 客户端配置\n- **多平台支持**：覆盖主流 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）\n- **CI/CD 友好**：支持 JSON、SARIF 等结构化输出，便于集成到自动化流水线\n\n资料来源：[README.md:1-3]()\n\n## 核心功能\n\ndecoy-scan 提供全面的 MCP 安全扫描能力，涵盖以下检查维度：\n\n| 检查类别 | 功能描述 |\n|---------|---------|\n| 工具风险分类 | 基于名称和描述将工具分为 critical/high/medium/low 四个风险等级 |\n| 提示注入检测 | 37 种正则模式，覆盖 20 个攻击类别，检测工具描述中的提示注入 |\n| 毒性流分析 | 识别跨服务器数据泄露（TF001）和破坏性攻击链（TF002） |\n| 工具清单哈希 | 追踪工具的增删改，检测扫描间的清单变化 |\n| Skill 扫描 | 检测 Claude Code 中的提示注入、硬编码密钥、可疑 URL |\n| 服务器命令分析 | 检测管道到 shell、内联代码、域名仿冒、临时目录生成 |\n| 环境变量暴露 | 识别传递给服务器的 API 密钥、令牌、敏感凭证 |\n| 供应链告警 | 对接 Decoy 告警数据库，覆盖 40+ 已知漏洞 MCP 包 |\n| 传输安全 | 检查 HTTP 无 TLS、缺失认证、通配符 CORS、公共 SSE |\n| 输入验证 | 验证参数约束、maxLength、开放模式 |\n| 权限范围 | 评估过度授权服务器和危险能力组合 |\n| OWASP 映射 | 将所有发现映射到 ASI01–ASI05（OWASP Agentic Top 10） |\n\n资料来源：[README.md:1]()\n\n### 工具风险等级定义\n\n| 等级 | 含义 | 示例工具 |\n|------|------|---------|\n| Critical | 可执行代码、修改数据或造成不可逆变更 | execute_command, write_file |\n| High | 可读取文件或发起网络请求 | read_file, fetch_url |\n| Medium | 轻度风险，需注意配置 | list_directory |\n| Low | 安全工具，可放心使用 | get_time |\n\n资料来源：[AGENTS.md:1]()\n\n### 提示注入检测类型\n\ndecoy-scan 内置 37 种提示注入检测模式，涵盖以下攻击类别：\n\n- 指令覆盖（Instruction Override）\n- 隐匿（Concealment）\n- 数据外泄（Data Exfiltration）\n- 凭证收割（Credential Harvesting）\n- 强制执行（Coercive Execution）\n- 工具影身（Tool Shadowing）\n- 规避技术（Evasion Techniques）\n\n资料来源：[AGENTS.md:1]()\n\n## 支持的平台\n\ndecoy-scan 支持检测以下 MCP 客户端的配置文件：\n\n| 平台 | 操作系统 | 配置文件路径 |\n|------|---------|-------------|\n| Claude Desktop | macOS / Windows / Linux | 平台相关配置目录 |\n| Cursor | macOS / Windows / Linux | 平台相关配置目录 |\n| Windsurf | macOS / Windows / Linux | 平台相关配置目录 |\n| VS Code | macOS / Windows / Linux | 平台相关配置目录 |\n| Claude Code | macOS / Windows / Linux | 平台相关配置目录 |\n| Zed | macOS / Windows / Linux | 平台相关配置目录 |\n| Cline | macOS / Windows / Linux | 平台相关配置目录 |\n\n配置文件路径根据操作系统自动适配（macOS、Windows、Linux）。\n\n资料来源：[AGENTS.md:1]()\n\n## 技术架构\n\n### 架构概览\n\n```mermaid\ngraph TD\n    A[用户执行 decoy-scan] --> B[发现 MCP 配置]\n    B --> C{配置类型}\n    C -->|项目级| D[扫描 .mcp.json]\n    C -->|用户级| E[扫描各客户端配置]\n    D --> F[探针 MCP 服务器]\n    E --> F\n    F --> G[获取工具列表]\n    G --> H[分类工具风险]\n    G --> I[检测提示注入]\n    G --> J[分析服务器命令]\n    G --> K[检查环境变量]\n    H --> L[生成扫描报告]\n    I --> L\n    J --> L\n    K --> L\n    L --> M[JSON / SARIF / CLI 输出]\n```\n\n### 核心模块结构\n\n根据 CONTRIBUTING.md 的代码结构说明，主逻辑位于 `index.mjs`：\n\n| 模块 | 功能 |\n|------|------|\n| `RISK_PATTERNS` + `classifyTool()` | 基于名称/描述的工具风险分类 |\n| `POISONING_PATTERNS` + `detectPoisoning()` | 工具描述中的提示注入检测 |\n| `analyzeServerCommand()` | 服务器启动命令分析 |\n| `SENSITIVE_ENV_PATTERNS` + `analyzeEnvExposure()` | 环境变量暴露检测 |\n| `analyzeReadiness()` | 生产就绪状态启发式检查 |\n| `OWASP_MAP` + `mapToOwasp()` | OWASP Agentic Top 10 映射 |\n| `HOST_CONFIGS` + `discoverConfigs()` | MCP 客户端配置发现 |\n| `probeServer()` | MCP stdio 探针 |\n| `scan()` | 完整扫描编排器 |\n| `toSarif()` | SARIF 输出生成器 |\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 库模式使用\n\ndecoy-scan 不仅可作为 CLI 工具使用，还提供编程接口：\n\n```javascript\nimport {\n  scan,\n  toSarif,\n  classifyTool,\n  detectPoisoning,\n  analyzeToxicFlows,\n  hashToolManifest,\n  detectManifestChanges,\n  discoverSkills,\n  analyzeSkill,\n} from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.toxicFlows);    // [{ id: \"TF001\", severity: \"critical\", roles: {...} }]\nconsole.log(results.skills);        // [{ name: \"...\", findings: [...] }]\nconsole.log(results.servers[0].manifestHash);  // \"45c4c571f03c78a2\"\n```\n\n资料来源：[README.md:1]()\n\n## 安装与使用\n\n### 快速开始\n\n无需安装，直接使用 npx 运行：\n\n```bash\nnpx decoy-scan                        # 完整扫描\nnpx decoy-scan --json                 # 机器可读输出\nnpx decoy-scan --sarif                # SARIF 2.1.0 格式（适用于 CI/CD）\nnpx decoy-scan explain <target>       # 解释风险等级/类别/工具\nnpx decoy-scan explain <target> --json  # 结构化解释输出\n```\n\n资料来源：[AGENTS.md:1]()\n\n### CLI 选项\n\n| 选项 | 简写 | 描述 |\n|------|------|------|\n| `--json` | `-j` | 输出 JSON 格式 |\n| `--sarif` | - | 输出 SARIF 2.1.0 格式 |\n| `--brief` | - | 输出最小摘要（隐含 `--json`） |\n| `--verbose` | `-v` | 显示所有工具，包括低风险 |\n| `--quiet` | `-q` | 抑制状态输出 |\n| `--version` | `-V` | 打印版本 |\n| `--help` | `-h` | 打印帮助信息 |\n\n资料来源：[AGENTS.md:1]()\n\n### GitHub Actions 集成\n\ndecoy-scan 提供官方 GitHub Action，可直接集成到 CI/CD 流水线：\n\n```yaml\n# .github/workflows/mcp-security.yml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n        with:\n          policy: no-critical,no-poisoning,no-toxic-flows\n          sarif: true\n          report: true\n          token: ${{ secrets.DECOY_TOKEN }}\n```\n\nAction 输入参数：\n\n| 输入 | 默认值 | 描述 |\n|------|--------|------|\n| `policy` | `no-critical,no-poisoning` | 逗号分隔的策略规则 |\n| `sarif` | `true` | 上传 SARIF 到 GitHub Security |\n| `report` | `false` | 上传到 Decoy Guard 仪表板 |\n| `token` | — | Decoy API 令牌 |\n| `verbose` | `false` | 显示所有工具包括低风险 |\n\n策略规则示例：\n\n```\nno-critical          关键工具失败（代码执行、文件写入）\nno-high              高风险工具失败（文件读取、网络）\nno-poisoning         提示注入失败\nno-toxic-flows       跨服务器数据泄露/破坏链失败\nno-secrets           MCP 配置中的密钥暴露失败\nrequire-tripwires    未安装 decoy-tripwire 时失败\nmax-critical=N       关键工具数量限制\n```\n\n资料来源：[README.md:1]()\n\n## 输出格式\n\n### JSON 输出结构\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null,\n    \"findings\": [{\n      \"type\": \"env-exposure\",\n      \"severity\": \"high\",\n      \"description\": \"...\",\n      \"source\": \"env-config\"\n    }]\n  }],\n  \"summary\": {\n    \"total\": 2, \"critical\": 1, \"high\": 1, \"medium\": 0, \"low\": 0, \"poisoned\": 0\n  },\n  \"exitCode\": 1\n}\n```\n\n资料来源：[AGENTS.md:1]()\n\n### SARIF 输出\n\nSARIF 2.1.0 格式输出，适用于 GitHub Security 标签页集成：\n\n```bash\nnpx decoy-scan --sarif\n```\n\n资料来源：[README.md:1]()\n\n### 退出码\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 未发现 critical 或 high 风险问题 |\n| `1` | 发现 high 风险问题 |\n| `2` | 发现 critical 问题、工具污染或毒性流 |\n\n退出码同时作为 `exitCode` 字段出现在 JSON 和 `--brief` 输出中，便于程序化判断。\n\n资料来源：[AGENTS.md:1]()\n\n## 设计原则\n\ndecoy-scan 遵循以下核心设计原则：\n\n1. **零依赖**：仅使用 Node.js 内置模块，不添加任何 npm 包\n2. **无构建步骤**：纯 ES 模块，无需 TypeScript 或打包器\n3. **高性能**：扫描应在数秒内完成，对服务器探针采用激进超时策略\n4. **安全扫描**：仅读取配置，不修改任何文件，及时终止启动的服务器\n5. **Agent 优先**：JSON 和 SARIF 输出必须可被机器解析，AGENTS.md 必须完整\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 版本历史\n\ndecoy-scan 采用语义化版本号，主要版本特性如下：\n\n| 版本 | 日期 | 主要更新 |\n|------|------|---------|\n| 0.7.0 | 2026-05-10 | v2遥测信封、重试+持久队列、首次运行仪表板链接 |\n| 0.6.0 | 2026-05-08 | 毒性流分析 v2、Skill 扫描、仪表板上传 |\n| 0.5.0 | 2026-04-21 | explain 子命令、CLI 输出重构 |\n| 0.2.0 | 2026-03-20 | SSE 传输安全、输入验证、动态诱饵检测 |\n| 0.1.0 | 2026-03-15 | 初始版本发布 |\n\n资料来源：[CHANGELOG.md:1]()\n\n## 开发指南\n\n### 本地开发\n\n```bash\ngit clone https://github.com/decoy-run/decoy-scan\ncd decoy-scan\nnode bin/cli.mjs --help\n```\n\n无需安装依赖，无需构建步骤，仅需 Node.js >= 18。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 测试\n\n运行完整测试套件：\n\n```bash\nnpm test\n```\n\n测试覆盖 CLI 输出、JSON/SARIF 结构、策略门控、毒性流检测、Skill 分析和清单哈希。所有测试通过后方可提交 PR。\n\n手动测试不同输出模式：\n\n```bash\nnode bin/cli.mjs --no-probe              # 仅配置扫描\nnode bin/cli.mjs --no-advisories         # 跳过网络请求\nnode bin/cli.mjs --json                  # 验证 JSON 结构\nnode bin/cli.mjs --sarif                 # 验证 SARIF 结构\nnode bin/cli.mjs --verbose               # 显示所有输出\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 添加新的检测模式\n\n污染检测模式定义在 `index.mjs` 的 `POISONING_PATTERNS` 中：\n\n```javascript\n{\n  pattern: /regex/i,           // 匹配规则\n  type: \"category-name\",       // 发现类型（用于 OWASP 映射）\n  severity: \"critical\",        // critical, high, medium, low\n  description: \"人类可读描述\"    // 输出中显示\n}\n```\n\n添加模式后，若适用，需将 `type` 添加到 `OWASP_MAP`。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 添加新平台支持\n\n在 `HOST_CONFIGS` 中添加新条目：\n\n```javascript\n\"New Client\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"config.json\");\n},\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 安全问题报告\n\n发现安全漏洞请通过电子邮件联系 `agent@decoy.run`，请勿为此项目创建公开 Issue。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n---\n\n<a id='getting-started'></a>\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#project-introduction), [命令行工具](#cli-usage)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [bin/cli.mjs](https://github.com/decoy-run/decoy-scan/blob/main/bin/cli.mjs)\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [action.yml](https://github.com/decoy-run/decoy-scan/blob/main/action.yml)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n</details>\n\n# 快速开始\n\ndecoy-scan 是一个 MCP（Model Context Protocol）供应链安全扫描工具，用于检测 MCP 服务器配置中的安全风险、提示注入和有毒数据流。\n\n## 功能概述\n\n| 功能模块 | 说明 |\n|---------|------|\n| 工具风险分类 | 按名称和描述将工具分类为 critical/high/medium/low |\n| 提示注入检测 | 37 种正则模式覆盖 20 个攻击类别 |\n| 有毒流分析 | 跨服务器数据泄漏（TF001）和破坏性（TF002）攻击链检测 |\n| 工具清单哈希 | 检测扫描间工具的增删改 |\n| 技能扫描 | Claude Code 技能中的提示注入、硬编码密钥、可疑 URL 检测 |\n| 服务器命令分析 | 管道到 shell、内联代码、 typosquatting、临时目录检测 |\n| 环境变量暴露 | API 密钥、令牌、密码、云凭证检测 |\n| 供应链情报 | 40+ 已知漏洞 MCP 包 |\n| 传输安全 | HTTP 无 TLS、缺失认证、泛域 CORS |\n| OWASP 映射 | 所有发现映射到 ASI01-ASI05 |\n\n资料来源：[README.md:37-51]()\n\n## 系统要求\n\n| 要求 | 详情 |\n|-----|------|\n| Node.js 版本 | >= 18 |\n| 依赖 | 零依赖（仅使用 Node.js 内置模块） |\n| 构建步骤 | 无需构建，直接运行 ES 模块 |\n| 支持平台 | macOS, Windows, Linux |\n\n资料来源：[CONTRIBUTING.md:8-10]()\n\n## 基本用法\n\n### 方式一：直接运行（推荐）\n\n```bash\nnpx decoy-scan\n```\n\n无需安装，直接运行。工具会自动扫描本地所有支持的 MCP 客户端配置。\n\n资料来源：[README.md:23-24]()\n\n### 方式二：本地开发\n\n```bash\ngit clone https://github.com/decoy-run/decoy-scan\ncd decoy-scan\nnode bin/cli.mjs --help\n```\n\n资料来源：[CONTRIBUTING.md:4-8]()\n\n## 支持的主机\n\ndecoy-scan 支持以下 7 个 MCP 客户端的配置文件自动发现：\n\n| 主机 | 平台支持 |\n|-----|---------|\n| Claude Desktop | macOS, Windows, Linux |\n| Cursor | macOS, Windows, Linux |\n| Windsurf | macOS, Windows, Linux |\n| VS Code | macOS, Windows, Linux |\n| Claude Code | macOS, Windows, Linux |\n| Zed | macOS, Windows, Linux |\n| Cline | macOS, Windows, Linux |\n\n配置文件路径根据操作系统自动适配（macOS 使用 `~/Library/...`，Windows 使用 `%APPDATA%`，Linux 使用 `~/.config`）。\n\n资料来源：[AGENTS.md:59-61]()\n\n## 扫描工作流\n\n```mermaid\ngraph TD\n    A[启动 decoy-scan] --> B[发现 MCP 服务器配置]\n    B --> C{配置检测}\n    C -->|有配置| D[启动服务器进程]\n    C -->|无配置| E[生成诊断信息]\n    D --> F[通过 stdio 查询工具列表]\n    F --> G[工具风险分类]\n    F --> H[提示注入检测]\n    F --> I[环境变量暴露分析]\n    G --> J[生成扫描报告]\n    H --> J\n    I --> J\n    E --> K[输出 --json / --sarif 格式]\n    J --> K\n```\n\n## CLI 参数参考\n\n### 全局参数\n\n| 参数 | 简写 | 说明 |\n|-----|-----|------|\n| `--json` | `-j` | JSON 结构化输出（机器可读） |\n| `--sarif` | `-s` | SARIF 2.1.0 格式输出（CI/CD 集成） |\n| `--brief` | `-b` | 最小摘要信息 |\n| `--verbose` | `-v` | 显示所有工具包括低风险项 |\n| `--quiet` | `-q` | 静默模式，不输出状态信息 |\n| `--version` | `-V` | 显示版本号 |\n| `--help` | `-h` | 显示帮助信息 |\n\n资料来源：[AGENTS.md:13-18]()\n\n### 扫描控制参数\n\n| 参数 | 说明 |\n|-----|------|\n| `--no-probe` | 仅扫描配置，不探测服务器 |\n| `--no-advisories` | 跳过网络请求（不查询供应链情报） |\n| `--no-telemetry` | 禁用遥测数据收集 |\n| `--verify` | AI 验证扫描结果 |\n\n资料来源：[AGENTS.md:19-26]()\n\n### 策略控制参数\n\n| 参数 | 说明 |\n|-----|------|\n| `--policy <rules>` | 逗号分隔的策略规则 |\n| `--report` | 上报结果到 Decoy Guard 仪表板 |\n\n策略规则包括：`no-critical`、`no-high`、`no-poisoning`、`no-toxic-flows`、`no-secrets`、`require-tripwires`、`max-critical=N`。\n\n资料来源：[README.md:78-82]()\n\n## 输出格式\n\n### 标准输出\n\n默认情况下，decoy-scan 输出人类可读的彩色终端界面：\n\n```\n▸ Discovering MCP servers…\n▸ Running N checks…\n\n✗ filesystem 2 critical\n  Critical: read_file, write_file\n  High: list_directory\n\n✓ claude-desktop passed\n\nN issues found · N critical, N high · N checks passed · Ns\n```\n\n服务器状态徽章：\n- `✗ name N critical` - 发现严重问题\n- `! name poisoned tool` - 检测到提示注入（洋红色）\n- `? name probe failed` - 服务器探测失败\n- `✓ name passed` - 通过扫描\n\n资料来源：[CHANGELOG.md:12-22]()\n\n### JSON 输出\n\n```bash\ndecoy-scan --json\n```\n\n输出结构：\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null,\n    \"findings\": [{\n      \"type\": \"env-exposure\",\n      \"severity\": \"high\",\n      \"description\": \"...\",\n      \"source\": \"env-config\"\n    }]\n  }],\n  \"summary\": {\n    \"total\": 2, \"critical\": 1, \"high\": 1, \"medium\": 0, \"low\": 0,\n    \"poisoned\": 0, \"toxicFlows\": [], \"status\": \"warn\", \"exitCode\": 1\n  }\n}\n```\n\n资料来源：[AGENTS.md:64-93]()\n\n### SARIF 输出\n\n```bash\ndecoy-scan --sarif\n```\n\n生成符合 SARIF 2.1.0 标准的输出，可直接上传到 GitHub Security 选项卡。\n\n资料来源：[README.md:57-58]()\n\n### Brief 输出\n\n```bash\ndecoy-scan --brief\n```\n\n最小摘要格式：\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"medium\": 4,\n  \"low\": 5,\n  \"poisoned\": 0,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n资料来源：[AGENTS.md:100-116]()\n\n## 退出码\n\n| 退出码 | 含义 |\n|-------|------|\n| `0` | 无 critical 或 high 风险问题 |\n| `1` | 发现 high 风险问题 |\n| `2` | 发现 critical 问题、工具中毒或有毒流 |\n\n退出码在 `--json` 和 `--brief` 输出中通过 `exitCode` 字段暴露，便于自动化脚本处理。\n\n资料来源：[AGENTS.md:45-54]()\n\n## GitHub Action 集成\n\n### 基本配置\n\n在 `.github/workflows/mcp-security.yml` 中添加：\n\n```yaml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n```\n\n资料来源：[README.md:60-71]()\n\n### 完整配置示例\n\n```yaml\n- uses: decoy-run/decoy-scan@v1\n  with:\n    policy: no-critical,no-poisoning,no-toxic-flows\n    sarif: true\n    report: true\n    token: ${{ secrets.DECOY_TOKEN }}\n    verbose: false\n```\n\n| 输入参数 | 默认值 | 说明 |\n|---------|-------|------|\n| `policy` | `no-critical,no-poisoning` | 逗号分隔的策略规则 |\n| `sarif` | `true` | 上传 SARIF 到 GitHub Security |\n| `report` | `false` | 上传到 Decoy Guard 仪表板 |\n| `token` | — | Decoy API 令牌 |\n| `verbose` | `false` | 显示所有工具包括低风险 |\n\n资料来源：[README.md:73-80]()\n\n### GitHub Action 输出\n\nAction 提供以下输出供后续步骤使用：\n\n| 输出 | 说明 |\n|-----|------|\n| `exit-code` | 扫描退出码 |\n| `sarif-file` | SARIF 文件路径 |\n| `summary` | 摘要信息 |\n\n资料来源：[action.yml:45-54]()\n\n## explain 子命令\n\n用于解释扫描发现的含义，无需解析完整输出：\n\n```bash\ndecoy-scan explain critical              # 严重等级\ndecoy-scan explain tool-description       # 发现类别\ndecoy-scan explain prompt-override        # 中毒类型\ndecoy-scan explain read_file             # 工具名称\ndecoy-scan explain list                  # 列出所有可解释目标\ndecoy-scan explain <target> --json       # 结构化输出\n```\n\nJSON 输出示例：\n\n```json\n{\n  \"tool\": \"decoy-scan\",\n  \"version\": \"0.5.1\",\n  \"target\": \"critical\",\n  \"result\": {\n    \"kind\": \"tier\",\n    \"key\": \"critical\",\n    \"title\": \"Critical\",\n    \"summary\": \"Can execute code, modify data, or cause irreversible changes.\",\n    \"body\": \"...\",\n    \"examples\": [\"execute_command\", \"write_file\"],\n    \"advice\": \"...\"\n  }\n}\n```\n\n`result.kind` 可能是：`tier`（等级）、`category`（类别）、`poisoning`（中毒类型）、`tool`（工具）。\n\n资料来源：[AGENTS.md:24-49]()\n\n## 库模式使用\n\ndecoy-scan 也可作为 Node.js 模块导入使用：\n\n```javascript\nimport {\n  scan,\n  toSarif,\n  classifyTool,\n  detectPoisoning,\n  analyzeToxicFlows,\n  hashToolManifest,\n  detectManifestChanges,\n  discoverSkills,\n  analyzeSkill,\n} from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.toxicFlows);    // 有毒流分析结果\nconsole.log(results.skills);        // 技能扫描结果\nconsole.log(results.servers[0].manifestHash);  // \"45c4c571f03c78a2\"\n```\n\n资料来源：[README.md:86-97]()\n\n## 扫描检查项速查\n\n| 检查项 | 检测内容 |\n|-------|---------|\n| 工具风险分类 | 按名称和描述评估风险等级 |\n| 提示注入检测 | 指令覆盖、隐藏、凭证窃取、强制执行、工具影子、规避技术 |\n| 有毒流分析 | 跨服务器数据泄漏（TF001）和破坏性攻击链（TF002） |\n| 清单变更追踪 | 工具增删、描述变更的哈希对比 |\n| 服务器命令 | 管道到 shell、内联代码、typosquatting |\n| 环境暴露 | API 密钥、令牌、数据库 URL、云凭证 |\n| 供应链情报 | 40+ 已知漏洞 MCP 包 |\n| 传输安全 | HTTP 明文、缺失认证、公开 SSE |\n| 输入验证 | 无约束参数、缺失长度限制、开放 schema |\n| 权限范围 | 过度特权、危险能力组合 |\n\n资料来源：[README.md:37-51]()\n\n## 下一步\n\n- 查看 [AGENTS.md](AGENTS.md) 了解机器可读输出的详细 schema\n- 查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何扩展检测模式\n- 查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史\n- 访问 [decoy.run 文档](https://decoy.run/docs/scan/overview) 获取完整文档\n\n---\n\n<a id='cli-usage'></a>\n\n## 命令行工具\n\n### 相关页面\n\n相关主题：[快速开始](#getting-started)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [bin/cli.mjs](https://github.com/decoy-run/decoy-scan/blob/main/bin/cli.mjs)\n- [lib/explain.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/explain.mjs)\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [action.yml](https://github.com/decoy-run/decoy-scan/blob/main/action.yml)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n</details>\n\n# 命令行工具\n\n## 概述\n\ndecoy-scan 提供了一个零依赖的 Node.js CLI 工具，用于扫描 MCP（Model Context Protocol）客户端配置中的安全风险。该命令行工具无需安装配置，下载后即可直接运行，支持对 Claude Desktop、Cursor、Windsurf、VS Code、Claude Code、Zed 和 Cline 等多种 MCP 主机进行安全扫描。\n\nCLI 的核心功能包括：工具风险分类、提示注入检测、有毒数据流分析、工具清单哈希追踪、技能扫描、服务器命令分析、环境变量暴露检测、供应链告警以及 OWASP Agentic Top 10 映射。资料来源：[README.md:1-45]()\n\n## 快速开始\n\n```bash\nnpx decoy-scan                        # 完整扫描\nnpx decoy-scan --json                 # 机器可读输出\nnpx decoy-scan --sarif                # SARIF 2.1.0 格式（用于 CI/CD）\nnpx decoy-scan explain <target>       # 解释风险等级/类别/工具名称\n```\n\n该工具要求 Node.js 18 或更高版本，无需预先安装任何依赖包。资料来源：[CONTRIBUTING.md:1-8]()\n\n## 全局选项\n\n| 选项 | 说明 |\n|------|------|\n| `--verbose`, `-v` | 显示所有工具，包括低风险项 |\n| `--quiet`, `-q` | 抑制状态输出 |\n| `--version`, `-V` | 打印版本号 |\n| `--help`, `-h` | 打印帮助信息 |\n\n### 扫描控制选项\n\n| 选项 | 说明 |\n|------|------|\n| `--no-probe` | 仅扫描配置文件，不探测服务器 |\n| `--no-advisories` | 跳过供应链告警检查（避免网络请求） |\n| `--json` | 输出 JSON 格式结果 |\n| `--sarif` | 输出 SARIF 2.1.0 格式结果 |\n| `--brief` | 仅输出摘要信息（隐含 `--json`） |\n\n### 输出控制选项\n\n| 选项 | 说明 |\n|------|------|\n| `--output <file>` | 将结果写入指定文件 |\n| `--no-telemetry` | 禁用遥测数据收集 |\n| `--report` | 上传结果至 Decoy Guard 仪表板 |\n\n资料来源：[AGENTS.md:1-10]()\n\n## 子命令\n\n### `explain` 子命令\n\n`explain` 子命令用于解析扫描结果的含义，无需解析完整的扫描输出。当 AI agent 看到某个发现并需要结构化上下文来采取行动时，此命令非常有用。\n\n```bash\ndecoy-scan explain critical              # 严重性等级\ndecoy-scan explain tool-description      # 发现类别\ndecoy-scan explain prompt-override       # 投毒类型\ndecoy-scan explain read_file             # 工具名称（运行真实分类规则）\ndecoy-scan explain list                  # 枚举所有可解释的目标\ndecoy-scan explain <target> --json       # 结构化输出（推荐用于 agent）\n```\n\n资料来源：[AGENTS.md:20-35]()\n\n#### `explain` 输出格式\n\n`--json` 输出的 JSON 结构如下：\n\n```json\n{\n  \"tool\": \"decoy-scan\",\n  \"version\": \"0.5.1\",\n  \"target\": \"critical\",\n  \"result\": {\n    \"kind\": \"tier\",\n    \"key\": \"critical\",\n    \"title\": \"Critical\",\n    \"summary\": \"Can execute code, modify data, or cause irreversible changes.\",\n    \"body\": \"...\",\n    \"examples\": [\"execute_command\", \"write_file\", \"...\"],\n    \"advice\": \"...\"\n  }\n}\n```\n\n`result.kind` 的值包括：\n\n| kind 值 | 说明 |\n|---------|------|\n| `tier` | 严重性等级（critical、high、medium、low） |\n| `category` | 发现类别（如 env-exposure、missing-description） |\n| `poisoning` | 投毒类型（如 prompt-override、credential-harvesting） |\n| `tool` | 工具名称（包含 risk、reason、matched 等字段） |\n\n资料来源：[AGENTS.md:36-50]()\n\n## 退出码\n\nCLI 通过退出码向调用者传递扫描结果的状态：\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 未发现严重或高风险问题 |\n| `1` | 发现高风险问题 |\n| `2` | 发现严重问题、工具投毒或有毒数据流 |\n\n退出码也会在 `--json` 和 `--brief` 输出的 `exitCode` 字段中暴露，便于 agent 在不重新解析严重性计数的情况下进行分支判断。资料来源：[AGENTS.md:58-68]()\n\n## 输出格式\n\n### JSON 输出架构\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null,\n    \"findings\": [{\n      \"type\": \"env-exposure\",\n      \"severity\": \"high\",\n      \"description\": \"...\",\n      \"source\": \"env-config\"\n    }]\n  }],\n  \"summary\": {\n    \"total\": 2,\n    \"critical\": 1,\n    \"high\": 2,\n    \"medium\": 4,\n    \"low\": 5,\n    \"poisoned\": 0\n  }\n}\n```\n\n资料来源：[AGENTS.md:75-100]()\n\n### `--brief` 输出架构\n\n`--brief` 隐含 `--json`，输出精简的摘要对象：\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"medium\": 4,\n  \"low\": 5,\n  \"poisoned\": 0,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n| 字段 | 说明 |\n|------|------|\n| `servers` | 扫描的非诱饵、非错误服务器数量 |\n| `critical`、`high`、`medium`、`low` | 各风险等级的工具数量 |\n| `poisoned` | 工具投毒发现数量 |\n| `status` | `pass`（清洁）、`warn`（高风险）或 `fail`（严重/投毒/有毒流） |\n| `exitCode` | 进程退出码 |\n\n资料来源：[AGENTS.md:102-125]()\n\n### SARIF 输出\n\n使用 `--sarif` 选项可生成 SARIF 2.1.0 格式的输出，适用于 GitHub Security 标签页集成：\n\n```bash\ndecoy-scan --sarif\nnpx decoy-scan --sarif | jq\n```\n\n资料来源：[README.md:15-18]()\n\n## 工作流程架构\n\n```mermaid\ngraph TD\n    A[用户执行 decoy-scan] --> B[发现 MCP 服务器配置]\n    B --> C{选项解析}\n    C -->|explain| D[解析 explain 子命令]\n    C -->|scan| E[执行安全扫描]\n    D --> F[查询 RISK_PATTERNS]\n    D --> G[查询 POISONING_PATTERNS]\n    F --> H[返回结构化解释]\n    G --> H\n    E --> I[探测 MCP 服务器]\n    I --> J[获取工具列表]\n    J --> K[执行安全分析]\n    K --> L{发现风险?}\n    L -->|是| M[分类风险等级]\n    L -->|否| N[标记为通过]\n    M --> O[生成扫描报告]\n    N --> O\n    O --> P[根据结果设置退出码]\n```\n\n## 支持的主机\n\ndecoy-scan 支持以下 7 个 MCP 主机：\n\n| 主机 | 平台支持 |\n|------|----------|\n| Claude Desktop | macOS, Windows, Linux |\n| Cursor | macOS, Windows, Linux |\n| Windsurf | macOS, Windows, Linux |\n| VS Code | macOS, Windows, Linux |\n| Claude Code | macOS, Windows, Linux |\n| Zed | macOS, Windows, Linux |\n| Cline | macOS, Windows, Linux |\n\n配置文件路径根据操作系统自动适配（macOS、Windows、Linux）。资料来源：[AGENTS.md:70-73]()\n\n## CI/CD 集成\n\n### GitHub Action\n\ndecoy-scan 提供官方 GitHub Action，可用于 CI/CD 流水线：\n\n```yaml\n# .github/workflows/mcp-security.yml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n```\n\n#### Action 输入参数\n\n| 输入 | 默认值 | 说明 |\n|------|--------|------|\n| `policy` | `no-critical,no-poisoning` | 逗号分隔的策略规则 |\n| `sarif` | `true` | 上传 SARIF 至 GitHub Security 标签页 |\n| `report` | `false` | 上传至 Decoy Guard 仪表板 |\n| `token` | — | Decoy API token（用于 `report`） |\n| `verbose` | `false` | 显示所有工具包括低风险项 |\n\n#### 策略规则\n\n```\nno-critical          严重工具（代码执行、文件写入）导致失败\nno-high              高风险工具（文件读取、网络）导致失败\nno-poisoning         工具描述中的提示注入导致失败\nno-toxic-flows       跨服务器数据泄露/破坏链导致失败\nno-secrets           MCP 配置中暴露的密钥导致失败\nrequire-tripwires    未安装 decoy-tripwire 导致失败\nmax-critical=N       允许的严重问题数量\n```\n\n资料来源：[README.md:75-100]()\n\n### CLI 参数与 GitHub Action 输入的映射\n\n```mermaid\ngraph LR\n    A[CLI 参数] --> B[Action 输入]\n    A1[--json] --> B1[sarif=false, brief=true]\n    A2[--verbose] --> B2[verbose=true]\n    A3[--report] --> B3[report=true]\n    A4[--policy] --> B4[policy]\n    A5[--token] --> B5[token]\n```\n\n## 代码结构\n\nCLI 的核心实现在 `index.mjs` 中，各模块职责如下：\n\n| 模块 | 功能 |\n|------|------|\n| `RISK_PATTERNS` + `classifyTool()` | 基于名称/描述的工具风险分类 |\n| `POISONING_PATTERNS` + `detectPoisoning()` | 工具描述中的提示注入检测 |\n| `analyzeServerCommand()` | 服务器启动命令分析 |\n| `SENSITIVE_ENV_PATTERNS` + `analyzeEnvExposure()` | 环境变量暴露检测 |\n| `analyzeReadiness()` | 生产就绪性启发式检查 |\n| `OWASP_MAP` + `mapToOwasp()` | OWASP Agentic Top 10 映射 |\n| `HOST_CONFIGS` + `discoverConfigs()` | MCP 客户端配置发现 |\n| `probeServer()` | MCP stdio 探测 |\n| `scan()` | 完整扫描编排器 |\n| `toSarif()` | SARIF 输出生成器 |\n\n资料来源：[CONTRIBUTING.md:12-30]()\n\n## 扫描类别详解\n\n### 1. 工具风险分类\n\n根据名称模式和描述分析，将每个工具分类为严重/高/中/低风险。关键风险模式包括代码执行、文件写入、网络调用等。资料来源：[CONTRIBUTING.md:20-22]()\n\n### 2. 工具投毒检测\n\n37 种正则表达式模式横跨 20 个攻击类别，检测隐藏在工具描述中的提示注入，包括指令覆盖、隐藏、数据外泄、凭证窃取、强制执行、工具影子和规避技术。资料来源：[CONTRIBUTING.md:22-24]()\n\n### 3. 服务器命令分析\n\n检查启动命令中的管道到 shell、临时目录、内联代码、域名仿冒和网络工具。资料来源：[CONTRIBUTING.md:24-26]()\n\n### 4. 环境变量暴露\n\n标记 12 类敏感凭证，包括 API 密钥、令牌、密码、数据库 URL 和云凭证。资料来源：[CONTRIBUTING.md:26-28]()\n\n### 5. 生产就绪性\n\n检查缺失描述、缺失模式、无必需字段、过度作用域以及无安全提示的危险工具。资料来源：[CONTRIBUTING.md:28-30]()\n\n### 6. 供应链告警\n\n通过 Decoy 告警数据库交叉引用 40+ 个已知易受攻击的 MCP 包。资料来源：[CONTRIBUTING.md:30-32]()\n\n## 设计原则\n\n- **零依赖**：仅使用 Node.js 内置模块，不添加 npm 包。\n- **无需构建**：纯 ES 模块，无 TypeScript，无打包器。\n- **快速**：扫描应在数秒内完成，积极设置服务器超时。\n- **安全**：从不修改配置，仅读取扫描，遇到问题时立即终止。\n- **面向 Agent**：JSON 和 SARIF 输出必须是机器可解析的。资料来源：[CONTRIBUTING.md:50-57]()\n\n## 手动测试模式\n\n```bash\nnode bin/cli.mjs --no-probe              # 仅配置扫描\nnode bin/cli.mjs --no-advisories         # 跳过网络调用\nnode bin/cli.mjs --json                  # 验证 JSON 结构\nnode bin/cli.mjs --sarif                 # 验证 SARIF 结构\nnode bin/cli.mjs --verbose               # 显示所有输出\n```\n\n资料来源：[CONTRIBUTING.md:45-49]()\n\n## 库导出\n\nCLI 的核心功能也可作为库导入使用：\n\n```javascript\nimport {\n  scan,\n  toSarif,\n  classifyTool,\n  detectPoisoning,\n  analyzeToxicFlows,\n  hashToolManifest,\n  detectManifestChanges,\n  discoverSkills,\n  analyzeSkill,\n} from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.toxicFlows);    // [{ id: \"TF001\", severity: \"critical\", roles: {...} }]\nconsole.log(results.skills);        // [{ name: \"...\", findings: [...] }]\nconsole.log(results.servers[0].manifestHash);  // \"45c4c571f03c78a2\"\n```\n\n资料来源：[README.md:25-40]()\n\n## 遥测数据\n\nCLI 默认收集匿名使用统计信息，可通过以下方式禁用：\n\n- 设置环境变量 `DECOY_TELETELRY=0`\n- 使用 `--no-telemetry` 标志\n\n首次运行会显示遥测通知，并缓存于 `~/.decoy/telemetry-notice-shown`。资料来源：[CHANGELOG.md:2026-05-10]()\n\n## 常见使用场景\n\n| 场景 | 命令 |\n|------|------|\n| 快速扫描 | `npx decoy-scan` |\n| CI 集成 | `npx decoy-scan --sarif --no-advisories` |\n| Agent 集成 | `npx decoy-scan --brief --json` |\n| 了解风险 | `npx decoy-scan explain critical` |\n| 详细输出 | `npx decoy-scan --verbose` |\n| 仅配置检查 | `npx decoy-scan --no-probe` |\n\n资料来源：[README.md:10-25]()\n\n---\n\n<a id='security-checks'></a>\n\n## 安全检查项目\n\n### 相关页面\n\n相关主题：[项目介绍](#project-introduction), [风险分级系统](#risk-classification), [提示注入检测](#prompt-injection-detection)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n</details>\n\n# 安全检查项目\n\ndecoy-scan 是一款针对 MCP (Model Context Protocol) 供应链安全的扫描工具，零依赖，基于 Node.js 18+ 运行。本文档详细说明该工具执行的所有安全检查项目及其检测机制。\n\n## 核心安全检查概览\n\ndecoy-scan 实现了 **12 大安全检查类别**，涵盖从工具风险分类到供应链威胁检测的完整攻击面分析。\n\n| 检查类别 | 检测内容 | 严重级别 |\n|----------|----------|----------|\n| 工具风险分类 | 按名称和描述将工具分为 critical/high/medium/low |\n| 提示词注入检测 | 37 种正则模式覆盖 20 个攻击类别 |\n| 有毒数据流分析 | 跨服务器数据泄露和破坏性攻击链 |\n| 工具清单哈希 | 检测工具新增、移除和描述变更 |\n| 技能扫描 | Claude Code 技能中的注入和敏感信息 |\n| 服务器命令分析 | 管道到 shell、内联代码、域名仿冒等 |\n| 环境变量暴露 | API 密钥、令牌、云凭证等 |\n| 供应链预警 | 40+ 已知漏洞 MCP 包 |\n| 传输安全 | HTTP 无 TLS、缺失认证、公开 SSE |\n| 输入验证 | 无约束参数、缺失 maxLength、开放 schema |\n| 权限范围 | 过度授权服务器、危险能力组合 |\n| OWASP 映射 | 每项发现映射到 ASI01-ASI05 |\n\n资料来源：[README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n\n## 工具风险分类体系\n\n### 风险级别定义\n\n工具风险分类是 decoy-scan 的核心检测引擎，通过 `RISK_PATTERNS` 和 `classifyTool()` 函数实现。\n\n```mermaid\ngraph TD\n    A[工具输入] --> B{名称模式匹配}\n    B -->|^execute.*| C[Critical 级别]\n    B -->|^read.*|^write.*| D[High 级别]\n    B -->|^list.*|^search.*| E[Medium 级别]\n    B -->|其他| F[Low 级别]\n    C --> G[可执行代码、修改数据、不可逆变更]\n    D --> H[文件读写、网络访问]\n    E --> I[信息列举]\n    F --> J[安全工具]\n```\n\n资料来源：[CONTRIBUTING.md:1-9]()\n\n### Critical 级别工具模式\n\n以下工具名称模式被直接判定为 **critical** 风险：\n\n| 正则模式 | 匹配示例 | 风险说明 |\n|----------|----------|----------|\n| `^execute[_-]?(script\\|code\\|js\\|javascript\\|python\\|sql)$` | `execute_code`, `execute_python` | 可执行任意代码 |\n| `^evaluate[_-]?(script\\|code)$` | `evaluate_script` | 脚本评估执行 |\n| `^run[_-]?(script\\|code\\|js\\|python\\|sql)$` | `run_javascript` | 代码运行 |\n| `^eval[_-]?(script\\|code)$` | `eval_code` | 直接代码执行 |\n| `^write[_-]?file$` | `write_file` | 文件写入 |\n| `^spawn[_-]?process$` | `spawn_process` | 进程生成 |\n\n资料来源：[CHANGELOG.md:1-20]()\n\n### 分类算法改进\n\n在 v0.5.6 版本中修复了此前版本存在的边界问题：之前版本对每个名称模式都使用了锚点 `^`，导致带有后缀的代码执行名称（如 `evaluate_script`、`execute_python`）被错误分类为 \"low\"。\n\n改进措施包括：\n\n1. 添加了完整的带后缀代码执行模式到 critical 层级\n2. 子串回退机制现在同时对**小写化的名称**运行，使 `evaluate`、`spawn`、`fetch` 等危险动词即使没有提供描述也能正确分类\n\n资料来源：[CHANGELOG.md:1-20]()\n\n## 提示词注入检测\n\n### 攻击类别体系\n\n提示词注入检测通过 `POISONING_PATTERNS` 和 `detectPoisoning()` 函数实现，包含 **37 种正则模式**覆盖 **20 个攻击类别**。\n\n```mermaid\ngraph TD\n    A[工具描述文本] --> B{Poisoning Pattern 匹配}\n    B -->|指令覆盖| C[instruction-override]\n    B -->|隐匿| D[concealment]\n    B -->|数据泄露| E[data-exfiltration]\n    B -->|凭证窃取| F[credential-harvesting]\n    B -->|强制执行| G[coercive-execution]\n    B -->|工具影子| H[tool-shadowing]\n    B -->|规避技术| I[evasion-techniques]\n    C --> J[Critical/High 级别发现]\n    D --> J\n    E --> J\n    F --> J\n    G --> J\n    H --> J\n    I --> J\n```\n\n### 检测模式结构\n\n每个 poisoning 检测模式包含以下字段：\n\n```javascript\n{\n  pattern: /regex/i,           // 匹配规则\n  type: \"category-name\",       // 发现类型（用于 OWASP 映射）\n  severity: \"critical\",        // critical/high/medium/low\n  description: \"Human-readable\" // 人类可读说明\n}\n```\n\n资料来源：[CONTRIBUTING.md:1-20]()\n\n### OWASP Agentic Top 10 映射\n\n所有提示词注入检测结果都会映射到 OWASP Agentic Top 10 for 2026 标准，通过 `OWASP_MAP` 和 `mapToOwasp()` 函数实现。\n\n| 发现类型 | OWASP 映射 | 严重级别 |\n|----------|------------|----------|\n| instruction-override | ASI01 | Critical |\n| credential-harvesting | ASI02 | Critical |\n| data-exfiltration | ASI03 | High |\n| tool-shadowing | ASI04 | High |\n| coercive-execution | ASI05 | Medium |\n\n## 有毒数据流分析\n\n### 攻击链检测\n\n有毒数据流分析检测跨服务器的数据泄露和破坏性攻击链。\n\n```mermaid\ngraph LR\n    A[服务器 A] -->|敏感数据流| B[服务器 B]\n    B -->|外部通信| C[攻击者控制端点]\n    D[服务器 X] -->|破坏操作| E[系统资源]\n    \n    subgraph TF001[数据泄露攻击链]\n        A\n        B\n        C\n    end\n    \n    subgraph TF002[破坏性攻击链]\n        D\n        E\n    end\n```\n\n### 攻击链类型\n\n| ID | 类型 | 说明 |\n|----|------|------|\n| TF001 | 数据泄露 | 跨服务器敏感数据流向外部 |\n| TF002 | 破坏性攻击 | 跨服务器破坏操作链 |\n\n资料来源：[README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n\n## 服务器命令分析\n\n### 检测能力\n\n`analyzeServerCommand()` 函数分析 MCP 服务器的启动命令，检测以下可疑特征：\n\n| 检测类型 | 特征 | 风险 |\n|----------|------|------|\n| 管道到 shell | `| bash`, `| sh` | 命令注入 |\n| 临时目录执行 | `/tmp/`, `/var/tmp/` | 持久化攻击 |\n| 内联代码 | `node -e \"...\"`, `python -c \"...\"` | 混淆执行 |\n| 域名仿冒 | 相似拼写的包名 | typosquatting |\n| 网络工具 | `curl`, `wget`, `nc` | 外部通信 |\n\n资料来源：[CONTRIBUTING.md:1-9]()\n\n## 环境变量暴露检测\n\n### 敏感信息模式\n\n`SENSITIVE_ENV_PATTERNS` 和 `analyzeEnvExposure()` 函数检测 12 类敏感环境变量暴露：\n\n```mermaid\ngraph TD\n    A[MCP 配置] --> B{环境变量分析}\n    B -->|API 密钥| C[API_KEY, OPENAI_API_KEY]\n    B -->|令牌| D[AWS_SECRET, GITHUB_TOKEN]\n    B -->|密码| E[DB_PASSWORD, MYSQL_PWD]\n    B -->|数据库 URL| F[DATABASE_URL]\n    B -->|云凭证| G[AWS_ACCESS_KEY, AZURE_KEY]\n    B -->|其他| H[12 类总计]\n    C --> I[High 级别发现]\n    D --> I\n    E --> I\n    F --> I\n    G --> I\n```\n\n### 暴露类别\n\n| 类别 | 模式示例 | 严重级别 |\n|------|----------|----------|\n| API 密钥 | `*_API_KEY`, `*_SECRET_KEY` | High |\n| 访问令牌 | `*_TOKEN`, `*_ACCESS_TOKEN` | High |\n| 数据库凭证 | `*_PASSWORD`, `*_CREDENTIALS` | Critical |\n| 云服务密钥 | `AWS_*`, `AZURE_*`, `GCP_*` | Critical |\n\n## 生产就绪性检查\n\n### 检查项目\n\n`analyzeReadiness()` 函数实现以下生产就绪性检查：\n\n| 检查项 | 条件 | 严重级别 |\n|--------|------|----------|\n| 缺失描述 | 工具缺少 description 字段 | Medium |\n| 缺失 schema | 工具缺少 inputSchema | Medium |\n| 无必需字段 | 关键参数缺少 required 声明 | Medium |\n| 过度授权 | 权限范围过大 | High |\n| 破坏性工具无安全提示 | 危险操作无 confirm 参数 | Medium |\n\n资料来源：[CONTRIBUTING.md:1-20]()\n\n## 工具清单变更追踪\n\n### 哈希机制\n\ndecoy-scan 通过 `hashToolManifest()` 和 `detectManifestChanges()` 函数追踪工具清单变更：\n\n```mermaid\ngraph LR\n    A[首次扫描] -->|生成哈希| B[工具清单哈希]\n    C[后续扫描] -->|生成哈希| D[工具清单哈希]\n    B --> E{哈希比对}\n    D --> E\n    E -->|哈希变化| F[变更检测]\n    E -->|哈希相同| G[无变更]\n    F --> H[报告变更详情]\n```\n\n### 检测变更类型\n\n| 变更类型 | 说明 |\n|----------|------|\n| 工具新增 | 新增的工具可能引入风险 |\n| 工具移除 | 移除的工具有安全盲区 |\n| 描述变更 | 描述修改可能隐藏恶意行为 |\n\n## 供应链预警集成\n\n### 预警数据库\n\ndecoy-scan 通过供应链预警功能交叉引用 **Decoy 预警数据库**，覆盖 40+ 已知存在漏洞的 MCP 包：\n\n```mermaid\ngraph TD\n    A[扫描的 MCP 包] --> B{Decoy 预警数据库}\n    B -->|已知漏洞| C[高风险警告]\n    B -->|未知| D[通过扫描]\n    C --> E[提供修复建议]\n```\n\n### 检查方式\n\n预警检查默认启用，可通过以下方式跳过：\n\n```bash\nnpx decoy-scan --no-advisories  # 跳过网络调用\n```\n\n## 退出码与状态\n\n### 退出码定义\n\n| 退出码 | 含义 | 触发条件 |\n|--------|------|----------|\n| 0 | 通过 | 无 critical 或 high 风险问题 |\n| 1 | 警告 | 发现 high 风险问题 |\n| 2 | 失败 | 发现 critical 问题、工具投毒或有毒数据流 |\n\n### `--brief` 输出状态\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"medium\": 4,\n  \"low\": 5,\n  \"poisoned\": 0,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n| 状态值 | 含义 |\n|--------|------|\n| `pass` | 清洁无问题 |\n| `warn` | 存在 high 风险 |\n| `fail` | 存在 critical/poisoned/toxic-flows |\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 输出格式\n\n### 支持的输出格式\n\n| 格式 | 用途 | 使用场景 |\n|------|------|----------|\n| 人类可读 | 默认输出 | 终端查看 |\n| `--json` | 机器可读输出 | CI/CD 集成、代理消费 |\n| `--sarif` | SARIF 2.1.0 | GitHub Security 标签 |\n| `--brief` | 摘要输出 | 快速状态检查 |\n\n### JSON 输出结构\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null,\n    \"findings\": [{\n      \"type\": \"env-exposure\",\n      \"severity\": \"high\",\n      \"description\": \"...\",\n      \"source\": \"env-config\"\n    }]\n  }],\n  \"summary\": {\n    \"total\": 2,\n    \"critical\": 1,\n    \"high\": 1,\n    \"medium\": 0,\n    \"low\": 0\n  }\n}\n```\n\n## 架构组件\n\n### 核心模块结构\n\n| 模块 | 职责 | 文件位置 |\n|------|------|----------|\n| `RISK_PATTERNS` | 工具风险分类正则 | index.mjs |\n| `POISONING_PATTERNS` | 提示词注入检测正则 | index.mjs |\n| `SENSITIVE_ENV_PATTERNS` | 环境变量暴露模式 | index.mjs |\n| `OWASP_MAP` | OWASP 映射表 | index.mjs |\n| `HOST_CONFIGS` | MCP 客户端配置发现 | index.mjs |\n| `classifyTool()` | 工具风险分类函数 | index.mjs |\n| `detectPoisoning()` | 投毒检测函数 | index.mjs |\n| `analyzeServerCommand()` | 服务器命令分析 | index.mjs |\n| `analyzeEnvExposure()` | 环境变量暴露分析 | index.mjs |\n| `analyzeReadiness()` | 生产就绪性检查 | index.mjs |\n| `probeServer()` | MCP stdio 探测 | index.mjs |\n| `scan()` | 完整扫描编排 | index.mjs |\n| `toSarif()` | SARIF 输出生成 | index.mjs |\n\n资料来源：[CONTRIBUTING.md:1-15]()\n\n### 扫描流程\n\n```mermaid\ngraph TD\n    A[启动扫描] --> B[发现 MCP 服务器]\n    B --> C[探测服务器工具列表]\n    C --> D[工具风险分类]\n    C --> E[提示词注入检测]\n    C --> F[服务器命令分析]\n    C --> G[环境变量暴露检测]\n    C --> H[生产就绪性检查]\n    D --> I[汇总发现]\n    E --> I\n    F --> I\n    G --> I\n    H --> I\n    I --> J[输出报告]\n    J --> K{退出码判定}\n    K -->|0| L[无问题]\n    K -->|1| M[High 风险]\n    K -->|2| N[Critical/投毒]\n```\n\n## 设计原则\n\ndecoy-scan 的安全检查遵循以下核心设计原则：\n\n1. **零依赖** — 仅使用 Node.js 内置模块，不引入外部包\n2. **零构建** — 原始 ES 模块，无需 TypeScript 或打包工具\n3. **快速** — 扫描应在秒级完成，激进地设置超时\n4. **安全** — 只读扫描，不修改配置，及时终止派生的服务器进程\n5. **代理优先** — JSON 和 SARIF 输出必须机器可解析\n\n资料来源：[CONTRIBUTING.md:1-5]()\n\n## 扩展检测能力\n\n### 添加新的投毒检测模式\n\n在 `POISONING_PATTERNS` 中添加新模式：\n\n```javascript\n{\n  pattern: /new-suspicious-pattern/i,\n  type: \"new-category-name\",\n  severity: \"high\",\n  description: \"Human-readable description\"\n}\n```\n\n添加后需在 `OWASP_MAP` 中注册（如果适用）。\n\n### 添加新的就绪性检查\n\n在 `analyzeReadiness()` 函数中添加：\n\n```javascript\nif (/* condition */) {\n  findings.push({\n    type: \"readiness-check-name\",\n    severity: \"medium\",\n    description: \"What's wrong and why it matters\"\n  });\n}\n```\n\n### 添加新的主机支持\n\n在 `HOST_CONFIGS` 中添加新客户端配置：\n\n```javascript\n\"New Client\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"config.json\");\n}\n```\n\n## 相关文档\n\n- [CLI 使用指南](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md) — 完整的命令行接口文档\n- [贡献指南](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md) — 如何添加新的检测模式\n- [OWASP Agentic Top 10 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) — 安全检查的威胁模型基础\n\n---\n\n<a id='risk-classification'></a>\n\n## 风险分级系统\n\n### 相关页面\n\n相关主题：[安全检查项目](#security-checks), [扫描架构](#scanning-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [lib/tier.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/tier.mjs)\n- [lib/owasp.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/owasp.mjs)\n- [lib/constants.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/constants.mjs)\n</details>\n\n# 风险分级系统\n\ndecoy-scan 的风险分级系统是 MCP 安全扫描的核心组件，负责对 MCP 服务器中的工具进行分类、评级和映射。该系统通过多层检测机制，识别工具的风险等级，并将所有发现映射到行业标准 OWASP Agentic Top 10。\n\n## 系统概述\n\n风险分级系统位于 `index.mjs` 主模块中，核心由以下组件构成：\n\n| 组件 | 位置 | 功能描述 |\n|------|------|----------|\n| `RISK_PATTERNS` | index.mjs | 工具风险模式正则表达式集合 |\n| `classifyTool()` | index.mjs | 工具风险分类核心函数 |\n| `POISONING_PATTERNS` | index.mjs | 提示注入检测模式 |\n| `detectPoisoning()` | index.mjs | 提示注入检测函数 |\n| `OWASP_MAP` | index.mjs | OWASP 映射配置 |\n| `mapToOwasp()` | index.mjs | OWASP 映射转换函数 |\n\n资料来源：[CONTRIBUTING.md:代码结构表]()\n\n## 风险等级架构\n\n系统采用四级风险分类体系，每个等级对应不同的安全影响和处置策略。\n\n### 风险等级定义\n\n| 等级 | 严重性 | 影响范围 | 示例工具 |\n|------|--------|----------|----------|\n| Critical | 关键 | 可执行代码、修改数据、不可逆变更 | execute_command, write_file, eval_code |\n| High | 高 | 文件读取、网络访问、数据外泄风险 | read_file, fetch, spawn |\n| Medium | 中 | 中等权限操作、需关注配置 | write_config, create_resource |\n| Low | 低 | 有限权限、安全风险较低 | read_info, list_items |\n\nCritical 等级工具包括代码执行、文件写入等可能造成不可逆影响的操作。High 等级涵盖文件读取和网络访问等存在数据泄露风险的工具。\n\n资料来源：[AGENTS.md:Exit Codes]()、[index.mjs:RISK_PATTERNS]()\n\n### 分类算法流程\n\n```mermaid\ngraph TD\n    A[工具输入] --> B[提取工具名称]\n    B --> C{名称匹配 Critical 模式}\n    C -->|匹配| D[返回 Critical]\n    C -->|未匹配| E{名称匹配 High 模式}\n    E -->|匹配| F[返回 High]\n    E -->|未匹配| G{名称匹配 Medium 模式}\n    G -->|匹配| H[返回 Medium]\n    G -->|未匹配| I{名称包含高风险关键词}\n    I -->|匹配| J[返回 High]\n    I -->|未匹配| K{描述分析}\n    K --> L{关键词匹配}\n    L -->|匹配| M[返回对应等级]\n    L -->|未匹配| N[返回 Low]\n    \n    style D fill:#ff6b6b\n    style F fill:#ffa500\n    style H fill:#ffd93d\n    style N fill:#6bcb77\n```\n\n`classifyTool()` 函数首先检查工具名称是否匹配预定义的正则表达式模式，若未匹配则回退到描述分析。\n\n资料来源：[CONTRIBUTING.md:RISK_PATTERNS + classifyTool()]()\n\n## 工具名称模式匹配\n\n系统通过 `RISK_PATTERNS` 定义的正则表达式对工具名称进行精确匹配。\n\n### Critical 等级模式\n\n| 模式 | 匹配示例 | 说明 |\n|------|----------|------|\n| `^execute_command$` | execute_command | 命令执行 |\n| `^run_.*` | run_script, run_sql | 带前缀的运行命令 |\n| `^exec_.*` | exec_shell, exec_python | exec 前缀执行 |\n| `^eval[_-]?(script\\|code)$` | eval_script, eval-code | 脚本/代码评估 |\n| `^evaluate[_-]?(script\\|code)$` | evaluate_script | 脚本评估 |\n| `^execute[_-]?(script\\|code\\|js\\|python\\|sql)$` | execute_python, execute_js | 多语言执行 |\n| `^run[_-]?(script\\|code\\|js\\|python\\|sql)$` | run_javascript, run_sql | 多语言运行 |\n\nv0.5.4 版本修复了后缀代码执行名称漏检问题，将正则模式从锚定匹配改为灵活匹配。\n\n资料来源：[CHANGELOG.md:v0.5.4 Fixed]()\n\n### 描述回退机制\n\n当工具名称未匹配任何模式时，`classifyTool()` 会将工具名称小写后进行子字符串匹配，作为回退策略。\n\n```mermaid\ngraph LR\n    A[名称未匹配] --> B[转小写]\n    B --> C{子字符串匹配}\n    C -->|eval| D[可能 High]\n    C -->|spawn| E[可能 High]\n    C -->|fetch| F[可能 High]\n    C -->|无匹配| G[低风险关键词分析]\n```\n\n这一机制确保即使工具名称不符合标准命名约定，只要包含高风险动词也能被正确分类。\n\n## OWASP Agentic Top 10 映射\n\n系统通过 `OWASP_MAP` 将所有发现映射到 OWASP Agentic Top 10 标准。\n\n### 映射配置结构\n\n```javascript\nOWASP_MAP = {\n  \"type-name-1\": \"ASI01\",\n  \"type-name-2\": \"ASI02\",\n  // ...\n}\n```\n\n每个 `POISONING_PATTERNS` 条目的 `type` 字段值会关联到对应的 OWASP 分类标准。\n\n资料来源：[CONTRIBUTING.md:OWASP_MAP + mapToOwasp()]()\n\n### ASI01–ASI05 映射范围\n\n| OWASP 标准 | 映射类型 | 检测内容 |\n|------------|----------|----------|\n| ASI01 | 提示注入相关 | 指令覆盖、隐藏注入 |\n| ASI02 | 凭证窃取相关 | API 密钥、令牌暴露 |\n| ASI03 | 数据外泄相关 | 敏感数据访问 |\n| ASI04 | 权限提升相关 | 过度权限配置 |\n| ASI05 | 工具影子供给 | 恶意工具替换 |\n\n所有发现都会通过 `mapToOwasp()` 函数转换为其对应的 OWASP 分类。\n\n## 提示注入检测模式\n\n`POISONING_PATTERNS` 包含 37 个正则表达式模式，分布在 20 个攻击类别中。\n\n### 攻击类别分类\n\n| 类别 | 严重性 | 描述 |\n|------|--------|------|\n| instruction-override | critical | 指令覆盖攻击 |\n| concealment | critical | 隐藏指令 |\n| credential-harvesting | critical | 凭证收割 |\n| data-exfiltration | critical | 数据外泄 |\n| coercive-execution | high | 强制执行 |\n| tool-shadowing | high | 工具影子 |\n| evasion-techniques | medium | 规避技术 |\n\n每个模式定义包含 `pattern`（正则表达式）、`type`（分类类型）、`severity`（严重等级）和 `description`（描述文本）。\n\n资料来源：[CONTRIBUTING.md:POISONING_PATTERNS]()\n\n### 检测函数工作流程\n\n```mermaid\ngraph TD\n    A[工具描述文本] --> B[遍历 POISONING_PATTERNS]\n    B --> C{正则匹配}\n    C -->|匹配| D[生成 poisoning 发现]\n    C -->|未匹配| E{继续下一模式}\n    E --> B\n    D --> F[聚合同一工具的所有发现]\n    F --> G[返回发现列表]\n    \n    style A fill:#e3f2fd\n    style D fill:#ffcdd2\n    style G fill:#c8e6c9\n```\n\n## 退出码与状态映射\n\n风险分级直接影响程序退出码和扫描状态。\n\n### 退出码定义\n\n| 退出码 | 触发条件 | status 值 |\n|--------|----------|-----------|\n| 0 | 无 critical 或 high 风险问题 | pass |\n| 1 | 发现 high 风险问题 | warn |\n| 2 | 发现 critical 问题、工具中毒或毒性数据流 | fail |\n\n`--json` 和 `--brief` 输出中都包含 `exitCode` 字段，便于程序化处理。\n\n资料来源：[AGENTS.md:Exit Codes]()\n\n### 状态计算逻辑\n\n```mermaid\ngraph TD\n    A[扫描结果] --> B{critical 计数 > 0?}\n    B -->|是| C[status = fail, exitCode = 2]\n    B -->|否| D{poisoned 计数 > 0?}\n    D -->|是| C\n    D -->|否| E{toxicFlows 计数 > 0?}\n    E -->|是| C\n    E -->|否| F{high 计数 > 0?}\n    F -->|是| G[status = warn, exitCode = 1]\n    F -->|否| H[status = pass, exitCode = 0]\n    \n    style C fill:#ff6b6b\n    style G fill:#ffa500\n    style H fill:#6bcb77\n```\n\n## 策略门控\n\n通过命令行 `--policy` 参数可以配置策略规则。\n\n| 策略规则 | 失败条件 |\n|----------|----------|\n| `no-critical` | 存在 critical 工具 |\n| `no-high` | 存在 high 工具 |\n| `no-poisoning` | 检测到提示注入 |\n| `no-toxic-flows` | 存在毒性数据流 |\n| `no-secrets` | 配置中存在暴露的密钥 |\n| `require-tripwires` | 未安装 decoy-tripwire |\n\n策略规则在 CI/CD 环境中用于自动化安全门控。\n\n## explain 子命令\n\n`decoy-scan explain` 提供风险分级的交互式解释功能。\n\n### 支持的查询类型\n\n| kind | 说明 | 示例 |\n|------|------|------|\n| tier | 严重等级 | `explain critical` |\n| category | 发现类别 | `explain tool-description` |\n| poisoning | 中毒类型 | `explain prompt-override` |\n| tool | 工具名称 | `explain read_file` |\n\n`explain` 解析器使用与扫描器相同的 `RISK_PATTERNS` 和 `POISONING_PATTERNS` 数据源，确保解释与实际检测结果一致。\n\n资料来源：[AGENTS.md:explain subcommand]()\n\n### JSON 输出结构\n\n```json\n{\n  \"tool\": \"decoy-scan\",\n  \"version\": \"0.5.1\",\n  \"target\": \"critical\",\n  \"result\": {\n    \"kind\": \"tier\",\n    \"key\": \"critical\",\n    \"title\": \"Critical\",\n    \"summary\": \"Can execute code, modify data, or cause irreversible changes.\",\n    \"body\": \"...\",\n    \"examples\": [\"execute_command\", \"write_file\", \"...\"],\n    \"advice\": \"...\"\n  }\n}\n```\n\n## 库导出接口\n\ndecoy-scan 作为库使用时可直接导入分类功能：\n\n```javascript\nimport {\n  classifyTool,\n  detectPoisoning,\n  mapToOwasp,\n} from 'decoy-scan';\n\nconst risk = classifyTool({ name: \"read_file\", description: \"...\" });\nconst poisoningFindings = detectPoisoning(toolDescription);\nconst owaspCategory = mapToOwasp(findingType);\n```\n\n这使得其他安全工具可以复用 decoy-scan 的风险分级能力。\n\n资料来源：[README.md:Library]()\n\n## 版本演进\n\n| 版本 | 重要变更 |\n|------|----------|\n| v0.1.0 | 初始发布，基础风险分类 |\n| v0.5.4 | 修复后缀代码执行名称漏检，子字符串回退增强 |\n| v0.5.6 | 增强对 evaluate_script、eval_code 等工具的检测 |\n\nCHANGELOG.md 记录了风险分级系统的所有重要变更。\n\n---\n\n<a id='prompt-injection-detection'></a>\n\n## 提示注入检测\n\n### 相关页面\n\n相关主题：[安全检查项目](#security-checks), [有毒数据流分析](#toxic-flow-analysis)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [lib/patterns.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/patterns.mjs)\n- [lib/analyzers.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/analyzers.mjs)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n</details>\n\n# 提示注入检测\n\n## 概述\n\n提示注入检测（Prompt Injection Detection）是 decoy-scan 工具的核心安全功能之一，旨在识别 MCP（Model Context Protocol）服务器工具描述中隐藏的恶意提示注入攻击。该功能通过正则表达式模式匹配技术，分析工具的名称和描述文本，检测 37 种不同的攻击模式，覆盖 20 个攻击类别。\n\n主要职责包括：\n\n- 在工具描述中识别隐藏的指令覆盖攻击\n- 检测伪装和隐蔽性攻击\n- 发现数据泄露和凭证收集企图\n- 识别强制执行和工具影子供给\n- 映射攻击类型至 OWASP Agentic Top 10 标准\n\n资料来源：[README.md:47]()\n\n## 架构设计\n\n### 整体架构\n\n提示注入检测系统位于扫描流程的核心位置，与工具风险分类、毒性流分析和 OWASP 映射等功能紧密协作。\n\n```mermaid\ngraph TD\n    A[MCP Server 工具列表] --> B[detectPoisoning 检测器]\n    B --> C{匹配结果}\n    C -->|有匹配| D[生成 Poisoning Finding]\n    C -->|无匹配| E[标记为安全]\n    D --> F[OWASP 映射]\n    F --> G[风险报告输出]\n    E --> G\n    B --> H[explain 子命令]\n    H --> I[结构化解释 JSON]\n```\n\n### 核心模块关系\n\n| 模块 | 文件位置 | 职责 |\n|------|----------|------|\n| `POISONING_PATTERNS` | `index.mjs` / `lib/patterns.mjs` | 定义所有检测正则表达式模式 |\n| `detectPoisoning()` | `index.mjs` / `lib/analyzers.mjs` | 执行模式匹配和分析逻辑 |\n| `OWASP_MAP` | `index.mjs` | 将攻击类型映射至 OWASP 标准 |\n| `explain` 子命令 | `bin/cli.mjs` | 提供人可读和机器可解析的解释 |\n\n资料来源：[CONTRIBUTING.md:23]()\n\n## 检测模式体系\n\n### 攻击类别总览\n\ndecoy-scan 采用分层分类体系组织检测模式，每个模式包含正则表达式、攻击类型、严重等级和人类可读的描述。\n\n```javascript\n{\n  pattern: /regex/i,           // 正则匹配表达式\n  type: \"category-name\",       // 攻击类型标识\n  severity: \"critical\",        // 严重等级\n  description: \"人类可读描述\"   // 输出展示\n}\n```\n\n资料来源：[CONTRIBUTING.md:42-47]()\n\n### 支持的攻击类别\n\n系统支持检测以下 20 个攻击类别的提示注入模式：\n\n| 类别 | 描述 | 严重等级示例 |\n|------|------|--------------|\n| `instruction-override` | 指令覆盖攻击 | critical |\n| `concealment` | 伪装攻击 | critical/high |\n| `data-exfiltration` | 数据泄露 | critical |\n| `credential-harvesting` | 凭证收集 | critical |\n| `coercive-execution` | 强制执行 | high |\n| `tool-shadowing` | 工具影子 | high |\n| `evasion-techniques` | 规避技术 | medium/high |\n| 其他 13 个类别 | 各类隐蔽攻击 | varying |\n\n资料来源：[README.md:47]()\n\n### 严重等级定义\n\n| 等级 | 含义 | 退出码影响 |\n|------|------|-----------|\n| `critical` | 可执行代码、修改数据或造成不可逆变更 | 退出码 2 |\n| `high` | 高风险操作如文件读取、网络访问 | 退出码 1 |\n| `medium` | 中等风险，需关注 | 无退出码影响 |\n| `low` | 低风险操作 | 无退出码影响 |\n\n资料来源：[AGENTS.md:43-47]()\n\n## 工作流程\n\n### 扫描执行流程\n\n```mermaid\nsequenceDiagram\n    participant Scanner as 扫描器\n    participant Pattern as POISONING_PATTERNS\n    participant Analyzer as 检测引擎\n    participant OWASP as OWASP_MAP\n    participant Output as 输出系统\n\n    Scanner->>Scanner: 发现 MCP 服务器\n    Scanner->>Scanner: 获取工具列表\n    Loop 每个工具\n        Scanner->>Analyzer: 传入工具名称和描述\n        Analyzer->>Pattern: 遍历正则模式\n        Pattern-->>Analyzer: 匹配结果\n        Analyzer->>Analyzer: 分类严重等级\n        Analyzer->>OWASP: 映射攻击类型\n        OWASP-->>Analyzer: ASI 代码\n    end\n    Analyzer-->>Scanner: 检测结果\n    Scanner->>Output: 生成报告\n```\n\n### 输出格式\n\n#### 工具级别输出\n\n每个被检测为存在提示注入的工具包含以下字段：\n\n```json\n{\n  \"name\": \"tool-name\",\n  \"risk\": \"critical\",\n  \"poisoning\": [{\n    \"type\": \"instruction-override\",\n    \"severity\": \"critical\",\n    \"description\": \"发现指令覆盖攻击模式\"\n  }]\n}\n```\n\n#### JSON 完整输出\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"tools\": [{\n      \"name\": \"tool-name\",\n      \"description\": \"...\",\n      \"risk\": \"critical\",\n      \"poisoning\": [...]\n    }]\n  }],\n  \"summary\": {\n    \"poisoned\": 0\n  }\n}\n```\n\n资料来源：[AGENTS.md:59-74]()\n\n## API 与接口\n\n### 库函数导出\n\ndecoy-scan 提供独立的 JavaScript 模块接口，可供其他项目导入使用：\n\n```javascript\nimport {\n  scan,\n  detectPoisoning,\n  classifyTool,\n  analyzeToxicFlows,\n} from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.servers[0].tools[0].poisoning);\n```\n\n### detectPoisoning 函数签名\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `toolName` | string | 工具名称 |\n| `toolDescription` | string | 工具描述文本 |\n| 返回值 | array | 匹配到的 poisoning 对象数组 |\n\n### explain 子命令\n\n用于解析特定发现含义的辅助命令：\n\n```bash\ndecoy-scan explain prompt-override       # 攻击类型说明\ndecoy-scan explain list                  # 列举所有可解释目标\ndecoy-scan explain <target> --json       # 机器可读输出\n```\n\n#### --json 输出结构\n\n```json\n{\n  \"tool\": \"decoy-scan\",\n  \"version\": \"0.5.1\",\n  \"target\": \"instruction-override\",\n  \"result\": {\n    \"kind\": \"poisoning\",\n    \"key\": \"instruction-override\",\n    \"title\": \"指令覆盖\",\n    \"summary\": \"攻击者尝试覆盖原始指令\",\n    \"examples\": [\"...具体示例...\"],\n    \"advice\": \"建议修复措施\"\n  }\n}\n```\n\n资料来源：[AGENTS.md:29-41]()\n\n## 配置与扩展\n\n### 添加新的检测模式\n\n在 `POISONING_PATTERNS` 中添加新模式：\n\n```javascript\n{\n  pattern: /new-malicious-pattern/i,\n  type: \"new-attack-category\",\n  severity: \"high\",\n  description: \"新攻击类型的描述\"\n}\n```\n\n添加后需将 `type` 值注册到 `OWASP_MAP` 中：\n\n```javascript\nconst OWASP_MAP = {\n  // ... 现有映射\n  \"new-attack-category\": \"ASI01\",\n};\n```\n\n资料来源：[CONTRIBUTING.md:35-41]()\n\n### OWASP Agentic Top 10 映射\n\n所有攻击类型均映射至 OWASP Agentic Top 10 标准，便于安全合规报告：\n\n| OWASP 代码 | 攻击类型 |\n|-----------|---------|\n| ASI01 | Agentic 系统提示注入 |\n| ASI02 | 敏感信息泄露 |\n| ASI03 | 工具操作验证不足 |\n| ASI04 | 供应链攻击 |\n| ASI05 | 权限过度授予 |\n\n资料来源：[README.md:56]()\n\n## 输出与报告\n\n### 退出码机制\n\n提示注入检测结果直接影响命令退出码：\n\n| 退出码 | 触发条件 |\n|--------|----------|\n| `0` | 无 critical 或 high 风险问题 |\n| `1` | 发现 high 风险问题 |\n| `2` | 发现 critical 问题、工具污染或毒性流 |\n\n### --brief 摘要输出\n\n最小化摘要对象：\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"poisoned\": 0,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n### SARIF 格式支持\n\n支持 SARIF 2.1.0 标准输出，可上传至 GitHub Security：\n\n```bash\ndecoy-scan --sarif\n```\n\n### 毒性流分析\n\n除了单工具检测外，系统还支持跨服务器数据泄露（TF001）和破坏性（TF002）攻击链分析：\n\n```javascript\nimport { analyzeToxicFlows } from 'decoy-scan';\n\nconst results = await scan();\nconsole.log(results.toxicFlows);\n```\n\n资料来源：[README.md:66-68]()\n\n## 版本变更历史\n\n### 关键版本更新\n\n| 版本 | 日期 | 变更内容 |\n|------|------|---------|\n| 0.1.0 | 2026-03-15 | 初始发布，支持基础提示注入检测 |\n| 0.2.0 | 2026-03-20 | 添加 SSE 传输安全检查和输入验证 |\n| 0.5.0 | 2026-04-21 | 新增 explain 子命令，改进分类逻辑 |\n| 0.5.6 | 2026-04-28 | 修复 classifyTool 对代码执行名称的遗漏 |\n| 0.7.0 | 2026-05-10 | 增强遥测功能，完善 v2 事件信封 |\n\n资料来源：[CHANGELOG.md:1-100]()\n\n## 设计原则\n\n### 零依赖原则\n\n检测引擎完全基于 Node.js 原生能力实现，无外部 npm 依赖：\n\n- 仅使用内置 `RegExp` 模块进行模式匹配\n- 不依赖第三方安全扫描库\n- 确保扫描速度和可靠性\n\n### 无修改原则\n\n所有检测操作均为只读扫描：\n\n- 不修改任何 MCP 配置文件\n- 不修改工具描述或服务器状态\n- 及时终止检测过程中启动的服务器进程\n\n### 快速完成原则\n\n扫描应在数秒内完成：\n\n- 主动超时机制终止响应慢的服务器\n- 高效的正则表达式模式匹配\n- 并行处理多服务器扫描\n\n### Agent 优先原则\n\n所有输出格式优先考虑机器可解析性：\n\n- JSON 输出格式稳定、结构化\n- SARIF 格式符合行业标准\n- `--json` 和 `--brief` 输出包含 `exitCode` 字段便于自动化决策\n\n资料来源：[CONTRIBUTING.md:64-72]()\n\n## 命令行使用\n\n### 基础扫描\n\n```bash\nnpx decoy-scan                        # 完整扫描\nnpx decoy-scan --json                 # 机器可读输出\nnpx decoy-scan --sarif                # SARIF 格式输出\n```\n\n### 详细模式\n\n```bash\nnpx decoy-scan --verbose              # 显示所有工具包括 low 风险\nnpx decoy-scan --no-probe             # 仅配置文件检测\nnpx decoy-scan --no-advisories        # 跳过网络调用\n```\n\n### CI/CD 集成\n\n```yaml\n# .github/workflows/mcp-security.yml\nname: MCP Security\non: [push, pull_request]\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n        with:\n          policy: no-critical,no-poisoning\n          sarif: true\n```\n\n### 策略规则\n\n| 规则 | 描述 |\n|------|------|\n| `no-critical` | 禁止 critical 级别工具 |\n| `no-high` | 禁止 high 级别工具 |\n| `no-poisoning` | 禁止工具描述中的提示注入 |\n| `no-toxic-flows` | 禁止跨服务器数据泄露 |\n| `no-secrets` | 禁止 MCP 配置中的敏感信息 |\n| `require-tripwires` | 要求安装 decoy-tripwire |\n\n资料来源：[README.md:89-96]()\n\n## 局限性说明\n\n### 检测范围限制\n\n- 检测基于正则表达式模式匹配，可能无法识别未知变体攻击\n- 仅分析工具名称和描述文本，不深入分析工具实现逻辑\n- 依赖服务器正确响应工具列表请求\n\n### 误报与漏报\n\n- 高敏感度配置可能导致部分合法工具被标记\n- 混淆或编码的恶意内容可能被遗漏\n- 建议结合人工审查进行最终判断\n\n### 跨语言支持\n\n- 默认检测模式针对英文文本设计\n- 非英文工具描述的检测准确度可能降低\n\n---\n\n如需报告安全问题，请联系 agent@decoy.run。请勿为此项目公开提交安全问题。\n\n---\n\n<a id='scanning-architecture'></a>\n\n## 扫描架构\n\n### 相关页面\n\n相关主题：[MCP 主机发现](#mcp-host-discovery), [风险分级系统](#risk-classification)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [lib/scan.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/scan.mjs)\n- [lib/verify.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/verify.mjs)\n- [lib/probe.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/probe.mjs)\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs)\n- [bin/cli.mjs](https://github.com/decoy-run/decoy-scan/blob/main/bin/cli.mjs)\n</details>\n\n# 扫描架构\n\n## 概述\n\ndecoy-scan 的扫描架构是一套零依赖的 MCP（Model Context Protocol）安全扫描解决方案，采用纯 Node.js 原生模块实现。该架构通过配置文件发现、服务器探测、工具风险分析、投毒检测、有毒流程分析和供应链审查等多个环节，对本地 MCP 服务器配置进行全面的安全评估。\n\n扫描架构的核心设计原则包括：\n\n- **零依赖**：仅使用 Node.js 内置模块，无需安装任何 npm 包\n- **无构建步骤**：直接运行 ES 模块\n- **快速执行**：对服务器进行激进超时，扫描应在数秒内完成\n- **安全操作**：仅读取配置，从不修改，使用后立即终止生成的服务器进程\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n## 核心模块划分\n\ndecoy-scan 的扫描架构由多个核心模块组成，每个模块负责特定的安全检查功能：\n\n| 模块 | 文件位置 | 核心功能 |\n|------|----------|----------|\n| 扫描编排器 | `lib/scan.mjs` | 协调整个扫描流程 |\n| 服务器探测 | `lib/probe.mjs` | 通过 stdio 协议探测 MCP 服务器 |\n| 策略验证 | `lib/verify.mjs` | 验证扫描结果是否满足策略要求 |\n| 工具分类器 | `index.mjs` | 工具风险等级分类 |\n| 投毒检测器 | `index.mjs` | 检测提示词注入攻击 |\n| 环境分析器 | `index.mjs` | 分析敏感环境变量暴露 |\n| 就绪检查器 | `index.mjs` | 生产环境就绪状态评估 |\n| 配置发现器 | `index.mjs` | 发现本地 MCP 客户端配置 |\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n## 扫描流程架构图\n\n扫描流程采用流水线式的处理架构，从配置发现到最终报告生成依次执行：\n\n```mermaid\ngraph TD\n    A[开始扫描] --> B[发现 MCP 配置]\n    B --> C{发现配置?}\n    C -->|无| D[生成空结果]\n    C -->|有| E[遍历每个服务器配置]\n    E --> F[解析服务器启动命令]\n    F --> G{是否探测服务器}\n    G -->|否| H[跳过探测]\n    G -->|是| I[通过 stdio 探测服务器]\n    I --> J{探测成功?}\n    J -->|失败| K[记录探测失败]\n    J -->|成功| L[获取工具列表]\n    L --> M[执行安全分析]\n    M --> N{分析完成?}\n    N -->|是| O[汇总结果]\n    K --> O\n    H --> O\n    O --> P[生成输出报告]\n    P --> Q[退出]\n    D --> Q\n```\n\n## 配置发现模块\n\n配置发现模块负责定位本地系统中各 MCP 客户端的配置文件。该模块维护了一个 `HOST_CONFIGS` 配置映射，支持以下 MCP 客户端：\n\n- Claude Desktop\n- Cursor\n- Windsurf\n- VS Code\n- Claude Code\n- Zed\n- Cline\n\n配置发现器针对不同操作系统（macOS、Windows、Linux）使用不同的配置文件路径：\n\n```javascript\n\"Claude Desktop\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"config.json\");\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n### 项目级配置支持\n\n除系统级 MCP 客户端配置外，扫描器还支持项目级别的 `.mcp.json` 配置文件。从项目根目录运行时，会自动包含项目级配置扫描。\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 服务器探测模块\n\n探测模块是扫描架构的核心组件之一，负责与 MCP 服务器建立通信并获取其工具列表。\n\n### stdio 协议探测\n\n探测模块通过 stdio 协议与 MCP 服务器交互：\n\n1. 解析服务器启动命令和参数\n2. 生成子进程并启动 MCP 服务器\n3. 发送 JSON-RPC 格式的 `tools/list` 请求\n4. 接收并解析服务器返回的工具列表\n5. 正常终止服务器进程\n\n### 探测超时机制\n\n为保证扫描速度，探测模块采用激进超时策略：\n\n- 探测超时后会立即终止服务器进程\n- 探测失败的服务器会记录错误信息但不影响整体扫描继续\n\n```javascript\n// 超时后立即终止并清理\nkillSpawnedServers();\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n### 探测结果处理\n\n探测结果包含以下信息：\n\n| 字段 | 说明 |\n|------|------|\n| `name` | 服务器名称 |\n| `command` | 启动命令 |\n| `args` | 命令参数 |\n| `tools` | 工具列表（包含名称、描述、输入模式） |\n| `error` | 探测错误信息（如有） |\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 安全分析模块\n\n安全分析模块是扫描架构的核心部分，包含多个子分析器：\n\n### 工具风险分类器\n\n工具风险分类器（`classifyTool`）根据工具名称和描述将工具分为四个风险等级：\n\n| 风险等级 | 说明 | 示例 |\n|----------|------|------|\n| critical | 可执行代码、修改数据或造成不可逆更改 | `execute_command`, `write_file` |\n| high | 读取文件或发起网络请求 | `read_file`, `fetch_url` |\n| medium | 访问系统信息或执行其他操作 | `get_system_info` |\n| low | 低风险工具 | 其他工具 |\n\n分类器使用 `RISK_PATTERNS` 正则表达式模式匹配工具名称，并结合工具描述进行综合判断。\n\n关键风险模式包括：\n\n```javascript\n{\n  pattern: /^execute[_-]?(script|code|js|javascript|python|sql)$/,\n  type: \"critical\",\n  severity: \"critical\"\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n### 投毒检测器\n\n投毒检测器（`detectPoisoning`）使用 37 种正则模式检测工具描述中的提示词注入攻击，涵盖 20 个攻击类别：\n\n- 指令覆盖（instruction override）\n- 隐蔽技术（concealment）\n- 数据泄露（data exfiltration）\n- 凭证收割（credential harvesting）\n- 强制执行（coercive execution）\n- 工具影子（tool shadowing）\n- 规避技术（evasion techniques）\n\n每个投毒模式包含：\n\n```javascript\n{\n  pattern: /regex/i,\n  type: \"category-name\",\n  severity: \"critical\",\n  description: \"Human-readable description\"\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n### 服务器命令分析器\n\n命令分析器（`analyzeServerCommand`）检查服务器启动命令中的可疑特征：\n\n- 管道到 shell（pipe-to-shell）\n- 临时目录执行\n- 内联代码注入\n- 误植域名攻击（typosquatting）\n- 网络工具调用\n\n### 环境变量暴露分析器\n\n环境分析器（`analyzeEnvExposure`）使用 `SENSITIVE_ENV_PATTERNS` 模式检测 12 类敏感凭证暴露：\n\n- API 密钥\n- 访问令牌\n- 密码\n- 数据库连接 URL\n- 云服务凭证\n- 其他敏感环境变量\n\n### 就绪状态检查器\n\n就绪状态检查器（`analyzeReadiness`）评估生产环境部署就绪程度，检查项包括：\n\n- 缺失工具描述\n- 缺失输入模式\n- 缺少必需字段\n- 过度授权的工具范围\n- 破坏性工具缺少安全提示\n\n### OWASP 映射器\n\nOWASP 映射器（`mapToOwasp`）将所有发现映射到 OWASP Agentic Top 10：\n\n- ASI01 - Agentic AI Inventory and Tracking\n- ASI02 - Sensitive Data Exposure\n- ASI03 - Tool Poisoning\n- ASI04 - Agentic AI Hallucinations and Mismanagement\n- ASI05 - Overprivileged Agents and Tools\n\n资料来源：[README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n\n## 有毒流程分析\n\n除单个工具的安全分析外，扫描架构还支持跨服务器的有毒流程分析（`analyzeToxicFlows`）：\n\n| 流程类型 | ID | 严重性 | 说明 |\n|----------|-----|--------|------|\n| 数据泄露 | TF001 | critical | 跨服务器数据泄露攻击链 |\n| 破坏性操作 | TF002 | critical | 跨服务器破坏性操作链 |\n\n有毒流程分析在库模式下可用：\n\n```javascript\nimport { scan, analyzeToxicFlows } from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.toxicFlows);\n```\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 供应链审查\n\n扫描架构包含供应链安全审查功能：\n\n### 已知漏洞包检测\n\n通过 Decoy  advisory 数据库（40+ MCP 包）对配置中的服务器进行已知漏洞匹配。\n\n### 工具清单哈希追踪\n\n工具清单哈希（`hashToolManifest`）功能可以检测工具变更：\n\n- 工具新增\n- 工具移除\n- 工具描述变更\n\n通过 `detectManifestChanges` 函数比较两次扫描之间的工具清单差异。\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 技能扫描\n\n扫描架构支持对 Claude Code 技能进行专项安全扫描（`discoverSkills` 和 `analyzeSkill`）：\n\n- 提示词注入检测\n- 硬编码密钥检测\n- 可疑 URL 检测\n\n```javascript\nimport { scan, discoverSkills, analyzeSkill } from 'decoy-scan';\n\nconst results = await scan({ skills: true });\nconsole.log(results.skills);\n```\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 策略验证模块\n\n策略验证模块（`lib/verify.mjs`）根据用户定义的策略规则验证扫描结果：\n\n### 策略规则语法\n\n| 规则 | 说明 |\n|------|------|\n| `no-critical` | 不允许关键风险工具 |\n| `no-high` | 不允许高风险工具 |\n| `no-poisoning` | 不允许提示词注入 |\n| `no-toxic-flows` | 不允许有毒流程 |\n| `no-secrets` | 不允许暴露密钥 |\n| `require-tripwires` | 要求安装 decoy-tripwire |\n| `max-critical=N` | 限制关键问题数量 |\n\n策略检查失败会设置相应的退出码。\n\n资料来源：[README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n\n## 输出报告生成\n\n### SARIF 报告\n\nSARIF（Static Analysis Results Interchange Format）是一种结构化的安全报告格式，用于 CI/CD 集成：\n\n```javascript\nimport { scan, toSarif } from 'decoy-scan';\n\nconst results = await scan();\nconst sarif = toSarif(results);\n```\n\nSARIF 输出会包含：\n\n- 规则 ID 和级别\n- 问题位置和描述\n- 建议的修复方案\n- OWASP 映射信息\n\n### 退出码规范\n\n| 退出码 | 含义 |\n|--------|------|\n| 0 | 无关键或高风险问题 |\n| 1 | 发现高风险问题 |\n| 2 | 发现关键问题、工具投毒或策略违规 |\n\n退出码在 `--json` 和 `--brief` 输出的 `exitCode` 字段中也会体现，便于程序化处理。\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## CLI 入口\n\n命令行入口位于 `bin/cli.mjs`，负责：\n\n1. 解析命令行参数\n2. 初始化扫描配置\n3. 调用扫描模块\n4. 格式化输出结果\n5. 处理退出逻辑\n\n### 支持的输出模式\n\n| 模式 | 说明 |\n|------|------|\n| 默认 | 人类可读的彩色输出 |\n| `--json` | 机器可解析的 JSON 格式 |\n| `--sarif` | SARIF 2.1.0 标准格式 |\n| `--brief` | 最小化摘要信息 |\n| `--verbose` | 显示所有工具包括低风险 |\n\n### 可用参数\n\n| 参数 | 说明 |\n|------|------|\n| `--no-probe` | 仅扫描配置，不探测服务器 |\n| `--no-advisories` | 跳过网络请求（供应链审查） |\n| `--quiet` | 静默模式，抑制状态输出 |\n| `--version` | 显示版本信息 |\n\n资料来源：[AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n\n## 数据流架构图\n\n```mermaid\ngraph LR\n    A[MCP 配置文件] --> B[配置发现器]\n    B --> C[服务器列表]\n    C --> D{探测模式}\n    D -->|探测| E[stdio 探测]\n    D -->|跳过| F[跳过探测]\n    E --> G[工具列表]\n    F --> H[空工具列表]\n    G --> I[安全分析引擎]\n    H --> I\n    I --> J[风险分类结果]\n    I --> K[投毒检测结果]\n    I --> L[环境分析结果]\n    I --> M[就绪检查结果]\n    J --> N[结果汇总]\n    K --> N\n    L --> N\n    M --> N\n    N --> O[策略验证]\n    O --> P{SARIF 格式?}\n    P -->|是| Q[SARIF 报告]\n    P -->|否| R[JSON/文本报告]\n    Q --> S[GitHub Security]\n    R --> T[终端输出]\n```\n\n## 扩展机制\n\n### 添加新的投毒模式\n\n在 `POISONING_PATTERNS` 中添加新模式：\n\n```javascript\n{\n  pattern: /regex/i,\n  type: \"category-name\",\n  severity: \"critical\",\n  description: \"Human-readable description\"\n}\n```\n\n添加后需在 `OWASP_MAP` 中添加对应的映射。\n\n### 添加新的 MCP 客户端支持\n\n在 `HOST_CONFIGS` 中添加新的客户端条目：\n\n```javascript\n\"New Client\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"config.json\");\n}\n```\n\n### 添加新的就绪检查\n\n在 `analyzeReadiness()` 函数中添加检查逻辑：\n\n```javascript\nif (/* condition */) {\n  findings.push({\n    type: \"readiness-check-name\",\n    severity: \"medium\",\n    description: \"What's wrong and why it matters\"\n  });\n}\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md)\n\n## 性能特性\n\n扫描架构的性能设计目标：\n\n- **快速启动**：无依赖安装，npx 直接运行\n- **快速扫描**：激进超时策略，单个服务器探测有明确时间限制\n- **并行发现**：配置文件发现与初步分析可并行执行\n- **资源高效**：无额外进程开销，服务器进程及时清理\n\n## 安全特性\n\n扫描架构的安全设计原则：\n\n| 特性 | 实现方式 |\n|------|----------|\n| 读取隔离 | 仅读取配置，从不修改 |\n| 进程控制 | 服务器进程用后即删 |\n| 无持久化 | 不在系统留下痕迹 |\n| 隐私保护 | 支持 `--no-telemetry` 禁用遥测 |\n| 安全报告 | 敏感信息脱敏处理 |\n\n## 版本演进\n\n| 版本 | 重大变更 |\n|------|----------|\n| 0.8.0 | v2 遥测信封格式 |\n| 0.7.0 | 供应链 advisories、工具清单哈希追踪 |\n| 0.5.0 | 新增 `explain` 子命令 |\n| 0.2.0 | SSE 传输安全检查、输入验证 |\n| 0.1.0 | 初始版本发布 |\n\n资料来源：[CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n\n---\n\n<a id='mcp-host-discovery'></a>\n\n## MCP 主机发现\n\n### 相关页面\n\n相关主题：[扫描架构](#scanning-architecture), [快速开始](#getting-started)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [index.mjs](https://github.com/decoy-run/decoy-scan/blob/main/index.mjs) — 包含 `HOST_CONFIGS` 和 `discoverConfigs()` 实现\n- [lib/discovery.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/discovery.mjs) — 主机发现核心逻辑\n- [lib/sarif.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/sarif.mjs) — SARIF 输出格式转换\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md) — Agent 参考文档\n- [CONTRIBUTING.md](https://github.com/decoy-run/decoy-scan/blob/main/CONTRIBUTING.md) — 贡献指南\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md) — 项目说明文档\n</details>\n\n# MCP 主机发现\n\n## 概述\n\nMCP 主机发现是 decoy-scan 工具的核心功能之一，负责自动检测本地机器上所有已配置的 MCP（Model Context Protocol）客户端主机，并收集其 MCP 服务器配置信息。该功能使工具能够对用户环境中的 MCP 生态系统进行全面的安全扫描，无需用户手动指定配置文件路径。\n\ndecoy-scan 采用零依赖设计，完全使用 Node.js 内置模块实现主机发现功能，确保扫描过程快速、轻量且可靠。发现阶段会遍历操作系统特定的配置文件路径，解析 MCP 服务器定义，并准备后续的安全分析工作。\n\n## 支持的 MCP 主机\n\ndecoy-scan 目前支持 **7 种主流 MCP 客户端主机**，覆盖桌面 IDE、代码编辑器、AI 编程工具等多种开发环境。\n\n| 主机名称 | 类型 | 支持平台 | 典型用途 |\n|---------|------|---------|---------|\n| Claude Desktop | AI 助手 | macOS/Windows/Linux | Anthropic Claude 桌面集成 |\n| Cursor | AI 代码编辑器 | macOS/Windows/Linux | AI 驱动的代码补全与生成 |\n| Windsurf | AI 代码编辑器 | macOS/Windows/Linux | Cascade AI 工作流 |\n| VS Code | 代码编辑器 | macOS/Windows/Linux | Microsoft Copilot 集成 |\n| Claude Code | CLI 工具 | macOS/Windows/Linux | 命令行 Claude 交互 |\n| Zed | 代码编辑器 | macOS/Windows/Linux | 高性能 GPU 加速编辑器 |\n| Cline | VS Code 扩展 | macOS/Windows/Linux | AI 自主编程代理 |\n\n资料来源：[AGENTS.md:Supported Hosts (7)]()\n\n## 平台感知配置路径\n\nMCP 主机发现模块的核心设计原则是**平台感知**——根据不同操作系统采用相应的配置文件路径规范。这种设计确保工具在 macOS、Windows 和 Linux 三大主流平台上均能正确发现 MCP 配置。\n\n### 配置路径规范\n\n```mermaid\ngraph TD\n    A[启动扫描] --> B{检测操作系统}\n    B -->|macOS| C[使用 homedir() 路径]\n    B -->|Windows| D[使用 APPDATA 环境变量]\n    B -->|Linux| E[使用 ~/.config 目录]\n    \n    C --> F[调用平台特定路径解析函数]\n    D --> F\n    E --> F\n    \n    F --> G[发现 MCP 服务器配置]\n    G --> H[解析配置文件 JSON]\n    H --> I[提取服务器定义列表]\n```\n\n### 路径发现机制\n\n各平台的标准配置存储位置如下：\n\n| 平台 | 配置目录 | 说明 |\n|-----|---------|------|\n| macOS | `~/Library/Application Support/` | 使用 `homedir()` 获取用户主目录 |\n| Windows | `%APPDATA%` | 使用 `process.env.APPDATA` 环境变量 |\n| Linux | `~/.config/` | 标准 XDG 配置目录规范 |\n\n```javascript\n// 主机配置结构示例 (CONTRIBUTING.md)\n\"New Client\": () => {\n  const p = platform();\n  if (p === \"darwin\") return join(homedir(), \"path\", \"to\", \"config.json\");\n  if (p === \"win32\") return join(process.env.APPDATA || \"\", \"path\", \"config.json\");\n  return join(homedir(), \".config\", \"path\", \"to\", \"config.json\");\n},\n```\n\n资料来源：[CONTRIBUTING.md:Adding Host Configs]()\n\n## 发现流程架构\n\nMCP 主机发现模块位于 `lib/discovery.mjs`，是扫描管道的第一个关键环节。整个发现流程分为配置探测、服务器提取、重复数据删除三个主要阶段。\n\n### 完整发现流程\n\n```mermaid\ngraph TD\n    A[MCP 主机发现开始] --> B[遍历 HOST_CONFIGS]\n    B --> C{当前平台匹配?}\n    C -->|是| D[读取配置文件]\n    C -->|否| E[跳过该主机]\n    D --> F{配置文件存在?}\n    F -->|是| G[解析 JSON 配置]\n    F -->|否| E\n    G --> H[提取 servers 数组]\n    H --> I{发现 decoy-tripwire?}\n    I -->|是| J[去重标记]\n    I -->|否| K[添加至待扫描列表]\n    J --> L[跨主机去重]\n    K --> L\n    L --> M[返回已发现服务器列表]\n    \n    E --> B\n```\n\n### 配置文件解析\n\n发现的 MCP 配置文件通常为 JSON 格式，包含服务器的启动命令、参数列表等核心定义：\n\n```json\n{\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"env\": {}\n  }]\n}\n```\n\n解析后的数据将传递给后续的 `probeServer()` 模块进行 MCP stdio 探测。\n\n资料来源：[AGENTS.md:JSON Output Schema]()\n\n## 服务器探测阶段\n\n在主机发现完成后，decoy-scan 对每个已发现的 MCP 服务器执行 stdio 探测，查询其工具列表并进行分析。\n\n### 探测流程\n\n```mermaid\nsequenceDiagram\n    participant 扫描器 as decoy-scan\n    participant 服务器 as MCP Server\n    participant 分析器 as 安全分析引擎\n    \n    扫描器->>服务器: 启动服务器进程 (stdio)\n    扫描器->>服务器: 发送 initialize 请求\n    服务器-->>扫描器: 返回 server info\n    扫描器->>服务器: 发送 tools/list 请求\n    服务器-->>扫描器: 返回工具列表\n    扫描器->>分析器: 传递工具列表\n    分析器->>分析器: 风险分类\n    分析器->>分析器: 投毒检测\n    分析器->>分析器: 准备就绪检查\n    扫描器->>服务器: 终止进程\n```\n\n### 探测超时控制\n\n为确保扫描性能，服务器探测采用**激进超时策略**。如果服务器在规定时间内未响应，探测将被强制终止并记录错误信息。\n\n```javascript\n// 探测失败处理\nif (probeError) {\n  findings.push({\n    type: \"probe-failed\",\n    severity: \"medium\",\n    description: \"服务器探测超时或连接失败\"\n  });\n}\n```\n\n资料来源：[AGENTS.md:JSON Output Schema:error]()\n\n## 输出格式\n\n发现阶段的输出可采用多种格式，便于不同使用场景的消费：\n\n### JSON 格式\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [{\n    \"name\": \"server-name\",\n    \"hosts\": [\"Claude Desktop\"],\n    \"command\": \"npx\",\n    \"args\": [\"@modelcontextprotocol/server-filesystem\"],\n    \"tools\": [{\n      \"name\": \"read_file\",\n      \"description\": \"...\",\n      \"risk\": \"high\",\n      \"poisoning\": [{ \"type\": \"...\", \"severity\": \"...\", \"description\": \"...\" }]\n    }],\n    \"risk\": \"high\",\n    \"error\": null\n  }]\n}\n```\n\n### SARIF 格式\n\n通过 `--sarif` 参数可输出符合 SARIF 2.1.0 标准的格式，便于集成到 CI/CD 安全扫描流程中：\n\n```yaml\nruns:\n  - results:\n      - ruleId: \"critical-tool\"\n        level: \"error\"\n        message: \"发现高风险工具\"\n```\n\n资料来源：[lib/sarif.mjs]()\n\n## 与其他模块的集成\n\nMCP 主机发现是扫描管道的第一步，后续安全分析依赖于发现阶段提供的数据：\n\n```mermaid\ngraph LR\n    A[MCP 主机发现] --> B[工具风险分类]\n    A --> C[投毒检测]\n    A --> D[服务器命令分析]\n    A --> E[环境变量暴露检测]\n    A --> F[准备就绪检查]\n    A --> G[供应链告警]\n    \n    B --> H[结果聚合]\n    C --> H\n    D --> H\n    E --> H\n    F --> H\n    G --> H\n    \n    H --> I[JSON/SARIF 输出]\n    H --> J[策略检查]\n    J --> K{通过?}\n    K -->|是| L[退出码 0]\n    K -->|否| M[退出码 1/2]\n```\n\n### 各模块依赖关系\n\n| 模块 | 依赖发现数据 | 功能说明 |\n|-----|-------------|---------|\n| 工具风险分类 | ✓ | 基于工具名称和描述进行风险评级 |\n| 投毒检测 | ✓ | 检测工具描述中的提示注入模式 |\n| 服务器命令分析 | ✓ | 检查启动命令的安全性 |\n| 环境变量暴露检测 | ✓ | 扫描配置中的敏感凭证 |\n| 准备就绪检查 | ✓ | 评估生产环境就绪程度 |\n| 供应链告警 | ✓ | 对已知漏洞包进行交叉比对 |\n\n资料来源：[CONTRIBUTING.md:Code Structure]()\n\n## 扩展主机支持\n\ndecoy-scan 支持通过修改 `HOST_CONFIGS` 配置对象来添加新的 MCP 主机支持。\n\n### 添加新主机步骤\n\n1. 在 `index.mjs` 中的 `HOST_CONFIGS` 对象添加新条目\n2. 实现平台感知的路径解析逻辑\n3. 确保配置文件格式符合 MCP 规范\n4. 运行 `npm test` 验证测试通过\n\n### 配置模板\n\n```javascript\nHOST_CONFIGS: {\n  // ... 现有配置\n  \"New MCP Client\": () => {\n    const p = platform();\n    if (p === \"darwin\") {\n      return join(homedir(), \"Library\", \"Application Support\", \"NewClient\", \"config.json\");\n    }\n    if (p === \"win32\") {\n      return join(process.env.APPDATA || \"\", \"NewClient\", \"config.json\");\n    }\n    // Linux\n    return join(homedir(), \".config\", \"newclient\", \"config.json\");\n  }\n}\n```\n\n资料来源：[CONTRIBUTING.md:Adding Host Configs]()\n\n## 错误处理与鲁棒性\n\n主机发现模块具备完善的错误处理机制，确保在各种异常情况下仍能提供有用的诊断信息。\n\n### 常见错误场景\n\n| 错误类型 | 处理方式 | 用户提示 |\n|---------|---------|---------|\n| 配置文件不存在 | 静默跳过 | 无 |\n| JSON 解析失败 | 记录错误 | 显示解析错误详情 |\n| 权限不足 | 捕获异常 | 提示权限问题 |\n| 探测超时 | 强制终止 | 显示 `? probe failed` |\n\n### 探针失败展示\n\n当服务器探测失败时，CLI 输出会显示明确的错误标识：\n\n```\n? filesystem-server probe failed\n  Error: Connection timeout after 5000ms\n```\n\n资料来源：[CHANGELOG.md:0.5.3:Fixed]()\n\n## 设计原则\n\nMCP 主机发现模块遵循 decoy-scan 的核心设计理念：\n\n| 原则 | 实现方式 | 优势 |\n|-----|---------|------|\n| 零依赖 | 纯 Node.js 内置模块 | 无需安装额外包 |\n| 零配置 | 自动探测本机配置 | 开箱即用 |\n| 快速 | 异步 I/O + 超时控制 | 秒级完成扫描 |\n| 安全 | 只读扫描不修改配置 | 不影响用户环境 |\n| Agent 优先 | JSON/SARIF 结构化输出 | 便于自动化集成 |\n\n资料来源：[CONTRIBUTING.md:Design Principles]()\n\n## 命令行使用\n\n主机发现功能通过以下命令行参数进行控制：\n\n| 参数 | 功能 | 说明 |\n|-----|------|------|\n| 无参数 | 全量扫描 | 发现所有主机和服务器 |\n| `--no-probe` | 仅配置发现 | 跳过服务器探测，仅读取配置 |\n| `--no-advisories` | 跳过网络请求 | 跳过供应链告警检查 |\n| `--verbose` | 显示所有工具 | 包括低风险工具 |\n| `--json` | JSON 输出 | 结构化机器可读输出 |\n| `--sarif` | SARIF 输出 | 符合 SARIF 2.1.0 标准 |\n\n```bash\n# 仅发现配置，不探测服务器\nnpx decoy-scan --no-probe\n\n# 跳过供应链告警检查\nnpx decoy-scan --no-advisories\n\n# 详细输出模式\nnpx decoy-scan --verbose\n```\n\n资料来源：[AGENTS.md:CLI Flags]()\n\n## 技术规格\n\n| 规格项 | 值 |\n|-------|-----|\n| 支持平台 | macOS, Windows, Linux |\n| Node.js 最低版本 | 18+ |\n| 依赖数量 | 0 (零依赖) |\n| 配置格式 | JSON |\n| 默认超时 | 5000ms |\n| 并发探测 | 串行执行 |\n\n## 总结\n\nMCP 主机发现是 decoy-scan 实现自动化安全扫描的基础能力，通过平台感知的配置路径解析和结构化的服务器发现机制，为后续的安全分析提供了完整的目标清单。该模块的零依赖设计和只读扫描原则确保了工具的便携性和安全性，使其能够在各种开发环境中无缝集成到 CI/CD 流程中。\n\n---\n\n<a id='toxic-flow-analysis'></a>\n\n## 有毒数据流分析\n\n### 相关页面\n\n相关主题：[提示注入检测](#prompt-injection-detection), [安全检查项目](#security-checks)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [lib/analyzers.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/analyzers.mjs)\n- [lib/scan.mjs](https://github.com/decoy-run/decoy-scan/blob/main/lib/scan.mjs)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n</details>\n\n# 有毒数据流分析\n\n有毒数据流分析（Tainted Flow Analysis 或 Toxic Flow Analysis）是 decoy-scan 安全扫描器的核心检测模块之一。该模块通过追踪 MCP 服务器之间的数据传递路径，识别潜在的安全威胁链，包括跨服务器数据泄露和破坏性操作链。\n\n## 概述\n\n在 MCP（Model Context Protocol）生态系统中，多个服务器通常协同工作，每个服务器拥有不同的工具和权限。有毒数据流分析模块专门检测以下两类攻击链：\n\n| 攻击类型 | 标识符 | 严重级别 | 描述 |\n|---------|--------|---------|------|\n| 跨服务器数据泄露 | TF001 | Critical | 敏感数据通过多个服务器传递后被不当暴露 |\n| 破坏性攻击链 | TF002 | Critical | 多个工具组合执行导致不可逆的破坏性操作 |\n\n资料来源：[README.md:1]()\n\n## 核心功能\n\n### 攻击链检测机制\n\n有毒数据流分析通过分析工具调用序列和数据传递路径来识别潜在威胁。当扫描器探测 MCP 服务器时，会收集所有可用工具的元数据，包括工具名称、描述和参数模式。然后通过图分析算法构建工具调用依赖图，检测是否存在恶意的数据传递链。\n\n该模块的核心逻辑位于 `lib/analyzers.mjs` 中的 `analyzeToxicFlows` 函数。该函数接收扫描到的服务器列表和工具信息，返回检测到的有毒数据流列表。\n\n### 扫描结果数据结构\n\n扫描完成后，有毒数据流结果通过 `results.toxicFlows` 属性暴露：\n\n```javascript\nimport { scan } from 'decoy-scan';\n\nconst results = await scan();\nconsole.log(results.toxicFlows);\n// 输出格式：\n// [{ id: \"TF001\", severity: \"critical\", roles: {...} }]\n```\n\n每个有毒数据流包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| id | string | 攻击链标识符（如 TF001、TF002） |\n| severity | string | 严重级别（critical/high/medium/low） |\n| roles | object | 涉及的角色和权限信息 |\n\n资料来源：[AGENTS.md:1]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n    A[扫描 MCP 配置] --> B[探测服务器工具列表]\n    B --> C[收集工具元数据]\n    C --> D[构建工具依赖图]\n    D --> E{分析数据传递路径}\n    E -->|检测到 TF001| F[跨服务器数据泄露]\n    E -->|检测到 TF002| G[破坏性攻击链]\n    E -->|未检测到威胁| H[扫描通过]\n    F --> I[生成安全报告]\n    G --> I\n    H --> I\n```\n\n## 策略控制\n\ndecoy-scan 提供了细粒度的策略控制机制，允许用户在 CI/CD 环境中根据安全需求配置扫描行为。\n\n### 策略规则\n\n通过 `--policy` 参数可以配置以下与有毒数据流相关的策略：\n\n```\nno-toxic-flows       Fail on cross-server data leak / destructive chains\n```\n\n资料来源：[README.md:1]()\n\n### 退出码机制\n\n有毒数据流检测结果直接影响扫描器的退出码：\n\n| 退出码 | 含义 |\n|-------|------|\n| 0 | 无 critical 或 high 级别问题 |\n| 1 | 发现 high 级别风险问题 |\n| 2 | 发现 critical 级别问题、工具投毒或有毒数据流 |\n\n资料来源：[AGENTS.md:1]()\n\n## 集成使用\n\n### 作为库函数导入\n\ndecoy-scan 提供了模块化接口，可以直接导入 `analyzeToxicFlows` 函数用于自定义分析场景：\n\n```javascript\nimport {\n  scan,\n  analyzeToxicFlows,\n} from 'decoy-scan';\n\n// 执行完整扫描\nconst results = await scan();\n\n// 仅执行有毒数据流分析\nconst toxicFlows = analyzeToxicFlows(results.servers);\nconsole.log(toxicFlows);\n```\n\n### 完整扫描配置\n\n使用 `scan()` 函数时，可以通过选项对象配置扫描行为：\n\n```javascript\nconst results = await scan({\n  skills: true,           // 包含技能扫描\n  advisories: true,       // 包含供应链告警\n  verbose: false,         // 显示所有工具\n  noProbe: false          // 跳过服务器探测\n});\n```\n\n扫描结果对象包含完整的分析数据：\n\n```javascript\n{\n  servers: [...],        // 服务器列表及工具信息\n  toxicFlows: [...],     // 有毒数据流分析结果\n  skills: [...],         // 技能分析结果\n  summary: {\n    total: 2,\n    critical: 1,\n    high: 2,\n    medium: 4,\n    low: 5,\n    poisoned: 0,\n    status: \"fail\",\n    exitCode: 2\n  }\n}\n```\n\n资料来源：[AGENTS.md:1]()\n\n## GitHub Action 集成\n\n在 CI/CD 流程中使用 decoy-scan 时，可以通过 GitHub Action 启用有毒数据流检测：\n\n```yaml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n        with:\n          policy: no-critical,no-poisoning,no-toxic-flows\n          sarif: true\n```\n\n### Action 输入参数\n\n| 参数 | 默认值 | 说明 |\n|------|-------|------|\n| policy | no-critical,no-poisoning | 策略规则列表 |\n| sarif | true | 上传 SARIF 到 GitHub Security |\n| report | false | 上传到 Decoy Guard 仪表板 |\n| token | — | Decoy API 令牌（用于 report） |\n| verbose | false | 显示所有工具包括低风险 |\n\n资料来源：[README.md:1]()\n\n## 威胁场景示例\n\n### TF001：跨服务器数据泄露\n\n当一个服务器拥有读取敏感文件的能力，而该数据随后被传递给另一个具有网络访问权限的服务器时，就会形成数据泄露攻击链。decoy-scan 会检测这种跨服务器的敏感数据传递模式。\n\n### TF002：破坏性攻击链\n\n当多个工具按特定顺序组合使用时，可能导致文件系统破坏或数据不可逆损失。例如，读取配置 → 修改权限 → 删除文件的连续操作可能被识别为破坏性攻击链。\n\n## 输出格式\n\n### JSON 结构\n\n```json\n{\n  \"timestamp\": \"ISO-8601\",\n  \"hosts\": [\"Claude Desktop\", \"Cursor\"],\n  \"servers\": [...],\n  \"summary\": {\n    \"total\": 2,\n    \"critical\": 1,\n    \"high\": 2,\n    \"medium\": 4,\n    \"low\": 5,\n    \"poisoned\": 0,\n    \"toxicFlows\": 1,\n    \"status\": \"fail\",\n    \"exitCode\": 2\n  }\n}\n```\n\n### Brief 输出\n\n对于简化的概要输出：\n\n```json\n{\n  \"servers\": 3,\n  \"critical\": 1,\n  \"high\": 2,\n  \"medium\": 4,\n  \"low\": 5,\n  \"poisoned\": 0,\n  \"toxicFlows\": 1,\n  \"status\": \"fail\",\n  \"exitCode\": 2\n}\n```\n\n资料来源：[AGENTS.md:1]()\n\n## 版本历史\n\n有毒数据流分析功能在以下版本中逐步完善：\n\n| 版本 | 更新内容 |\n|------|---------|\n| 0.2.0 | 引入有毒数据流分析模块 |\n| 0.5.0 | 增强分析精度，修复边界情况 |\n| 0.5.8 | 优化性能，减少误报 |\n\n资料来源：[CHANGELOG.md:1]()\n\n## 相关模块\n\n有毒数据流分析与其他安全检测模块协同工作：\n\n| 模块 | 功能 |\n|-----|------|\n| 工具风险分类 | 评估单个工具的风险级别 |\n| 工具投毒检测 | 检测工具描述中的提示注入 |\n| 服务器命令分析 | 检查服务器启动命令的安全性 |\n| 环境变量暴露检测 | 识别敏感凭证的泄露风险 |\n\n所有模块的检测结果统一汇总到 `scan()` 函数的返回结果中，形成完整的安全态势报告。\n\n---\n\n<a id='github-action'></a>\n\n## GitHub Action 集成\n\n### 相关页面\n\n相关主题：[快速开始](#getting-started)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [action.yml](https://github.com/decoy-run/decoy-scan/blob/main/action.yml)\n- [README.md](https://github.com/decoy-run/decoy-scan/blob/main/README.md)\n- [AGENTS.md](https://github.com/decoy-run/decoy-scan/blob/main/AGENTS.md)\n- [CHANGELOG.md](https://github.com/decoy-run/decoy-scan/blob/main/CHANGELOG.md)\n</details>\n\n# GitHub Action 集成\n\n## 概述\n\ndecoy-scan 提供官方的 GitHub Action，用于在 CI/CD 流水线中自动化扫描 MCP 配置。该 Action 无需安装依赖，一行配置即可将 MCP 安全扫描集成到现有的 GitHub 工作流中，支持策略强制执行和 SARIF 结果上传功能。资料来源：[README.md:52-60]()\n\n## 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 自动发现 | 扫描仓库中的 MCP 配置文件 |\n| 策略强制 | 根据规则失败构建 |\n| SARIF 上传 | 将结果上传至 GitHub Security Tab |\n| 多主机支持 | 支持 Claude Desktop、Cursor、Windsurf、VS Code、Claude Code、Zed、Cline |\n\n## 工作原理\n\n```mermaid\ngraph TD\n    A[触发工作流] --> B[检出代码]\n    B --> C[运行 decoy-scan]\n    C --> D{扫描结果}\n    D -->|通过| E[✅ 成功]\n    D -->|有风险| F[🚨 失败 + 上传 SARIF]\n    D -->|仅 SARIF| G[上传 SARIF]\n    F --> H[GitHub Security Tab]\n    G --> H\n```\n\n## 使用方式\n\n### 基础配置\n\n在 `.github/workflows/mcp-security.yml` 中添加以下内容：\n\n```yaml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n```\n\n资料来源：[README.md:52-66]()\n\n### 完整配置示例\n\n```yaml\nname: MCP Security\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: decoy-run/decoy-scan@v1\n        with:\n          policy: no-critical,no-poisoning,no-toxic-flows\n          sarif: true\n          report: true\n          token: ${{ secrets.DECOY_TOKEN }}\n          verbose: false\n```\n\n## 输入参数\n\n| 参数 | 默认值 | 必填 | 说明 |\n|------|--------|------|------|\n| `policy` | `no-critical,no-poisoning` | 否 | 逗号分隔的策略规则 |\n| `sarif` | `true` | 否 | 上传 SARIF 到 GitHub Security Tab |\n| `report` | `false` | 否 | 上传到 Decoy Guard 仪表板 |\n| `token` | — | 条件 | Decoy API 令牌（仅 `report: true` 时需要） |\n| `verbose` | `false` | 否 | 显示所有工具包括低风险项 |\n\n资料来源：[README.md:68-76]()\n\n## 策略规则\n\n| 规则 | 说明 |\n|------|------|\n| `no-critical` | 遇到关键工具（代码执行、文件写入）时失败 |\n| `no-high` | 遇到高风险工具（文件读取、网络请求）时失败 |\n| `no-poisoning` | 检测到提示词注入时失败 |\n| `no-toxic-flows` | 检测到跨服务器数据泄露或破坏性链时失败 |\n| `no-secrets` | 检测到 MCP 配置中暴露的密钥时失败 |\n| `require-tripwires` | decoy-tripwire 未安装时失败 |\n| `max-critical=N` | 关键工具数量超过阈值时失败 |\n\n## 输出变量\n\nAction 执行后生成以下输出供后续步骤使用：\n\n| 输出 | 说明 |\n|------|------|\n| `exit-code` | 扫描退出码（0=通过, 1=高风险, 2=严重/投毒） |\n| `sarif-file` | 生成的 SARIF 文件路径 |\n| `summary` | 扫描摘要信息 |\n\n```yaml\nsteps:\n  - id: scan\n    uses: decoy-run/decoy-scan@v1\n  - name: 使用结果\n    run: |\n      echo \"Exit code: ${{ steps.scan.outputs.exit-code }}\"\n      echo \"Summary: ${{ steps.scan.outputs.summary }}\"\n```\n\n资料来源：[action.yml:55-60]()\n\n## SARIF 集成\n\n启用 `sarif: true` 后，Action 会自动：\n\n1. 生成 SARIF 2.1.0 格式的扫描报告\n2. 上传到 GitHub Security Tab\n3. 在 Pull Request 中显示安全警告\n\n```yaml\n- name: Upload SARIF to GitHub Security\n  if: always() && inputs.sarif == 'true' && steps.scan.outputs.sarif-file != ''\n  uses: github/codeql-action/upload-sarif@v3\n  with:\n    sarif_file: ${{ steps.scan.outputs.sarif-file }}\n    category: decoy-scan\n  continue-on-error: true\n```\n\n资料来源：[action.yml:68-76]()\n\n## 工作流状态处理\n\n```mermaid\ngraph TD\n    A[decoy-scan 执行] --> B{退出码}\n    B -->|0| C[✅ Clean - 无问题]\n    B -->|1| D[⚠️ Warnings - 高风险问题]\n    B -->|2| E[🚨 Failed - 严重/投毒]\n    C --> F[写入 GITHUB_STEP_SUMMARY]\n    D --> F\n    E --> F\n    F --> G[Exit 1 失败构建]\n```\n\nAction 使用 `set +e` 捕获退出码，不会立即失败 step，确保 SARIF 上传和摘要写入在所有情况下都能执行。资料来源：[action.yml:38-50]()\n\n## GitHub Step Summary\n\nAction 会在 GitHub Actions 运行日志中生成摘要：\n\n```markdown\n## Decoy Scan\n\n✅ **Clean** — no issues found\n```\n\n或\n\n```markdown\n## Decoy Scan\n\n🚨 **Issues found** — N servers scanned, N critical, N high\n\nRun `npx decoy-scan -v` locally for full details.\n```\n\n## 版本管理\n\n| 版本 | 说明 |\n|------|------|\n| `@v1` | 主版本，稳定接口 |\n| `@latest` | 始终指向最新发布 |\n| `@0.x.x` | 指定具体版本 |\n\n建议使用 `@v1` 以接收 bug 修复和安全更新，同时保持接口稳定性。\n\n## 与 decoy-scan CLI 的对比\n\n| 特性 | GitHub Action | CLI |\n|------|--------------|-----|\n| 部署方式 | GitHub 市场 | npx |\n| SARIF 上传 | 内置 | 需手动配置 |\n| 策略强制 | 通过 `policy` 参数 | 通过 `--policy` 参数 |\n| CI 集成 | 原生 | 需编写 YAML |\n| 密钥管理 | GitHub Secrets | 环境变量 |\n\n## 故障排除\n\n### SARIF 未上传\n\n确保 `permissions: security-events: write` 已配置：\n\n```yaml\npermissions:\n  security-events: write\n```\n\n### 构建未失败但有安全问题\n\n检查 `policy` 参数是否包含所需的规则：\n\n```yaml\nwith:\n  policy: no-critical,no-poisoning\n```\n\n### 令牌相关错误\n\n验证 Decoy API 令牌格式正确且未过期：\n\n```yaml\nwith:\n  token: ${{ secrets.DECOY_TOKEN }}\n```\n\n## 相关文档\n\n- [decoy-scan 主文档](https://decoy.run/docs/scan/overview)\n- [OWASP Agentic Top 10 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)\n- [SARIF 规范](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：decoy-run/decoy-scan\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | release_recency=unknown\n\n<!-- canonical_name: decoy-run/decoy-scan; human_manual_source: deepwiki_human_wiki -->\n",
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "Human Manual / 人类版说明书"
    },
    "pitfall_log": {
      "asset_id": "pitfall_log",
      "filename": "PITFALL_LOG.md",
      "markdown": "# Pitfall Log / 踩坑日志\n\n项目：decoy-run/decoy-scan\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1185640470 | https://github.com/decoy-run/decoy-scan | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# decoy-scan - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 decoy-scan 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想检查一个 AI 工具或 Agent 工作流在权限、提示注入和数据泄露上的风险。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Security scanner for MCP server configurations. Like npm audit, but for your AI agent tool servers. Finds risky tools, input validation gaps, transport vulnerabilities, and over-permissioned capability chains. Open source, zero dependencies. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. getting-started：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. cli-usage：命令行工具。围绕“命令行工具”模拟一次用户任务，不展示安装或运行结果。\n4. security-checks：安全检查项目。围绕“安全检查项目”模拟一次用户任务，不展示安装或运行结果。\n5. risk-classification：风险分级系统。围绕“风险分级系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. getting-started\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. cli-usage\n输入：用户提供的“命令行工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. security-checks\n输入：用户提供的“安全检查项目”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. risk-classification\n输入：用户提供的“风险分级系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / getting-started：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / cli-usage：Step 3 必须围绕“命令行工具”形成一个小中间产物，并等待用户确认。\n- Step 4 / security-checks：Step 4 必须围绕“安全检查项目”形成一个小中间产物，并等待用户确认。\n- Step 5 / risk-classification：Step 5 必须围绕“风险分级系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/decoy-run/decoy-scan\n- https://github.com/decoy-run/decoy-scan#readme\n- README.md\n- package.json\n- bin/cli.mjs\n- index.mjs\n- action.yml\n- lib/explain.mjs\n- lib/scan.mjs\n- lib/patterns.mjs\n- lib/tier.mjs\n- lib/owasp.mjs\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 decoy-scan 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
      "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
      "title": "Prompt Preview / 安装前试用 Prompt"
    },
    "quick_start": {
      "asset_id": "quick_start",
      "filename": "QUICK_START.md",
      "markdown": "# Quick Start / 官方入口\n\n项目：decoy-run/decoy-scan\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx decoy-scan\n```\n\n来源：https://github.com/decoy-run/decoy-scan#readme\n\n## 来源\n\n- repo: https://github.com/decoy-run/decoy-scan\n- docs: https://github.com/decoy-run/decoy-scan#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_433a8a227aee446a86b78cc771e0d20b"
}