自定义代码扫描的高级设置

您可以自定义高级设置如何扫描项目中的代码以查找漏洞和错误。

谁可以使用此功能？

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

本文内容

关于代码扫描配置

您可以使用 GitHub Actions 或您现有的持续集成 (CI) 系统在 GitHub 上运行代码扫描。有关更多信息，请参阅“编写工作流程”或“将代码扫描与您现有的 CI 系统一起使用”。

使用代码扫描的高级设置，您可以自定义代码扫描工作流程以精确控制您的配置。有关更多信息，请参阅“配置代码扫描的高级设置”。

CodeQL 分析只是您可以在 GitHub 中执行的一种代码扫描类型。GitHub Marketplace 包含您可以使用的其他代码扫描工作流程。您可以在“开始使用代码扫描”页面上找到这些工作流程的示例，您可以从** 安全**选项卡访问。本文中给出的具体示例与 CodeQL 分析工作流文件相关。

编辑代码扫描工作流程

GitHub 将工作流文件保存在存储库的.github/workflows目录中。您可以通过搜索其文件名来查找已添加的工作流。例如，默认情况下，CodeQL 代码扫描的工作流文件名为codeql-analysis.yml。

  1. 在您的存储库中，浏览到您要编辑的工作流文件。
  2. 在文件视图的右上角，单击以打开工作流编辑器.
  3. 编辑文件后，单击**开始提交**并完成“提交更改”表单。您可以选择直接提交到当前分支，或创建新分支并启动拉取请求。

有关编辑工作流文件的更多信息，请参阅“编写工作流程”。

配置频率

您可以将 CodeQL 分析工作流配置为按计划扫描代码或在存储库中发生特定事件时扫描代码。

当有人推送更改时扫描代码，以及每当创建拉取请求时扫描代码，都可以防止开发人员将新的漏洞和错误引入代码中。按计划扫描代码可以告知您 GitHub、安全研究人员和社区发现的最新漏洞和错误，即使开发人员没有积极维护存储库也是如此。

推送时扫描

默认情况下，CodeQL 分析工作流使用on:push事件来触发对存储库默认分支和任何受保护分支的每次推送的代码扫描。要触发指定分支上的代码扫描，工作流必须存在于该分支中。更多信息，请参阅“GitHub Actions 的工作流语法”。

如果在推送时进行扫描，则结果会显示在存储库的**安全**选项卡中。更多信息，请参阅“评估您的存储库的代码扫描警报”。

此外，当on:push扫描返回可以映射到打开的拉取请求的结果时，这些警报将自动显示在拉取请求中，位置与其他拉取请求警报相同。通过将分支头的现有分析与目标分支的分析进行比较来识别警报。有关拉取请求中代码扫描警报的更多信息，请参阅“处理拉取请求中的代码扫描警报”。

扫描拉取请求

默认的 CodeQL 分析工作流使用pull_request事件来触发针对默认分支的拉取请求的代码扫描。如果拉取请求来自私有fork，则只有在您选择了存储库设置中的“从fork拉取请求运行工作流”选项后，才会触发pull_request事件。更多信息，请参阅“管理存储库的 GitHub Actions 设置”。

有关pull_request事件的更多信息，请参阅“触发工作流的事件”。

如果扫描拉取请求，则结果会作为警报显示在拉取请求检查中。更多信息，请参阅“处理拉取请求中的代码扫描警报”。

使用配置为扫描拉取请求的合并提交而不是头提交的pull_request触发器，将比每次推送扫描分支头产生更高效、更准确的结果。但是，如果您使用无法配置为根据拉取请求触发CI/CD系统的系统，您仍然可以使用on:push触发器，代码扫描将结果映射到分支上的打开的拉取请求，并将警报作为注释添加到拉取请求中。更多信息，请参阅“推送时扫描”。

注意

如果您的存储库配置了合并队列，则需要包含merge_group事件作为代码扫描的附加触发器。这将确保在将拉取请求添加到合并队列时也对其进行扫描。更多信息，请参阅“管理合并队列”。

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

您可能希望避免在针对默认分支的特定拉取请求上触发代码扫描，而不管已更改了哪些文件。您可以通过在代码扫描工作流中指定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匹配的文件时，工作流将运行操作并扫描拉取请求中更改的所有文件，包括与on:pull_request:paths-ignore或on:pull_request:paths匹配的文件（除非已排除这些文件）。有关如何从分析中排除文件的更多信息，请参阅“指定要扫描的目录”。

有关使用on:pull_request:paths-ignore和on:pull_request:paths确定何时为拉取请求运行工作流的更多信息，请参阅“GitHub Actions 的工作流语法”。

按计划扫描

如果您使用默认的 CodeQL 分析工作流，则除了由事件触发的扫描外，工作流还将每周扫描一次存储库中的代码。要调整此计划，请编辑工作流中的cron值。更多信息，请参阅“GitHub Actions 的工作流语法”。

注意

GitHub 仅运行默认分支中工作流中安排的作业。更改任何其他分支中工作流中的计划无效，除非您将该分支合并到默认分支中。

示例

以下示例显示了特定存储库的 CodeQL 分析工作流，该存储库具有名为main的默认分支和一个名为protected的受保护分支。

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

此工作流扫描

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

指定操作系统

注意

  • Swift 代码的代码扫描默认使用 macOS 运行器。GitHub 托管的 macOS 运行器比 Linux 和 Windows 运行器更昂贵，因此您应该考虑只扫描构建步骤。有关配置 Swift 代码扫描的更多信息，请参阅“编译语言的 CodeQL 代码扫描”。有关 GitHub 托管运行器的定价信息，请参阅“关于 GitHub Actions 的计费”。

  • 由于 ARC 运行器仅使用 Linux，而 Swift 需要 macOS 运行器，因此不支持对作为 Actions Runner Controller (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。更多信息，请参阅“为作业选择运行器”和“使用自托管运行器的标签”。

如果您使用自托管运行器，则必须确保 Git 位于 PATH 变量中。更多信息，请参阅“关于自托管运行器”和“添加自托管运行器”。

有关在自托管机器上运行 CodeQL 分析的推荐规格（RAM、CPU 内核和磁盘），请参阅“运行 CodeQL 的推荐硬件资源”。

指定 CodeQL 数据库的位置

通常，您无需担心 CodeQL 分析工作流放置 CodeQL 数据库的位置，因为后续步骤会自动找到先前步骤创建的数据库。但是，如果您正在编写需要 CodeQL 数据库位于特定磁盘位置的自定义工作流步骤（例如，将数据库上传为工作流工件），则可以使用init操作下的db-location参数指定该位置。

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

CodeQL 分析工作流将期望db-location中提供的路径可写，并且要么不存在，要么为空目录。在自托管运行器上运行作业或使用 Docker 容器时，用户有责任确保在运行之间清除所选目录，或在不再需要数据库后将其删除。对于在 GitHub 托管的运行器上运行的作业，则无需执行此操作，因为每次运行时都会获得新的实例和干净的文件系统。更多信息，请参阅“使用 GitHub 托管的运行器”。

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

更改要分析的语言

CodeQL 代码扫描会自动检测用支持的语言编写的代码。

  • C/C++
  • C#
  • Go
  • Java/Kotlin
  • JavaScript/TypeScript
  • Python
  • Ruby
  • Swift

注意

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

更多信息，请参阅 CodeQL 网站上的文档：“支持的语言和框架”。

CodeQL 使用以下语言标识符

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

注意

如果指定了替代标识符之一，则等效于使用标准语言标识符。例如，指定javascript而不是javascript-typescript不会排除对 TypeScript 代码的分析。您可以在高级设置工作流程中使用--paths-ignore选项执行此操作。有关更多信息，请参阅“自定义代码扫描的高级设置”。

默认的 CodeQL 分析工作流程文件包含一个名为language的矩阵，其中列出了存储库中进行分析的语言。当您向存储库添加代码扫描时，CodeQL 会自动填充此矩阵。使用language矩阵可以优化 CodeQL，使其并行运行每个分析。我们建议所有工作流程都采用此配置，因为并行化构建具有性能优势。有关矩阵的更多信息，请参阅“在工作流程中运行作业的变体”。

如果您的存储库包含多种受支持语言的代码，您可以选择要分析的语言。您可能希望阻止分析某种语言的原因有很多。例如，项目可能具有与代码主体不同的语言的依赖项，您可能更倾向于不查看这些依赖项的警报。

如果您的工作流程使用language矩阵，则 CodeQL 会硬编码为仅分析矩阵中的语言。要更改要分析的语言，请编辑矩阵变量的值。您可以删除一种语言以防止对其进行分析，也可以添加在配置代码扫描时存储库中不存在的语言。例如，如果在配置代码扫描时存储库最初只包含 JavaScript，而您后来添加了 Python 代码，则需要将python添加到矩阵中。

YAML
jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript-typescript', 'python']

如果您的工作流程不包含名为language的矩阵，则 CodeQL 配置为顺序运行分析。如果您没有在工作流程中指定语言，CodeQL 会自动检测并尝试分析存储库中任何受支持的语言。如果您想选择要分析的语言，而不使用矩阵，则可以使用init操作下的languages参数。

YAML
- uses: github/codeql-action/init@v3
  with:
    languages: c-cpp, csharp, python

定义导致拉取请求检查失败的警报严重性

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

  • 必需的工具找到了规则集中定义的严重性代码扫描警报。

  • 必需的代码扫描工具的分析仍在进行中。

  • 未为存储库配置必需的代码扫描工具。

有关更多信息，请参阅“设置代码扫描合并保护”。有关规则集的更多一般信息，请参阅“关于规则集”。

为分析配置类别

使用category区分同一工具和提交的多个分析，但这些分析是在不同的语言或代码的不同部分上执行的。您在工作流程中指定的类别将包含在 SARIF 结果文件中。

如果您使用的是单体存储库并且对单体存储库的不同组件有多个 SARIF 文件，则此参数特别有用。

YAML
    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v3
      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。

category值将显示为 SARIF v2.1.0 中的<run>.automationDetails.id属性。有关更多信息，请参阅“代码扫描的 SARIF 支持”。

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

使用 CodeQL 模型包扩展 CodeQL 覆盖范围

如果您的代码库依赖于 CodeQL 中标准查询无法识别的库或框架，则可以通过指定已发布的 CodeQL 模型包来扩展代码扫描工作流程中的 CodeQL 覆盖范围。有关创建您自己的模型包的更多信息，请参阅“创建和使用 CodeQL 包”。

注意

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

使用 CodeQL 模型包

要添加一个或多个已发布的 CodeQL 模型包，请在工作流程的uses: github/codeql-action/init@v3部分内的with: packs:条目中指定它们。在packs中，您可以指定一个或多个要使用的包，以及可选的要下载的版本。如果您没有指定版本，则会下载最新版本。如果您想使用不可公开访问的包，则需要将GITHUB_TOKEN环境变量设置为具有访问包权限的密钥。有关更多信息，请参阅“自动令牌身份验证”和“在 GitHub Actions 中使用密钥”。

YAML
- uses: github/codeql-action/init@v3
  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 的默认查询，以及来自版本大于或等于7.8.9且小于7.9.0的查询包my-company/my-java-queries的查询。最新版本模型包my-repo/my-java-model-pack中建模的依赖项将可用于默认查询和my-company/my-java-queries中的查询。

运行其他查询

当您使用 CodeQL 扫描代码时，CodeQL 分析引擎会根据代码生成数据库，并在其上运行查询。CodeQL 分析使用一组默认查询，但您可以指定更多要运行的查询，以补充默认查询。

您还可以指定要从分析中排除或包含在分析中的查询。这需要使用自定义配置文件。有关更多信息，请参阅下面的“使用自定义配置文件”和“从分析中排除特定查询”。

如果其他查询是发布到 GitHub 容器注册表或存储在存储库中的 CodeQL 包的一部分，则可以运行它们。有关更多信息，请参阅“关于使用 CodeQL 进行代码扫描”。

可用于指定要运行的其他查询的选项包括：

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

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

我们不建议直接从github/codeql存储库引用查询套件，例如github/codeql/cpp/ql/src@main。此类查询必须重新编译，并且可能与当前在 GitHub Actions 上启用的 CodeQL 版本不兼容，这可能会导致分析过程中出现错误。

使用查询包

要添加一个或多个 CodeQL 查询包，请在工作流程的uses: github/codeql-action/init@v3部分内添加with: packs:条目。在packs中，您可以指定一个或多个要使用的包，以及可选的要下载的版本。如果您没有指定版本，则会下载最新版本。如果您想使用不可公开访问的包，则需要将GITHUB_TOKEN环境变量设置为具有访问包权限的密钥。有关更多信息，请参阅“自动令牌身份验证”和“在 GitHub Actions 中使用密钥”。

注意

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

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

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

注意

如果您指定要使用的查询包的特定版本，请注意，您指定的版本最终可能太旧而无法被 CodeQL 操作使用的默认 CodeQL 引擎有效使用。为了确保最佳性能，如果您需要指定确切的查询包版本，则应定期检查是否需要将查询包的固定版本向前移动。

有关包兼容性的更多信息，请参阅“发布和使用 CodeQL 包”。

从 GitHub Enterprise Server 下载 CodeQL 包

如果您的工作流程使用在 GitHub Enterprise Server 安装上发布的包，则需要告诉您的工作流程在哪里可以找到它们。您可以使用github/codeql-action/init@v3操作的registries输入来执行此操作。此输入接受如下所示的url、packages和token属性列表。

YAML
- uses: github/codeql-action/init@v3
  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@v3 action解析。

在QL包中使用查询

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

您也可以在queries的值中指定查询套件。查询套件是查询的集合，通常按用途或语言分组。

YAML
- uses: github/codeql-action/init@v3
  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 查询套件”。

这些查询套件中的每一个都包含该语言的内置CodeQL查询包中包含的不同子集的查询。查询套件是使用每个查询的元数据自动生成的。更多信息，请参见：“CodeQL 查询的元数据”。

指定查询套件时，CodeQL分析引擎将运行默认的查询集和附加查询套件中定义的任何额外查询。

使用自定义配置文件

如果您还使用配置文件进行自定义设置，则工作流中指定的任何其他包或查询将代替配置文件中指定的包或查询。如果您想运行组合的额外包或查询集，请在工作流中使用+符号作为packs或queries值的开头。更多信息，请参见：“使用自定义配置文件”。

在以下示例中，+符号确保指定的附加包和查询与引用的配置文件中指定的任何包和查询一起使用。

YAML
- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

使用自定义配置文件

自定义配置文件是指定要运行的其他包和查询的另一种方法。您还可以使用该文件禁用默认查询、排除或包含特定查询，以及指定分析期间要扫描的目录。

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

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

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

如果配置文件位于外部私有存储库中，请使用init操作的external-repository-token参数指定一个具有访问私有存储库权限的令牌。

YAML
- uses: github/codeql-action/init@v3
  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/[email protected]
  # 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是semver版本范围。如果缺少，则使用最新版本。有关semver范围的更多信息，请参阅npm上的semver文档。

如果您有一个生成多个CodeQL数据库的工作流，则可以使用嵌套的包映射在自定义配置文件中指定要运行的任何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/[email protected]

使用威胁模型扩展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，您可以单击**安全**选项卡中的警报列表中的警报。这将打开警报详细信息页面。规则ID字段包含查询ID。有关警报详细信息页面的更多信息，请参见：“关于代码扫描警报”。

提示

  • 过滤器的顺序很重要。查询和查询包说明后出现的第一个过滤器指令决定默认情况下是否包含或排除查询。
  • 后续指令按顺序执行，文件中后面出现的指令优先于前面出现的指令。

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

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

指定要扫描的目录

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

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代码扫描”。

修改特定目录中的代码时，您可以快速分析单体代码库的小部分内容。您需要在构建步骤中排除目录，并对工作流中的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'

以下配置文件仅运行生成严重性为错误的警报的查询。该配置首先选择所有默认查询、./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

使用config输入指定配置详细信息

如果您更愿意在工作流文件中指定其他配置详细信息，则可以使用 CodeQL action 的init命令的config输入。此输入的值必须是遵循上面“使用自定义配置文件”中记录的配置文件格式的 YAML 字符串。

示例配置

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

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

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

提示

您可以使用 GitHub Actions 变量在一个配置中跨多个存储库共享一个配置。此方法的一个好处是，您可以在一个地方更新配置，而无需编辑工作流文件。

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

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

配置编译语言的代码扫描

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

将代码扫描数据上传到 GitHub

GitHub 可以显示由第三方工具外部生成的代码分析数据。您可以使用upload-sarif action 上传代码分析数据。有关更多信息，请参阅“将 SARIF 文件上传到 GitHub”。