name: codeql description: >- 使用过程间数据流和污点追踪运行 CodeQL 静态分析以检测安全漏洞。适用于查找漏洞、运行安全扫描、执行安全审计、运行 CodeQL、构建 CodeQL 数据库、选择查询规则集、创建数据扩展模型或处理 CodeQL SARIF 输出。不适用于编写自定义 QL 查询或 CI/CD 管道设置。 allowed-tools:

Bash
Read
Write
Glob
Grep
AskUserQuestion
Task
TaskCreate
TaskList
TaskUpdate

CodeQL 分析

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

技能资源： 参考文件和模板位于 {baseDir}/references/ 和 {baseDir}/workflows/。使用 {baseDir} 在运行时解析这些文件的路径。

快速开始

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

# 1. 验证 CodeQL 是否安装
command -v codeql >/dev/null 2>&1 && codeql --version || echo "未安装"

# 2. 检查现有数据库
ls -dt codeql_*.db 2>/dev/null | head -1

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

何时使用

使用深度数据流分析扫描代码库以查找安全漏洞
从源代码构建 CodeQL 数据库（对于编译语言具有构建能力）
查找需要过程间污点追踪或 AST/CFG 分析的复杂漏洞
执行具有多个查询包的全面安全审计

何时不使用

编写自定义查询 - 使用专门的查询开发技能
CI/CD 集成 - 直接使用 GitHub Actions 文档
快速模式搜索 - 使用 Semgrep 或 grep 以提高速度
编译语言没有构建能力 - 考虑使用 Semgrep 替代
单文件或轻量级分析 - Semgrep 对于简单模式匹配更快

需要拒绝的合理化理由

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

“security-extended 就足够了” - 这是基线。始终检查是否适用于该语言的 Trail of Bits 包和社区包。它们捕获 security-extended 完全遗漏的类别。
“数据库构建了，所以它是好的” - 构建的数据库并不意味着提取良好。始终运行第 4 步（质量评估）并检查文件计数与预期的源文件。缓存的构建产生零有用的提取。
“标准框架不需要数据扩展” - 即使是 Django/Spring 应用程序也有围绕 ORM 调用、请求解析或 shell 执行的自定义包装器，CodeQL 默认不建模。跳过扩展工作流意味着在项目特定代码中遗漏漏洞。
“build-mode=none 对于编译语言没问题” - 它产生严重不完整的分析。通过编译代码的过程间数据流无法追踪。仅在绝对最后的手段时使用，并明确标记其局限性。
“没有发现意味着代码是安全的” - 零发现可能表示数据库质量差、缺少模型或错误的查询包。在报告清洁结果之前进行调查。
“我只运行默认套件” - 默认套件根据 CodeQL 的调用方式而变化。始终明确指定套件（例如，security-extended），以便结果可重现。

工作流选择

本技能有三个工作流：

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

自动检测逻辑

如果用户明确指定要做什么（例如，“构建数据库”、“运行分析”），则执行该工作流。

对于“测试”、“扫描”、“分析”或类似的默认管道： 依次执行所有三个工作流：构建 → 扩展 → 分析。创建数据扩展步骤对于在具有自定义框架或 CodeQL 默认未建模的注解的项目中查找漏洞至关重要。

# 检查数据库是否存在
DB=$(ls -dt codeql_*.db 2>/dev/null | head -1)
if [ -n "$DB" ] && codeql resolve database -- "$DB" >/dev/null 2>&1; then
  echo "数据库存在 ($DB) - 可以运行分析"
else
  echo "无数据库 - 需要先构建"
fi

条件	操作
无数据库存在	执行构建 → 扩展 → 分析（完整管道）
数据库存在，无扩展	执行扩展 → 分析
数据库存在，扩展存在	询问用户：在现有数据库上运行分析，或重建？
用户说“只运行分析”或“跳过扩展”	只运行分析

决策提示

如果不清楚，询问用户：

我可以帮助进行 CodeQL 分析。您想做什么？

1. **完整扫描（推荐）** - 构建数据库，创建扩展，然后运行分析
2. **构建数据库** - 从此代码库创建新的 CodeQL 数据库
3. **创建数据扩展** - 为项目 API 生成自定义源/汇模型
4. **运行分析** - 在现有数据库上运行安全查询

[如果数据库存在：“我找到了一个现有数据库在 <DB_NAME>”]