前言¶
在倉庫裏做安全掃描，常見做法是各自裝一套 CodeQL 或 Semgrep，記一堆 CLI 參數，再把多份 JSON/SARIF 手工合併。模型輔助編碼時，更容易出現「漏關 telemetry」「規則集未經確認就掃」「構建失敗卻當成無漏洞」這類流程問題。
Trail of Bits 在 skills 市場裏提供的 static-analysis 插件，把深度分析（CodeQL）、快速模式掃描（Semgrep）和結果處理（SARIF）寫成一組 Agent Skill，並附帶固定腳本與工作流命令。下面介紹它是什麼、能做什麼，以及如何安裝與調用。
這是什麼¶
static-analysis 是 Trail of Bits Skills Marketplace 裏 Code Auditing 類的一個插件，定位爲「靜態分析工具包」：用 CodeQL、Semgrep 做漏洞發現，並用 SARIF 解析與合併統一結果形態。
維護方與出處：倉庫 trailofbits/skills；插件 README 標註作者爲 Axel Mierczuk、Paweł Płatek。CodeQL 與 Semgrep 相關實踐與 Trail of Bits Testing Handbook 中的靜態分析章節對齊。
插件內包含三個 Skill（名稱即技能標識）：
| Skill | 作用 |
|---|---|
codeql |
過程間污點與數據流等深度安全分析 |
semgrep |
基於規則集的快速模式掃描 |
sarif-parsing |
解析、彙總、去重各工具輸出的 SARIF |
官方 Skill 目錄分別爲：
plugins/static-analysis/skills/codeqlplugins/static-analysis/skills/semgrepplugins/static-analysis/skills/sarif-parsing
核心功能¶
CodeQL（codeql Skill）¶
面向需要構建數據庫、跑查詢包的場景，強調「庫質量」與「顯式查詢套件」，而不是默認套件靜默過濾。
已文檔化的能力包括：
- 爲 Python、JavaScript/TypeScript、Go、Java/Kotlin、C/C++、C#、Ruby、Swift 等語言建庫並分析。
- 通過顯式
.qls引用查詢包（如security-extended、Trail of Bits、Community 等），輸出 SARIF/CSV。 - 生成 data extension，覆蓋項目自定義 API 的 source/sink。
- 構建後運行
check_db_quality.py、分析前校驗verify_query_suite.py，避免「零告警等於安全」的誤判。 - 掃描模式：
run all（security-and-quality + security-experimental）與important only（高精度子集）。
無人值守構建可走工作流 /static-analysis:codeql-build，例如：
/static-analysis:codeql-build {"target": "/abs/path", "lang": "cpp"}
工作流會按構建方法階梯（autobuild、自定義命令、多步、no-build）嘗試，並在質量門檻未達標時返回明確狀態。
Semgrep（semgrep Skill）¶
面向快速全庫或規則集驅動的第一次靜態掃描。設計要點是把「命令生成」交給腳本，減少模型手寫 CLI 時漏掉安全約束。
- 檢測語言與 Semgrep Pro 是否可用（Pro 用於跨文件污點分析）。
- 從內置與第三方規則集（文檔要求包含 Trail of Bits、0xdea、Decurity 等）組計劃，第三步必須經用戶明確批准後再執行。
- 通過
scripts/run-scans.sh批量執行掃描；強制--metrics=off，輸出寫入獨立OUTPUT_DIR。 - 用
merge_sarif.py合併爲results/results.sarif；支持run-all與important-only兩種模式。
若不需要規則集審批閘門、希望端到端一鍵跑完，可用工作流：
/static-analysis:semgrep-scan {"target": "/abs/path", "mode": "run-all"}
該命令對目標目錄只讀（無 --autofix），寫入僅限輸出目錄；若輸出目錄與掃描目標相同則拒絕執行。
SARIF（sarif-parsing Skill）¶
用於已有掃描產物時的後處理：理解 SARIF 2.1.0 結構、從 rule 繼承 severity（CodeQL 依賴此行爲）、用 jq 或 Python（pysarif、sarif-tools）做查詢，以及多文件聚合與去重、CI 集成模式。
腳本與工作流¶
| 組件 | 說明 |
|---|---|
workflows/semgrep-scan.js |
對應 /static-analysis:semgrep-scan，階段：Detect → Select → Scan → Report |
workflows/codeql-build.js |
對應 /static-analysis:codeql-build，階段：Detect → Build → Assess |
skills/semgrep/scripts/run-scans.sh |
根據選定規則集生成 semgrep 命令、克隆第三方規則倉庫、批跑並寫 scans.json |
skills/semgrep/scripts/merge_sarif.py |
合併分片 SARIF |
官方說明：掃描階段由工作流直接調用 shell 腳本，退出碼與 findings 來自工具進程與 JSON，而非模型自報。
安裝與啓用¶
先向 Claude Code 或兼容市場添加 Trail of Bits 市場，再安裝 static-analysis 插件。
Claude Code：添加市場
/plugin marketplace add trailofbits/skills
瀏覽並安裝：
/plugin menu
安裝 static-analysis 插件（插件 README 寫法）
/plugin install trailofbits/skills/plugins/static-analysis
Codex CLI
codex plugin marketplace add trailofbits/skills
codex plugin list
codex plugin add <plugin-name>@trailofbits
將 <plugin-name> 替換爲市場中的插件名（與倉庫目錄 static-analysis 對應）。Codex 文檔稱可直接兼容 Claude 插件市場，無需額外 sidecar 元數據。
本地開發時，在倉庫父目錄執行 /plugins marketplace add ./skills 可掛載本地市場副本。
運行前需在本機安裝對應 CLI：Semgrep（semgrep --version）、CodeQL（codeql --version），以及文檔中用於腳本與合併的 jq、uv 等。未在官方文檔中單獨列出的 IDE 集成方式，此處不展開。
典型用法¶
1. 讓 Agent 按 Semgrep Skill 五步走（含審批）¶
在對話中說明要對某代碼庫做 Semgrep 安全掃描。Skill 會：
- 解析輸出目錄（默認
static_analysis_semgrep_1遞增命名）。 - 檢測語言與 Pro 狀態。
- 展示規則集與模式，等待明確「同意/繼續」。
- 調用
run-scans.sh。 - 合併 SARIF 並彙報
scans.json中的failed、skipped。
目標路徑應使用絕對路徑；所有產物落在 $OUTPUT_DIR 下。
2. 工作流一鍵 Semgrep（無規則集審批）¶
適合已確認掃描範圍、只需只讀掃描的場景：
/static-analysis:semgrep-scan {"target": "/abs/path/to/repo", "mode": "run-all"}
mode 也可按 Skill 文檔選擇 important-only 等等價語義（以 references/scan-modes.md 爲準）。
3. CodeQL 全鏈路或僅構建¶
完整分析通常走：建庫 → data extensions → run-analysis 工作流；Quick Start 要求先確認 codeql、jq、uv 在 PATH 上。
僅把耗時的構建交給工作流時：
/static-analysis:codeql-build {"target": "/abs/path", "lang": "cpp"}
返回 no-method-succeeded 或 built-below-threshold 時，需在 Skill 流程裏繼續解讀日誌與質量腳本輸出，而不是直接當作掃描完成。
4. 多工具結果合併¶
Semgrep 路徑最終產物爲 $OUTPUT_DIR/results/results.sarif。若還有 CodeQL 或其他 SARIF 輸出，可啓用 sarif-parsing Skill 做 severity 解析、去重與 CI 側聚合。
適用場景與注意¶
適合：
- 需要在 AI 輔助審計裏系統化跑 SAST，且希望規則集、metrics、輸出目錄有固定約束。
- 同一倉庫既要 CodeQL 深度分析，又要 Semgrep 快速掃一遍，再統一成 SARIF。
- 與同一市場裏的
variant-analysis、semgrep-rule-creator等技能串聯（插件 README 已列出關聯）。
限制與坑：
- Semgrep 無 Pro 時跨文件污點能力受限，文檔建議此時考慮 CodeQL。
- CodeQL 對編譯型語言依賴構建；macOS Apple Silicon 上 exit 137 等需按參考文檔處理，不應默認
build-mode=none。 - 第三方規則集需要克隆倉庫；
run-scans.sh失敗時不應手工.subset 掃描冒充完整結果。 /static-analysis:semgrep-scan與semgrepSkill 共用references/，但前者跳過規則集審批；選型取決於你是否要在掃描前編輯規則列表。
插件自帶 hermetic 測試（tests/run_scan_tests.sh、tests/run_workflow_tests.sh），用於約束腳本與工作流行爲，本地改插件時可參考。
結尾¶
static-analysis 把專業 SAST 裏重複出現的步驟——選規則、關 telemetry、批跑、合併 SARIF、CodeQL 建庫與質量門禁——封裝進 Skill 與固定工作流，讓「讓模型掃一遍倉庫」更接近可審計的流程，而不是一次性 CLI 拼寫。
插件與 Skill 源碼：https://github.com/trailofbits/skills/tree/main/plugins/static-analysis
市場總覽：https://github.com/trailofbits/skills
