使用 CodeQL 查询分析您的代码

您可以针对从代码库提取的 CodeQL 数据库运行查询。

谁可以使用此功能？

CodeQL 可用于以下类型的仓库

本文内容

关于使用 CodeQL CLI 分析数据库

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

先决条件

在开始分析之前，您必须

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

运行codeql database analyze

运行database analyze时，它会

  1. 可选下载任何本地不可用的已引用 CodeQL 包。
  2. 通过在一个 CodeQL 数据库上运行它们来执行一个或多个查询文件。
  3. 根据特定查询元数据解释结果，以便可以在源代码的正确位置显示警报。
  4. 将任何诊断和汇总查询的结果报告到标准输出。

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

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

注意

如果您为单个提交分析多个 CodeQL 数据库，则必须为该命令生成的每一组结果指定一个 SARIF 类别。将结果上传到 GitHub 时，代码扫描会使用此类别分别存储每种语言的结果。如果您忘记执行此操作，则每次上传都会覆盖之前的结果。

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

您必须指定<database>、--format 和 --output。您可以根据要执行的分析指定其他选项。

选项必需用法
<database>指定包含要分析的 CodeQL 数据库的目录的路径。
<packs,queries>指定要运行的 CodeQL 包或查询。要运行用于代码扫描的标准查询，请省略此参数。要查看 CodeQL CLI 包含的其他查询套件，请查看/<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites。有关创建自己的查询套件的信息，请参阅文档中有关 CodeQL CLI 的创建 CodeQL 查询套件。
--format指定分析过程中生成的 results 文件的格式。支持多种不同的格式，包括 CSV、SARIF 和图形格式。要上传到 GitHub，这应该是：sarif-latest。有关更多信息，请参阅“代码扫描的 SARIF 支持”。
--output指定要保存 SARIF 结果文件的位置，包括带有 .sarif 扩展名的所需文件名。
--sarif-category对于单个数据库分析，可选。在分析存储库中单个提交的多个数据库时，需要定义语言。

指定一个类别，将其包含在此分析的 SARIF 结果文件中。类别用于区分同一工具和提交的多个分析，但这些分析是在不同的语言或代码的不同部分上执行的。
--sarif-add-baseline-file-info推荐。 用于将文件覆盖率信息提交到工具状态页面。有关更多信息，请参阅“关于代码扫描的工具状态页面”。
--sarif-include-query-help指定是否在 SARIF 输出中包含查询帮助。其中之一：always：包含所有查询的查询帮助。custom_queries_only（默认）：仅包含自定义查询的查询帮助，即不在 codeql/<lang>-queries 形式的查询包中的查询。never：不包含任何查询的查询帮助。在 SARIF 输出中包含的任何自定义查询的查询帮助都将显示在该查询的任何代码扫描警报中。有关更多信息，请参阅使用 CodeQL CLI 的自定义查询。
<packs>如果您想在分析中包含 CodeQL 查询包，请使用此选项。有关更多信息，请参阅下载和使用 CodeQL 包。
--download如果某些 CodeQL 查询包尚未在磁盘上并且需要在运行查询之前下载，则使用此选项。
--threads如果您想使用多个线程来运行查询，请使用此选项。默认值为 1。您可以指定更多线程来加快查询执行速度。要将线程数设置为逻辑处理器数，请指定 0。
--verbose使用此选项可获取有关分析过程和数据库创建过程的诊断数据的更多详细信息。
--threat-model(公开预览) 使用此选项可以添加威胁模型以在 CodeQL 分析中配置其他来源。在公开预览期间，威胁模型仅受 Java 分析支持。有关更多信息，请参阅database analyze。

升级数据库

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

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

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

分析 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-typescript \
    --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.

将文件覆盖率信息添加到您的结果以进行监控

您可以选择将文件覆盖率信息提交到 GitHub，以便在代码扫描的工具状态页面上显示。有关文件覆盖率信息的更多信息，请参阅关于代码扫描的工具状态页面。

要在您的代码扫描结果中包含文件覆盖率信息，请将 --sarif-add-baseline-file-info 标志添加到 CI 系统中的 codeql database analyze 调用中，例如

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

运行数据库分析的示例

以下示例显示如何使用 CodeQL 包运行 database analyze，以及如何使用 CodeQL 存储库的本地检出。这些示例假设您的 CodeQL 数据库已在与您的 CodeQL 存储库的本地副本相邻的目录中创建。

运行 CodeQL 查询包

要从 GitHub 容器注册表运行现有的 CodeQL 查询包，您可以指定一个或多个包名称

codeql database analyze <database> microsoft/[email protected] github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

此命令运行两个 CodeQL 查询包的默认查询套件：microsoft/coding-standards 版本 1.0.0 和指定数据库上的 github/security-queries 的最新版本。有关默认套件的更多信息，请参阅发布和使用 CodeQL 包。

--download 标志是可选的。使用它将确保如果查询包尚不可用，则会下载它。

运行单个查询

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

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

此命令运行一个简单的查询，查找与未使用的变量、导入、函数或类相关的潜在错误——它是 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 规范进行格式化。

运行 CodeQL 包中查询的子集

如果您使用的是 CodeQL CLI v2.8.1 或更高版本，则可以在包规范的末尾包含一个路径以运行包内的查询子集。这适用于在包内查找或运行查询的任何命令。

指定查询集的完整方法是采用 scope/name@range:path 的形式，其中

  • scope/name 是 CodeQL 包的限定名称。

  • range 是semver 范围。

  • path 是单个查询、包含查询的目录或查询套件文件的系统路径。

指定 scope/name 时，range 和 path 是可选的。如果您省略 range，则使用指定包的最新版本。如果您省略 path，则使用指定包的默认查询套件。

path 可以是 \*.ql 查询文件、包含一个或多个查询的目录或 .qls 查询套件文件。如果您省略包名称，则必须提供 path，它将被解释为当前进程的工作目录的相对路径。

如果您指定 scope/name 和 path，则 path 不能是绝对路径。它被认为是相对于 CodeQL 包根目录的相对路径。

要使用codeql/cpp-queries CodeQL 包中experimental/Security文件夹下的所有查询来分析数据库，可以使用

codeql database analyze --format=sarif-latest --output=results <db> \
    codeql/cpp-queries:experimental/Security

要运行codeql/cpp-queries CodeQL 包中的RedundantNullCheckParam.ql 查询，可以使用

codeql database analyze --format=sarif-latest --output=results <db> \
    'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'

要使用版本号大于等于 0.0.3 小于 0.1.0 的codeql/cpp-queries CodeQL 包中的cpp-security-and-quality.qls 查询套件分析您的数据库（将选择最高兼容版本），可以使用

codeql database analyze --format=sarif-latest --output=results <db> \
   'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'

如果需要引用路径中包含字面量@或:的查询文件、目录或套件，可以在查询规范前添加path:前缀，例如

codeql database analyze --format=sarif-latest --output=results <db> \
    path:C:/Users/ci/workspace@2/security/query.ql

有关 CodeQL 包的更多信息，请参阅使用 CodeQL 包自定义分析。

运行查询套件

要在 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-queries CodeQL 查询包，运行分析，并生成 SARIF 2.1.0 版本格式的文件，该格式受所有版本的 GitHub 支持。可以通过执行codeql github upload-results或代码扫描 API 将此文件上传到 GitHub。有关更多信息，请参阅将 CodeQL 分析结果上传到 GitHub或代码扫描的 REST API 端点。

CodeQL 查询套件是.qls文件，使用指令根据某些元数据属性选择要运行的查询。标准 CodeQL 包具有指定代码扫描使用的查询套件位置的元数据，因此 CodeQL CLI 知道在哪里自动查找这些套件文件，您无需在命令行上指定完整路径。有关更多信息，请参阅创建 CodeQL 查询套件。

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

包含模型包以添加潜在的污染数据源

注意

威胁模型目前处于公开预览阶段，可能会发生变化。在公开预览期间，威胁模型仅受 Java/Kotlin 和 C# 的分析支持。

您可以在代码扫描分析中配置威胁模型。有关更多信息，请参阅 CodeQL 文档中的Java 和 Kotlin 的威胁模型和C# 的威胁模型。

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --threat-model=local \
  --output=/temp/my-company.sarif codeql/java-queries

在此示例中，标准查询包codeql/java-queries中的相关查询将使用local威胁模型以及remote数据流源的默认威胁模型。如果您认为来自本地源（例如：文件系统、命令行参数、数据库和环境变量）的数据可能是代码库的潜在污染数据源，则应使用local威胁模型。

结果

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

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

有关 CSV 格式的结果外观的更多信息，请参阅CodeQL CLI CSV 输出。

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

查看日志和诊断信息

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

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

即使 CodeQL 分析失败，您也可以选择将诊断信息导出并上传到 GitHub。有关更多信息，请参阅将 CodeQL 分析结果上传到 GitHub。

后续步骤