scan-code

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js"——如果有输出消息，请在继续之前向用户展示。

扫描代码

扫描 Power Pages 站点项目的源文件和依赖项，查找安全问题。运行 opengrep（静态分析）和 trivy（依赖项／机密信息／许可证扫描），然后汇总发现的问题。

初始请求： $ARGUMENTS

警告： 在继续之前，告知用户：“此技能使用 opengrep 和 trivy，前提是它们已安装在您的本地计算机上。这些第三方开源工具会扫描您的源代码和依赖项，并可能根据其自身的条款、隐私政策和数据处理实践收集或传输数据。Microsoft 不对这些行为进行控制。如果您选择 AI 备用方案，AI 服务会处理您的源代码。请在继续之前查看您所在组织的政策以及适用的第三方条款。”

注意事项

• 必须安装这两个工具。 运行 check-tools.js 进行验证。如果缺少任何一个工具，请提供由 Agent 执行的审查备用方案（见步骤 1.2）。
• Opengrep 在发现问题时会以状态码 1 退出。 这是正常行为，并非错误——脚本会对此进行处理。
• 输出量可能很大。 对于大型项目，这两个工具都可能生成大量 JSON。脚本会将输出整理为扁平的问题列表。
• Trivy 的严重性标志只影响漏洞发现。 无论是否设置 --severity 标志，都会返回机密信息和许可证相关发现。
• 任何情况下都不会完整显示机密信息。 无论是您直接读取源代码（由 Agent 执行的审查），还是展示发现的问题，都要运用判断力识别任何凭据——API 密钥、令牌、密码、连接字符串、私钥，或任何其他可能属于机密信息的内容（没有固定清单）。绝不在任何地方输出其原始值——无论是您的上下文、会话、聊天、日志、摘要、报告，还是任何其他输出中——哪怕只输出一部分也不行；原本需要显示该值时，请用掩码替换（例如 ********）。

工作流

1. 先决条件 — 定位项目，检查工具是否可用
2. 选择范围 — 确定扫描内容和深度
3. 运行扫描 — 执行工具，收集结果
4. 汇总 — 展示发现的问题，记录使用情况，并提供后续选项

任务跟踪

创建三个分组的任务。开始时将任务标记为 in_progress，完成后标记为 completed。

分组	创建时间	任务
1	开始时	检查先决条件
2	先决条件通过后	选择范围（审查模式下跳过）
3	确定范围后（或处于审查模式时）	运行扫描 · 汇总（始终执行）

---

1. 先决条件

1.1 定位项目，检测审查模式

使用 Glob 查找 **/powerpages.config.json。如果 $ARGUMENTS 包含 --review <out-dir>，请记下输出目录——跳过步骤 2（以高级深度运行所有检查），步骤 4 仅写入 JSON。

1.2 检查工具是否可用

node "${PLUGIN_ROOT}/skills/scan-code/scripts/check-tools.js"

如果缺少任一工具，请告知用户缺少哪种工具。然后提供由 Agent 执行审查作为备用方案：

在审查模式（非交互式）下，不要提供由 Agent 执行的审查。 这需要用户交互式选择加入，而且编排器需要一个 JSON 文件。将 { "status": "skipped", "reason": "<which tool> is not installed" } 写入 <REVIEW_DIR>/scan-code.json，然后停止。

🚦 关卡（plan · scan-code:1.agent-review-fallback）： 缺少扫描工具时，开始任何工作之前，先提供由 Agent 执行的审查作为备用方案。审查会使用 Glob/Read/Grep 读取源代码，并消耗大量 token，因此必须先征得用户同意。

触发条件： 第 1.2 步，仅当 check-tools.js 报告缺少工具时触发（仅限交互模式——审查模式下，工具缺失时会立即停止，因此不会到达此处）。 询问原因： 未经同意就自动启动由 Agent 执行的审查会消耗大量 token；用户可能更愿意先安装工具再重新运行。 取消后的状态： 无任何变更——未读取文件，也未运行扫描。

措辞——所有面向用户的文本（警告、任何 AskUserQuestion 选项标签和摘要）都不得将此称为“人工审查”。 这是由 Agent 执行的审查——请描述为 我可以直接查看你的代码并指出问题 等表述。

告知用户，此审查会读取许多文件并消耗大量 token，然后检测 git 上下文：

• 功能分支（不是 main、master 或等效分支）：提供仅审查当前分支变更的选项（git diff <main-branch>...HEAD）。
• main/master 分支或不在 git 仓库中：提供审查整个项目源代码的选项。

如果用户同意，请使用 Glob + Read + Grep 检查相关文件中的常见安全模式（硬编码密钥、不安全的 API 用法、缺少输入验证、暴露的端点等），并汇报发现的问题。绝不要在任何地方暴露密钥值——不得在任何输出中（你的上下文、会话、聊天、日志等）输出凭证的原始值，即使是部分值也不行；否则会显示值的地方，请用掩码替换（例如 ********）。不要尝试安装这些工具。

---

2. 选择范围

在审查模式下跳过——以 Advanced 深度运行两种工具。

范围选择

按以下顺序提问。每个问题都必须单独调用一次 AskUserQuestion，切勿合并。如果用户最初的请求已经回答了某个问题，则跳过该问题并继续下一个。

🚦 关卡（规划 · scan-code:2.scope-choice）： 运行任何工具前，先选择要扫描的内容——代码、软件包或两者。此选择决定运行哪些扫描器。

触发条件： 进入第 2 阶段（仅交互模式——审查模式会以 Advanced 深度扫描所有内容，不会提问）。如果用户最初的请求已指定范围，则跳过。 提问原因： 自动扫描所有内容可能会运行用户不需要的工具（例如，用户只询问软件包时却运行耗时的代码扫描）；范围选择错误会导致报告遗漏用户关心的问题。 取消后状态： 无——尚未运行任何扫描器。

问题 1 — 要检查什么？

标签	描述
全部	检查代码和软件包。（推荐）
仅代码	检查源文件中的安全问题。
仅软件包	检查已安装软件包中的已知问题。

🚦 关卡（规划 · scan-code:2.depth-choice）： 选择代码检查的深入程度。只有在包含代码检查时才会询问。

触发条件： 第 2 阶段，范围选择包含代码之后（仅交互模式）。如果用户最初的请求已指定深度，或未包含代码检查，则跳过。 提问原因： 深入选项会运行更全面的规则集，耗时更长；自动选择该选项可能会意外拖慢大型项目，而自动选择快速选项则可能悄然跳过用户预期会检查的弱点。 取消后状态： 无——尚未运行任何扫描器。

问题 2 — 仅当包含代码检查时提问：检查要多深入？

标签	描述
Advanced	涵盖常见风险和更深入的代码弱点。（推荐）
Basic	仅涵盖常见风险。

深度映射（内部使用，不向用户显示）：Advanced = p/default,p/owasp-top-ten,p/cwe-top-25。Basic = p/default,p/owasp-top-ten。

自定义规则

两种工具都支持自定义规则。不要主动提供此选项——仅在用户提供规则时使用。

• Opengrep：--rulesets 接受以逗号分隔的注册表规则包和本地文件路径。自定义规则集会附加到所选深度的默认规则集，而非替换它们。
• Trivy：--secretConfig 用于自定义密钥检测模式，--ignoreFile 用于抑制已知发现项，--trivyConfig 用于许可证分类和其他设置，--no-licenseFull 用于跳过源代码级许可证扫描以加快运行速度。

---

3. 运行扫描

将每个工具的原始 JSON 输出保存到临时文件。第 4 步中的转换脚本会对其进行规范化。

静态分析（opengrep）

node "${PLUGIN_ROOT}/skills/scan-code/scripts/run-opengrep.js" --projectRoot "<PROJECT_ROOT>" --rulesets "<comma-separated-rulesets>" > "<TEMP_DIR>/opengrep.json"

传入所选深度（Basic 或 Advanced）对应的规则集。追加用户提供的任何自定义规则集。对于大型项目，使用 run_in_background: true 运行。

依赖项／密钥／许可证扫描（trivy）

node "${PLUGIN_ROOT}/skills/scan-code/scripts/run-trivy.js" --projectRoot "<PROJECT_ROOT>" > "<TEMP_DIR>/trivy.json"

默认启用 --licenseFull——除软件包元数据外，还会扫描源代码头部和 LICENSE 文件。对于大型项目，使用 run_in_background: true 运行。

规范化

node "${PLUGIN_ROOT}/skills/scan-code/scripts/transform-scan-code.js" --opengrepFile "<TEMP_DIR>/opengrep.json" --trivyFile "<TEMP_DIR>/trivy.json" --projectRoot "<PROJECT_ROOT>"

仅传入实际运行的工具所对应的文件。标准输出为统一的 { status, findings } 结构。

---

4. 汇总

4.1 审查模式

在审查模式下，将 transform-scan-code.js 的标准输出写入 <REVIEW_DIR>/scan-code.json。然后停止——负责协调的技能会处理结果展示。

4.2 渲染 HTML 报告

在审查模式下跳过。

渲染使用与汇总安全审查相同的共享模板。先将步骤 3 的标准化输出写入 <TEMP_DIR>/scan-code.json，然后构建单节审查数据负载并进行渲染：

node "${PLUGIN_ROOT}/scripts/build-review-data.js" \
  --reportName "Code Scan" \
  --inputDir "<TEMP_DIR>" \
  --siteName "<SITE_NAME>" \
  --goalLabel "Code & Packages scan" \
  --scopeLabel "<SCOPE_LABEL>" \
  --summary "<SUMMARY_TEXT>" \
  --output "<TEMP_DIR>/data.json"

node "${PLUGIN_ROOT}/scripts/render-review.js" \
  --data "<TEMP_DIR>/data.json" \
  --output "<PROJECT_ROOT>/docs/code-scan-<YYYY-MM-DD-HHMMSS>.html"

<TEMP_DIR> 还存放步骤 3 生成的中间文件 opengrep.json/trivy.json，以及 scan-code.json；build-review-data.js 只读取 scan-code.json，忽略其余文件。文件名必须包含本地时间戳（例如，code-scan-2026-05-14-053805.html）。渲染成功后删除 <TEMP_DIR>。在浏览器中打开渲染好的 HTML。

4.3 呈现摘要

在审查模式下跳过。

用通俗易懂的语言概述：发现总数、按类别划分的数量（代码模式、易受攻击的软件包、密钥、许可证），以及用户应优先查看的内容。

4.4 记录技能使用情况

参考：${PLUGIN_ROOT}/references/skill-tracking-reference.md

使用 --skillName "ScanCode"。

4.5 提供后续建议

如果发现的问题与其他技能相关，请推荐相应技能：

• 标头 / Cookie 问题 → /manage-headers
• WAF / 防火墙问题 → /manage-firewall
• 权限问题 → /audit-permissions，用于检查现有权限；和/或 /create-webroles，用于设置基于角色的访问控制
• 登录或外部身份问题 → /setup-auth
• 代码层面的问题（暴露的调试页面、信息泄露）→ 建议手动修复代码

如果没有有意义的后续建议，则结束此技能。

---

约束

• 通俗易懂——绝不能对用户使用技术术语。切勿使用 opengrep、trivy、OWASP、CWE、静态分析、SAST 或规则集等词语。使用日常用语，例如“检查代码中的安全问题”“检查软件包是否存在已知问题”“全面检查”“快速检查”。只有在用户询问时才解释技术名称。对于工具缺失时的备用方案，绝不能称其为“手动审查”——该工作由 Agent 执行；请描述为由你亲自检查代码。
• 后台运行耗时较长的调用——对于大型项目，运行这两个工具时都要使用 run_in_background: true。
• 根据上下文进行交互——建议必须反映网站的实际扫描结果。不要给出泛泛的建议。
• 建议不得破坏网站——建议修复代码问题时，要确认修复不会引入回归问题。
• 绝不要建议降低安全性——如果某项发现表明应加强限制（例如移除硬编码的密钥），不要为了方便而建议保留它。
• 绝不泄露密钥值——绝不要在任何地方输出、记录、存储或重复原始密钥，即使只重复一部分，或其被正则表达式 / grep 匹配到也不行。识别密钥发现时，应说明其类型、文件和行号，而不是密钥值。屏蔽处理（例如 ********）仅适用于原本会显示密钥值的情况；不要求显示该值。

参考资料

• references/commands.md——脚本标志和响应格式。构造脚本调用时请阅读。