使用 CodeQL 查询分析代码

关于使用CodeQL CLI分析数据库

注意

本文介绍了 GitHub Enterprise Server 3.15 的初始发行版中包含的 CodeQL CLI 2.18.4 捆绑包中可用的功能。

如果站点管理员已将 CodeQL CLI 版本更新为较新版本，请参阅本文的 GitHub Enterprise Cloud 版本，了解有关最新功能的信息。

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

先决条件

在开始分析之前，必须：

        [将 CodeQL CLI](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-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上传到后， code scanning 使用此类别单独存储每种语言的结果。如果忘记执行此操作，则每次上传都会覆盖之前的结果。

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

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

选项	必选	Usage
`<database>`		指定包含 CodeQL 数据库的目录路径以进行分析。
`<packs,queries>`		指定 CodeQL 包或查询以运行。若要运行用于 code scanning的标准查询，请省略此参数。若要查看捆绑包中包含的 CodeQL CLI 其他查询套件，请运行 `codeql resolve queries`。列出的套件可以带或不带 `.qls` 扩展名提供。有关创建自己的查询套件的信息，请参阅文档中的 CodeQL CLI。
`--format`		指定分析过程中生成的结果文件的格式。支持多种不同的格式，包括 CSV、SARIF 和图形格式。要上传到GitHub，应是：`sarifv2.1.0`。有关详细信息，请参阅“对代码扫描的 SARIF 支持”。
`--output`		指定要保存 SARIF 结果文件的位置，包括扩展名为 `.sarif` 的所需文件名。
`--sarif-category`		对于单一数据库分析是可选的。对于在为存储库中的单个提交分析多个数据库时定义语言是必需的。为此分析指定要包含在 SARIF 结果文件中的类别。类别用于区分针对同一工具和提交的多个分析，但在不同的语言或代码的不同部分执行。
`--sarif-add-baseline-file-info`

          **
          **建议 用于提交文件覆盖信息到工具状态页。 有关详细信息，请参阅“[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page#how-codeql-defines-scanned-files)”。 |

| --sarif-include-query-help | | 指定是否在 SARIF 输出中包含查询帮助。下列其中一项：always：包含所有查询的查询帮助。 custom_queries_only（默认）：仅包含自定义查询的查询帮助，即查询包中非 codeql/<lang>-queries 格式的查询。 never：不包含任何查询的查询帮助。 SARIF 输出中包含的自定义查询的任何查询帮助都将显示在该查询的任何代码扫描警报中。有关详细信息，请参阅“Writing custom queries for the CodeQL CLI”。 | | <packs> | | 如果要在 CodeQL 分析中包含查询包，请使用。有关详细信息，请参阅下载和使用 CodeQL 包。 | | --download | | 如果某些 CodeQL 查询包尚未在磁盘上，并且需要在运行查询之前下载，请使用。 | | --threads | | 如果想使用多个线程来运行查询，请使用此选项。默认值为 1。可以指定更多线程来加快查询执行速度。要将线程数设置为逻辑处理器数，请指定 0。 | | --verbose | | 用于从数据库创建过程中获取有关分析过程和诊断数据的更多详细信息。 | | --threat-model | | （beta 版本）用于在 CodeQL 分析中添加威胁模型以配置其他源。 beta 版本在此期间，威胁模型仅受 Java 分析支持。有关详细信息，请参阅“数据库分析”。 |

注意

          **数据库升级**

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

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

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

分析 CodeQL 数据库的基本示例

此示例分析CodeQL存储的数据库/codeql-dbs/example-repo，并将结果保存为 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=sarifv2.1.0 --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，以便在工具状态页上显示用于code scanning。有关文件覆盖率信息的更多信息，请参阅 Use the tool status page for code scanning。

若要在结果中包含 code scanning 文件覆盖率信息，请在 CI 系统中的 codeql database analyze 调用中添加 --sarif-add-baseline-file-info 参数，例如：

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

运行数据库分析的示例

以下示例演示如何使用CodeQL包运行database analyze，以及如何本地签出CodeQL存储库。假设您的 CodeQL 数据库已创建在一个目录中，该目录与 CodeQL 存储库的本地副本位于同一级别。

          CodeQL运行查询包

若要从中CodeQLGitHub运行现有Container registry查询包，可以指定一个或多个包名称：

codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

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

          `--download` 标志是可选的。 使用它可确保在本地尚不可用时下载查询包。

运行单个查询

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

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

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

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

或者，如果您已经检出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的详细信息，请参阅Writing custom queries for the CodeQL CLI。

运行目录中的所有查询

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

重要

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

例如，若要在 Functions 查询包中执行 codeql/python-queries 目录中包含的所有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 可确保根据最近支持的 CodeQLSARIF 规范设置结果的格式。

运行 CodeQL 包中的查询子集

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

指定一组查询的完整方法是采用格式 scope/name@range:path，其中：

        `scope/name` 是 CodeQL 包的限定名。

        `range` 是[语义化版本范围](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges)。

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

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

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

如果指定 scope/name 和 path，则 path 不能为绝对值。它被视为相对于CodeQL的根。软件包。

若要分析数据库，可以使用codeql/cpp-queriesCodeQL包中的experimental/Security文件夹内的所有查询：

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

若要在 RedundantNullCheckParam.ql 包中 codeql/cpp-queriesCodeQL 运行查询，请使用：

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

为了使用版本号为 >= 0.0.3 且 < 0.1.0 的包（会选择最高兼容版本）的查询套件来分析数据库，您可以使用：

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 包自定义分析。

运行查询套件

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

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”或“适用于代码扫描的 REST API 终结点”。

          CodeQL 查询套件是包含使用指令的文件，这些指令通过特定的元数据属性选择要运行的查询。 标准 CodeQL 包具有元数据，用于指定代码扫描使用的查询套件的位置，因此 CodeQL CLI 知道在何处自动查找这些套件文件，并且无需在命令行上指定完整路径。

有关详细信息，请参阅“创建 CodeQL 查询套件”。

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

包含模型包，以添加潜在受污染数据的其他来源

注意

风险模型功能目前为 beta 版本，可能随时更改。在 beta 版本期间，风险模型仅支持 Java/Kotlin 和 C# 分析。

可以在 code scanning 分析中配置威胁模型。有关详细信息，请参阅文档中适用于 Java 和 Kotlin 的威胁模型以及适用于 C#CodeQL 的威胁模型。

$ 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 威胁模型。

Results

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

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

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

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

查看日志和诊断信息

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

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

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

后续步骤

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

谁可以使用此功能？

在本文中