CodeQL C 查询精度改进:cs/call-to-object-tostring 对值元组的识别逻辑解析

原创2026-10-09 16:13:451,877 阅读
文章标签:静态分析SAST代码质量漏洞扫描应用安全开发工具代码评审

CodeQL C# 查询精度改进:cs/call-to-object-tostring 对值元组的识别逻辑解析

导读

本文围绕 CodeQL C# 查询 cs/call-to-object-tostring(“Use of default ToString()”)在 1.0.18 版本中的一次 Minor Analysis Improvements 展开:该版本针对 C# 值元组(ValueTuple)场景优化了查询判定逻辑,显著降低了元组类型上的误报。读完本文,你将掌握该查询的检测目标、默认 ToString() 判定的底层原理,以及元组特判在 DefaultToStringQuery.qll 中的具体实现,并了解如何运行查询与阅读对应测试用例加以验证。

版本变更背景

C# 1.0.18 变更记录 位于仓库 csharp/ql/src/change-notes/released/ 目录下,与其余上百个按版本号组织的变更记录并列。该版本在 Minor Analysis Improvements 分类下仅记录了一条针对 C# 的改动:

C#: Improve precision of the query cs/call-to-object-tostring for value tuples.

即:提升查询 cs/call-to-object-tostring 在值元组上的精度。“提高精度”在 CodeQL 语境下通常意味着两类效果:一是消除原本会误报(false positive)的元组场景,二是让应报的元组场景(如元组内部元素本身未覆写 ToString())继续被准确捕获。两条路径在 1.0.18 的实现中同时存在,下文结合源码逐一说明。

查询是什么:检测默认 ToString() 的调用

查询 cs/call-to-object-tostring 的正式名称为 Use of default ToString(),声明位于 DefaultToString.ql:

  • @kind problem,@problem.severity warning,@precision very-high;
  • @id cs/call-to-object-tostring;
  • 标签 quality、reliability、correctness;
  • 描述为:调用 ToString 的默认实现会返回一个“几乎不可能是你期望值”的字符串。

其语义在 DefaultToString.qhelp 中有权威说明:调用 System.Object 或 System.ValueType 上的 ToString 方法,返回的是该值的类型的完全限定名(fully qualified name),绝大多数情况下既没有用,也不是开发者本意。该规则同时查找对默认 ToString 的显式调用与隐式调用(例如字符串拼接、Console.WriteLine 自动装箱格式化等场景)。

典型误用与正确写法

仓库在 Useless code 目录 下提供了成对的示例代码。错误示例 DefaultToStringBad.cs 中,Person 类未覆写 ToString(),Console.WriteLine("p: " + p) 实际输出类型名 p: Bad+Person;int<a href="https://link.gitcode.com/i/6fef3fc056dcc11c27fb62a36c03b823" target="_blank">] 数组直接拼接同样输出 ints: System.Int32[]。修正示例 [DefaultToStringGood.cs 则通过覆写 ToString()(public override string ToString() => Name;)和使用 string.Join(", ", ints) 得到 p: Eric Arthur Blair 与 ints: 1, 2, 3。

这两份样例同时说明了一个重要的边界:数组无法通过覆写 ToString() 修正,只能改用显式拼接/序列化手段;而这正是元组场景的相似性所在——元组的“默认 ToString()”同样无法被用户直接覆写,必须按元素递归判断。

1.0.18 改进的核心:值元组的递归判定

查询的 QL 逻辑主体位于 DefaultToStringQuery.qll。与 1.0.18 改动直接相关的谓词是 alwaysDefaultToString,其完整语义为:

t 自身或 t 的任何子类型继承了来自 System.Object 或 System.ValueType 的默认 ToString() 方法。

predicate alwaysDefaultToString(ValueOrRefType t) {
  not t instanceof TupleType and
  not t instanceof Enum and
  exists(ToStringMethod m | t.hasMethod(m) |
    m.getDeclaringType() instanceof SystemObjectClass or
    m.getDeclaringType() instanceof SystemValueTypeClass
  ) and
  not exists(RefType overriding |
    overriding.getAMethod() instanceof ToStringMethod and
    overriding.getABaseType+() = t
  ) and
  ((t.isAbstract() or t instanceof Interface) implies not t.isEffectivelyPublic())
  or
  exists(ValueOrRefType elem |
    elem = t.(TupleType).getElementType(_) and
    alwaysDefaultToString(elem)
  )
}

从源码结构可以读出该版本针对元组的两个关键改动:

其一,主分支显式排除 TupleType。 主判定分支开头新增 not t instanceof TupleType。这是因为 C# 编译器为元组生成的底层类型是 System.ValueTuple,它确实继承自 System.ValueType,若不做排除,任何元组都会被直接命中“继承默认 ToString()”的主分支而一律报出——这恰恰是 1.0.18 之前元组场景精度不佳的根源。

其二,新增元组递归分支。 最后一个 or 分支处理元组:取元组的每一个元素类型(t.(TupleType).getElementType(_)),递归调用 alwaysDefaultToString。因此元组整体是否命中,取决于其元素类型是否递归地命中。这是 1.0.18 的核心改进逻辑。

TupleType 的类型抽象

递归中用到的 TupleType 定义于 Type.qll:

  • class TupleType extends ValueType, @tuple_type,注释明确其为元组类型,例如 (int, bool, string);
  • getUnderlyingType() 返回底层类型 System.ValueTuple;
  • getElement(int n) 返回第 n 个元素字段(如 (int, string) 的第 0 个元素是字段 Item1 int)。

可见元组在数据库模式中被建模为独立实体(@tuple_type),并记录每个元素的类型,这正是 QL 侧能对元素逐一递归判定的数据基础。

结合测试用例理解改进效果

仓库测试目录 DefaultToString 查询测试 恰好覆盖了 1.0.18 新增的元组场景(该测试文件与变更记录同时期演进):

Console.WriteLine(new ValueTuple<int, int>(1, 2)); // GOOD
Console.WriteLine((1, 2));                          // GOOD
var t1 = new ValueTuple<int, DefaultToString>(1, new DefaultToString());
Console.WriteLine(t1);                              // BAD
var t2 = new ValueTuple<A, D>(new A(), new D());
Console.WriteLine(t2);                              // GOOD

逐条对照递归分支的判定:

测试行 元素类型 递归判定结果 期望
new ValueTuple<int, int>(1, 2) int int 本身不命中默认 ToString 主分支 GOOD(1.0.18 消除的误报)
(1, 2)(语法糖) int 同上 GOOD
new ValueTuple<int, DefaultToString>(...) int + DefaultToString 元素 DefaultToString 未覆写 ToString(),命中主分支 BAD(元组内部隐患仍被捕获)
new ValueTuple<A, D>(...) A + D 子类型 D 覆写了 ToString(),A 覆写后子类 B 继承覆写,均不命中 GOOD

同时注意测试中的边界组合:Console.WriteLine(new ValueTuple<int, DefaultToString>(...)) 被判为 BAD,说明 1.0.18 的元组特判不是简单地对所有元组放行,而是把“默认 ToString() 风险”下沉到元素级别递归判断,既修掉了 (int, int) 这类纯值元组的误报,又保住了包含未覆写引用类型的元组告警。

相邻版本的协同演进

值得说明的是,元组分支与同文件中的其他排除条件共同构成完整判定:

  • not t instanceof Enum 与 1.4.0 的改动对应——1.4.0 变更记录 记载该版本“移除了枚举类型上的误报”;
  • 主分支中 (t.isAbstract() or t instanceof Interface) implies not t.isEffectivelyPublic() 处理内部接口/抽象类型的可见性边界(测试中 IPrivate 报 BAD、IPublic 报 GOOD 即为此规则的验证);
  • 子类型覆写检查(overriding.getABaseType+() = t)保证子类覆写了 ToString() 时不再命中(测试中 B : A、D : C 均归为 GOOD)。

底层原理:invokesToString 如何捕获显式与隐式调用

元组判定只解决“哪些类型算默认 ToString()”,而“哪些表达式算调用了 ToString()”由 invokesToString 谓词负责,它定义了三种捕获途径:

  1. 显式调用:MethodCall 的限定符(qualifier)是表达式 e,且调用目标 mc.getTarget() 是 ToStringMethod;
  2. 隐式调用:e 是 ImplicitToStringExpr(即编译器在字符串拼接、格式化插值等场景自动插入的 ToString() 调用节点);
  3. 转发调用:通过可赋值参数定义(AssignableDefinitions::ImplicitParameterDefinition)判定某参数的所有读取路径必然触发 ToString(),从而把“传入该参数的实参”也视为触发了默认 ToString()。

这三类途径确保查询能覆盖 p.ToString() 显式写法、"hello " + p 拼接写法,以及 Console.WriteLine(p) 这类经框架方法转发的隐式写法。查询最终通过 problems 谓词输出结果,消息模板为:

Default 'ToString()': $@ inherits 'ToString()' from 'Object', and so is not suitable for printing.

如何运行查询并验证精度

定位查询与套件

该查询在仓库中的完整路径为 csharp/ql/src/Useless code/DefaultToString.ql,并被收录进默认套件 csharp-security-and-quality.qls,因此普通 codeql database analyze 的默认配置即可触发。

命令行运行方式

在已提取好的 C# 数据库上运行该查询的典型命令为:

codeql database analyze <database> \
  csharp/ql/src/Useless\ code/DefaultToString.ql \
  --format=sarif-latest \
  --output=default-tostring.sarif

也可按规则 ID 从套件中筛选:

codeql database analyze <database> \
  --suite=csharp/ql/src/codeql-suites/csharp-security-and-quality.qls \
  --format=sarif-latest \
  --output=results.sarif

前提是本地具备可用的 CodeQL CLI 与对应版本的 C# 查询包(qpack);命令中的路径需替换为仓库实际检出位置。

用测试验证精度行为

仓库自带回归测试可直接验证 1.0.18 的行为变化:

运行方式为 CodeQL 标准查询测试(codeql test run 指向该测试目录),.expected 文件即“预期结果快照”——任何判定变化都会导致测试失败,从而防止未来改动意外回退 1.0.18 的精度改进。

变更记录体系与阅读指引

本次改动记录在 1.0.18.md,该文件遵循仓库统一的 change-notes 规范:每个版本一个 Markdown 文件,按 Major/Minor Analysis Improvements、Deprecated Queries、Bug Fixes 等分类组织。C# 相关的全部历史变更汇总于 csharp/ql/src/CHANGELOG.md。若想追踪该查询的后续演进,可对比 1.4.0 变更记录(枚举误报移除)及 1.0.19.md 等相邻版本记录。

小结

1.0.18 对 cs/call-to-object-tostring 的改进可概括为一句话:将值元组的默认 ToString() 判定从“类型级一刀切”改为“元素级递归判定”。实现上通过 alwaysDefaultToString 中 not t instanceof TupleType 排除元组直判、再以 TupleType.getElementType 逐元素递归两条规则完成;测试用例验证了 (int, int) 误报被消除、而 (int, DefaultToString) 隐患仍被捕获的精度行为。这一改动体现了 CodeQL 查询精度工程的一般方法:识别编译器自动生成/框架继承导致的宽泛类型匹配,下钻到可被用户行为影响的粒度重新判定,并同步补充回归测试锁定行为。

登录后查看全文
codeql