CodeQL查询元数据与告警信息编写规范指南
项目地址: https://gitcode.com/gh_mirrors/co/codeql 引言
在静态代码分析工具CodeQL中，查询文件(.ql)是核心组成部分。本文将深入解析如何规范编写CodeQL查询文件的元数据和告警信息，帮助开发者编写高质量、标准化的查询文件。
查询文件结构解析
每个CodeQL查询文件包含两个主要部分：
- 元数据区域：位于文件顶部，采用QLDoc注释格式（以
/**开头，*/结尾），包含查询的关键描述信息 - 查询定义区域：使用QL语言编写的实际查询逻辑，包含select语句定义结果内容和格式
元数据编写规范
基础元数据字段
-
@name（必填）
- 查询的显示名称
- 采用句子首字母大写格式，不加句号
- 示例：
@name Access to variable in enclosing class
-
@description（必填）
- 查询的简短描述
- 采用完整句子格式，包含句号
- 代码元素使用单引号包裹
- 示例：
@description Using a format string with an incorrect format causes a 'System.FormatException'.
-
@id（必填）
- 查询的唯一标识符
- 格式：语言代码/描述短语
- 支持的语言代码：cpp(c/c++)、cs(c#)、go、java、js(javascript)、py(python)等
- 示例：
@id cs/command-line-injection
-
@kind（必填）
- 查询类型：
problem：普通告警查询path-problem：包含路径信息的告警查询metric：度量查询
- 查询类型：
高级元数据字段
-
@problem.severity
- 告警严重程度：
error：可能导致程序错误行为warning：潜在问题或代码脆弱性recommendation：代码改进建议
- 告警严重程度：
-
@precision
- 查询结果精确度：
low、medium、high、very-high
- 查询结果精确度：
-
@security-severity
- 安全问题的严重程度评分(0.0-10.0)
标签系统(@tags)
CodeQL使用标签系统对查询进行分类：
安全类查询(@tags security)
- 关联CWE弱点分类：
external/cwe/cwe-XXX - 示例：
@tags security、external/cwe/cwe-022
质量类查询(@tags quality)
-
可维护性相关：
maintainability：代码可维护性readability：代码可读性useless-code：无用代码complexity：代码复杂度
-
可靠性相关：
reliability：代码可靠性correctness：正确性问题performance：性能问题concurrency：并发问题error-handling：错误处理
告警信息编写规范
在查询的select语句中定义的告警信息应遵循以下准则：
-
格式规范
- 使用完整句子，包含句号
- 代码元素用单引号包裹
- 避免使用"here"，改用"this location"
-
内容规范
- 客观描述问题，不包含修复建议
- 尽可能包含上下文信息
- 示例：
The class 'Foo' is duplicated as 'Bar'.
-
链接使用规范
- 使用
$@进行变量替换 - 链接文本应简洁准确
- 避免使用"click here"等模糊描述
- 使用
度量查询规范
度量查询(@kind metric)的select语句结果模式：
- 仅包含数字：表示无特定位置的度量（如代码总行数）
- 代码实体+数字：表示有特定位置的度量（如文件行数）
最佳实践建议
- 对于跨语言相同问题的查询，保持@id一致性
- 查询变更时使用@previous-id记录历史
- 标签数量不超过10个
- 安全相关查询必须包含@security-severity
- 质量相关查询使用@problem.severity
通过遵循这些规范，可以确保CodeQL查询的一致性和可维护性，提高静态分析结果的质量和可用性。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
