「 CodeQL从入门到精通系列 」03.CodeQL常用术语介绍

相比其他代码检测工具，CodeQL中定义了很多专用术语，为了更快上手后续章节，本文对接下来要用到的术语做了统一汇总与解读。

1. 查询语言(QL)

QL是一种声明性、面向对象的查询语言，经过优化，可实现对分层数据结构（尤其是表示软件项目的数据库）的高效分析。查询语言的用途是提供一个编程平台，可以在其中查询有关数据库中存储的信息。

2. SARIF文件

静态分析结果交换格式（Static Analysis Results Interchange Format，SARIF）是一种用于共享静态分析结果的输出格式。有关更多信息可参阅SARIF官方文档。

3. bqrs文件

一种二进制查询结果集（Binary Query Result Set，BQRS）文件。BQRS是查询原始结果的二进制表示，扩展名为.BQRS。BQRS文件可以解释为有意义的结果，并与源代码相关。例如，告警查询结果被解释为在源代码中告警发生的位置显示字符串，就像在QL中指定的那样。类似地，路径查询结果被解释为信息可以在其之间流动的位置对（sources和sinks）。这些结果可以导出为各种不同的格式，包括SARIF格式。

4. QL数据库规范（QL database schema）

QL数据库规范？是描述构成原始QL数据集的列类型和扩展关系的文件。它是一个扩展名为.dbscheme的文本文件。
一种语言的提取器和核心CodeQL包分别声明它们使用的数据库模式。这定义了他们创建或期望的数据库布局。创建CodeQL数据库时，提取器会将其模式复制到数据库中。CLI使用它来检查CodeQL数据库是否与特定的CodeQL库兼容。如果它们不兼容，您可以使用数据库升级来升级CodeQL数据库的架构。

目前还没有面向公众的模式语法规范。

5. TRAP文件

TRAP文件是由扩展名为.TRAP的CodeQL提取器生成的UTF-8编码文件。为了节省空间，通常会将其压缩存档。TRAP文件包含在相对于QL数据库进行解释时用于创建QL数据集的信息。

6. CodeQL数据库（CodeQL database）

CodeQL数据库是一个目录，主要包含如下信息：

• 从代码中提取的可查询数据。
• 源引用，用于在代码中直接显示查询结果。
• 查询结果。
• 在数据库创建、查询执行和其他操作期间生成的日志文件。

7. .qlo文件

在查询编译过程中，可以选择生成.qlo文件。如果为codeql查询编译指定–dump-qlo选项，则codeql会为其编译的查询写入.qlo文件。它们可以作为高级用户调试和性能调优的辅助工具。

qlo是一种二进制格式，它表示根据关系代数（RA）或中间DIL格式编译和优化的查询。可以使用codeql查询反编译将qlo文件扩展为可读文本。

在不同CLI版本之间，.qlo格式的确切细节可能会发生变化，而不会发出任何警告。

8. 提取器（Extractor）

提取器是一种为每个输入文件生成关系数据和源引用的工具，从中可以构建CodeQL数据库。它是CodeQL引擎的关键组件。

9. DIL

DIL（Datalog Intermediary Language）是数据日志中间语言。它是QL和关系代数（RA）之间的中间表示，在查询编译过程中生成。DIL对于高级用户非常有用，有助于调试查询性能。

Note：当为codeql查询编译指定–dump-dil选项时，codeql会将dil打印到它编译的查询的标准输出中。当您在VS代码中运行查询时，可以以DIL格式查看结果。

10. CodeQL包（CodeQL packs）

CodeQL包用于创建、共享、依赖和运行CodeQL查询、库和模型。用户可以发布自己的CodeQL包，也可以下载其他人创建的包。CodeQL查询包可能包含查询、库文件、查询套件和元数据。CodeQL库包包括一个或多个CodeQL库。CodeQL模型包包括一个或多个数据扩展文件，这些文件通过对其他库和框架（代码库的依赖项）进行建模来扩展核心库。
比如在CodeQL 2.15.5版本中可以看到默认有如下主流语言的查询包

11. 数据扩展（Data extensions）

当我们想对自定义依赖项的sources和sinks进行建模时，可以创建一个CodeQL库（.qll文件）并编写使用它的查询，但创建数据扩展文件通常要简单得多。如果在数据扩展中对source和sink进行建模，则可以使用这些信息来扩展标准查询覆盖自定义依赖项，而不需要编写任何新的查询。

12. 查询套件(Qpack)

CodeQL 查询套件提供了一种基于文件名、磁盘或 QL 包中的位置或元数据属性来选择查询的方法。 为想要在 CodeQL 分析中经常使用的查询创建查询套件。

使用查询套件，可将多个查询传递给 CodeQL，而无需单独指定每个查询文件的路径。 查询套件定义存储在扩展名为 .qls 的 YAML 文件中。 套件定义是一系列指令，其中每条指令都是带有（通常）单个键的 YAML 映射。 指令按它们在查询套件定义中的显示顺序执行。 执行套件定义中所有指令后，结果为一组选定的查询。

Note：CodeQL有三个默认查询套件：

• 1、code-scanning：默认情况下，查询在 GitHub 上的 CodeQL 代码扫描中运行。
• 2、security-extended：来自 code-scanning 的查询，以及精度和严重性略低的额外安全查询。
• 3、security-and-quality：来自 code-scanning、security-extended 的查询，以及额外的可维护性和可靠性查询。

13. 源引用（Source reference）

源引用是一种允许检索源文件内容的机制，给定文件在提取过程中所在的绝对文件名。具体示例包括：

• 一个源归档目录，在该目录中，请求的绝对文件名映射到一个UTF8编码的文件。
• 源归档文件，通常为ZIP格式，其中包含所有源文件的UTF8编码内容。
• 源归档存储库，通常为git格式，通常为裸存储库，其中包含所有源文件的UTF8编码内容。

Note：CodeQL数据库中已经默认包含了源引用。

14. 参考

[1] https://learn.microsoft.com/zh-cn/training/modules/code-scanning-with-github-codeql/2-what-is-codeql
[2] https://codeql.github.com/docs/codeql-overview/codeql-glossary/