使用 CodeQL 查询分析代码

关于使用 CodeQL CLI 分析数据库

要分析代码库，可以针对从代码中提取的 CodeQL 数据库运行查询。 CodeQL 分析可生成结果，这些结果可以上传到 GitHub AE 以生成代码扫描警报。

先决条件

在开始分析之前，必须：

设置 CodeQL CLI 以在本地运行命令。
为要分析的源代码创建 CodeQL 数据库。

运行 codeql database analyze 最简单的方法是使用 CodeQL CLI 捆绑包中包含的标准查询。

正在运行 `codeql database analyze`

运行 database analyze 时，其：

（可选）下载任何引用的 CodeQL 包，这些包在本地不可用。
执行一个或多个查询文件，方法是通过 CodeQL 数据库运行它们。
根据特定的查询元数据解释结果，以便可以在源代码中的正确位置显示警报。
将任何诊断和摘要查询的结果报告给标准输出。

可以通过运行以下命令来分析数据库：

codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...

注意：如果你针对某个提交分析了一个以上的 CodeQL 数据库，需要为此命令生成的每组结果指定 SARIF 类别。当您上传结果到 GitHub AE 时，code scanning 使用此类别来分别存储每种语言的结果。如果忘记执行此操作，则每次上传都会覆盖之前的结果。

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <queries>

必须指定 <database>、--format 和 --output。可以指定其他选项，具体取决于要执行的分析。

选项	必选	使用情况
`<database>`		指定包含要分析的 CodeQL 数据库的目录路径。
`<packs,queries>`		指定要运行 CodeQL 包或查询。要运行用于 code scanning 的标准查询，请省略此参数。要查看 CodeQL CLI 捆绑包中包含的其他查询套件，请查看 `/<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites`。有关创建你自己的查询套件的信息，请参阅 CodeQL CLI 文档中的创建 CodeQL 查询套件。
`--format`		指定分析过程中生成的结果文件的格式。支持多种不同的格式，包括 CSV、SARIF 和图形格式。要上传到 GitHub，这应该是：`sarif-latest`。有关详细信息，请参阅“对代码扫描的 SARIF 支持”。
`--output`		指定要保存 SARIF 结果文件的位置，包括扩展名为 `.sarif` 的所需文件名。
`--sarif-category`		对于单一数据库分析是可选的。对于在为存储库中的单个提交分析多个数据库时定义语言是必需的。为此分析指定要包含在 SARIF 结果文件中的类别。类别用于区分针对同一工具和提交的多个分析，但在不同的语言或代码的不同部分执行。
`--sarif-add-query-help`		如果想为分析中使用的自定义查询包含任何可用的 Markdown 呈现查询帮助，请使用此选项。如果相关查询生成警报，则包含在 SARIF 输出中的自定义查询的任何查询帮助都将显示在代码扫描 UI 中。有关详细信息，请参阅“在 CodeQL CLI 中使用自定义查询”。
`--threads`		如果想使用多个线程来运行查询，请使用此选项。默认值是 `1`。可以指定更多线程来加快查询执行速度。要将线程数设置为逻辑处理器数，请指定 `0`。
`--verbose`		用于从数据库创建过程中获取有关分析过程和诊断数据的更多详细信息。

升级数据库

对于由 CodeQL CLI v2.3.3 或更早版本创建的数据库，需要显式升级数据库，然后才能使用较新版本的 CodeQL CLI 运行分析。如果此步骤是必需的，则会看到一条消息，告知在运行 database analyze 时需要升级数据库。

对于由 CodeQL CLI v2.3.4 或更高版本创建的数据库，CLI 将隐式运行任何所需的升级。无需显式运行升级命令。

有关分析数据库时可以使用的所有选项的完整详细信息，请参阅“数据库分析”。

分析 CodeQL 数据库的基本示例

此示例分析存储在 /codeql-dbs/example-repo 的 CodeQL 数据库并将结果保存为 SARIF 文件：/temp/example-repo-js.sarif。它使用 --sarif-category 在 SARIF 文件中包含将结果标识为 JavaScript 的额外信息。当你有多个 CodeQL 数据库来分析存储库中的单个提交时，这一点至关重要。

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

运行数据库分析的示例

以下示例演示如何使用 CodeQL 包运行 database analyze，以及如何使用 CodeQL 存储库的本地签出。这些示例假定 CodeQL 数据库是在 CodeQL 存储库本地副本的同级目录中创建的。

运行单个查询

若要对 JavaScript 代码库的 CodeQL 数据库运行单个查询，可以从包含数据库的目录中使用以下命令：

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

此命令运行一个简单的查询，用于查找与未使用的变量、导入、函数或类相关的潜在 bug，它是包含在 CodeQL 存储库中的 JavaScript 查询之一。可通过指定类似路径的空格分隔列表来运行多个查询。

分析会在新目录 (js-analysis) 中生成一个 CSV 文件 (js-results.csv)。

或者，如果已签出 CodeQL 存储库，则可以直接指定查询的路径来执行相同的查询：

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

还可以使用 database analyze 命令运行自己的自定义查询。若需详细了解如何准备查询以用于 CodeQL CLI，请参阅“在 CodeQL CLI 中使用自定义查询”。

运行目录中的所有查询

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

重要说明

在执行 database analyze 时，应避免指定核心 CodeQL 查询包的根，因为它可能包含一些并非设计用于命令的特殊查询。相反，运行查询包以在分析中包含包的默认查询，或运行代码扫描查询套件之一。

例如，要执行 codeql/python-queries 查询包中 Functions 目录中包含的所有 Python 查询，可以运行：

codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download

或者，如果已签出 CodeQL 存储库，则可以直接指定目录的路径来执行相同的查询：

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 规范设置结果的格式。

运行查询套件

要在 C/C++ 代码库的 CodeQL 数据库上运行查询套件，可以从包含数据库的目录中使用以下命令：

codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download

此命令下载 codeql/cpp-queriesCodeQL 查询包，运行分析，并生成 SARIF 版本 2.1.0 格式的文件，所有版本的 GitHub 都支持该格式的文件。可通过执行 codeql github upload-results 或代码扫描 API 将此文件上传到 GitHub。有关详细信息，请参阅“将 CodeQL 分析结果上传到 GitHub”或“代码扫描”。

CodeQL 查询套件是 .qls 文件，它们使用指令来选择要根据某些元数据属性运行的查询。标准 CodeQL 包具有指定代码扫描使用的查询套件位置的元数据，因此 CodeQL CLI 知道在哪里可以自动找到这些套件文件，并且不必在命令行中指定完整路径。有关详细信息，请参阅“创建 CodeQL 查询套件”。

有关创建自定义查询套件的信息，请参阅“创建 CodeQL 查询套件”。

结果

可通过多种不同的格式保存分析结果，包括 SARIF 和 CSV。

SARIF 格式旨在表示各种静态分析工具的输出。有关详细信息，请参阅“CodeQL CLI SARIF 输出”。

有关采用 CSV 格式的结果的外观的详细信息，请参阅“CodeQL CLI CSV 输出”。

结果文件可以集成到你自己的代码评审或调试基础结构中。例如，使用 IDE 的 SARIF 查看器插件，可以使用 SARIF 文件输出在源代码中的正确位置突出显示警报。

查看日志和诊断信息

当您使用 code scanning 查询套件分析 CodeQL 数据库时，除了生成有关警报的详细信息外，CLI 还报告数据库生成步骤和汇总指标的诊断数据。如果选择生成 SARIF 输出，则附加数据也会包含在 SARIF 文件中。对于警报很少的存储库，您可能会发现此信息可用于确定代码中是否真的存在很少的问题，或者生成 CodeQL 数据库时是否出错。要获取 codeql database analyze 更详细的输出，请使用 --verbose 选项。

有关可用诊断信息类型的详细信息，请参阅“查看代码扫描日志”。

即使 CodeQL 分析失败，你也可以选择将诊断信息导出并上传到 GitHub AE。有关详细信息，请参阅“将 CodeQL 分析结果上传到 GitHub”。

后续步骤

若要了解如何将 CodeQL 分析结果上传到 GitHub AE，请参阅“将 CodeQL 分析结果上传到 GitHub”。

使用 CodeQL 查询分析代码

本文内容