CodeQL CLI入门
一、CodeQL CLI 安装和配置
1.下载CodeQL CLI 压缩包
//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
仓库下载地址：//github.com/github/codeql
- go的仓库地址：//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查询。
