配置代码扫描

您可以配置 GitHub 如何扫描项目代码以查找漏洞和错误。

People with write permissions to a repository can configure 代码扫描 for the repository.

代码扫描 可用作 GitHub Advanced Security 的一部分,在测试期间免费使用。 更多信息请参阅“关于 GitHub Advanced Security”。

注意:代码扫描 目前处于测试阶段,可能会更改。

关于 代码扫描 配置

您可以使用 GitHub Actions 在 GitHub AE 中运行 代码扫描,或从持续集成 (CI) 系统运行它。 更多信息请参阅“关于 GitHub Actions”或 "在 CI 系统中运行 CodeQL runner."

本文说明使用操作在 GitHub AE 上运行 代码扫描。

在为仓库配置 代码扫描 之前,必须将 GitHub Actions 工作流程添加到仓库中以设置 代码扫描。 更多信息请参阅“为仓库设置 代码扫描”。

一般情况下无需编辑 代码扫描 的默认工作流程。 但是,如果需要,您可以编辑工作流程以自定义某些设置。 例如,您可以编辑 GitHub 的 CodeQL 分析工作流程 来指定扫描频率、要扫描的语言或目录,以及 CodeQL 代码扫描 在代码中的查找内容。 如果您使用一组特定的命令来编译代码,您可能还需要编辑 CodeQL 分析工作流程。

您可以为 代码扫描 编写配置文件。 GitHub Marketplace包含您可以使用的其他 代码扫描 工作流程。 本文给出的具体示例与 CodeQL 分析工作流程 文件相关。

Editing a code scanning workflow

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

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

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

配置频率

您可以按时间表或在仓库中发生特定事件时扫描代码。

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

按推送扫描

如果使用默认工作流程,则除了事件触发的扫描之外,代码扫描 还会每周扫描一次仓库代码。 要调整此时间表,请编辑工作流程中的 cron 值。 更多信息请参阅“GitHub Actions 的工作流程语法”。

如果您在推送时扫描,则结果将出现在仓库的 Security(安全性)选项卡中。 更多信息请参阅“管理仓库的代码扫描警报”。

扫描拉取请求

默认 CodeQL 分析工作流程 使用 pull_request 事件在针对默认分支的拉取请求上触发代码扫描。 如果拉取请求来自私有复刻,pull_request 事件仅在仓库设置中选择了“Run workflows from fork pull requests(从复刻拉取请求运行工作流程)”选项时触发。 For more information, see "Managing GitHub Actions settings for a repository."

有关 pull_request 事件的更多信息,请参阅“GitHub Actions 的工作流程语法”。

如果您扫描拉取请求,则结果在拉取请求检查中显示为警报。 更多信息请参阅“对拉取请求中的代码扫描警报分类”。

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

您可能希望避免针对默认分支的特定拉取请求触发代码扫描,而不管更改了哪些文件。 可以通过在 代码扫描 工作流程中指定 on:pull_request:paths-ignore or on:pull_request:paths 来进行配置。 例如,如果拉取请求中唯一的更改是文件扩展名为 .md.txt 的文件,则您可以使用以下 paths-ignore 数组。

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

注:

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

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

按时间表扫描

默认 代码扫描 工作流程在拉取请求的 HEAD 提交时使用 pull_request 事件触发代码扫描。 要调整此时间表,请编辑工作流程中的 cron 值。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

示例

GitHub saves workflow files in the .github/workflows directory of your repository. You can find the workflow by searching for its file name. For example, the default workflow file for CodeQL code scanning is called codeql-analysis.yml.

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

此工作流程扫描:

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

指定操作系统

如果您的代码需要使用特定的操作系统进行编译,您可以在工作流程中配置它。 编辑 jobs.analyze.runs-on 的值以指定运行 代码扫描 操作的机器操作系统。

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

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

代码扫描 支持 macOS、Ubuntu 和 Windows 的最新版本。 因此,此设置的典型值为:ubuntu-latestwindows-latestmacos-latest。 For more information, see "Workflow syntax for GitHub Actions."

If you use a self-hosted runner, you must ensure that Git is in the PATH variable.

更改分析的语言

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

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

默认 CodeQL 分析工作流程 文件包含一个名为 language 的构建矩阵,其中列出了仓库中被分析的语言。 将 代码扫描 添加到仓库时,CodeQL 会自动填充此矩阵。 使用 language 矩阵优化 CodeQL 以并行运行每个分析。 由于并行构建的性能优势,我们建议所有工作流程都采用此配置。 有关构建矩阵的更多信息,请参阅“管理复杂的工作流程”。

如果仓库中包含多种支持的语言的代码,您可以选择要分析的语言。 在有些情况下您可能需要阻止分析某种语言。 例如,项目中可能存在与代码主体语言不同的依赖项,并且您可能不希望看到关于这些依赖项的警报。

如果您的工作流程使用 language 矩阵,则 CodeQL 会被硬编码为仅分析矩阵中的语言。 如需更改要分析的语言,请编辑矩阵变量的值。 您可以删除某种语言以防止被分析,也可以添加在设置 代码扫描 时仓库中不存在的语言。 例如,如果在设置 代码扫描 时,仓库最初只包含 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@v1
  with:
    languages: cpp, csharp, python

运行额外查询

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

Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About 代码扫描 with CodeQL."

您可以指定一个 .ql 文件(一个目录中包含多个 .ql 文件)、一个 .qls 查询套件定义文件或任意组合。 有关查询套件定义的更多信息,请参阅“创建 CodeQL 查询套件”。

要添加一个或多个查询套件,请在配置文件中添加 queries 部分。 If the queries are in a private repository, use the external-repository-token parameter to specify a token that has access to checkout the private repository.

- uses: github/codeql-action/init@v1
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # 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 分析引擎将运行套件中包含的查询,以及默认查询集。

If you also use a configuration file for custom settings, any additional queries specified in your workflow are used instead of those specified in the configuration file. If you want to run the combined set of additional queries, prefix the value of queries in the workflow with the + symbol. 有关配置文件的示例,请参阅“配置文件示例”。

In the following example, the + symbol ensures that the specified additional queries are used together with any specified in the referenced configuration file.

- uses: github/codeql-action/init@v1
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main

使用第三方代码扫描工具

A custom configuration file is an alternative way to specify additional queries to run. You can also use the file to disable the default queries and to specify which directories to scan during analysis.

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

- uses: github/codeql-action/init@v1
  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@v1
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

指定额外查询

您可以在 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 来禁用默认安全查询。

指定要扫描的目录

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

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

  • 在 代码扫描 配置文件上下文中使用的 pathspaths-ignore 关键字,不应与用于工作流程中 on.<push|pull_request>.paths 的相同关键字相混淆。 当它们用于修改工作流程中的 on.<push|pull_request> 时,它们将决定在有人修改指定目录中的代码时是否运行操作。 更多信息请参阅“GitHub Actions 的工作流程语法”。
  • 不支持过滤模式字符 ?+[]!,将逐字匹配。
  • ** 字符只能用在行的开头或结尾,或用斜杠包围,并且不能将 ** 与其他字符混合在一起。 例如,foo/****/foofoo/**/bar 都是允许的语法,但 **foo 不是。 但是,可以将单星号与其他字符一起使用,如示例中所示。 您需要引用任何包含 * 字符的内容。

对于编译的语言,如果要将 代码扫描 限制到项目中的特定目录,您必须在工作流程中指定适当的构建步骤。 用于在构建过程中排除目录的命令将取决于您的构建系统。 更多信息请参阅“为编译语言配置 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'

为编译语言配置 代码扫描

对于受支持的编译语言,您可以使用 CodeQL 分析工作流程 中的 autobuild 操作来构建代码。 这样您无需为 C/C++、C# 和 Java 指定显式构建命令。 CodeQL 也运行 Go 项目的构建来设置项目。 但是,与其他编译语言相比,仓库中的所有 Go 文件都是提取的,而不仅仅是构建的文件。 您可以使用自定义构建命令跳过提取未受构建影响的 Go 文件。

如果仓库中的 C/C++、C# 或 Java 代码含有非标准的构建过程,autobuild 可能会失败。 您需要从工作流程中删除 autobuild 步骤,然后手动添加构建步骤。 如果您要指定仓库中的哪个 Go 文件要提取,则需要添加生成步骤。 有关如何为编译语言配置 CodeQL 代码扫描 的更多信息,请参阅“为编译语言配置 CodeQL 工作流程”。

将 代码扫描 数据上传到 GitHub

GitHub 可显示通过第三方工具在外部生成的代码分析数据。 通过在工作流程中添加 upload-sarif 操作,您可以在 GitHub 中显示第三方工具的代码分析。 更多信息请参阅“将 SARIF 文件上传到 GitHub”。

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。