CodeQL 静态污点分析引擎深度工程实战：从关系代数模型、QL 不动点语义到跨过程数据流与告警治理的全链路解析

CodeQL 静态污点分析引擎深度工程实战：从关系代数模型、QL 不动点语义到跨过程数据流与告警治理的全链路解析

执行摘要

绝大多数团队接触静态应用安全测试（SAST）的第一印象是"正则匹配 + 一堆误报"。这种印象来自基于模式匹配的扫描器，而不是 CodeQL 这一类把程序编译成关系数据库、再用声明式查询做数据流推导的引擎。理解这一点，是从"跑规则"走向"写规则、调规则、治理规则"的分水岭。

真正值得理解的四件事：

第一，CodeQL 的核心不是"查找"，而是"关系代数 + 不动点递归"。 抽取器（extractor）把源码变成 AST、CFG、DFG 三张关系表，QL 语言本质是带递归与聚合的 Datalog。你在写 predicate 时，写的是关系推导规则，不是控制流代码。

第二，污点分析的精度由四个旋钮决定：isSource、isSink、isSanitizer、isAdditionalTaintStep。前两个决定分析范围，后两个决定漏报率——绝大多数"为什么这个洞没扫出来"的问题，答案都在第四个旋钮上。

第三，跨过程分析的代价是指数级的。 字段敏感（field-sensitive）、上下文敏感（context-sensitive）、路径敏感（path-sensitive）三者不能同时拉满。CodeQL 的默认配置是一次务实的取舍，理解取舍点才能解释为什么某条路径断掉了。

第四，SAST 落地的真正难点不在扫描，而在告警治理。 没有 baseline、没有 diff-aware、没有 SARIF 归一化到研发流程里，再准的引擎也会在第三周被工程师屏蔽掉。

本文沿"关系模型 → QL 语义 → 污点传播 → 工程落地"这条链路拆开讲，并给出可以直接跑起来的查询与命令。

一、关系模型：为什么 SAST 引擎必须先把程序变成数据库

CodeQL 的流水线分两步：抽取与查询。

抽取阶段，语言相关的 extractor 把编译过程拦下来（Java 用 Maven/Gradle 钩子，C/C++ 用 build tracer），产出一种叫 TRAP 的关系事实文件，再经 codeql database finalize 编成列式存储的关系库。库里最重要的三张逻辑表是：

• AST 表：Expr、Stmt、Callable、Class 等语法实体的父子关系与属性；
• CFG 表：successors 之类，给出基本块与控制流边；
• DFG 表：def-use 边，即"这个变量的值来自哪里"。

有了这三张表，"查找 request.getParameter 的返回值是否流到了 Statement.execute 的参数"这件事，就变成了"在 DFG 图上求一条从 A 到 B 的路径"——一个图可达性问题。而图可达性天然可以用递归关系表达，这正是 Datalog 的主场。

一个最小但完整的 QL 查询长这样：

import java

from Method m, Parameter p
where m.hasName("execute") and
      m.getDeclaringType().getASourceSupertype*().hasQualifiedName("java.sql", "Statement") and
      p = m.getParameter(0)
select m, "SQL 执行入口：" + p.getName()

注意 getASourceSupertype*() 里的星号：这是 Kleene 闭包，表示"沿此关系走零次或多次"。它是 QL 表达传递闭包的核心语法糖，也是"跨继承层级匹配"这种需求能一行写出来的原因。

这里的工程含义是：CodeQL 的查询不是"搜索"，而是"对关系做代数运算"。你一旦接受这个模型，就会明白为什么 QL 里没有循环、没有变量赋值——那些东西在关系代数里本来就不存在。

二、QL 语言的三块基石：类型、谓词、聚合

QL 表面像 SQL，骨子里是 Datalog。三个必须掌握的概念：

1. 类（class）是"带条件的关系视图"

class SqlSinkMethod extends Method {
  SqlSinkMethod() {
    this.getDeclaringType().getASourceSupertype*()
        .hasQualifiedName("java.sql", "Statement") and
    this.hasName(["execute", "executeQuery", "executeUpdate"])
  }
}

这不是定义一个新数据结构，而是定义一个派生关系：所有满足构造条件的 Method 元组构成一个逻辑类。类的继承就是关系的包含。

2. 谓词（predicate）分有值与无值两种

无值谓词是布尔约束，有值谓词是关系投影。带 = 的是完全绑定的标量函数：

class ServletParamSource extends Expr {
  ServletParamSource() {
    exists(MethodAccess ma |
      ma.getMethod().getDeclaringType()
        .getASourceSupertype*()
        .hasQualifiedName("javax.servlet", "HttpServletRequest") and
      ma.getMethod().hasName(["getParameter", "getHeader", "getParameterValues"]) and
      this = ma
    )
  }
}

exists(...) 是存在量词，等价于 SQL 的 EXISTS；this = ma 把类实例绑定到某个表达式节点上。

3. 聚合用于精度控制，不能替代传播

from Method m
where strictcount(m.getAParam()) > 3
select m, "参数过多，注意调用点歧义"

聚合（count / strictcount / min / sum）主要用于约束与裁剪，不要试图用它做数据流——数据流必须交给 DataFlow / TaintTracking 库。

三、污点分析的四个旋钮

CodeQL 的污点追踪用 TaintTracking::Configuration 表达。下面是一条可直接使用的 Java SQL 注入规则：

/**
 * @name SQL injection from servlet parameter
 * @kind path-problem
 * @problem.severity error
 * @security-severity 9.8
 * @id java/custom-sqli
 */
import java
import semmle.code.java.dataflow.TaintTracking
import semmle.code.java.security.SqlInjectionQuery
import DataFlow::PathGraph

class ServletToSqlConfig extends TaintTracking::Configuration {
  ServletToSqlConfig() { this = "ServletToSqlConfig" }

  override predicate isSource(DataFlow::Node src) {
    src.asExpr() instanceof ServletParamSource
  }

  override predicate isSink(DataFlow::Node sink) {
    sink.asExpr() = any(SqlInjectionSink s).asExpr()
  }

  override predicate isSanitizer(DataFlow::Node node) {
    node.asExpr().(MethodAccess).getMethod()
        .hasQualifiedName("org.owasp.encoder", "Encode", "forSql")
  }

  override predicate isAdditionalTaintStep(DataFlow::Node from, DataFlow::Node to) {
    // 自定义框架：MyRowMapper.getString("x") 视为从 row 对象取污点
    exists(MethodAccess ma |
      ma.getMethod().hasName("getString") and
      ma.getMethod().getDeclaringType().hasName("MyRowMapper") and
      from.asExpr() = ma.getQualifier() and
      to.asExpr() = ma
    )
  }
}

from ServletToSqlConfig cfg, DataFlow::PathNode src, DataFlow::PathNode sink
where cfg.hasFlowPath(src, sink)
select sink.getNode(), src, sink, "污点从 HTTP 请求参数流入 SQL 执行：" +
      src.getNode().asExpr().toString()

四个旋钮的作用与典型误用：

• isSource：定义污点源。写太宽是误报的主要来源（比如把整个 HttpServletRequest 当源，导致请求对象本身的所有字段都带污点）。
• isSink：定义危险汇聚点。写太窄是漏报来源之一。优先复用官方 semmle 库里的 Sink 类，而不是自己枚举方法名。
• isSanitizer：定义清洗点。这是消除误报最直接的手段。生产上建议把公司内部的校验/转义工具类集中列进一个共享 pack。
• isAdditionalTaintStep：定义额外传播边。这是补漏报的关键。任何自研框架、RPC 序列化、ORM 映射、ThreadLocal 透传、MQ 消息体，只要不是编译器可见的赋值，都必须在这里显式补边。

实战经验：一条规则上线后如果零告警，先别高兴。八成是 isAdditionalTaintStep 没写，污点在你自研的框架边界处断了。用一个已知漏洞做回归验证（CodeQL 里叫 positive test），比任何精度指标都可靠。

四、跨过程分析：精度三角与代价

污点能传多远，取决于分析的敏感度。三个敏感维度构成一组不可能三角：

CodeQL 默认采用流敏感 + 字段敏感，上下文用调用点敏感但有界的组合，并在 Configuration 上暴露了几个实用的调节字段：

class BoundedConfig extends TaintTracking::Configuration {
  BoundedConfig() { this = "BoundedConfig" }

  // 限制跨过程探索的调用深度，防止在深调用链上爆炸
  override int explorationLimit() { result = 20 }

  // 字段敏感开关：false 时把对象整体视为一个槽位，召回上升精度下降
  override predicate fieldFlowBranchLimit(int limit) { limit = 5 }
}

调优顺序建议：先用 explorationLimit 卡住爆炸的查询，再用 isAdditionalTaintStep 补召回，最后才动敏感度。反过来做会让你在错误的方向上消耗大量调试时间。

还有一个容易被忽略的机制：virtual dispatch 的保守性。CodeQL 对虚方法调用会枚举所有可能的覆写实现。如果某个接口的污点传播在运行期根本不会发生，直接用 isSanitizer 把该实现剪掉，比调参数有效得多。

五、工程落地：从一条命令到一套流水线

1. 建库与扫描

# 1) 抽取：Java 需要 autobuild 或显式指定构建命令
codeql database create ./db-java \
  --language=java \
  --source-root=./service \
  --command="mvn -B -DskipTests clean package" \
  --threads=0 --ram=16384

# 2) 扫描：用官方安全扩展包 + 自定义 pack
codeql database analyze ./db-java \
  --format=sarifv2.1.0 \
  --output=results.sarif \
  --threads=0 --ram=16384 \
  --sarif-add-baseline-file \
  java-security-extensions my-org/java-custom-queries

# 3) 只跑指定 suite（在 qlpack 内定义 .qls 文件）
codeql database analyze ./db-java my-org/java-custom-queries:security-extended

--threads=0 表示用满 CPU；--ram 建议设为物理内存的 70%~80%，设太小会触发 evaluator 的缓存淘汰，性能断崖式下跌。

2. CI 分层策略

把扫描拆成三档，是控制成本的关键：

• PR 级（分钟级）：只扫变更文件涉及的规则子集，或直接用 --rerun 复用上次数据库。目标是把反馈压到 5 分钟内。
• 主干级（10~20 分钟）：全量安全扩展包，结果上传代码扫描平台，作为发布门禁。
• 夜间级（小时级）：开高敏感度、跑自定义深度规则、做趋势统计。

3. 告警治理：SARIF + baseline

SARIF 是唯一值得投入的归一化格式。有了它，你才能做三件事：

# .github/workflows/codeql.yml 片段
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
    # 严重级别以下不阻断流水线
    category: security-and-quality

1. 去重与指纹：SARIF 的 partialFingerprints 提供跨扫描的稳定标识，是做 baseline 的前提；
2. 增量阻断：只对本 PR 新引入的告警 fail，历史债务走工单不阻断；
3. 误报回写：把人工确认的误报存成 suppress 列表，下次扫描直接过滤，而不是让人重复劳动。

一个残酷的现实：SAST 项目失败的原因，90% 不是"扫不出来"，而是"第一天倒了三万条告警，研发集体屏蔽通知"。上线第一周只开 3~5 条高置信规则，比一上来全开更容易活下来。

4. 自定义 pack 的组织方式

my-org-java-queries/
├── qlpack.yml                 # name: my-org/java-custom-queries
├── src/
│   └── security/
│       ├── CustomSqlInjection.ql
│       └── CustomSsrf.ql
├── lib/
│   └── MyFrameworkTaintSteps.qll   # 自研框架传播边，被所有 query 复用
└── suites/
    └── security-extended.qls

把 lib/ 里的传播边沉淀为组织资产，是 CodeQL 相对其他 SAST 最大的长期价值——领域知识以代码形式复用，而不是散落在规则作者的脑子里。

六、结论

CodeQL 这一类引擎的复杂度不在命令行多，而在于它把"程序分析"这件事拆成了模型层（关系代数与不动点语义）与工程层（抽取、查询优化、告警治理）两个几乎正交的问题。模型层保证表达力与正确性，工程层负责把理论上的精度压进可接受的 CPU 与内存预算——这两层的解耦，才是它既能写复杂规则又能跑在 CI 上的原因。

值得记住的三句话：污点传播是图可达性问题，所以补边（isAdditionalTaintStep）永远比调参数更能解决漏报；精度三角不可能全拉满，先卡 explorationLimit 再谈敏感度；SAST 的胜负手在告警治理，不在规则数量。