代码扫描的工作流配置选项

编辑工作流文件，以配置高级设置如何扫描项目中的代码，查找漏洞和错误。

谁可以使用此功能？

如果已启用高级设置，则具有 写入 权限的用户

本文内容

先决条件

您必须使用高级设置进行代码扫描，并且能够编辑定义配置的工作流文件。

本文提供的示例与 CodeQL 分析工作流文件相关。默认情况下，该文件位于 .github/workflows/codeql-analysis.yml。

扫描频率

您可以配置 CodeQL 分析工作流，以在计划时间或仓库中发生特定事件时扫描代码。

当有人推送更改时以及每次创建拉取请求时进行代码扫描，可防止开发者向代码中引入新的漏洞和错误。按计划扫描代码可让您了解 GitHub、安全研究人员以及社区发现的最新漏洞和错误，即使开发者并未积极维护仓库。

推送时扫描

默认情况下，CodeQL 分析工作流使用 on:push 事件在每次向仓库的默认分支以及任何受保护分支推送时触发代码扫描。若要在指定分支上触发代码扫描，工作流必须存在于该分支中。欲了解更多信息，请参阅 Workflow syntax for GitHub Actions。

如果您在推送时进行扫描，则结果会出现在仓库的 安全性和质量 选项卡中。欲了解更多信息，请参阅 Assessing code scanning alerts for your repository。

此外，当 on:push 扫描返回的结果可以映射到一个打开的拉取请求时，这些警报会自动出现在该拉取请求的同一位置，类似于其他拉取请求警报。系统通过比较分支头部的现有分析与目标分支的分析来识别这些警报。有关拉取请求中代码扫描警报的更多信息，请参阅 Triaging code scanning alerts in pull requests。

扫描拉取请求

默认的 CodeQL 分析工作流使用 pull_request 事件在针对默认分支的拉取请求上触发代码扫描。如果拉取请求来自私有分叉，则只有在仓库设置中选中了“Run workflows from fork pull requests”选项时才会触发 pull_request 事件。欲了解更多信息，请参阅 Managing GitHub Actions settings for a repository。

有关 pull_request 事件的更多信息，请参阅 Events that trigger workflows。

如果您扫描拉取请求，则结果会作为警报出现在拉取请求检查中。欲了解更多信息，请参阅 Triaging code scanning alerts in pull requests。

使用 pull_request 触发器并配置为扫描拉取请求的合并提交（而不是 HEAD 提交），比在每次推送时扫描分支的 HEAD 更高效且更准确。然而，如果您使用的 CI/CD 系统无法配置为在拉取请求时触发，仍可以使用 on:push 触发器，代码扫描会将结果映射到该分支的打开拉取请求，并在拉取请求上添加注释。更多信息请参阅 Scanning on push。

注意

如果您的仓库已配置合并队列，则需要在代码扫描的触发器中额外加入 merge_group 事件，以确保当拉取请求被加入合并队列时也会被扫描。更多信息请参阅 Managing a merge queue。

避免对拉取请求进行不必要的扫描

您可能希望避免在针对默认分支的特定拉取请求上触发代码扫描，无论更改了哪些文件。可以通过在代码扫描工作流中指定 on:pull_request:paths-ignore 或 on:pull_request:paths 来实现。例如，如果拉取请求仅修改了后缀为 .md 或 .txt 的文件，则可以使用以下 paths-ignore 数组。

YAML
on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

注意

on:pull_request:paths-ignore 和 on:pull_request:paths 用于设定在拉取请求上是否运行工作流中的操作的条件。它们并不决定在实际运行时会分析哪些文件。当拉取请求包含任意未被 on:pull_request:paths-ignore 或 on:pull_request:paths 匹配的文件时，工作流仍会运行操作并扫描该拉取请求中所有更改的文件，包括那些本应被 paths-ignore 排除的文件，除非这些文件已被排除。有关如何在分析中排除文件，请参阅 Specifying directories to scan。

有关使用 on:pull_request:paths-ignore 和 on:pull_request:paths 来决定工作流何时在拉取请求上运行的更多信息，请参阅 Workflow syntax for GitHub Actions。

按计划扫描

如果使用默认的 CodeQL 分析工作流，工作流除了响应事件触发的扫描外，还会每周对仓库代码进行一次扫描。要调整此计划，请编辑工作流中 on.schedule 事件的 cron 值。更多信息请参阅 Workflow syntax for GitHub Actions。

注意

仅当工作流文件存在于默认分支时，此事件才会触发工作流运行。

示例

下面的示例展示了一个针对特定仓库的 CodeQL 分析工作流，该仓库的默认分支为 main，并且还有一个受保护分支 protected。

YAML
on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

此工作流会扫描

  • 对默认分支和受保护分支的每次推送
  • 对默认分支的每个拉取请求
  • 默认分支每周一 14:20 UTC

操作系统

注意

  • Swift 代码的代码扫描默认使用 macOS 运行器。GitHub 托管的 macOS 运行器比 Linux 和 Windows 运行器更昂贵，因此建议仅在构建步骤时进行扫描。有关为 Swift 配置代码扫描的更多信息，请参阅 CodeQL code scanning for compiled languages。有关 GitHub 托管运行器定价的更多信息，请参阅 GitHub Actions billing。

  • ARC（Actions Runner Controller）中的运行器仅支持 Linux，且 Swift 需要 macOS 运行器，因此不支持在 ARC 运行器上进行 Swift 代码扫描。不过，您可以同时使用 ARC 运行器和自托管的 macOS 运行器。更多信息请参阅 Actions Runner Controller。

如果您的代码在编译时需要特定的操作系统，可以在 CodeQL 分析工作流中配置操作系统。编辑 jobs.analyze.runs-on 的值，以指定运行代码扫描操作的机器的操作系统。

YAML
jobs:
  analyze:
    name: Analyze
    runs-on: [ubuntu-latest]

如果选择使用自托管运行器进行代码扫描，可以在 self-hosted 之后的两元素数组的第二个元素中使用适当的标签来指定操作系统。

YAML
jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

CodeQL 代码扫描支持最新版本的 Ubuntu、Windows 和 macOS。因此此设置的常见取值为：ubuntu-latest、windows-latest 和 macos-latest。更多信息请参阅 Choosing the runner for a job 与 Using labels with self-hosted runners。

如果使用自托管运行器，必须确保 Git 已加入到 PATH 环境变量中。更多信息请参阅 Self-hosted runners 与 Adding self-hosted runners。

关于在自托管机器上运行 CodeQL 分析的推荐硬件规格（内存、CPU 核心数、磁盘空间），请参阅 Recommended hardware resources for running CodeQL。

CodeQL 数据库位置

通常情况下，您不必关心 CodeQL 分析工作流将数据库放置在何处，因为后续步骤会自动找到之前步骤创建的数据库。不过，如果您编写的自定义工作流步骤需要 CodeQL 数据库位于特定磁盘位置（例如，要将数据库作为工作流工件上传），可以在 init 动作下的 db-location 参数中指定该位置。

YAML
- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

CodeQL 分析工作流会假设 db-location 指定的路径可写，且该路径要么不存在，要么是空目录。若在自托管运行器或使用 Docker 容器的作业中使用此参数，需要自行确保在每次运行之间清理该目录，或在数据库不再需要时将其删除。GitHub 托管运行器每次运行时都会获取全新的实例和干净的文件系统，因此无需执行此操作。更多信息请参阅 GitHub-hosted runners。

如果未使用此参数，CodeQL 分析工作流将会在其自行选择的临时位置创建数据库。目前的默认值为 ${{ github.runner_temp }}/codeql_databases。

要分析的语言

CodeQL 代码扫描支持以下语言编写的代码

  • C/C++
  • C#
  • Go
  • Java/Kotlin
  • JavaScript/TypeScript
  • Python
  • Ruby
  • Rust
  • Swift
  • GitHub Actions 工作流

注意

  • 使用 java-kotlin 可分析用 Java、Kotlin 或两者混合编写的代码。
  • 使用 javascript-typescript 可分析用 JavaScript、TypeScript 或两者混合编写的代码。

更多信息请参阅 CodeQL 官方网站的文档：Supported languages and frameworks。

CodeQL 使用以下语言标识符

语言标识符可选的替代标识符（如有）
C/C++c-cppc 或 cpp
C#csharp
GitHub Actions 工作流actions
Gogo
Java/Kotlinjava-kotlinjava 或 kotlin
JavaScript/TypeScriptjavascript-typescriptjavascript 或 typescript
Pythonpython
Rubyruby
Rustrust
Swiftswift

注意

如果使用其中的替代标识符，其效果等同于使用标准语言标识符。例如，指定 javascript 而不是 javascript-typescript 并不会排除对 TypeScript 代码的分析。若需排除特定文件，请使用自定义配置文件的 paths-ignore 设置。更多信息请参阅 Using a custom configuration file 与 Specifying directories to scan。

这些语言标识符可作为 init 动作的 languages 输入参数。我们建议一次仅提供一个语言作为参数。

YAML
- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

在 使用 CodeQL 配置高级代码扫描 之后自动创建的默认 CodeQL 分析工作流文件会定义一个矩阵，其中包含名为 language 的属性，列出仓库中将被分析的语言。该矩阵已自动预填充检测到的受支持语言。使用 language 矩阵可让 CodeQL 并行运行每种语言的分析，并为每种语言定制分析。在单个分析中，矩阵中的语言名称会作为 languages 输入的参数传递给 init 动作。我们建议所有工作流都采用此配置。有关矩阵的更多信息，请参阅 Running variations of jobs in a workflow。

YAML
- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

如果您的工作流使用了 language 矩阵，则 CodeQL 只会分析矩阵中的语言。若要更改要分析的语言，请编辑矩阵配置。您可以删除不想分析的语言。可能需要排除某些语言的原因包括：项目依赖于与主要代码不同的语言，而您不希望看到这些依赖的警报。您也可以添加在配置代码扫描时仓库中不存在的语言。例如，最初仅包含 JavaScript，后续加入了 Python，则需要在矩阵中添加 python。

YAML
jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

对于编译语言，矩阵还可用于通过更改 build-mode 属性的值来配置分析时使用的构建模式。有关构建模式的更多信息，请参阅 CodeQL code scanning for compiled languages。

如果您的工作流未向 init 动作的 languages 输入提供参数，则 CodeQL 会被配置为顺序运行分析。在这种情况下，CodeQL 会自动检测并尝试分析仓库中所有受支持的语言，取决于仓库规模和语言数量，这可能会耗时很长。如果其中一种语言的分析失败，则所有语言的分析都会失败。因此不推荐此配置。

注意

顺序分析语言时，将使用每种语言的默认 build-mode。或者，如果您显式提供了 autobuild 步骤，则所有支持 autobuild 模式的语言都会使用该模式，其他语言仍使用各自的默认模式。如需更复杂的 build-mode 配置，需要使用矩阵。

检查失败的警报严重性

您可以使用规则集（rulesets）在满足以下任意条件时阻止拉取请求合并

  • 必需的工具发现了规则集中定义的严重程度的代码扫描警报。
  • 必需的工具仍在进行分析。
  • 必需的工具未为该仓库配置。

更多信息请参阅 Set code scanning merge protection。关于规则集的一般信息，请参阅 About rulesets。

分析类别

使用 category 可在同一工具和同一次提交的多次分析之间进行区分，这些分析可能针对不同语言或代码的不同部分。您在工作流中指定的类别会包含在 SARIF 结果文件中。

如果您使用 monorepo（单体仓库）并且为 monorepo 的不同组件生成多个 SARIF 文件，此参数尤为有用。

YAML
    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

如果在工作流中未指定 category 参数，GitHub 会基于触发该动作的工作流文件名、动作名称以及任何矩阵变量为您生成一个类别名称。例如：

  • 工作流 .github/workflows/codeql-analysis.yml 和 analyze 动作将生成类别 .github/workflows/codeql.yml:analyze。
  • 工作流 .github/workflows/codeql-analysis.yml、analyze 动作以及矩阵变量 {language: javascript-typescript, os: linux} 将生成类别 .github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux。

在 SARIF v2.1.0 中，category 值会出现在 <run>.automationDetails.id 属性中。更多信息请参阅 SARIF support for code scanning。

如果 SARIF 文件中已包含 runAutomationDetails 对象，您指定的类别不会覆盖其中的细节。

CodeQL 模型包

如果您的代码库依赖于标准 CodeQL 查询未识别的库或框架，您可以通过指定已发布的 CodeQL 模型包来扩展代码扫描工作流中的覆盖范围。有关创建自定义模型包的更多信息，请参阅 Creating and working with CodeQL packs。

注意

CodeQL 模型包目前处于公开预览阶段，可能会更改。模型包支持 C/C++、C#、Java/Kotlin、Python、Ruby 和 Rust 的分析。

Visual Studio Code 的 CodeQL 扩展中的 CodeQL 模型编辑器支持对 C#、Java/Kotlin、Python 和 Ruby 的依赖建模。

使用 CodeQL 模型包

要添加一个或多个已发布的 CodeQL 模型包，请在工作流的 uses: github/codeql-action/init@v4 部分的 with: packs: 条目中指定它们。在 packs 中您可以列出要使用的一个或多个包，并可选指定下载的版本。如果未指定版本，则下载最新版本。若要使用非公开的包，需要将 GITHUB_TOKEN 环境变量设为拥有访问这些包权限的密钥。更多信息请参阅 Use GITHUB_TOKEN for authentication in workflows 与 Using secrets in GitHub Actions。

YAML
- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

在此示例中，默认查询将针对 Java 运行，同时还会运行来自查询包 my-company/my-java-queries（版本 ≥ 7.8.9 且 < 7.9.0）的查询。最新版本的模型包 my-repo/my-java-model-pack 中建模的依赖将对默认查询和 my-company/my-java-queries 中的查询均可用。

非默认查询

使用 CodeQL 扫描代码时，分析引擎会从代码生成数据库并在其上运行查询。CodeQL 分析使用默认查询集，但您可以在默认查询之外指定额外的查询运行。

提示

您还可以指定想要排除或包含在分析中的查询，这需要使用自定义配置文件。更多信息请参阅 Custom configuration files 与 Excluding specific queries from analysis。

如果额外查询是发布到 GitHub Container Registry 的 CodeQL 包或存放在某仓库中的 CodeQL 包的一部分，您即可运行这些额外查询。更多信息请参阅 About code scanning with CodeQL。

指定要运行的额外查询的可用选项包括：

  • packs：安装一个或多个 CodeQL 查询包，并运行这些包的默认查询套件或查询。
  • queries：指定单个 .ql 文件、包含多个 .ql 文件的目录、.qls 查询套件定义文件，或任意组合。有关查询套件定义的更多信息，请参阅 Creating CodeQL query suites。

您可以在同一工作流中同时使用 packs 与 queries。

我们不建议直接引用 github/codeql 仓库中的查询套件，例如 github/codeql/cpp/ql/src@main。这些查询需要重新编译，且可能与 GitHub Actions 当前使用的 CodeQL 版本不兼容，从而导致分析出错。

使用查询包

要添加一个或多个 CodeQL 查询包，请在工作流的 uses: github/codeql-action/init@v4 部分的 with: packs: 条目中指定它们。其余步骤与前述 packs 用法相同。若要使用非公开的包，需要将 GITHUB_TOKEN 环境变量设为拥有访问这些包权限的密钥。更多信息请参阅 Use GITHUB_TOKEN for authentication in workflows 与 Using secrets in GitHub Actions。

注意

对于为多语言生成 CodeQL 数据库的工作流，必须在配置文件中指定 CodeQL 查询包。更多信息请参阅下面的 Specifying CodeQL query packs。

在下面的示例中，scope 表示发布该包的组织或个人账户。当工作流运行时，四个 CodeQL 查询包将从 GitHub 下载，并运行每个包的默认查询或查询套件。

  • 将下载 pack1 的最新版本，并运行所有默认查询。
  • 将下载 pack2 的 1.2.3 版本，并运行所有默认查询。
  • 将下载与版本 3.2.1 兼容的最新 pack3 版本，并运行全部查询。
  • 将下载 pack4 的 4.5.6 版本，并仅运行位于 path/to/queries 中的查询。
YAML
- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

注意

如果您指定了特定的查询包版本，请注意该版本可能最终会因默认 CodeQL 引擎的更新而变得过旧而影响性能。若需锁定查询包版本，建议定期检查并根据需要升级至较新版本。

有关包兼容性的更多信息，请参阅 CodeQL query packs reference。

从 GitHub Enterprise Server 下载 CodeQL 包

如果工作流使用的包发布在 GitHub Enterprise Server 实例上，需要告诉工作流到哪里去获取它们。可以通过在 github/codeql-action/init@v4 动作中使用 registries 输入来实现。该输入接受一个包含 url、packages 与 token 属性的列表，如下所示。

YAML
- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

注册表列表中的包模式会按顺序检查，因此一般应将最具体的包模式放在前面。token 的取值必须是您从下载所在的 GitHub 实例生成的个人访问令牌（经典），并具备 read:packages 权限。

请注意 registries 属性名后面的 |。这很重要，因为 GitHub Actions 的输入只能接受字符串。使用 | 可将后续文本转换为字符串，随后由 github/codeql-action/init@v4 动作解析。

在 QL 包中使用查询

要添加一个或多个查询，请在工作流的 uses: github/codeql-action/init@v4 部分的 with: queries: 条目中指定它们。如果查询位于私有仓库，请使用 external-repository-token 参数指定具有检出该私有仓库权限的令牌。

您还可以在 queries 的值中指定查询套件。查询套件是一组查询，通常按用途或语言进行分组。

YAML
- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

以下查询套件已内置于 CodeQL 代码扫描，可直接使用。

查询套件描述
security-extended基于默认套件的查询，另加低严重性和低精度的查询
security-and-quality在 security-extended 的基础上，额外包含可维护性和可靠性查询

更多信息请参阅：CodeQL query suites。

每个查询套件都包含了内置 CodeQL 查询包中对应语言的不同子集。查询套件是根据每个查询的元数据自动生成的。更多信息请参阅 Metadata for CodeQL queries。

当您指定查询套件时，CodeQL 分析引擎会运行默认查询集以及该额外查询套件中定义的查询。

使用自定义配置文件

如果您同时使用了自定义配置文件进行设置，工作流中指定的额外 pack 或 query 将覆盖配置文件中指定的相同内容。若想在使用引用的配置文件的同时再加入工作流中指定的额外 pack 或 query，请在工作流中的 packs 或 queries 值前加上 + 符号。更多信息请参阅 Custom configuration files。

下面的示例中，+ 符号确保指定的额外 pack 和 query 会与引用的配置文件中指定的内容一起使用。

YAML
- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

自定义配置文件

自定义配置文件是一种指定要运行的额外查询包和查询的替代方式。您也可以使用该文件来禁用默认查询、排除或包含特定查询，以及指定在分析期间要扫描的目录。

在工作流文件中，使用 config-file 参数（init 动作）来指定要使用的配置文件路径。此示例加载配置文件 ./.github/codeql/codeql-config.yml。

YAML
- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml

配置文件可以位于您正在分析的仓库内部，也可以位于外部仓库。使用外部仓库可以让您在一个位置为多个仓库指定配置选项。当您引用位于外部仓库的配置文件时，可以使用 OWNER/REPOSITORY/FILENAME@BRANCH 语法。例如，octo-org/shared/codeql-config.yml@main。

如果配置文件位于外部私有仓库，请使用 external-repository-token 参数（init 动作）来指定拥有该私有仓库访问权限的令牌。

YAML
- uses: github/codeql-action/init@v4
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

配置文件中的设置采用 YAML 格式编写。

指定 CodeQL 查询包

您在数组中指定 CodeQL 查询包。请注意，这种格式与工作流文件中使用的格式不同。

YAML
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

指定查询包的完整格式为 scope/name[@version][:path]。version 和 path 均为可选项。version 使用语义化版本范围。如果未提供，则使用最新版本。有关语义化版本范围的更多信息，请参阅 npm 上的 semver 文档。

如果您的工作流会生成多个 CodeQL 数据库，您可以在自定义配置文件中使用嵌套映射（map）来为每个数据库指定要运行的任意 CodeQL 查询包。

YAML
packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

使用威胁模型扩展 CodeQL 覆盖范围

注意

威胁模型目前处于公开预览阶段，可能会更改。在公开预览期间，威胁模型仅在针对 Java/Kotlin 和 C# 的分析中受支持。

默认威胁模型包括来自不可信数据的远程来源。通过在自定义配置文件中指定 threat-models: local，您可以将本地不可信数据来源（例如：命令行参数、环境变量、文件系统和数据库）加入 CodeQL 威胁模型。若您扩展了威胁模型，默认的威胁模型仍会一起使用。

指定额外查询

您在 queries 数组中指定额外查询。数组的每个元素包含一个 uses 参数，其值标识单个查询文件、包含查询文件的目录，或查询套件定义文件。

YAML
queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

您还可以像下面的示例配置文件那样为每个数组元素指定一个名称。有关额外查询的更多信息，请参阅上文的 非默认查询。

禁用默认查询

如果您只想运行自定义查询，可以通过使用 disable-default-queries: true 来禁用默认的安全查询。

从分析中排除特定查询

您可以在自定义配置文件中添加 exclude 与 include 过滤器，以指定要在分析中排除或包含的查询。

例如，您可能想要排除以下情况：

  • 默认套件中的特定查询（security、security-extended 和 security-and-quality）。
  • 结果对您没有意义的特定查询。
  • 所有产生警告和建议的查询。

您可以使用类似下面配置文件中的 exclude 过滤器来排除不想在默认分析中运行的查询。在下面的示例配置文件中，js/redundant-assignment 与 js/useless-assignment-to-local 两个查询均被排除。

YAML
query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

要查找查询的 ID，您可以在 安全与质量 选项卡中点击警报。该页面会打开警报详情页，其中的 Rule ID 字段即为查询 ID。有关警报详情页的更多信息，请参阅 关于代码扫描警报。

提示

  • 过滤器的顺序很重要。位于查询和查询包说明之后的第一条过滤指令决定这些查询默认是被包含还是被排除。
  • 随后出现的指令按顺序执行，文件后出现的指令会覆盖前面的指令。

您可以在 示例配置文件 部分找到另一个展示这些过滤器用法的示例。

有关在自定义配置文件中使用 exclude 与 include 过滤器的更多信息，请参阅 创建 CodeQL 查询套件。有关可以用于过滤的查询元数据，请参阅 CodeQL 查询的元数据。

指定要扫描的目录

当在未构建代码的情况下分析代码库时，您可以通过在配置文件中添加 paths 数组来限制代码扫描仅针对特定目录下的文件。您也可以通过添加 paths-ignore 数组来排除特定目录下的文件。此选项适用于在解释型语言（Python、Ruby、JavaScript/TypeScript）上运行 CodeQL 动作，或在不构建代码的情况下分析已编译语言（当前支持 C/C++、C#、Java 和 Rust）。

YAML
paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

注意

  • paths 与 paths-ignore 关键字在代码扫描配置文件中的含义，不能与工作流中用于 on.<push|pull_request>.paths 的同名关键字混淆。当它们用在工作流的 on.<push|pull_request> 中时，用来决定在指定目录的代码变动时是否触发动作。更多信息请参阅 GitHub Actions 工作流语法。
  • 过滤模式字符 ?、+、[、] 与 ! 不受支持，会被视为普通字符进行匹配。
  • ** 只能出现在行首、行尾或被斜杠包围，且不能与其他字符混用。例如 foo/**、**/foo 与 foo/**/bar 都是合法语法，但 **foo 则不行。不过您可以在同一模式中使用单星号与其他字符，如示例所示。含有 * 的模式需要加引号。

对于需要构建代码的分析，如果希望将代码扫描限制在项目的特定目录下，必须在工作流中指定相应的构建步骤。排除某个目录的构建指令取决于您使用的构建系统。更多信息请参阅 已编译语言的 CodeQL 代码扫描。

当您在特定目录修改代码时，可快速分析 monorepo 中的少量子项目。为实现此目的，您需要在构建步骤中排除相应目录，并在工作流的 on.<push|pull_request> 中同时使用 paths-ignore 与 paths 关键字。

示例配置文件

此配置文件将 security-and-quality 查询套件添加到 CodeQL 扫描代码时运行的查询列表中。有关可用查询套件的更多信息，请参阅 非默认查询。

name: "My CodeQL config"

queries:
  - uses: security-and-quality

下面的配置文件禁用了默认查询，并指定了一组自定义查询来代替运行。它还配置 CodeQL 扫描位于 src 目录（相对于仓库根目录）的文件，但排除 src/node_modules 目录以及所有文件名以 .test.js 结尾的文件。因此，src/node_modules 中的文件和以 .test.js 结尾的文件都会被排除在分析之外。

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository CodeQL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript CodeQL pack (run queries from an external repo)
    uses: octo-org/javascript-codeql-pack@main
  - name: Use an external query (run a single query from an external CodeQL pack)
    uses: octo-org/python-codeql-pack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

下面的配置文件仅运行产生 **error** 严重性警报的查询。该配置首先选择所有默认查询、./my-queries 中的所有查询以及 codeql/java-queries 中的默认套件，然后排除所有产生警告或建议的查询。

queries:
  - name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

配置细节

如果您更倾向于在工作流文件中直接指定额外的配置细节，可以使用 CodeQL 动作的 init 命令的 config 输入参数。该输入的值必须是符合 自定义配置文件 部分文档的 YAML 字符串。

示例配置

此 GitHub Actions 工作流文件中的步骤使用 config 输入来禁用默认查询、添加 security-extended 查询套件，并排除带有 cwe-020 标签的查询。

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      threat-models: local
      queries:
        - uses: security-extended
      query-filters:
        - exclude:
            tags: /cwe-020/

您可以采用相同的方式在工作流文件中指定任何有效的配置选项。

提示

您可以使用 GitHub Actions 变量在多个仓库之间共享同一套配置。这种做法的一个好处是，只需在一个位置更新配置即可，无需逐个编辑工作流文件。

在下面的示例中，vars.CODEQL_CONF 是一个 GitHub Actions 变量。它的值可以是任何有效配置文件的内容。更多信息请参阅 在变量中存储信息。

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

已编译语言

对于已编译语言，您可以决定 CodeQL 动作如何为分析创建 CodeQL 数据库。有关可用构建选项的详细信息，请参阅 已编译语言的 CodeQL 代码扫描。

数据上传

GitHub 可以显示由第三方工具在外部生成的代码分析数据。您可以使用 upload-sarif 动作上传代码分析数据。更多信息请参阅 将 SARIF 文件上传至 GitHub。

© . This site is unofficial and not affiliated with GitHub, Inc.