semgrep

Semgrep 安全掃描

使用自動語言偵測、透過 Task 子代理平行執行，並合併 SARIF 輸出，執行 Semgrep 掃描。

基本原則

一律使用 --metrics=off — Semgrep 預設會傳送遙測資料；--config auto 也會回傳資料。每個 semgrep 指令都必須包含 --metrics=off，以防止安全稽核期間的資料外洩。
使用者必須核准掃描計畫（步驟 3 是嚴格關卡） — 原始的「掃描此程式碼庫」要求不等於核准。必須呈現確切的規則集、目標、引擎和模式；在啟動掃描器之前等待明確的「是」/「繼續」。
第三方規則集是必要而非選用 — Trail of Bits、0xdea 和 Decurity 的規則能捕捉官方註冊表中沒有的漏洞。只要偵測到的語言相符，就應納入。
在單一訊息中啟動所有掃描 Task — 平行執行是核心效能優勢。絕不要依序啟動 Task；一律在一個回應中發出所有 Task 工具呼叫。
掃描前務必檢查 Semgrep Pro — Pro 支援跨檔案污點追蹤，可捕捉約 250% 更多的真實漏洞。跳過檢查意味著默默遺漏關鍵的跨檔案漏洞。

使用時機

程式碼庫安全稽核
在程式碼審查前尋找漏洞
掃描已知的錯誤模式
初步靜態分析

不應使用時機

二進位分析 → 使用二進位分析工具
已設定 Semgrep CI → 使用現有管線
需要跨檔案分析但無 Pro 授權 → 考慮使用 CodeQL 作為替代方案
建立自訂 Semgrep 規則 → 使用 semgrep-rule-creator 技能
將現有規則移植到其他語言 → 使用 semgrep-rule-variant-creator 技能

輸出目錄

所有掃描結果、SARIF 檔案和暫存資料都儲存在單一輸出目錄中。

如果使用者在提示中指定了輸出目錄，則將其用作 OUTPUT_DIR。
如果未指定，則預設為 ./static_analysis_semgrep_1。如果該目錄已存在，則遞增為 _2、_3 等。

在兩種情況下，一律使用 mkdir -p 建立目錄，然後再寫入任何檔案。

# 解析輸出目錄
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                 # 已核准的規則集（步驟 3 後記錄）
├── raw/                         # 每次掃描的原始輸出（未過濾）
│   ├── python-python.json
│   ├── python-python.sarif
│   ├── python-django.json
│   ├── python-django.sarif
│   └── ...
└── results/                     # 最終合併輸出
    └── 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 中選擇模式。模式會影響掃描器旗標和後處理。

模式	覆蓋範圍	回報的發現
全部執行	所有規則集，所有嚴重性等級	全部
僅重要項目	所有規則集，預先和事後過濾	僅安全漏洞，中高可信度/影響

僅重要項目 套用兩層過濾：

預先過濾：--severity MEDIUM --severity HIGH --severity CRITICAL（CLI 旗標）
事後過濾：JSON 元資料 — 僅保留 category=security、confidence∈{MEDIUM,HIGH}、impact∈{MEDIUM,HIGH}

請參閱 scan-modes.md 了解元資料條件和 jq 過濾指令。

編排架構

┌──────────────────────────────────────────────────────────────────┐
│ 主要代理（此技能）                                                │
│ 步驟 1：偵測語言 + 檢查 Pro 可用性                                │
│ 步驟 2：選擇掃描模式 + 規則集（參考：rulesets.md）                 │
│ 步驟 3：呈現計畫 + 規則集，取得核准 [⛔ 嚴格關卡]                   │
│ 步驟 4：啟動平行掃描 Task（已核准的規則集 + 模式）                 │
│ 步驟 5：合併結果並回報                                           │
└──────────────────────────────────────────────────────────────────┘
         │ 步驟 4
         ▼
┌─────────────────┐
│ 掃描 Task       │
│ （平行）         │
├─────────────────┤
│ Python 掃描器   │
│ JS/TS 掃描器    │
│ Go 掃描器       │
│ Docker 掃描器   │
└─────────────────┘

工作流程

請遵循 scan-workflow.md 中的詳細工作流程。 摘要：

步驟	動作	關卡	主要參考
1	解析輸出目錄，偵測語言 + Pro 可用性	—	使用 Glob，非 Bash
2	選擇掃描模式 + 規則集	—	rulesets.md
3	呈現計畫，取得明確核准	⛔ 嚴格	AskUserQuestion
4	啟動平行掃描 Task	—	scanner-task-prompt.md
5	合併結果並回報	—	合併腳本（如下）

Task 強制執行： 呼叫時，建立 5 個具有 blockedBy 相依性的 Task（每個步驟阻擋前一個）。步驟 3 是嚴格關卡 — 僅在使用者明確核准後才標記為完成。

合併指令（步驟 5）：

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

代理

代理	工具	用途
`static-analysis:semgrep-scanner`	Bash	為語言類別執行平行 semgrep 掃描

在步驟 4 啟動 Task 子代理時，使用 subagent_type: static-analysis:semgrep-scanner。

應拒絕的合理化藉口

捷徑	為何錯誤
"使用者要求掃描，那就是核准"	原始要求 ≠ 計畫核准。呈現計畫，使用 AskUserQuestion，等待明確的「是」
"步驟 3 的 Task 在阻擋，直接標記完成"	謊報 Task 狀態會破壞強制執行。僅在真正核准後才標記完成
"我已經知道他們要什麼"	假設會導致掃描錯誤的目錄/規則集。呈現計畫以供驗證
"只用預設規則集"	使用者必須在掃描前看到並核准確切的規則集
"未經詢問就加入額外規則集"	未經同意修改已核准的清單會破壞信任
"第三方規則集是選用的"	Trail of Bits、0xdea、Decurity 能捕捉官方註冊表中沒有的漏洞 — 必要
"使用 --config auto"	會傳送指標；對規則集的控制較少
"一次一個 Task"	破壞平行性；應一起啟動所有 Task
"Pro 太慢，跳過 --pro"	跨檔案分析可捕捉 250% 更多的真實漏洞；值得花時間
"Semgrep 原生支援 GitHub URL"	URL 處理在具有非標準 YAML 的儲存庫上會失敗；一律先複製
"清理是選用的"	複製的儲存庫會污染使用者的工作區，並在多次執行中累積
"使用 `.` 或相對路徑作為目標"	子代理需要絕對路徑以避免歧義
"讓使用者稍後選擇輸出目錄"	輸出目錄必須在步驟 1 解析，在任何檔案建立之前

參考索引

檔案	內容
rulesets.md	完整規則集目錄和選擇演算法
scan-modes.md	預先/事後過濾條件和 jq 指令
scanner-task-prompt.md	啟動掃描子代理的範本