CodeQL Java 污点传播规则详解<\/h1>

一、概述<\/h2>
CodeQL 的污点分析（Taint Tracking）用于追踪不可信数据（source）在程序中的传播路径，直到危险使用点（sink）。污点传播规则定义了数据如何在各种操作中保持污染状态，是提高漏洞检测准确性的关键。<\/p>

二、基本规则结构<\/h2>

2.1 标准检测模板<\/h3>

import semmle.code.java.dataflow.FlowSources
private import semmle.code.java.dataflow.TaintTracking
import BaseInjectionFlow::PathGraph

module BaseFlowConfig implements DataFlow::ConfigSig {
  predicate isSource(DataFlow::Node source) { 
    source instanceof ActiveThreatModelSource 
  }
  
  predicate isSink(DataFlow::Node sink) { 
    sink instanceof ceshiServiceSink 
  }
  
  predicate isAdditionalFlowStep(DataFlow::Node node1, DataFlow::Node node2) {
    none()
  }
  
  predicate observeDiffInformedIncrementalMode() { 
    any() 
  }
}

module BaseInjectionFlow = TaintTracking::Global<BaseFlowConfig>;

from BaseInjectionFlow::PathNode source, BaseInjectionFlow::PathNode sink
where BaseInjectionFlow::flowPath(source, sink)
select sink.getNode(), source, sink, "cccccc", source.getNode(), "this user input"
<\/code><\/pre>
2.2 污点传播架构<\/h3>
QueryInjectionFlowConfig (implements DataFlow::ConfigSig)
            ↓
TaintTracking::Global<QueryInjectionFlowConfig>
            ↓
AddTaintDefaults<Config> (添加默认污点传播规则)
            ↓
defaultAdditionalTaintStep() (定义在 TaintTrackingUtil.qll)
<\/code><\/pre>
三、默认传播逻辑<\/h2>
3.1 核心文件<\/h3>

semmle.code.java.dataflow.internal.TaintTrackingUtil<\/code><\/li>
semmle.code.java.dataflow.TaintTracking<\/code><\/li>
codeql.dataflow.TaintTracking<\/code><\/li>
<\/ul>
3.2 表达式级别传播 (localAdditionalTaintExprStep)<\/h3>
字符串操作传播<\/h4>

字符串拼接 (AddExpr<\/code>)："hello" + taintedVar<\/code><\/li>
赋值拼接 (AssignAddExpr<\/code>)：str += taintedVar<\/code><\/li>
字符串模板 (StringTemplateExpr<\/code>)：Java 字符串模板表达式<\/li>
逻辑表达式 (LogicExpr<\/code>)：&&<\/code> 和 ||<\/code> 操作<\/li>
<\/ul>
方法调用传播（返回值）<\/h4>


构造函数步骤 (constructorStep<\/code>)：<\/p>

InputStream 包装器构造函数<\/li>
通过扩展构造的包装器<\/li>
TaintPreservingCallable 构造函数<\/li>
<\/ul>
<\/li>

限定符到方法调用 (qualifierToMethodStep<\/code>)：<\/p>

StringWriter.getBuffer()<\/code> \/ StringWriter.toString()<\/code><\/li>
ObjectInputStream.read*()<\/code> 方法<\/li>
Spring 不受信任数据类型的 getter 方法<\/li>
TaintPreservingCallable 返回污点，且 returnsTaintFrom(-1)<\/code>（从 qualifier 返回污染）<\/li>
JAX-RS 资源方法的 getter<\/li>
<\/ul>
<\/li>

参数到方法调用 (argToMethodStep<\/code>)：<\/p>

Base64 编码\/解码：Base64.decodeBase64()<\/code>, Base64.encodeBase64*()<\/code><\/li>
Spring ResponseEntity：ResponseEntity.ok()<\/code>, ResponseEntity.of()<\/code><\/li>
Spring ResponseEntityBodyBuilder：body()<\/code> 方法<\/li>
TaintPreservingCallable 参数传播（参数 i ≥ 0）<\/li>
<\/ul>
<\/li>
<\/ul>
特殊操作<\/h4>

比较步骤 (comparisonStep<\/code>)：与常量的比较或相等测试<\/li>
序列化步骤 (serializationStep<\/code>)：通过 ObjectOutputStream 的数据序列化<\/li>
格式化步骤 (formatStep<\/code>)：通过 Formatter 的字符串格式化<\/li>
<\/ul>
3.3 更新级别传播 (localAdditionalTaintUpdateStep)<\/h3>

限定符到参数 (qualifierToArgumentStep<\/code>)：obj.method(arg)<\/code> 中从 obj 到 arg<\/li>
参数到参数 (argToArgStep<\/code>)：方法参数之间的污点传播<\/li>
参数到限定符 (argToQualifierStep<\/code>)：从方法参数到调用对象<\/li>
<\/ul>
3.4 容器内容传播<\/h3>

数组内容：DataFlow::ArrayContent<\/code><\/li>
集合内容：DataFlow::CollectionContent<\/code><\/li>
Map 值内容：DataFlow::MapValueContent<\/code> 或 MapKeyContent<\/code><\/li>
继承污点的内容：TaintInheritingContent<\/code><\/li>
<\/ul>
3.5 流总结步骤<\/h3>

库代码流总结：FlowSummaryImpl<\/code> 定义的本地步骤<\/li>
<\/ul>
3.6 入口点字段步骤 (entrypointFieldStep)<\/h3>

字段读取传播：从威胁模型源类型的对象到其字段的污点传播<\/li>
适用场景：当源是 ActiveThreatModelSource 参数类型的字段访问时<\/li>
<\/ul>
四、自定义传播规则<\/h2>
4.1 AdditionalTaintStep 扩展<\/h3>
官方内部扩展机制，用于框架特定传播规则：<\/p>
\/\/ semmle.code.java.dataflow.FlowSources 中的示例
private class InputStreamAdditionalTaintStep extends AdditionalTaintStep {
  override predicate step(DataFlow::Node node1, DataFlow::Node node2) {
    exists(ConstructorCall cc, MethodAccess ma |
      \/\/ InputStream 包装器构造函数传播
      cc.getConstructedType() instanceof InputStreamWrapperType and
      node1.asExpr() = cc.getArgument(0) and
      node2.asExpr() = cc
    )
  }
}
<\/code><\/pre>
4.2 TaintPreservingCallable 扩展<\/h3>
更灵活的扩展方式，支持参数到参数的污点传播：<\/p>
class MyTaintPreservingCallable extends TaintPreservingCallable {
  \/\/ 从参数到返回值的传播
  override predicate returnsTaintFrom(int i) {
    i = 0 and this instanceof StringValueOfCall
  }
  
  \/\/ 参数到参数的传播（修改对象状态）
  override predicate transfersTaint(int src, int sink) {
    src = 0 and sink = -1 and \/\/ 从第一个参数到调用对象
    this instanceof CollectionAddMethod
  }
}
<\/code><\/pre>
transfersTaint 参数含义<\/h4>

src<\/code>：污点源的位置索引

src >= 0<\/code>：方法参数索引（0 = 第一个参数）<\/li>
src = -1<\/code>：调用对象（qualifier）<\/li>
<\/ul>
<\/li>
sink<\/code>：污点目标的位置索引

sink >= 0<\/code>：方法参数索引（会被修改）<\/li>
sink = -1<\/code>：调用对象（会被修改）<\/li>
<\/ul>
<\/li>
<\/ul>
与 returnsTaintFrom 的区别<\/h4>



方面<\/th>
returnsTaintFrom<\/th>
transfersTaint<\/th>
<\/tr>
<\/thead>


传播目标<\/td>
方法返回值<\/td>
方法参数或调用对象<\/td>
<\/tr>

对象状态<\/td>
创建新对象<\/td>
修改现有对象<\/td>
<\/tr>

使用场景<\/td>
result = obj.method(param)<\/code><\/td>
obj.method(param)<\/code> 修改 obj 或 param<\/td>
<\/tr>

数据流类型<\/td>
值流<\/td>
引用流\/状态更新<\/td>
<\/tr>
<\/tbody>
<\/table>
4.3 库规则自定义（推荐）<\/h3>
使用 YAML 文件定义外部库的污点传播行为：<\/p>
# ext\/com.squareup.okhttp.model.yml<\/span>
<\/span><\/span>- type<\/span>: model<\/span>
<\/span><\/span>  input<\/span>: 
<\/span><\/span>    package<\/span>: "com.squareup.okhttp"<\/span>
<\/span><\/span>    type<\/span>: "Request.Builder"<\/span>
<\/span><\/span>    method<\/span>: "url(String)"<\/span>
<\/span><\/span>  output<\/span>:
<\/span><\/span>    kind<\/span>: "taint"<\/span>  # 关键：必须是 taint 才能在污点分析中使用<\/span>
<\/span><\/span>    type<\/span>: "Request.Builder"<\/span>
<\/span><\/span>    index<\/span>: "return"<\/span>
<\/span><\/span><\/code><\/pre>在 qlpack.yml<\/code> 中添加引用：<\/p>
models<\/span>:
<\/span><\/span>  - ext\/com.squareup.okhttp.model.yml<\/span>
<\/span><\/span><\/code><\/pre>五、实际应用案例<\/h2>
5.1 String.valueOf() 传播缺失问题<\/h3>
官方规则中，String.valueOf(url)<\/code> 的污点传播可能缺失，可通过 TaintPreservingCallable 扩展：<\/p>
\/\/ propagate.qll
private class StringValueOfCall extends MethodAccess {
  StringValueOfCall() {
    this.getMethod().hasName("valueOf") and
    this.getMethod().getDeclaringType().hasName("String")
  }
}

class StringValueOfTaint extends TaintPreservingCallable {
  StringValueOfTaint() { this instanceof StringValueOfCall }
  
  override predicate returnsTaintFrom(int i) {
    i = 0 \/\/ 从第一个参数传播到返回值
  }
}
<\/code><\/pre>
5.2 SSRF 检测中的 OkHttp 传播<\/h3>
对于 com.squareup.okhttp<\/code>（非 okhttp3<\/code>），需要手动添加传播规则：<\/p>
# ext\/com.squareup.okhttp.model.yml<\/span>
<\/span><\/span>- type<\/span>: model<\/span>
<\/span><\/span>  input<\/span>: 
<\/span><\/span>    package<\/span>: "com.squareup.okhttp"<\/span>
<\/span><\/span>    type<\/span>: "Request.Builder"<\/span>
<\/span><\/span>    method<\/span>: "url(String)"<\/span>
<\/span><\/span>  output<\/span>:
<\/span><\/span>    kind<\/span>: "taint"<\/span>
<\/span><\/span>    type<\/span>: "Request.Builder"<\/span>
<\/span><\/span>    index<\/span>: "return"<\/span>
<\/span><\/span>
<\/span><\/span>- type<\/span>: model<\/span>
<\/span><\/span>  input<\/span>: 
<\/span><\/span>    package<\/span>: "com.squareup.okhttp"<\/span>
<\/span><\/span>    type<\/span>: "Request.Builder"<\/span>
<\/span><\/span>    method<\/span>: "build()"<\/span>
<\/span><\/span>  output<\/span>:
<\/span><\/span>    kind<\/span>: "taint"<\/span>
<\/span><\/span>    type<\/span>: "Request"<\/span>
<\/span><\/span>    index<\/span>: "return"<\/span>
<\/span><\/span>
<\/span><\/span>- type<\/span>: model<\/span>
<\/span><\/span>  input<\/span>: 
<\/span><\/span>    package<\/span>: "com.squareup.okhttp"<\/span>
<\/span><\/span>    type<\/span>: "OkHttpClient"<\/span>
<\/span><\/span>    method<\/span>: "newCall(Request)"<\/span>
<\/span><\/span>  output<\/span>:
<\/span><\/span>    kind<\/span>: "taint"<\/span>
<\/span><\/span>    type<\/span>: "Call"<\/span>
<\/span><\/span>    index<\/span>: "return"<\/span>
<\/span><\/span><\/code><\/pre>六、最佳实践<\/h2>

优先使用库规则<\/strong>：YAML 模型文件更简洁易维护<\/li>
合理选择扩展方式<\/strong>：

通用传播规则：使用 TaintPreservingCallable<\/li>
框架特定规则：使用 AdditionalTaintStep<\/li>
外部库模型：使用 YAML 模型文件<\/li>
<\/ul>
<\/li>
注意传播方向<\/strong>：

值传播：returnsTaintFrom<\/code>（创建新对象）<\/li>
引用传播：transfersTaint<\/code>（修改现有对象）<\/li>
<\/ul>
<\/li>
测试验证<\/strong>：确保自定义规则不会引入误报或漏报<\/li>
<\/ol>
七、总结<\/h2>
CodeQL 提供了多层次的污点传播机制，从默认的表达式级别传播到高度可定制的扩展机制。实际应用中需要注意：<\/p>

官方默认规则并不完整，需要根据目标代码库特点进行补充<\/li>
不同的扩展方式适用于不同场景，需要合理选择<\/li>
库规则自定义是官方推荐的发展方向，提供了更简洁的语法<\/li>
污点传播的准确性直接影响漏洞检测的漏报率和误报率<\/li>
<\/ol>
通过深入理解污点传播机制并合理扩展，可以显著提高 CodeQL 在复杂代码库中的漏洞检测能力。<\/p>

方面<\/th>	returnsTaintFrom<\/th>	transfersTaint<\/th> <\/tr> <\/thead>
传播目标<\/td>	方法返回值<\/td>	方法参数或调用对象<\/td> <\/tr>
对象状态<\/td>	创建新对象<\/td>	修改现有对象<\/td> <\/tr>
使用场景<\/td>	`result = obj.method(param)<\/code><\/td>`	`obj.method(param)<\/code> 修改 obj 或 param<\/td> <\/tr>`
数据流类型<\/td>	值流<\/td>	引用流\/状态更新<\/td> <\/tr> <\/tbody> <\/table> 4.3 库规则自定义（推荐）<\/h3> 使用 YAML 文件定义外部库的污点传播行为：<\/p> # ext\/com.squareup.okhttp.model.yml<\/span> <\/span><\/span>- type<\/span>: model<\/span> <\/span><\/span> input<\/span>: <\/span><\/span> package<\/span>: "com.squareup.okhttp"<\/span> <\/span><\/span> type<\/span>: "Request.Builder"<\/span> <\/span><\/span> method<\/span>: "url(String)"<\/span> <\/span><\/span> output<\/span>: <\/span><\/span> kind<\/span>: "taint"<\/span> # 关键：必须是 taint 才能在污点分析中使用<\/span> <\/span><\/span> type<\/span>: "Request.Builder"<\/span> <\/span><\/span> index<\/span>: "return"<\/span> <\/span><\/span><\/code><\/pre>在 qlpack.yml<\/code> 中添加引用：<\/p> models<\/span>: <\/span><\/span> - ext\/com.squareup.okhttp.model.yml<\/span> <\/span><\/span><\/code><\/pre>五、实际应用案例<\/h2> 5.1 String.valueOf() 传播缺失问题<\/h3> 官方规则中，String.valueOf(url)<\/code> 的污点传播可能缺失，可通过 TaintPreservingCallable 扩展：<\/p> \/\/ propagate.qll private class StringValueOfCall extends MethodAccess { StringValueOfCall() { this.getMethod().hasName("valueOf") and this.getMethod().getDeclaringType().hasName("String") } } class StringValueOfTaint extends TaintPreservingCallable { StringValueOfTaint() { this instanceof StringValueOfCall } override predicate returnsTaintFrom(int i) { i = 0 \/\/ 从第一个参数传播到返回值 } } <\/code><\/pre> 5.2 SSRF 检测中的 OkHttp 传播<\/h3> 对于 com.squareup.okhttp<\/code>（非 okhttp3<\/code>），需要手动添加传播规则：<\/p> # ext\/com.squareup.okhttp.model.yml<\/span> <\/span><\/span>- type<\/span>: model<\/span> <\/span><\/span> input<\/span>: <\/span><\/span> package<\/span>: "com.squareup.okhttp"<\/span> <\/span><\/span> type<\/span>: "Request.Builder"<\/span> <\/span><\/span> method<\/span>: "url(String)"<\/span> <\/span><\/span> output<\/span>: <\/span><\/span> kind<\/span>: "taint"<\/span> <\/span><\/span> type<\/span>: "Request.Builder"<\/span> <\/span><\/span> index<\/span>: "return"<\/span> <\/span><\/span> <\/span><\/span>- type<\/span>: model<\/span> <\/span><\/span> input<\/span>: <\/span><\/span> package<\/span>: "com.squareup.okhttp"<\/span> <\/span><\/span> type<\/span>: "Request.Builder"<\/span> <\/span><\/span> method<\/span>: "build()"<\/span> <\/span><\/span> output<\/span>: <\/span><\/span> kind<\/span>: "taint"<\/span> <\/span><\/span> type<\/span>: "Request"<\/span> <\/span><\/span> index<\/span>: "return"<\/span> <\/span><\/span> <\/span><\/span>- type<\/span>: model<\/span> <\/span><\/span> input<\/span>: <\/span><\/span> package<\/span>: "com.squareup.okhttp"<\/span> <\/span><\/span> type<\/span>: "OkHttpClient"<\/span> <\/span><\/span> method<\/span>: "newCall(Request)"<\/span> <\/span><\/span> output<\/span>: <\/span><\/span> kind<\/span>: "taint"<\/span> <\/span><\/span> type<\/span>: "Call"<\/span> <\/span><\/span> index<\/span>: "return"<\/span> <\/span><\/span><\/code><\/pre>六、最佳实践<\/h2> 优先使用库规则<\/strong>：YAML 模型文件更简洁易维护<\/li> 合理选择扩展方式<\/strong>：通用传播规则：使用 TaintPreservingCallable<\/li> 框架特定规则：使用 AdditionalTaintStep<\/li> 外部库模型：使用 YAML 模型文件<\/li> <\/ul> <\/li> 注意传播方向<\/strong>：值传播：returnsTaintFrom<\/code>（创建新对象）<\/li> 引用传播：transfersTaint<\/code>（修改现有对象）<\/li> <\/ul> <\/li> 测试验证<\/strong>：确保自定义规则不会引入误报或漏报<\/li> <\/ol> 七、总结<\/h2> CodeQL 提供了多层次的污点传播机制，从默认的表达式级别传播到高度可定制的扩展机制。实际应用中需要注意：<\/p> 官方默认规则并不完整，需要根据目标代码库特点进行补充<\/li> 不同的扩展方式适用于不同场景，需要合理选择<\/li> 库规则自定义是官方推荐的发展方向，提供了更简洁的语法<\/li> 污点传播的准确性直接影响漏洞检测的漏报率和误报率<\/li> <\/ol> 通过深入理解污点传播机制并合理扩展，可以显著提高 CodeQL 在复杂代码库中的漏洞检测能力。<\/p>

CodeQL Java 污点传播规则详解<\/h1>

一、概述<\/h2> CodeQL 的污点分析（Taint Tracking）用于追踪不可信数据（source）在程序中的传播路径，直到危险使用点（sink）。污点传播规则定义了数据如何在各种操作中保持污染状态，是提高漏洞检测准确性的关键。<\/p>

二、基本规则结构<\/h2>

三、默认传播逻辑<\/h2>

3.2 表达式级别传播 (localAdditionalTaintExprStep)<\/h3>

四、自定义传播规则<\/h2>

五、实际应用案例<\/h2>

一、概述<\/h2>
CodeQL 的污点分析（Taint Tracking）用于追踪不可信数据（source）在程序中的传播路径，直到危险使用点（sink）。污点传播规则定义了数据如何在各种操作中保持污染状态，是提高漏洞检测准确性的关键。<\/p>