CodeQL学习——CodeQL CLI入门
一、CodeQL 工作流程
CodeQL 的整体工作流程如下图所示：
(图片来源：https://blog.semmle.com/introduction-to-variant-analysis-part-2/)
CodeQL 的整体思路是把源代码转化成一个可查询的数据库，通过 Extractor 模块对源代码工程进行关键信息分析提取，构成一个关系型数据库。CodeQL 的数据库并没有使用现有的数据库技术，而是一套基于文件的自己的实现。
对于编译型语言，Extractor 会监控编译过程，编译器每处理一个源代码文件，它都会收集源代码的相关信息，如：语法信息（AST 抽象语法树）、语意信息（名称绑定、类型信息、运算操作等），控制流、数据流等，同时也会复制一份源代码文件。而对于解释性语言，Extractor 则直接分析源代码，得到类似的相关信息。
关键信息提取完成后，所有分析所需的数据都会导入一个文件夹，这个就是 CodeQL database, 其中包括了源代码文件、关系数据、语言相关的 database schema（schema 定义了数据之间的相互关系）。
接下来就可以对数据库进行查询了，CodeQL 自己定义实现了一套名为 QL 的查询语言，并提供了相应的支持库和运行环境。
最终将查询结果展示给用户，方便用户进行进一步的人工审计分析。
二、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 pack的根目录， 因为它包含一些并非为命令使用而设计的特殊查询。如果要运行更多的有用的查询，请选择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 |
结果文件可以集成到您自己的代码审查或调试设施中。例如，借助IDE的SARIF文件查看插件查看输出的SARIF文件时，可以让告警在源代码中突出显示。
