CodeQL学习——自定义查询

在CodeQL CLI中使用自定义查询

为了使用CodeQL进行定制分析，我们可以通过自己编写查询来实现查找漏洞或错误。CodeQL的查询类型有：

• 告警查询：突出显示代码中特定位置的问题的查询。
• 路径查询：代码中source和sink之间信息流的查询。

基本查询结构

用CodeQL编写的查询文件扩展名为.ql，并包含一个select子句。许多现有查询都包含其他可选信息，并具有以下结构：

/**
 *
 * Query metadata
 *
 */

import /* ... CodeQL libraries or modules ... */

/* ... Optional, define CodeQL classes and predicates ... */

from /* ... variable declarations ... */
where /* ... logical formula ... */
select /* ... expressions ... */

import语句

每个查询通常包含一个或多个import语句，这些语句定义了要导入到查询中的库或模块。库和模块提供了一种将相关类型，谓词（用于描述组成QL程序的逻辑关系）和其他模块组合在一起的方法。然后，查询可以访问您导入的每个库或模块的内容。

From子句

该from子句声明查询中使用的变量。每个声明必须采用 <type> <variable name>的形式。

Where子句

该where子句定义了适用于该from子句中声明的变量以生成结果的逻辑条件。该子句使用聚合，谓词和逻辑公式将目标变量限制为较小的集合，这些集合满足已定义的条件。

Select 子句

该select子句指定要显示的变量，这些变量需符合where子句中定义的条件。select子句的有效结构由元数据中指定的@kind属性定义。

告警查询（@kind problem）的Select子句由两“列”组成，其结构如下：

select element, string
 element：查询标识的代码元素，用于定义显示告警的位置。
 string：一条消息，其中还可以包含链接和占位符，说明生成告警的原因。

您可以修改select语句最后一栏中定义的告警消息，使用有关链接或占位符，提供通过查询所找到的告警或路径的更多详细信息。

编写查询元数据

每个查询文件都是以查询元数据作为开始，它为用户提供有关查询的信息，并告诉CodeQL CLI如何处理查询结果。

我们在使用database analyze命令进行查询时，必须包括以下两个属性，以确保得到正确的查询结果：

• 查询标识符（@id）：是一串小写字母或数字，通过/或-分隔构成的单词序列，用于识别和分类查询。
• 查询类型（@kind）：标识查询是告警（@kind problem）还是路径（@kind path-problem）。

元数据属性

所有查询文件都支持以下属性：

属性	值	描述
@description	<text>	用一段简单的话描述查询的目的以及查询结果的重要性。该描述以纯文本编写，并使用单引号（'）将代码括起来。
@id	<text>	是一串小写字母或数字，通过/或-分隔构成的单词序列，用于识别和分类查询。每个查询必须具有唯一的 ID。为确保这一点，对每个ID使用固定的结构可能会有所帮助。例如，标准LGTM查询具有以下格式：<language>/<brief-description>。
@kind	problem path-problem	标识查询是告警（@kind problem）还是路径（@kind path-problem）。有关这些查询类型的更多信息，请参见关于CodeQL查询。
@name	<text>	定义查询标签的语句。该名称以纯文本形式编写，并使用单引号（'）将代码括起来。
@tags	correctness maintainability readability security	这些标签将查询按大类分组在一起，以使其更易于搜索和识别。除了此处列出的常用标签外，还有许多更具体的类别。有关更多信息，请参阅《 查询元数据样式指南》。
@precision	medium high very-high	表示查询结果为“真肯定”（相对于“假肯定”结果）的百分比。这与@problem.severity属性一起确定默认情况下是否在LGTM上显示结果。
@problem.severity	error warning recommendation	定义查询生成的任何警报的严重性级别。这与@precision属性一起确定默认情况下是否在LGTM上显示结果。

对于过滤器查询的其他属性

过滤器查询用于定义其他约束，以限制其他查询返回的结果。筛选器查询必须具有与@kind要筛选其结果的查询相同的属性。不需要其他元数据属性。

例子

一个标准的Java查询元数据：

有关查询元数据的更多示例，请参见GitHub存储库中的标准CodeQL查询。

定义查询结果

您可以通过修改查询的select语句来控制分析结果在源代码中的显示方式。

概述

告警查询必须在元数据中定义@kind problem属性。有关更多信息，请参见CodeQL查询的元数据。select 语句最基本的形式必须包含两“列”：

• Element ——查询所标识的代码元素。这定义了告警的位置。
• String——为该代码元素显示的消息，描述了生成告警的原因。

编写一个select语句

我们以一个使用标准CodeQL CodeDuplication.qll库识别相似文件的简单查询作为示例。

基本select语句

import java
import external.CodeDuplication

from File f, File other, int percent
where similarFiles(f, other, percent)
select f, "This file is similar to another file."

这个基本的select语句有两列：

1. 显示告警的元素：f对应于File。
2. 要显示的字符串消息： "This file is similar to another file."

 

包含相似文件的名称

select语句定义的告警信息是固定的，不能给用户提供太多信息。由于查询识别出了相似文件（other），因此很容易扩展select语句以告知用户这些相似文件的名称。例如：

select f, "This file is similar to " + other.getBaseName()

1. Element ：和之前一样为f。
2. String："This file is similar to "—字符串文本与相似文件的文件名通过getBaseName()拼接在一起。

尽管这比原始的select语句提供了更多信息，但用户仍然需要手动查找其他文件。

添加链接到相似文件

您可以在告警信息中使用占位符以插入其他信息，例如，指向相似文件的链接。占位符使用$@定义，并使用select语句的后两列中的信息来填充。例如，下述select语句就返回了4列信息：

select f, "This file is similar to $@.", other, other.getBaseName()

1. Element：和之前一样为f。
2. 字符串消息："This file is similar to $@."——该字符串包含一个占位符，它将显示接下来两列的合并内容。
3. 占位符元素：other对应于相似文件。
4. 占位符的字符串文本：other.getBaseName()所返回的短文件名。

显示告警消息时，$@占位符将替换为根据该select语句定义的第三第四列内容创建的链接。

如果使用$@在说明信息中多次使用占位符标记，则第N个使用的$@将由2N+2列和2N+3列组成的链接代替。如果附加列数量多于占位符标记，则末尾的列将被忽略。相反，如果附加列数量少于占位符标记，则末尾的$@标记将被视为普通文本，而不是占位符。

增加文件相似程度的一些细节

我们可以更进一步，更改select语句以报告两个文件中相似的内容部分，因为这部分信息已经在查询中可用。例如：

select f, percent + "% of the lines in " + f.getBaseName() + " are similar to lines in $@.", other, other.getBaseName()

由于此处添加的新元素不需要是可单击的，因此我们可以将它们直接拼接到字符串信息中。

创建一个自定义的QL包

　　我们编写的查询应该保存在自定义QL包文件夹或其子目录中。QL包用来整理在分析时使用的文件，包括查询、库文件、查询套件和重要的元数据。QL包目录的根目录下必须包含一个以qlpack.yml命名的文件，该文件包含name、version以及libraryPathDependencies字段属性。如果这个包还包含查询套件，可以使用suites这个字段来指定其位置。
　　执行命令的时候，codeql会扫描其安装目录或者子目录查找qlpack.yml文件，文件中的元数据会告知codeql如何编译查询、依赖什么库以及查询套件所在的位置。
　　例如一个自定义C++查询和库的QL包的qlpack.yml文件可能包含以下内容：

name: my-custom-queries
version: 0.0.0
libraryPathDependencies: codeql-cpp
suites: my-custom-suites

其中codeql-cpp是codeql仓库中用于C/C++分析的QL包的名称。
QL包包含的其它内容（codeql分析时使用的查询和库文件）与qlpack.yml放在同一个目录，或者它的子目录中。
例如，一个包含如下文件目录的QL包，如果需要导入CustomSinks.qll只需要在包的任意目录声明：

import mycompany.java.CustomSinks

qlpack.yml
mycompany/
  java/
    security/
      CustomSinks.qll
Security/
CustomQuery.ql

我们可以通过如下方式使用自定义的查询：

codeql database analyze xssdb E:\codeql\codeql-repo\customql\java\xss.ql --format=sarif-latest --output=result.sarif
codeql database analyze xssdb E:\codeql\codeql-repo\customql\java\xss.ql --format=csv --output=codeql.csv