codeql

CodeQL 分析

支持的语言：Python、JavaScript/TypeScript、Go、Java/Kotlin、C/C++、C#、Ruby、Swift。

**技能资源：**参考文件和模板位于 references/ 和 workflows/。

基本原则

1. **数据库质量不容妥协。**数据库能成功构建，并不代表质量合格。始终进行质量评估（文件数量、基线 LoC、提取器错误），并与预期的源文件进行比较。缓存构建不会产生任何有用的提取结果。

2. **数据扩展能捕获 CodeQL 遗漏的问题。**即便使用标准框架（Django、Spring、Express）的项目，也可能围绕数据库调用、请求解析或 Shell 执行封装自定义逻辑。跳过 create-data-extensions 工作流，意味着会遗漏项目特定代码路径中的漏洞。

3. **显式指定套件可防止查询被静默丢弃。**切勿将包名称直接传给 codeql database analyze——每个包的 defaultSuiteFile 都会应用隐藏筛选条件，可能导致结果为零。始终生成自定义 .qls 套件文件。

4. **发现结果为零时应调查，而非庆祝。**零结果可能意味着数据库质量不佳、缺少模型、查询包错误，或套件筛选静默生效。报告未发现问题之前，务必先调查。

5. **macOS Apple Silicon 运行编译型语言时需要变通方案。**退出代码 137 表示 arm64e/arm64 不匹配，并非构建失败。尝试使用 Homebrew arm64 工具或 Rosetta，再考虑退回 build-mode=none。

6. **逐步遵循工作流。**选定工作流后，应逐步执行，不要跳过阶段。每个阶段都是下一阶段的前置条件——跳过质量评估或数据扩展会导致分析不完整。

输出目录

所有生成的文件（数据库、构建日志、诊断信息、扩展、结果）都存储在同一个输出目录中。

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

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

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

在执行任何工作流之前，输出目录只解析一次。所有工作流都会接收 $OUTPUT_DIR，并将其生成的文件存储在该目录中：

$OUTPUT_DIR/
├── rulesets.txt                 # Selected query packs (logged after Step 3)
├── codeql.db/                   # CodeQL database (dir containing codeql-database.yml)
├── build.log                    # Build log
├── codeql-config.yml            # Exclusion config (interpreted languages)
├── diagnostics/                 # Diagnostic queries and CSVs
├── extensions/                  # Data extension YAMLs
├── raw/                         # Unfiltered analysis output
│   ├── results.sarif
│   └── <mode>.qls
└── results/                     # Final results (filtered for important-only, copied for run-all)
    └── results.sarif

数据库发现

如果目录中存在标记文件 codeql-database.yml，则该目录被视为 CodeQL 数据库。搜索现有数据库时，务必收集所有匹配项——之前的运行可能生成了多个数据库，也可能为不同语言生成了多个数据库。

发现命令：

# Find ALL CodeQL databases (top-level and one subdirectory deep)
find . -maxdepth 3 -name "codeql-database.yml" -not -path "*/\.*" 2>/dev/null \
  | while read -r yml; do dirname "$yml"; done

• 在 $OUTPUT_DIR 中：find "$OUTPUT_DIR" -maxdepth 2 -name "codeql-database.yml"
• 在整个项目范围内（用于自动检测）：find . -maxdepth 3 -name "codeql-database.yml"——可搜索项目顶层（./db-name/）以及深一层子目录（./subdir/db-name/）中的数据库，不会继续深入搜索。

切勿假定数据库名为 codeql.db——应通过标记文件发现数据库。

发现多个数据库时：

对于每个发现的数据库，都收集元数据以帮助用户选择：

# For each database, extract language and creation time
for db in $FOUND_DBS; do
  CODEQL_LANG=$(codeql resolve database --format=json -- "$db" 2>/dev/null | jq -r '.languages[0]')
  CREATED=$(grep '^creationMetadata:' -A5 "$db/codeql-database.yml" 2>/dev/null | grep 'creationTime' | awk '{print $2}')
  echo "$db — language: $CODEQL_LANG, created: $CREATED"
done

然后使用 AskUserQuestion 让用户选择要使用的数据库，或选择新建数据库。如果用户已在提示词中明确说明要使用哪个数据库或要新建数据库，则跳过 AskUserQuestion。

快速开始

对于常见场景（“扫描此代码库以查找漏洞”）：

# 1. Verify CodeQL is installed
if ! command -v codeql >/dev/null 2>&1; then
  echo "NOT INSTALLED: codeql binary not found on PATH"
else
  codeql --version || echo "ERROR: codeql found but --version failed (check installation)"
fi

# 2. Resolve output directory
BASE="static_analysis_codeql"; N=1
while [ -e "${BASE}_${N}" ]; do N=$((N + 1)); done
OUTPUT_DIR="${BASE}_${N}"; mkdir -p "$OUTPUT_DIR"

然后使用以下工作流执行完整流程：构建数据库 → 创建数据扩展 → 运行分析。

适用场景

• 通过深入的数据流分析扫描代码库中的安全漏洞
• 从源代码构建 CodeQL 数据库（支持为编译型语言构建）
• 查找需要跨过程污点跟踪或 AST/CFG 分析的复杂漏洞
• 使用多个查询包执行全面的安全审计

不适用的场景

• 编写自定义查询——使用专用的查询开发技能
• CI/CD 集成——直接使用 GitHub Actions 文档
• 快速搜索模式——使用 Semgrep 或 grep 提高速度
• 无法为编译型语言构建——考虑改用 Semgrep
• 单文件或轻量级分析——对于简单的模式匹配，Semgrep 更快

应拒绝的自我安慰

这些捷径会导致遗漏发现。不要接受：

• “security-extended 已经够用了”——它只是基线。务必检查是否有适用于该语言的 Trail of Bits 包和 Community Packs。它们能捕获 security-extended 完全遗漏的类别。
• “数据库构建成功了，所以没问题”——数据库构建成功，不代表提取质量良好。务必进行质量评估，并将文件数量与预期的源文件数量进行核对。
• “标准框架不需要数据扩展”——即使是 Django/Spring 应用，也有 CodeQL 未建模的自定义封装。跳过扩展意味着遗漏漏洞。
• “对于编译型语言，build-mode=none 没问题”——这会导致分析严重不完整。只能作为最后手段。在 macOS 上，先尝试 arm64 工具链解决方法或 Rosetta。
• “macOS 上构建失败了，直接用 build-mode=none 就好”——退出代码 137 是由 arm64e/arm64 不匹配导致的，并非根本性的构建失败。请参阅 macos-arm64e-workaround.md。
• “没有发现就说明代码安全”——零发现可能意味着数据库质量较差、缺少模型，或查询包有误。报告结果干净之前，先进行调查。
• “我就运行默认套件” / “我直接传入包名”——每个包的 defaultSuiteFile 都会应用隐藏筛选条件，可能导致结果为零。务必使用显式的套件引用。
• “我把文件放在当前目录就行”——所有生成的文件都必须放在 $OUTPUT_DIR 中。将文件散落在工作目录会导致无法清理，还有覆盖之前运行结果的风险。
• “我就用找到的第一个数据库”——可能存在用于不同语言或来自先前运行的多个数据库。找到多个数据库时，应向用户列出所有选项。只有用户已经指定要使用哪个数据库时，才跳过询问。
• “用户说了‘扫描’，就是让我选数据库”——“扫描”并不代表选择数据库。如果存在多个数据库而用户没有指定，应当询问。

---

工作流选择

此技能包含三个工作流。选定工作流后，必须逐步执行，不得跳过任何阶段。

工作流	用途
build-database	按顺序使用构建方法创建 CodeQL 数据库
create-data-extensions	检测或生成项目 API 的数据扩展模型
run-analysis	选择规则集、执行查询、处理结果

自动检测逻辑

如果用户明确指定要执行的操作（例如，“构建数据库”“对 ./my-db 运行分析”），则直接执行相应工作流。如果用户的提示已清楚表达意图，则不要调用 AskUserQuestion 来选择数据库——例如，“构建一个新数据库”“分析 static_analysis_codeql_2 中的 codeql 数据库”“从头开始运行完整扫描”。

**对于“测试”“扫描”“分析”或类似请求的默认流程：**先查找现有数据库，再做决定。

# Find ALL CodeQL databases by looking for codeql-database.yml marker file
# Search top-level dirs and one subdirectory deep
FOUND_DBS=()
while IFS= read -r yml; do
  db_dir=$(dirname "$yml")
  codeql resolve database -- "$db_dir" >/dev/null 2>&1 && FOUND_DBS+=("$db_dir")
done < <(find . -maxdepth 3 -name "codeql-database.yml" -not -path "*/\.*" 2>/dev/null)

echo "Found ${#FOUND_DBS[@]} existing database(s)"

条件	操作
未找到数据库	确定新的 $OUTPUT_DIR，执行构建 → 扩展 → 分析（完整流程）
找到一个数据库	使用 AskUserQuestion：询问是复用该数据库还是新建
找到多个数据库	使用 AskUserQuestion：列出所有数据库及其元数据，让用户选择一个或新建
用户已明确说明意图	跳过 AskUserQuestion，直接按用户指示操作

数据库选择提示词

当发现现有数据库，且用户未明确指定要使用哪个数据库时，通过 AskUserQuestion 提示：

header: "Existing CodeQL Databases"
question: "I found existing CodeQL database(s). What would you like to do?"
options:
  - label: "<db_path_1> (language: python, created: 2026-02-24)"
    description: "Reuse this database"
  - label: "<db_path_2> (language: cpp, created: 2026-02-23)"
    description: "Reuse this database"
  - label: "Build a new database"
    description: "Create a fresh database in a new output directory"

选择后：

• 如果用户选择现有数据库： 将 $OUTPUT_DIR 设置为其父目录（或包含该数据库的目录），将 $DB_NAME 设置为所选路径，然后继续执行扩展 → 分析。
• 如果用户选择“Build new”： 确定新的 $OUTPUT_DIR，执行构建 → 扩展 → 分析。

通用决策提示词

如果用户的意图不明确（既未说明数据库选择，也未说明工作流），请询问：

I can help with CodeQL analysis. What would you like to do?

1. **Full scan (Recommended)** - Build database, create extensions, then run analysis
2. **Build database** - Create a new CodeQL database from this codebase
3. **Create data extensions** - Generate custom source/sink models for project APIs
4. **Run analysis** - Run security queries on existing database

[If databases found: "I found N existing database(s): <list paths with language>"]
[Show output directory: "Output will be stored in <OUTPUT_DIR>"]

---

参考索引

文件	内容
工作流
workflows/build-database.md	按构建方法顺序创建数据库
workflows/create-data-extensions.md	数据扩展生成流程
workflows/run-analysis.md	查询执行与结果处理
参考资料
references/macos-arm64e-workaround.md	Apple Silicon 构建追踪的解决方法
references/build-fixes.md	构建失败修复目录
references/quality-assessment.md	数据库质量指标与改进
references/extension-yaml-format.md	数据扩展 YAML 列定义与示例
references/sarif-processing.md	用于处理 SARIF 输出的 jq 命令
references/diagnostic-query-templates.md	用于枚举 source/sink 的 QL 查询
references/important-only-suite.md	仅重要项套件模板与生成
references/run-all-suite.md	全部运行套件模板
references/ruleset-catalog.md	按语言分类的可用查询包
references/threat-models.md	威胁模型配置
references/language-details.md	特定语言的构建与提取详情
references/performance-tuning.md	内存、线程与超时配置

---

成功标准

完整的 CodeQL 分析运行应满足以下条件：

• 已确定输出目录（由用户指定或使用自动递增的默认目录）
• 所有生成的文件均存储在 $OUTPUT_DIR 内
• 已构建数据库（通过 codeql-database.yml 标记发现），且通过质量评估（基线 LoC > 0，错误 < 5%）
• 已评估数据扩展——在 $OUTPUT_DIR/extensions/ 中创建，或明确说明跳过的理由
• 使用显式套件引用运行分析（而非默认包套件）
• 已使用所有已安装的查询包（官方 + Trail of Bits + 社区），或明确排除
• 已将选定的查询包记录到 $OUTPUT_DIR/rulesets.txt
• 未筛选的结果已保存在 $OUTPUT_DIR/raw/results.sarif
• 最终结果位于 $OUTPUT_DIR/results/results.sarif（仅保留重要项时为筛选后结果；全部运行时为复制结果）
• 已调查零发现结果（数据库质量、模型覆盖率、套件选择）
• 构建日志已保存在 $OUTPUT_DIR/build.log，包含所有命令、修复和质量评估