Skip to main content
我们经常发布文档更新,此页面的翻译可能仍在进行中。 有关最新信息,请访问英语文档

自定义代码扫描

可以自定义 GitHub 如何扫描项目代码以查找漏洞和错误。

谁可以使用此功能

People with write permissions to a repository can customize code scanning for the repository.

Code scanning 可用于 GitHub.com 上的所有公共存储库。 Code scanning 也可用于使用 GitHub Enterprise Cloud 并拥有 GitHub Advanced Security 许可证的组织所拥有的专用存储库。 有关详细信息,请参阅“关于 GitHub Advanced Security”。

关于 code scanning 配置

您可以使用 GitHub Actions 在 GitHub 中运行 code scanning,或从持续集成 (CI) 系统运行它。 有关详细信息,请参阅“关于 GitHub Actions”或“关于 CI 系统中的 CodeQL code scanning”。

code scanning 的默认设置和高级设置都在 GitHub Actions 上运行。 默认设置会自动检测存储库的最佳 code scanning 配置,而你可使用高级设置自定义 code scanning 工作流。 有关详细信息,请参阅“为存储库配置 code scanning”。本文介绍如何配置 code scanning 的高级设置。

使用高级设置,可以编辑工作流(如 GitHub 的 CodeQL analysis workflow)来指定扫描频率、要扫描的语言或目录,以及 code scanning 在代码中查找的内容。 如果使用一组特定的命令来编译代码,你可能还需要编辑工作流。

CodeQL 分析只是您可以在 GitHub 中执行的一种 code scanning。 GitHub Marketplace包含您可以使用的其他 code scanning 工作流程。 可以在“开始使用 code scanning”页面上找到这些选项,可以从“ 安全性”选项卡访问该页面。本文中提供的特定示例与 CodeQL analysis workflow 文件相关。

编辑 code scanning 工作流

GitHub 将工作流文件保存在存储库的 .github/workflows 目录中。 可搜索文件名来查找已添加的工作流。 例如,默认情况下,CodeQL code scanning 的工作流文件称为 codeql-analysis.yml。

  1. 在仓库中,浏览至要编辑的工作流程文件。
  2. 要打开工作流编辑器,在文件视图右上角单击 编辑工作流文件按钮
  3. 编辑完文件后,请单击“开始提交”,并完成“提交更改”窗体。 可以选择直接提交到当前分支,也可以创建一个新分支,并发起拉取请求。 将更新提交到 codeql.yml 工作流程

有关编辑工作流文件的详细信息,请参阅“了解 GitHub Actions”。

配置频率

可以将 CodeQL analysis workflow 配置为按计划或在存储库中发生特定事件时扫描代码。

每当推送到仓库以及每次创建拉取请求时,时扫描代码可防止开发者在代码中引入新的漏洞和错误。 按时间表扫描可了解 GitHub、安全研究者和社区发现的最新漏洞和错误,即使开发者并未主动维护仓库。

按推送扫描

默认情况下,CodeQL analysis workflow 使用 on.push 事件在每次推送到存储库的默认分支和任何受保护分支时触发代码扫描。 要使 code scanning 指定分支上触发,工作流程必须存在于该分支中。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。

如果在推送时扫描,结果会显示在存储库的“安全性”选项卡中。 有关详细信息,请参阅“管理存储库的代码扫描警报”。

此外,当 on:push 扫描返回可映射到打开的拉取请求的结果时,这些警报将自动出现在拉取请求中,与其他拉取请求警报位于同一位置。 警报是通过比较对分支头的现有分析与对目标分支的分析来确定的。 有关 code scanning 的详细信息,请参阅“会审拉取请求中的 code scanning 警报”。

扫描拉取请求

默认 CodeQL analysis workflow 使用 pull_request 事件在发生针对默认分支的拉取请求时触发代码扫描。 如果拉取请求来自专用分支,则仅当你在存储库设置中选择了“从分支拉取请求运行工作流”选项时,才会触发 pull_request 事件。 有关详细信息,请参阅“管理存储库的 GitHub Actions 设置”。

有关 pull_request 事件的详细信息,请参阅“触发工作流的事件”。

如果扫描拉取请求,结果将在拉取请求检查中显示为警报。 有关详细信息,请参阅在拉取请求中对代码扫描警报进行会审

使用 pull_request 触发器(配置为扫描拉取请求的合并提交,而不是头提交)与每次推送时扫描分支头相比,可产生更高效且准确的结果。 但是,如果使用的 CI/CD 系统无法配置为发生拉取请求时触发,你仍然可以使用 on:push 触发器和 code scanning 会将结果映射到在分支上打开的拉取请求,并将警报作为注释添加到拉取请求。 有关详细信息,请参阅“推送时扫描”。

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

默认情况下,只有严重性级别为 Error 或安全严重级别为 CriticalHigh 的警报会导致拉取请求检查失败,而对于较低严重性的警报,检查仍会成功。 可以在存储库设置中更改将导致拉取请求检查失败的警报严重性和安全严重性级别。 有关严重性级别的详细信息,请参阅“关于代码扫描警报”。

  1. 在 GitHub.com 上,导航到存储库的主页。 1. 在存储库名称下,单击 “设置”。 “存储库设置”按钮

  2. 在边栏的“安全性”部分中,单击“ 代码安全性和分析”。

  3. 在“Code scanning(代码扫描)”下的“Check Failure(检查失败)”右边,使用下拉菜单选择您想要导致拉请求检查失败的严重程度。 检查失败设置

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

你可能希望避免触发针对默认分支的特定拉取请求的代码扫描,而不考虑哪些文件已更改。 可以通过在 code scanning 数据流中指定 on:pull_request:paths-ignoreon:pull_request:paths 来进行配置。 例如,如果拉取请求中仅更改了文件扩展名为 .md.txt 的文件,你可以使用以下 paths-ignore 数组。

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

说明

  • on:pull_request:paths-ignoreon:pull_request:paths 可设置用于决定工作流中的操作是否将在发生拉取请求时运行的条件。 它们不会决定操作运行时将分析哪些文件。 当拉取请求包含任何未被 on:pull_request:paths-ignoreon:pull_request:paths 匹配的文件时,工作流会运行操作并扫描拉动请求中更改的所有文件,包括那些被 on:pull_request:paths-ignoreon:pull_request:paths 匹配的文件,除非这些文件已被排除。 有关如何从分析中排除文件的信息,请参阅“指定要扫描的目录”。
  • 对于 CodeQL code scanning 工作流文件,请勿对 paths-ignore 事件使用 pathson:push 关键字,因为这可能会导致缺少分析。 为了获得准确的结果,CodeQL code scanning 需要能够与上次提交的分析比较新的变化。

有关使用 on:pull_request:paths-ignoreon:pull_request:paths 确定工作流何时为拉取请求运行的详细信息,请参阅“GitHub Actions 的工作流语法”。

按时间表扫描

如果使用默认 CodeQL analysis workflow,则除了由事件触发的扫描之外,工作流还将每周扫描一次存储库中的代码。 若要调整此计划,请在工作流中编辑 cron 值。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。

注意:GitHub 只运行默认分支上的工作流中的预定作业。 在任何其他分支上的工作流程中更改时间表后,需要将该分支合并到默认分支才能使更改生效。

示例

以下示例显示了特定存储库的 CodeQL analysis workflow,该存储库具有一个名为 main 的默认分支和一个名为 protected 的受保护分支。

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

此工作流扫描:

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

指定操作系统

如果代码需要特定的操作系统来编译,则可以在 CodeQL analysis workflow 中配置操作系统。 编辑 jobs.analyze.runs-on 的值,指定运行 code scanning 操作的计算机操作系统。

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

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

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

CodeQL code scanning 支持最新版本的 Ubuntu、Windows 和 macOS。 因此,此设置的典型值为:ubuntu-latestwindows-latestmacos-latest。 有关详细信息,请参阅“为作业选择运行器”和“将标签用于自托管运行器”。

如果你使用自托管运行器,则必须确保 Git 在 PATH 变量中。 有关详细信息,请参阅“关于自托管运行器”和“添加自托管运行器”。

有关在自托管计算机上运行 CodeQL 分析 的建议规范(RAM、CPU 核心和磁盘),请参阅“用于运行 CodeQL 的建议硬件资源”。

指定 CodeQL 数据库的位置

通常,无需担心 CodeQL analysis workflow 将 CodeQL 数据库放置的位置,因为后面的步骤会自动查找前面步骤创建的数据库。 但是,如果你正在编写一个自定义工作流步骤,要求 CodeQL 数据库位于特定的磁盘位置,例如将数据库作为工作流工件上传,则可以使用 init 下的 db-location 参数指定该位置。

- uses: github/codeql-action/init@v2
  with:
    db-location: '${{ github.workspace }}/codeql_dbs'

CodeQL analysis workflow 期望 db-location 中提供的路径是可写的,或者不存在,或者是一个空目录。 当在运行自托管运行器或使用 Docker 容器的作业中使用此参数时, 用户有责任确保所选目录在运行之间被清空, 或数据库一旦不再需要即予移除。 对于运行在 GitHub 托管的运行器中的任务,这是不必要的,因为每次运行时都会获得一个新的实例和一个清洁的文件系统。 有关详细信息,请参阅“有关 GitHub 托管的运行器”。

如果不使用此参数,CodeQL analysis workflow 将在自己选择的临时位置创建数据库。

更改分析的语言

CodeQL code scanning 会自动检测用受支持的语言编写的代码。

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

注意:

  • 用于 Kotlin 的 CodeQL 分析目前为 beta 版。 在 beta 版中,Kotlin 的分析将不如其他语言的 CodeQL 分析全面。
  • 使用 java 分析用 Java、Kotlin 或两者编写的代码。
  • 使用 javascript 分析用 JavaScript、TypeScript 或两者编写的代码。

有关详细信息,请参阅 CodeQL 网站上的文档:“支持的语言和框架”。

默认 CodeQL analysis workflow 文件包含一个名为 language 的矩阵,其中列出了存储库中要分析的语言。 将 code scanning 添加到仓库时,CodeQL 会自动填充此矩阵。 使用 language 矩阵优化 CodeQL 以并行运行每个分析。 由于并行生成的性能优势,建议所有工作流都采用此配置。 有关矩阵的详细信息,请参阅“为作业使用矩阵”。

如果存储库包含的代码支持多种语言,可以选择要分析的语言。 有几种原因可能使你想阻止对某种语言进行分析。 例如,项目中可能有其他语言的代码主体依赖项,你可能不想看到这些依赖项的警报。

如果工作流使用 language 矩阵,则 CodeQL 会被硬编码为仅分析矩阵中的语言。 若要更改要分析的语言,请编辑 matrix 变量的值。 可以删除某种语言以防止被分析,也可以添加在配置 code scanning 时存储库中不存在的语言。 例如,如果在配置 code scanning 时存储库最初只包含 JavaScript,而后来添加了 Python 代码,则需要向矩阵中添加 python

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

如果工作流程中不包含名为 language 的矩阵,则 CodeQL 将被配置为按顺序运行分析。 如果您未在工作流程中指定语言,则 CodeQL 将自动检测并尝试分析仓库中所有受支持的语言。 如果要选择要分析的语言,而不使用矩阵,则可以在 init 操作下使用 languages 参数。

- uses: github/codeql-action/init@v2
  with:
    languages: cpp, csharp, python

分析 Python 依赖项

对于仅使用 Linux 的 GitHub 托管的运行器,CodeQL analysis workflow 将尝试自动安装 Python 依赖项,以便为 CodeQL 分析提供更多结果。 可以通过为“初始化 CodeQL”步骤调用的操作指定 setup-python-dependencies 参数来控制此行为。 默认情况下,此参数设置为 true

  • 如果仓库包含用 Python 编写的代码,“初始化 CodeQL”步骤将在 GitHub 托管的运行器上安装必要的依赖项。 如果自动安装成功,该操作还会将环境变量 CODEQL_PYTHON 设置为包含依赖项的 Python 可执行文件。

  • 如果仓库没有任何 Python 依赖项,或者依赖项是以意外方式指定的,您将收到警告,并且该操作会继续执行其余作业。 即使在解释依赖项时出现问题,该操作也可以成功运行,但结果可能不完整。

或者,您也可以在任何操作系统上手动安装 Python 依赖项。 需要添加 setup-python-dependencies 并将其设置为 false,并将 CODEQL_PYTHON 设置为包含依赖项的 Python 可执行文件,如以下工作流提取所示:

jobs:
  CodeQL-Build:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      actions: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          if [ -f requirements.txt ];
          then pip install -r requirements.txt;
          fi
          # Set the `CODEQL-PYTHON` environment variable to the Python executable
          # that includes the dependencies
          echo "CODEQL_PYTHON=$(which python)" >> $GITHUB_ENV
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: python
          # Override the default behavior so that the action doesn't attempt
          # to auto-install Python dependencies
          setup-python-dependencies: false

配置分析类别

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

如果您使用单一仓库,并且对单一仓库的不同部分有多个对应的 SARIF 文件,此参数是特别有用。

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v2
      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, os: linux} 矩阵变量将生成类别 .github/workflows/codeql-analysis.yml:analyze/language:javascript/os:linux

category 值将显示为 <run>.automationDetails.id SARIF v2.1.0 中的属性。 有关详细信息,请参阅“code scanning 的 SARIF 支持”。

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

运行额外查询

使用 CodeQL 扫描代码时,CodeQL 分析引擎将从代码生成数据库并对其运行查询。 CodeQL 分析使用默认的查询集,但除了默认查询外,您还可以指定更多的查询来运行。

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

如果它们是发布到 GitHub Container registry 的 CodeQL 包(beta 版本)或存储在存储库中的 QL 包的一部分,则可以运行额外的查询。 有关详细信息,请参阅“关于 code scanning 和 CodeQL。”

可用于指定要运行的其他查询的选项有:

  • packs,可安装一个或多个 CodeQL 查询包(beta 版本)并为这些包运行默认查询套件或查询。
  • queries,可指定单个 .ql 文件、包含多个 .ql 文件的目录、.qls 查询套件定义文件或任意组合 。 有关查询套件定义的详细信息,请参阅“创建 CodeQL 查询套件”。

可以在同一工作流中同时使用 packsqueries

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

使用 CodeQL 查询包

注意:CodeQL 包管理功能(包括 CodeQL 包)当前为 beta 版本,可能会发生更改。

要添加一个或多个 CodeQL 查询包 (beta),请在工作流的 uses: github/codeql-action/init@v2 部分中添加一个 with: packs: 条目。 在 packs 中,可以指定要使用的一个或多个包,还可以指定要下载的版本。 在未指定版本的情况下,将下载最新版本。 如果要使用不可公开使用的包,则需要将 GITHUB_TOKEN 环境变量设置为有权访问包的机密。 有关详细信息,请参阅“工作流中的身份验证”和“加密机密”。

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

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

  • 下载最新版本的 pack1 并运行所有默认查询。
  • 下载版本 1.2.3 的 pack2 并运行所有默认查询。
  • 下载与版本 3.2.1 兼容的最新版本 pack3,并运行所有查询。
  • 下载 4.5.6 版本的 pack4,并且仅运行在 path/to/queries 中找到的查询。
- uses: github/codeql-action/init@v2
  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 引擎有效使用。 为了确保最佳性能,如果需要指定确切的查询包版本,应考虑定期查看是否需要前移所固定的查询包版本。

有关包兼容性的详细信息,请参阅“关于 CodeQL 包兼容性”。

从 GitHub Enterprise Server 下载 CodeQL 包

如果工作流使用在 GitHub Enterprise Server 安装上发布的包,则需要告知工作流在何处查找这些包。 为此,可以使用 github/codeql-action/init@v2 操作的 registries 输入。 此输入接受 urlpackagestoken 属性的列表,如下所示。

- uses: github/codeql-action/init@v2
  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 的值必须是通过 read:packages 权限从中下载的 GitHub 实例生成的 personal access token (classic)。

注意 registries 属性名称之后的 |。 这一点很重要,因为 GitHub Actions 输入只能接受字符串。 使用 | 将后续文本转换为字符串,稍后由 github/codeql-action/init@v2 操作分析。

在 QL 包中使用查询

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

- uses: github/codeql-action/init@v2
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

以下查询套件内置于 CodeQL code scanning,可供使用。

查询套件说明
security-extended来自默认套件的查询,以及较低严重性和精度查询
security-and-quality来自 security-extended 的查询,以及可维护性和可靠性查询。

指定查询套件时,CodeQL 分析引擎将运行默认查询集和其他查询套件中定义的任何其他查询。 JavaScript 的 security-extendedsecurity-and-quality 查询套件包含实验性查询。 有关详细信息,请参阅“关于 code scanning 警报”。

使用自定义配置文件

如果还将配置文件用于自定义设置,则将使用工作流中指定的任何其他包或查询,而不是配置文件中指定的查询。 如果要运行其他包或查询的组合,请在工作流中的 packsqueries 值前附加 + 符号。 有关详细信息,请参阅使用自定义配置文件

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

- uses: github/codeql-action/init@v2
  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

使用自定义配置文件

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

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

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

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

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

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

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

指定 CodeQL 查询包

注意:CodeQL 包管理功能(包括 CodeQL 包)当前为 beta 版本,可能会发生更改。

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

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]versionpath 都是可选的。 version 是 semver 版本范围。 如果缺少该版本,则使用最新版本。 有关 semver 范围的详细信息,请参阅 npm 上的 semver 文档

如果您的工作流程生成多个 CodeQL 数据库,则可以使用包的嵌套映射指定要在自定义配置文件中运行的任何 CodeQL 查询包。

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

指定额外查询

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

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

(可选)您可以给每个数组元素一个名称,如下面的示例配置文件所示。 有关其他查询的详细信息,请参阅上面的“运行其他查询”。

禁用默认查询

如果只想运行自定义查询,可以使用 disable-default-queries: true 禁用默认安全查询。

从分析中排除特定查询

可以向自定义配置文件添加 excludeinclude 筛选器,以指定要在分析中排除或包含的查询。

这在要排除诸如以下内容时非常有用:

  • 来自默认套件的特定查询(securitysecurity-extendedsecurity-and-quality)。
  • 对其结果不感兴趣的特定查询。
  • 生成警告和建议的所有查询。

可以使用 exclude 筛选器(类似于以下配置文件中的筛选器)来排除要从默认分析中移除的查询。 在以下配置文件示例中,js/redundant-assignmentjs/useless-assignment-to-local 查询都从分析中排除。

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

若要查找查询的 ID,可以在“安全性”选项卡中的警报列表中单击警报。此操作会打开警报详细信息页。 Rule ID 字段包含查询 ID。有关警报详细信息页的详细信息,请参阅“关于 code scanning 警报”。

提示:

  • 筛选器的顺序非常重要。 在有关查询和查询包的指令之后出现的第一个筛选器指令确定在默认情况下是包含还是排除查询。
  • 后续指令按顺序执行,在文件后面出现的指令优先于前面的指令。

可以在“示例配置文件”部分中找到说明这些筛选器的使用的另一个示例。

有关在自定义配置文件中使用 excludeinclude 筛选器的详细信息,请参阅“创建 CodeQL 查询套件”。 有关可以筛选的查询元数据的信息,请参阅“CodeQL 查询的元数据”。

指定要扫描的目录

对于 CodeQL 支持的解释语言(Python、Ruby 和 JavaScript/TypeScript),你可以通过在配置文件中添加 paths 数组将 code scanning 限制为特定目录中的文件。 你可以通过添加 paths-ignore 数组从分析中排除特定目录中的文件。

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

注意

  • 在 code scanning 配置文件的上下文中使用的 pathspaths-ignore 关键字在工作流中用于 on.<push|pull_request>.paths 时不应与相同的关键字混淆。 当它们用于修改工作流中的 on.<push|pull_request> 时,它们确定当有人修改指定目录中的代码时是否会运行这些操作。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
  • 筛选模式字符 ?+[]! 不受支持,将按字面意思进行匹配。
  • ** 字符只能位于行首或行尾,或被斜线包围,并且不能混用 ** 和其他字符。 例如,foo/****/foofoo/**/bar 都是允许的语法,但 **foo 不是。 但是,可以将单星与其他字符一起使用,如示例中所示。 需要引用包含 * 字符的任何内容。

对于编译的语言,如果要将 code scanning 限制到项目中的特定目录,您必须在工作流程中指定适当的构建步骤。 需要用于从构建中排除目录的命令取决于你的构建系统。 有关详细信息,请参阅“为已编译语言配置 CodeQL 工作流”。

修改特定目录中的代码时,可以快速分析单存储库的一小部分。 需要在构建步骤中排除目录,并在工作流中为 on.<push|pull_request> 使用 paths-ignorepaths 关键字。

示例配置文件

当扫描代码时,此配置文件将 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 QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

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

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

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

为编译语言配置 code scanning

对于受支持的编译语言,你可使用 CodeQL analysis workflow 中的 autobuild 操作来生成代码。 这样就无需为 C/C++、C#、Go、Kotlin 和 Java 指定显式生成命令。 对于这些语言,CodeQL 分析生成的存储库中的源文件。 对于上述任何语言,可以禁用 autobuild 并改用自定义生成命令,以仅分析这些自定义命令生成的文件。

如果 autobuild 失败,或者你想要分析与 autobuild 进程生成的源文件不同的一组源文件,则需要从工作流中删除 autobuild 步骤,并手动添加生成步骤。 对于 C/C++、C#、Go、Kotlin 和 Java 项目,CodeQL 将分析由指定的生成步骤生成的任何源代码。 要详细了解如何为编译语言配置 CodeQL code scanning,请参阅“编译语言配置 CodeQL 工作流”。

将 code scanning 数据上传到 GitHub

GitHub 可显示通过第三方工具在外部生成的代码分析数据。 可以使用 upload-sarif 操作上传代码分析数据。 有关详细信息,请参阅“将 SARIF 文件上传到 GitHub”。