semgrep

Semgrep 安全扫描

运行 Semgrep 扫描，自动检测语言；宿主支持委派时通过子 Agent 并行执行（否则顺序扫描），并合并生成 SARIF 输出。

核心原则

1. 始终使用 --metrics=off — Semgrep 默认会发送遥测数据；--config auto 也会向外部发送请求。每条 semgrep 命令都必须包含 --metrics=off，以防安全审计期间泄露数据。
2. 用户必须批准扫描计划（步骤 3 是硬性门槛） — 用户原先提出的“扫描此代码库”请求不代表批准。请列出确切的规则集、目标、引擎和模式；等待用户明确回复“是”或“继续”后再启动扫描器。
3. 第三方规则集是必需项，而非可选项 — Trail of Bits、0xdea 和 Decurity 规则可以捕获官方注册表中没有的漏洞。检测到的语言匹配时，必须包含这些规则集。
4. 宿主支持子 Agent 委派时，始终并发启动所有扫描 — 按语言／类别并行执行是主要的性能优势。如果宿主没有子 Agent／并行任务机制，则按顺序运行扫描，而不是一次只运行一个 Task。
5. 扫描前始终检查是否有 Semgrep Pro — Pro 可启用跨文件污点追踪，并多捕获约 250% 的真阳性。跳过检查会导致关键的跨文件漏洞被悄然漏掉。

适用场景

• 对代码库进行安全审计
• 在代码审查前查找漏洞
• 扫描已知缺陷模式
• 初步静态分析

不适用场景

• 二进制分析 → 使用二进制分析工具
• 已配置 Semgrep CI → 使用现有流水线
• 需要跨文件分析但没有 Pro 许可证 → 考虑使用 CodeQL 作为替代方案
• 创建自定义 Semgrep 规则 → 使用 semgrep-rule-creator skill
• 将现有规则移植到其他语言 → 使用 semgrep-rule-variant-creator skill

输出目录

所有扫描结果、SARIF 文件和临时数据都存放在同一个输出目录中。

• 如果用户在提示中指定了输出目录，将其用作 OUTPUT_DIR。
• 如果未指定，则默认使用 ./static_analysis_semgrep_1。如果该目录已存在，则依次递增为 _2、_3 等。

无论哪种情况，都必须在写入任何文件之前使用 mkdir -p 创建目录。

# Resolve output directory
if [ -n "$USER_SPECIFIED_DIR" ]; then
  OUTPUT_DIR="$USER_SPECIFIED_DIR"
else
  BASE="static_analysis_semgrep"
  N=1
  while [ -e "${BASE}_${N}" ]; do
    N=$((N + 1))
  done
  OUTPUT_DIR="${BASE}_${N}"
fi
mkdir -p "$OUTPUT_DIR/raw" "$OUTPUT_DIR/results"

输出目录在步骤 1 开始时解析一次，并在后续所有步骤中使用。

$OUTPUT_DIR/
├── rulesets.txt                 # Approved rulesets (logged after Step 3)
├── raw/                         # Per-scan raw output (unfiltered)
│   ├── python-python.json
│   ├── python-python.sarif
│   ├── python-django.json
│   ├── python-django.sarif
│   └── ...
└── results/                     # Final merged output
    └── results.sarif

前置条件

必需： Semgrep CLI（semgrep --version）。如果尚未安装，请参阅 Semgrep 安装文档。

可选： Semgrep Pro — 可启用跨文件污点追踪、过程间分析和额外语言支持（Apex、C#、Elixir）。使用以下命令检查：

semgrep --pro --validate --config p/default 2>/dev/null && echo "Pro available" || echo "OSS only"

限制： OSS 模式无法追踪跨文件的数据流。Pro 模式在跨文件分析时使用 -j 1（每个规则集速度较慢，但并行运行规则集可以弥补）。

扫描模式

在工作流的步骤 2 中选择模式。模式会影响扫描器标志和后处理。

模式	覆盖范围	报告的问题
全部运行	所有规则集、所有严重级别	全部
仅重要项	所有规则集，经过前置和后置过滤	仅安全漏洞，置信度／影响为中到高

仅重要项会应用两层过滤：

1. 前置过滤：--severity MEDIUM --severity HIGH --severity CRITICAL（CLI 标志）
2. 后置过滤：JSON 元数据 — 仅保留 category=security、confidence∈{MEDIUM,HIGH}、impact∈{MEDIUM,HIGH}

元数据条件和 jq 过滤命令请参阅 scan-modes.md。

编排架构

┌──────────────────────────────────────────────────────────────────┐
│ MAIN AGENT (this skill)                                          │
│ Step 1: Detect languages + check Pro availability                │
│ Step 2: Select scan mode + rulesets (ref: rulesets.md)           │
│ Step 3: Present plan + rulesets, get approval [⛔ HARD GATE]     │
│ Step 4: Run one scan per language/category (parallel if the      │
│         host supports subagent delegation, else sequential)      │
│ Step 5: Merge results and report                                 │
└──────────────────────────────────────────────────────────────────┘
         │ Step 4
         ▼
┌─────────────────┐
│ Per-language    │
│ scan            │
├─────────────────┤
│ Python scanner  │
│ JS/TS scanner   │
│ Go scanner      │
│ Docker scanner  │
└─────────────────┘

工作流

**请遵循 scan-workflow.md 中的详细工作流。**概要：

步骤	操作	门槛	主要参考
1	确定输出目录，检测语言和 Pro 可用性	—	使用 Glob，而不是 Bash
2	选择扫描模式和规则集	—	rulesets.md
3	提出计划并获得明确批准	⛔ 硬性门槛	直接询问用户，或通过宿主提供的结构化提问工具（如果有）
4	按语言／类别分别运行一次扫描	—	scanner-task-prompt.md — 面向会委派给子 Agent 的宿主的提示词模板；否则直接执行相同步骤
5	合并结果并汇报	—	合并脚本（如下）

**执行要求：**将这 5 个步骤作为依赖链进行跟踪（每一步都会阻止下一步），使用宿主的任务跟踪工具（如果有）。第 3 步是硬性门槛——在用户明确批准计划之前，不要继续执行第 4 步。

合并命令（第 5 步）：

uv run scripts/merge_sarif.py $OUTPUT_DIR/raw $OUTPUT_DIR/results/results.sarif

需要拒绝的合理化说法

捷径	错误原因
“用户要求扫描，就等于批准了”	原始请求 ≠ 对计划的批准。提出计划，使用 AskUserQuestion，并等待明确的“是”
“第 3 步任务正在阻塞，直接标记完成就行”	谎报任务状态会破坏执行要求。只有在获得实际批准后才能标记完成
“我已经知道他们想要什么”	假设会导致扫描错误的目录／规则集。应提出计划以供核验
“直接使用默认规则集”	扫描前，用户必须看到并批准确切的规则集
“不询问就添加额外规则集”	未经同意修改已批准的列表会破坏信任
“第三方规则集是可选的”	Trail of Bits、0xdea、Decurity 能发现官方注册表中没有的漏洞——这是必需的
“使用 --config auto”	这会发送指标；对规则集的控制也更少
“可以并行时仍一次只运行一个扫描”	这会失去性能优势；宿主支持时，应并发运行所有按语言划分的扫描
“Pro 太慢，跳过 --pro”	跨文件分析可多发现 250% 的真阳性；值得花费时间
“Semgrep 原生支持 GitHub URL”	对采用非标准 YAML 的仓库，URL 处理会失败；务必先克隆
“清理是可选的”	克隆的仓库会污染用户的工作区，并在多次运行中不断累积
“将 . 或相对路径用作目标”	并行／委派扫描需要绝对路径，以避免歧义
“稍后再让用户选择输出目录”	必须在第 1 步确定输出目录，且要在创建任何文件之前

参考索引

文件	内容
rulesets.md	完整的规则集目录和选择算法
scan-modes.md	前置／后置筛选条件和 jq 命令
scanner-task-prompt.md	将按语言划分的扫描委派给子 Agent 的提示词模板

工作流	用途
scan-workflow.md	完整的 5 步扫描执行流程

成功标准

• 已确定输出目录（用户指定或自动递增的默认目录）
• 所有生成的文件均存储在 $OUTPUT_DIR 中
• 已检测语言并统计文件数量；已检查 Pro 状态
• 用户已选择扫描模式（全部运行 / 仅扫描重要项）
• 规则集包含所有已检测语言的第三方规则
• 用户已明确批准扫描计划（已通过步骤 3 的关卡）
• 已并发启动所有按语言划分的扫描（如果宿主不支持委派，则按顺序启动），且扫描已完成
• 每条 semgrep 命令均使用了 --metrics=off
• 已将获批的规则集记录到 $OUTPUT_DIR/rulesets.txt
• 各次扫描的原始输出均存储在 $OUTPUT_DIR/raw/ 中
• $OUTPUT_DIR/results/ 中存在 results.sarif，且其为有效 JSON
• 仅扫描重要项模式：已在合并前应用后置筛选；未经筛选的结果保留在 raw/ 中
• 已报告结果摘要，并按严重程度和类别细分
• 已从 $OUTPUT_DIR/repos/ 清理克隆的仓库（如有）