# CodeQL 静态分析 ## 何时使用 CodeQL **理想场景：** * 跨文件和模块的深度过程间污点跟踪 * 需要语义理解的复杂数据流分析 * 大型代码库中的安全漏洞检测 * 查找跨越多个函数调用的漏洞 * 变体分析（在代码库中查找类似的错误） * GitHub 高级安全集成 * 合规性驱动的安全扫描 * 针对组织特定模式的自定义查询开发 **补充其他工具：** * 在 Semgrep 之后使用，对标记区域进行更深入的分析 * 结合 SARIF Issue Reporter 获取详细调查结果 * 与供应链依赖扫描仪（OSV-Scanner）配对 * 与 Gitleaks 一起使用进行秘密检测 **在以下情况下考虑使用 Semgrep：** * 需要基于模式的快速扫描（分钟 vs 小时） * 简单的文件内模式匹配就足够了 * 无需学习QL语言即可编写规则 * CI/CD 需要快速反馈循环 ## 何时不使用请勿将此技能用于： * 基于模式的快速扫描（使用 Semgrep） * 秘密检测（使用Gitleaks） * 依赖漏洞扫描（使用OSV-Scanner、Depscan） * IaC安全分析（使用KICS） * API端点发现（使用Noir） * 无需源代码的二进制分析 * CodeQL 不支持的语言 ## 支持的语言语言 |数据库|成熟度 ---|---|--- C/C++ | `cpp` |稳定 C# | `csharp` |稳定去 | `去` |稳定 Java/Kotlin | `java` |稳定 JavaScript/TypeScript | `javascript` |稳定蟒蛇 | `蟒蛇` |稳定红宝石 | `红宝石` |稳定斯威夫特 | `迅速` |贝塔 ## 安装 ### GitHub CLI（推荐） # 通过 GitHub CLI 安装 CodeQL CLI gh 扩展安装 github/gh-codeql # 验证安装 gh代码ql版本 ### 直接下载 # 下载最新版本 (Linux/macOS) wget https://github.com/github/codeql-cli-binaries/releases/latest/download/codeql-linux64.zip 解压codeql-linux64.zip 导出 PATH="$PWD/codeql:$PATH" # 窗口 # 下载地址：https://github.com/github/codeql-cli-binaries/releases # 验证代码版本 ### 克隆标准查询 # 克隆 CodeQL 查询存储库 git clone --深度 1 https://github.com/github/codeql.git codeql-repo # 设置 CODEQL_HOME 导出 CODEQL_HOME="$PWD/codeql-repo" ### VS 代码扩展从市场安装“CodeQL”扩展以进行查询开发和调试。 ## 核心工作流程 ### 1\.创建数据库 # 自动检测语言 codeql 数据库创建 <数据库名称> --source-root=<源路径> # 明确指定语言 codeql 数据库创建 my-db --language=python --source-root=./src # 多种语言 codeql 数据库创建 my-db --language=javascript,python --source-root=. # 使用构建命令（编译语言） codeql 数据库创建 my-db --language=java --command="mvn cleancompile" --source-root=. codeql 数据库创建 my-db --language=cpp --command="make" --source-root=. # 覆盖现有数据库 codeql 数据库创建 my-db --language=python --overwrite --source-root=. ### 2\.运行分析 # 运行默认安全查询 codeql 数据库分析 --format=sarif-latest --output=results.sarif # 使用特定的查询套件 codeql 数据库分析 my-db codeql/python-queries:codeql-suites/python-security-extended.qls \ --format=sarif-latest --output=结果.sarif # 运行单个查询 codeql 数据库分析 my-db path/to/query.ql --format=sarif-latest --output=results.sarif # 多个查询包 codeql 数据库分析 my-db \ codeql/javascript 查询 \ codeql/python 查询 \ --format=sarif-latest --output=结果.sarif ### 3\.查询套件套房 |描述 ---|--- `-security-extended.qls` |全面的安全查询 `-security-and-quality.qls` |安全+代码质量 `-code-scanning.qls` | GitHub扫码默认 `-lgtm-full.qls` |所有可用的查询 # Python 安全扩展 codeql 数据库分析 my-db \ codeql/python-queries:codeql-suites/python-security-extended.qls \ --format=sarif-latest --output=python-results.sarif # JavaScript 安全性 codeql 数据库分析 my-db \ codeql/javascript-queries:codeql-suites/javascript-security-extended.qls \ --format=sarif-latest --output=js-results.sarif ## 输出格式 # SARIF（推荐用于 CI/CD） codeql 数据库分析 my-db --format=sarif-latest --output=results.sarif # CSV codeql 数据库分析 my-db --format=csv --output=results.csv # JSON codeql 数据库分析 my-db --format=json --output=results.json # 文本（人类可读） codeql 数据库分析 my-db --format=text --output=results.txt # 带有源代码片段的 SARIF codeql 数据库分析 my-db --format=sarif-latest \ --sarif-add-snippets --output=结果.sarif ## 编写自定义查询 ### 基本查询结构 /** * @name SQL注入漏洞 * @description 用户输入流向 SQL 查询，无需清理 * @kind 路径问题 * @问题.严重性错误 * @安全严重性9.8 * @精度高 * @id py/sql 注入 * @标签安全 * 外部/cwe/cwe-089 */ 导入Python 导入 semmle.python.dataflow.new.DataFlow 导入 semmle.python.dataflow.new.TaintTracking 导入 semmle.python.Concepts 导入 DataFlow::PathGraph 类 SqlInjectionConfig 扩展 TaintTracking::Configuration { SqlInjectionConfig() { this = "SqlInjectionConfig" } 覆盖谓词 isSource(DataFlow::Node source) { 存在（RemoteFlowSource 远程 | 源 = 远程） } 覆盖谓词 isSink(DataFlow::Node sink) { 存在（SqlExecution sql |接收器= sql.getSql（）） } } 来自 SqlInjectionConfig 配置、DataFlow::PathNode 源、DataFlow::PathNode 接收器其中 config.hasFlowPath(源、接收器) 选择sink.getNode()，源，接收器， “从$@到$@的SQL注入。”，source.getNode()，“用户输入”，sink.getNode()，“SQL查询” ### 查询元数据元数据 |描述 ---|--- `@name` |人类可读的查询名称 `@描述` |详细说明 `@kind` |查询类型：“问题”、“路径问题”、“指标” `@问题.严重性` | “错误”、“警告”、“建议” `@安全严重性` | CVSS 分数（0.0-10.0） `@精确` | “非常高”、“高”、“中”、“低” `@id` |唯一标识符（例如“py/sql-injection”） `@tags` |类别：`安全性`、`正确性`、`可维护性` ### 数据流与污点跟踪特色 |数据流 |污点追踪 ---|---|--- **曲目** |精确值|派生值 **用例** |价值平等|安全流程 **示例** | “这个密码是用过的吗？” | “用户输入是否到达SQL？” **消毒剂** |不适用 |支持 ## GitHub 操作集成 ### 基本工作流程名称：CodeQL 于：推：分支：[主要] 拉请求：分支：[主要] 时间表： - cron: '0 0 * * 0' # 每周职位：分析：名称：分析运行：ubuntu-latest 权限：行动：阅读内容：阅读安全事件：写策略：快速失败： false 矩阵：语言：['javascript', 'python'] 步骤： - 名称：结账使用：actions/checkout@v4 - 名称：初始化 CodeQL 使用：github/codeql-action/init@v3 与：语言：${{ 矩阵.语言 }} 查询：安全扩展 - 名称：自动构建使用：github/codeql-action/autobuild@v3 - 名称：执行 CodeQL 分析使用：github/codeql-action/analyze@v3 与：类别：“/语言：${{矩阵.语言}}” ### CI 中的自定义查询 - 名称：初始化 CodeQL 使用：github/codeql-action/init@v3 与：语言：蟒蛇查询：安全扩展，./自定义查询配置文件：./.github/codeql/codeql-config.yml ### CodeQL 配置文件 # .github/codeql/codeql-config.yml 名称：“自定义 CodeQL 配置” 查询： - 用途：安全扩展 - 用途：安全和质量 - 使用：./自定义查询路径忽略： - '**/测试/**' - '**/测试/**' - '**/供应商/**' - '**/node_modules/**' 查询过滤器： - 排除： id：py/冗余比较 ## CLI 快速参考命令 |目的 ---|--- `codeql 数据库创建` |创建分析数据库 `codeql 数据库分析` |对数据库运行查询 `codeql 数据库升级` |升级数据库架构 `codeql 数据库包` |打包数据库共享 `codeql 查询编译` |编译 QL 查询 `codeql 查询运行` |直接运行查询 `codeql 包下载` |安装查询包 `codeql pack ls` |列出已安装的包 `codeql 包初始化` |创建自定义包 ## 常见用例 ### 1\.全面的安全审计 # 创建数据库 codeql 数据库创建audit-db --language=python --source-root=./app # 运行全面的安全分析 Codeql 数据库分析audit-db \ codeql/python-queries:codeql-suites/python-security-extended.qls \ --format=sarif-最新 \ --sarif-add-snippets \ --output=安全审计.sarif # 查看结果猫安全审计.sarif | jq '.runs[].results[] | jq '.runs[].results[] | {规则：.ruleId，消息：.message.text，位置：.locations[0].physicalLocation.artifactLocation.uri}' ### 2\.变异分析 # 运行自定义查询来查找相似模式 codeql查询运行variants.ql --database=my-db --output=variants.bqrs codeql bqrs 解码variants.bqrs --format=csv --output=variants.csv ### 3\.多语言分析 # 为每种语言创建数据库 codeql 数据库创建 js-db --language=javascript --source-root=./frontend codeql 数据库创建 py-db --language=python --source-root=./backend # 分别分析 codeql 数据库分析 js-db codeql/javascript-queries \ --format=sarif-latest --output=frontend.sarif codeql 数据库分析 py-db codeql/python-queries \ --format=sarif-latest --output=backend.sarif # 合并 SARIF 结果 jq -s '.[0].runs += .[1].runs | .[0]' 前端.sarif 后端.sarif > 组合.sarif ## 性能优化 # 增加大型代码库的内存 codeql 数据库分析 my-db --ram=8192 --threads=4 ... # 使用编译缓存导出 CODEQL_COMPILATION_CACHE="$HOME/.codeql/cache" # 增量分析（复用数据库） codeql 数据库创建 my-db --overwrite=false ... # 限制查询超时 codeql 数据库分析 my-db --timeout=600 ... ## 故障排除 ### 常见问题 # 数据库创建失败 - 检查构建命令 codeql 数据库创建 my-db --language=java --command="mvn -X 编译" ... # 查询编译错误 codeql 查询编译 --warnings=show query.ql # 缺少依赖项 codeql 包下载 codeql/python-all # 数据库版本不匹配 codeql数据库升级my-db # 调试查询执行 codeql 查询运行 query.ql --database=my-db --output=debug.bqrs -- --dump-ra ### 验证 # 验证 SARIF 输出 codeql 数据库分析 my-db --format=sarif-latest --output=results.sarif jq '.runs[0].结果 |长度' results.sarif # 检查查询元数据 codeql 查询元数据 query.ql # 根据预期结果测试查询 codeql 测试运行测试/ ## 限制 * **需要构建** ：编译语言需要成功构建 * **分析时间**：在大型代码库上进行深入分析可能需要数小时 * **内存使用**：大型数据库需要大量 RAM (8GB+) * **学习曲线**：QL语言需要专门学习 * **语言覆盖范围**：并非所有语言都受到同等支持 * **误报**：复杂的流程可能会产生需要调整的 FP ## 拒绝的理由快捷方式|为什么这是错误的 ---|--- “CodeQL 没有发现任何内容，代码是安全的” | CodeQL 查询涵盖已知模式；新漏洞需要自定义查询 “CI 太慢了”|使用缓存、增量分析或按计划运行而不是每个 PR “QL太难了”|从内置查询开始；自定义查询可以等待 “仅限 GitHub 的工具”| CLI 可以在任何地方使用； GitHub 集成是可选的 “Semgrep 涵盖相同的内容”| CodeQL 擅长深度过程间分析，而 Semgrep 无法做到 ## 参考文献 * 文档： * 查询参考： * GitHub 存储库： * 查询套件： * VS 代码扩展： * GitHub 操作： * SARIF 规范： * 学习实验室： * 查询控制台：

代码ql

包含技能