Semmle QL查询元数据与告警信息编写规范指南

Semmle QL查询元数据与告警信息编写规范指南

codeql 项目地址: https://gitcode.com/gh_mirrors/ql/ql

引言

在Semmle QL静态分析平台中，查询文件(.ql)是代码分析的核心载体。本文将深入解析如何规范编写QL查询文件的元数据区域和告警信息，帮助开发者创建高质量、标准化的代码分析规则。

QL查询文件结构

每个.ql文件由两个关键部分组成：

1. 元数据区域：位于文件顶部，采用QLDoc注释格式(/** ... */)，定义查询的基本属性和分类信息
2. 查询定义区域：使用QL语言编写的实际查询逻辑，包含select语句定义结果集

元数据编写规范

基础元数据属性

@name 查询名称

• 必须属性，采用句子首字母大写格式
• 示例：@name Unsafe string concatenation
• 避免使用技术术语缩写，确保名称直观易懂

@description 查询描述

• 必须属性，简明描述查询检测的问题
• 采用完整句子结构，包含句号结尾
• 代码元素使用单引号标注，如：'System.FormatException'
• 推荐使用"X导致Y"的因果描述模式

@id 查询标识符

• 必须属性，遵循语言代码/问题类型的命名规范
• 支持的语言代码：
  • C/C++: cpp
  • C#: cs
  • Java/Kotlin: java
  • JavaScript/TypeScript: js
  • Python: py
  • Go: go
• 示例：@id java/unsafe-file-operation

查询类型与严重程度

@kind 查询类型

• 必须属性，定义查询结果呈现形式：
  • problem：基础告警
  • path-problem：包含路径信息的告警
  • metric：代码度量指标

@problem.severity 问题严重级别

• 适用于告警类查询
• 等级划分：
  • error：可能导致程序错误或安全问题
  • warning：潜在问题或代码脆弱点
  • recommendation：代码优化建议

@precision 结果精确度

• 评估查询结果的准确性
• 等级：low → medium → high → very-high

分类标签系统

@tags 分类标签

• 采用分层标签体系，使用/表示层级关系
• 主要分类：
  • correctness：正确性问题
  • maintainability：可维护性问题
  • readability：可读性问题
  • security：安全问题

安全相关标签

• 关联CWE编号：external/cwe/cwe-xxx
• 示例：@tags security external/cwe/cwe-079

告警信息编写指南

基础规范

1. 使用完整句子结构，包含句号结尾
2. 客观描述问题，避免修复建议
3. 代码元素使用单引号标注
4. 提供具体上下文信息

链接使用规范

1. 优先使用$@变量引用代码元素
2. 链接文本应简洁明确
3. 避免使用"here"等模糊引用
4. 多链接时，将变量最多的链接放在最后

路径查询模板

• 推荐句式："This path depends on [user-provided value]"
• 替代句式："[User input] flows to this location"

度量查询规范

度量查询(@kind metric)的select子句应返回：

1. 纯数字结果：表示全局度量值(如总代码行数)
2. 代码实体+数字：表示特定位置的度量值(如文件代码行数)

最佳实践示例

/**
 * @name SQL injection risk
 * @description Building SQL queries from unescaped user input may lead to SQL injection issues.
 * @kind path-problem
 * @problem.severity error
 * @id java/sql-injection
 * @tags security
 *       external/cwe/cwe-089
 * @precision high
 */
 
from /* 查询逻辑 */
select element, "SQL query depends on [user input from $@]", source

总结

规范的元数据和告警信息编写能够：

1. 提升查询结果的可读性和可操作性
2. 确保分析结果在不同项目间的一致性
3. 便于查询的分类管理和质量评估
4. 增强安全问题的追踪能力

遵循这些规范将帮助您创建专业级的代码分析规则，为团队提供更有价值的静态分析结果。

codeql 项目地址: https://gitcode.com/gh_mirrors/ql/ql