使用 CodeQL 查询分析代码

关于使用 CodeQL CLI 分析数据库

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

先决条件

在开始分析之前，必须：

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

运行 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 database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

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

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

分析 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=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 Enterprise Server，以供显示在 code scanning 的 工具状态页 上。 有关文件覆盖率信息的详细信息，请参阅“关于代码扫描的工具状态页”。

若要在 code scanning 结果中包含文件覆盖率信息，请将 --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=sarifv2.1.0 \
    --output=/temp/example-repo-js.sarif

运行数据库分析的示例

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

运行 CodeQL 查询包

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

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。 有关默认套件的详细信息，请参阅“发布及使用 CodeQL 包”。

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

运行单个查询

若要对 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 中使用自定义查询”。

运行目录中的所有查询

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

例如，要执行 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'

使用 codeql/cpp-queries CodeQL 包版本中的 cpp-security-and-quality.qls 查询套件分析数据库，版本 >= 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 包自定义分析”。

运行查询套件

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

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

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

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

可以在 code scanning 分析中配置威胁模型。 有关更多信息，请参阅 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 输出”。

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

查看日志和诊断信息

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

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

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

后续步骤

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