需要跨过程数据流/污点分析查找多语言仓库安全漏洞时，用…

适用于对 Python、JavaScript/TypeScript、Go、Java/Kotlin、C/C++、C#、Ruby、Swift 代码库执行 CodeQL SAST 扫描并产出 SARIF。

适用场景

解决思路

1. 使用 CodeQL 的跨过程数据流和污点跟踪分析扫描代码库安全漏洞；支持 Python、JavaScript/TypeScript、Go、Java/Kotlin、C/C++、C#、Ruby、Swift。
2. 使用 {baseDir}/references/ 和 {baseDir}/workflows/ 中的参考文件和模板。
3. 坚持数据库质量不可妥协：数据库能构建不代表质量好；缓存的构建可能提取不到内容却报告成功。
4. 用数据扩展捕获 CodeQL 遗漏：Django、Spring、Express 等项目仍会用项目特定 API 包装数据库调用、请求解析和 shell 执行，需创建数据扩展模型。
5. 始终生成 .qls 显式 suite 引用，绝不把 pack 名称直接传给 codeql database analyze；每个 pack 的 defaultSuiteFile 有隐藏过滤，可能导致零结果。
6. 零发现时调查而非庆祝：可能因提取差、模型缺失、错误 pack 或 suite 过滤；构建后运行 {baseDir}/scripts/check_db_quality.py，确认 {baseDir}/scripts/verify_query_suite.py 对所用 suite 退出零（生成脚本会运行它，仅复用或手工编辑的 suite 需手动调用），并在报告中说明两者通过。
7. macOS Apple Silicon 编译语言需 workaround：退出码 137 是 arm64e/arm64 不匹配，不是构建失败；先尝试 Homebrew arm64 工具或 Rosetta，再回退 build-mode=none。
8. 按工作流逐步执行：每个阶段门控下一阶段；跳过质量评估或数据扩展会让缺口在结果中不可见。
9. 每个 Bash 调用都是新 shell：变量、数组、从 build_log.sh source 的函数都不保留；每个使用值的代码块必须在该块内重新建立。
10. 注意丢失 function 会让 run_logged 退出 127，构建阶梯会把它读成失败方法并走到 --build-mode=none，从未调用 CodeQL。
11. 注意丢失 array 会展开为空，导致用户选择的每个 --threat-model 和 --model-packs 被丢弃，而最终报告仍列出它们为已使用。
12. 注意丢失 scalar 在 set -u 下会以 unbound variable 中止块。
13. 所有生成文件（数据库、构建日志、诊断、扩展、结果）存放在单一输出目录。
14. 若用户指定输出目录，将其用作 OUTPUT_DIR；若未指定，默认 ./static_analysis_codeql_1，若已存在则递增到 _2、_3 等。
15. 写入任何文件前始终用 mkdir -p 创建目录。
16. 运行前将 USER_SPECIFIED_DIR 设为用户提示中的字面路径，或留空以自动递增。
17. 使用提供的解析块：设置 USER_SPECIFIED_DIR，判断是否为空，否则 BASE=static_analysis_codeql，N=1，while [ -e ${BASE}_${N} ]; do N=$((N + 1)); done，OUTPUT_DIR=${BASE}_${N}，然后 mkdir -p $OUTPUT_DIR。
18. 输出目录在工作流执行前只解析一次；所有工作流接收 $OUTPUT_DIR 并把工件存到那里；目录结构包括 rulesets.txt、codeql.db/、build.log、codeql-config.yml、diagnostics/、extensions/、raw/results.sarif、raw/run-all.qls 或 important-only.qls、results/results.sarif。
19. 数据库发现：CodeQL 数据库由目录内存在 codeql-database.yml 标记文件识别。
20. 搜索现有数据库时总是收集所有匹配；可能有多个来自先前运行或不同语言的数据库。
21. 使用 find_databases.sh 打印每个数据库路径一行，过滤失败构建留下的标记文件。
22. 在同一块中构建数组并从中选择，因为每个 Bash 调用是新 shell；如果跨调用，数组为空，运行会认为没有数据库。
23. 使用命令替换而不是进程替换：if ! DB_LIST=$({baseDir}/scripts/find_databases.sh ${OUTPUT_DIR:-.} .); then 报错 database discovery failed 并 exit 1; fi。
24. 用 while IFS= read -r db; do [ -n $db ] || continue; FOUND_DBS+=($db); done <<<$DB_LIST 构建 FOUND_DBS。
25. 打印 Found ${#FOUND_DBS[@]} existing database(s)。
26. 选择提示所需元数据在同一块收集：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。
27. 永远不要假设数据库命名为 codeql.db；通过标记文件发现。
28. 当找到多个数据库：用 AskUserQuestion 让用户选择使用哪个数据库或构建新数据库，基于上面打印的语言和创建时间；AskUserQuestion 最多四个选项，因此数据库多于四个时，提供三个最新加 Build a new database，并在提示文本中列出其余。如果用户明确说明使用哪个数据库或构建新数据库，则跳过 AskUserQuestion。
29. 验证 CodeQL 已安装：如果 codeql 不在 PATH，报错并给出安装方式：gh extension install github/gh-codeql 然后 gh codeql install-stub；brew install --cask codeql；https://github.com/github/codeql-action/releases 下载 codeql-bundle。
30. 验证 jq 已安装：如果 jq 不在 PATH，报错并提示 brew install jq 或 apt install jq。
31. 验证 uv 已安装：如果 uv 不在 PATH，报错并提示 https://docs.astral.sh/uv/getting-started/。
32. 运行 codeql --version。
33. 用 Output Directory 块解析 OUTPUT_DIR，再执行完整 pipeline：build database → create data extensions → run analysis。
34. 不要接受 security-extended 足够：它是基线；始终检查 Trail of Bits packs 和 Community Packs 是否可用于该语言；它们能捕获 security-extended 完全遗漏的类别。
35. 不要接受 security-and-quality 是最广套件：security-and-quality 排除所有 experimental/ 查询路径；run-all 模式要同时导入 security-and-quality 和 security-experimental；差异取决于语言为 1-52 个查询。
36. 不要接受数据库构建了所以就好：构建成功不代表提取好；始终运行质量评估并对照预期源文件检查文件数。
37. 不要接受标准框架不需要数据扩展：即使 Django/Spring 应用也有 CodeQL 未建模的自定义包装；跳过扩展会漏漏洞。
38. 不要接受 build-mode=none 对编译语言没问题：它产生严重不完整分析，仅作为绝对最后手段；macOS 上先尝试 arm64 工具链 workaround 或 Rosetta。
39. 不要接受 macOS 构建失败就用 build-mode=none：退出码 137 是 arm64e/arm64 不匹配，不是根本构建失败；见 references/macos-arm64e-workaround.md。
40. 不要接受没有发现意味着代码安全：运行 check_db_quality.py 和 verify_query_suite.py 并报告通过；否则零发现和提取不到内容的数据库输出相同。
41. 不要接受直接运行默认套件或直接传 pack 名称：每个 pack 的 defaultSuiteFile 应用隐藏过滤，可能产生零结果；始终使用显式 suite 引用。
42. 不要接受把文件放在当前目录：所有生成文件必须放到 $OUTPUT_DIR；散落文件使清理不可能，并可能覆盖先前运行。
43. 不要接受用找到的第一个数据库：可能存在多个不同语言或先前运行的数据库；发现多个时向用户展示所有选项；仅在用户已指定用哪个数据库时跳过提示。
44. 不要接受用户说了 scan 就替你选数据库：scan 不是数据库选择；如果存在多个数据库且用户未指定，询问。
45. 技能有三个工作流：build-database、create-data-extensions、run-analysis；一旦选定一个工作流，逐步执行，不跳过阶段。
46. 运行时间长；数据库构建有四种回退方法，所以使用 task 工具跟踪进度；根据运行决定哪些步骤值得跟踪。
47. 无人值守构建：使用 /static-analysis:codeql-build 端到端运行 build-database 步骤：检测语言和工具链，走方法阶梯并在梯级之间应用 build-fixes.md 中的修复，执行质量门。
48. 运行 /static-analysis:codeql-build {\"target\": \"/abs/path\", \"lang\": \"cpp\"}。
49. 它不询问；每个方法失败以及数据库构建但低于质量阈值，返回状态 no-method-succeeded 和 built-below-threshold 供你处理，因为剩余提取器错误是否限于无需分析代码是判断问题。
50. 当构建是漫长不确定部分并想驱动到结论时使用它；当想对尝试哪个方法有发言权，或构建失败需要实时解释时，手动执行 workflows/build-database.md。
51. 如果用户明确指定要做什么（例如 build a database、run analysis on ./my-db），直接执行该工作流；如果用户提示已明确意图（例如 build a new database、analyze the codeql database in static_analysis_codeql_2、run a full scan from scratch），不要调用 AskUserQuestion 进行数据库选择。
52. 默认 pipeline for test、scan、analyze 或类似：使用 Database Discovery 命令发现现有数据库，然后决定。
53. 无数据库：解析新 $OUTPUT_DIR，执行 build → extensions → analysis（完整 pipeline）。
54. 一个数据库：使用 AskUserQuestion 询问重用它还是构建新。
55. 多个数据库：使用 AskUserQuestion，最多四个选项——见 Database Discovery。
56. 用户明确说明意图：跳过 AskUserQuestion，直接按其指示行动。
57. 当现有数据库被发现且用户未明确指定用哪个时，通过 AskUserQuestion 在标题 Existing CodeQL Databases 下展示；每个选项标签包含路径、语言和创建时间，如 ./static_analysis_codeql_1/codeql.db (language: python, created: 2026-02-24)，最后选项为 Build a new database。
58. 如果用户选现有数据库，将 $OUTPUT_DIR 设为其父目录（或包含它的目录），将 $DB_NAME 设为所选路径，然后 proceed to extensions → analysis。
59. 如果用户选 Build new，解析新 $OUTPUT_DIR，执行 build → extensions → analysis。
60. 如果数据库或工作流从提示中不清楚，通过 AskUserQuestion 提供四个工作流——full scan (recommended)、build database、create data extensions、run analysis——并命名发现的数据库和解析的 $OUTPUT_DIR。
61. 使用 verify_query_suite.py：对解析为零查询的 suite 失败；生成脚本会运行它，仅对复用或手工编辑的 suite 手动调用。
62. 使用 check_db_quality.py：对没有可分析源代码的数据库失败；每次构建后运行。
63. 使用 build_log.sh：提供 log_step/run_logged helpers；在任何构建步骤前 source。
64. 使用 find_databases.sh：打印 codeql resolve database 接受的每个数据库，一行一个；在读取它的同一块中构建数组。
65. 使用 generate_suite.sh：写入 run-all 或 important-only .qls 并验证其解析到非零查询数。
66. 参考 macos-arm64e-workaround.md 获取 Apple Silicon 构建跟踪 workaround。
67. 参考 build-fixes.md 获取构建失败修复目录。
68. 参考 quality-assessment.md 获取数据库质量指标和改进。
69. 参考 extension-yaml-format.md 获取数据扩展 YAML 列定义和示例。
70. 参考 sarif-processing.md 获取 SARIF 输出处理的 jq 命令。
71. 参考 diagnostic-query-templates.md 获取用于 source/sink 枚举的 QL 查询。
72. 参考 important-only-suite.md 获取 important-only suite 模板和生成。
73. 参考 run-all-suite.md 获取 run-all suite 模板。
74. 参考 ruleset-catalog.md 获取按语言可用的查询 pack。
75. 参考 threat-models.md 获取威胁模型配置。
76. 参考 language-details.md 获取语言特定构建和提取细节。
77. 参考 performance-tuning.md 获取内存、线程和超时配置。
78. 完成时验证：输出目录已解析（用户指定或自动递增默认）。
79. 完成时验证：所有生成文件存储在 $OUTPUT_DIR 内。
80. 完成时验证：数据库已构建（通过 codeql-database.yml 标记发现）且 {baseDir}/scripts/check_db_quality.py 退出零。
81. 完成时验证：数据扩展已评估——要么创建在 $OUTPUT_DIR/extensions/，要么明确跳过并说明理由。
82. 完成时验证：分析使用显式 suite 引用（不是默认 pack suite）运行，且 {baseDir}/scripts/verify_query_suite.py 对其退出零。
83. 完成时验证：所有已安装查询 pack（官方 + Trail of Bits + Community）已使用或明确排除。
84. 完成时验证：选定的查询 pack 记录到 $OUTPUT_DIR/rulesets.txt。
85. 完成时验证：未过滤结果保留在 $OUTPUT_DIR/raw/results.sarif。
86. 完成时验证：最终结果在 $OUTPUT_DIR/results/results.sarif（important-only 过滤，run-all 复制）。
87. 完成时验证：零发现结果已调查（数据库质量、模型覆盖、套件选择）。
88. 完成时验证：构建日志保留在 $OUTPUT_DIR/build.log，包含所有命令、修复和质量评估。

适用边界 · 注意事项

• 需要快速单文件模式匹配时，用 semgrep skill，而不是 CodeQL。
• 编译语言没有可用构建时，用 semgrep skill；CodeQL 的 build-mode=none 仅作为绝对最后手段且分析严重不完整。
• 需要解析已有 SARIF 而不是生成时，用 sarif-parsing skill。