CodeQL CLI入门

一、CodeQL CLI 安装和配置

1.下载CodeQL CLI 压缩包

https://github.com/github/codeql-cli-binaries/releases

2.创建CodeQL目录，如$HOME/codeql-home

3.创建CodeQL查询的本地拷贝

CodeQL仓库包含分析C/C++, C#, Java, JavaScript、python等所需的查询和库文件。需要拷贝一份仓库到codeql-home目录，重命名仓库文件夹为codeql-repo

仓库下载地址：https://github.com/github/codeql

• go的仓库地址：https://github.com/github/codeql-go/
• 假设CodeQL仓库目录为$HOME/codeql-home/codeql-repo，那么go的仓库目录可以设置为$HOME/codeql-home/codeql-go

4.解压CodeQL CLI 压缩包$HOME/codeql-home目录

5.运行CodeQL

（1）通过直接执行$HOME/codeql-home/codeql/codeql来运行CodeQL

（2）将$HOME/codeql-home/codeql目录添加到环境变量

二、创建CodeQL数据库

命令：

codeql database create <database> --language=<language-identifier>

参数说明：

<database>：创建的数据库的路径，必须是不存在的文件夹

--language：如下

C/C++	cpp
C#	csharp
Go	go
Java	java
JavaScript/TypeScript	javascript
Python	python

其它参数：

--source-root 指定数据库创建时的源文件根目录，默认为当前目录。

--command 指定语言的编译命令，不要给python和JavaScript指定该命令。

非编译型语言创建数据库

codeql database create --language=javascript --source-root <folder-to-extract> <output-folder>/javascript-database

三、使用CodeQL CLI分析数据库

命令：

codeql database analyze <database> <queries> --format=<format> --output=<output>

参数说明：

<database> 预分析的数据库路径

<queries> 要在数据库上运行的查询。可以指定一个或多个单独的查询文件，指定将以递归方式搜索查询文件的目录，或者命名定义了一组特定查询的查询套件。

--format  分析生成的结果文件的文件格式

--output  分析结果的输出路径

还可以通过--threads指定运行查询时要使用的线程数。默认选项是1

示例：

codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

上述分析的结果会在新创建的文件夹js-analysis下的js-results.csv文件中输出

运行目录中的所有查询

您可以通过提供目录路径而不是列出所有单个查询文件来运行目录中的所有查询。路径是递归搜索的，因此子文件夹中包含的所有查询也将被执行。

重要

您不应在执行database analyze时指定QL包的根目录， 因为它包含一些并非为命令使用而设计的特殊查询。相反，要运行各种有用的查询，请运行LGTM.com查询套件之一。

例如，要执行Functions 目录中包含的所有Python查询，您将运行：

codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif

会生成一个SARIF结果文件。通过--format=sarif-latest可确保结果根据CodeQL支持的最新SARIF规范进行格式化。

结果

您可以将分析结果保存为多种不同格式，包括SARIF和CSV。

SARIF（数据分析结果交换格式）是定义输出文件格式的OASIS 标准。 SARIF 标准用于简化静态分析工具分享其结果的方式。 有关更多信息，请参见SARIF概述。

如果选择将结果生成为CSV，则输出的每条告警将包含以下信息：

名称	标识结果的查询名称。	Inefficient regular expression
描述	查询的描述。	A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks.
严重程度	查询的严重性。	error
信息	告警消息。	This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'.
路径	包含告警的文件的路径。	/vendor/codemirror/markdown.js
起跑线	触发告警的代码开始的文件行。	617
开始栏	起始行的列，用于标记告警代码的开始。第一列不包括在内。	32
终点线	触发告警的代码结束的文件行。与起始行相同时不包括在内。	64
结束栏	可能的话，在结束行的列中标记告警代码的结尾。否则，将重复结束行。	617

结果文件可以集成到您自己的代码审查或调试基础结构中。例如，SARIF文件输出可通过IDE的SARIF查看插件在源代码中的正确告警位置进行突出显示。

在CodeQL CLI中使用自定义查询

您可以通过编写自己的查询来突出显示特定的漏洞或错误，从而自定义CodeQL分析。

写一个有效的查询

在运行自定义分析之前，您需要编写一个有效的查询，并将其保存在带有.ql扩展名的文件中。有大量可用的文档可帮助您编写查询。有关更多信息，请参阅学习CodeQL帮助中的CodeQL查询。

包括查询的元数据

查询元数据包含在每个查询文件的顶部。它为用户提供有关查询的信息，并告诉CodeQL CLI如何处理查询结果。

使用命令运行查询时，必须包括以下两个属性，以确保正确解释结果：database analyze

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

有关这些元数据属性的更多信息，请参见CodeQL查询的元数据和《查询元数据样式指南》。

注意

如果要与其他应用程序一起使用查询，则元数据要求可能会有所不同。有关更多信息，请参见学习CodeQL帮助 中的关于CodeQL查询。

创建一个自定义的QL包

编写自己的查询时，应将它们保存在自定义QL pack目录中。QL包提供了一种组织CodeQL分析中使用的文件的方法。该目录必须包含一个qlpack.yml在根目录下命名的文件。您的自定义查询应保存在QL包根目录或其子目录中。

对于每个QL包，该qlpack.yml文件都包含告诉CodeQL如何编译查询，该包所依赖的库以及在何处查找查询套件定义的信息。有关此文件中包含的内容的更多信息，请参见“ 定制QL包”。