我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

配置代码扫描

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

拥有仓库写入权限的人可配置仓库的 代码扫描。

本文内容

注意:代码扫描 目前处于测试阶段,可能会更改。 要申请访问测试版,请加入等待列表

关于 代码扫描 配置

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

一般情况下无需编辑 代码扫描 的默认工作流程。 您可以编辑工作流程以指定扫描频率、要扫描的语言或目录以及 代码扫描 在代码中查找的内容。 如果使用一组特定的命令来编译代码,则可能也需要编辑工作流程。

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

配置频率

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

For example, the following configuration scans on push, on creation of a pull request, and on a schedule.

on:
  push:
  pull_request:
  schedule:
    - cron: '0 15 * * 0'

Scanning code on every push to the repository, and every time a pull request is created, prevents developers from introducing new vulnerabilities and errors into the code. 按时间表扫描可了解 GitHub、安全研究者和社区发现的最新漏洞和错误,即使开发者并未主动维护仓库。

按推送扫描

默认 代码扫描 工作流程使用 on.push 事件触发代码扫描 - 每次推送到任何包含工作流程文件的分支时触发。 更多信息请参阅“GitHub 操作 的工作流程语法”。

我们不建议使用 branches 关键字将 on.push 限制到指定分支。 If you specify branches for on.push, 代码扫描 will only run when you push branches that you specify in the workflow.

Scanning pull requests

The default 代码扫描 workflow uses the pull_request event to trigger a code scan on the HEAD commit of a pull request. Scanning on the pull_request event doesn't work if you open a pull request from a private fork.

For more information about the pull_request event, see "Workflow syntax for GitHub 操作."

按时间表扫描

If you use the default workflow, 代码扫描 will scan the code in your repository once a week, in addition to the scans triggered by events. 要调整此时间表,请编辑工作流程中的 cron 值。 更多信息请参阅“GitHub 操作 的工作流程语法”。

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

指定操作系统

如果您的代码需要使用特定的操作系统进行编译,您可以在工作流程中配置它。 编辑 jobs.<job_id>.runs-on 的值以指定运行 代码扫描 操作的机器操作系统。 代码扫描 支持 macOS、Ubuntu 和 Windows 的最新版本。 更多信息请参阅“GitHub 操作的工作流程语法”。

覆盖自动语言检测

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

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

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

要覆盖自动语言检测,请将 with:languages: 添加到工作流程中的 init 操作。 受支持语言的关键字是 cppcsharpgojavajavascriptpython

例如,以下配置可将 代码扫描 限制到 C/C++、C# 和 Python。

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

添加编译语言的构建步骤

对于 C/C++、C# 和 Java,默认工作流程中的 autobuild 步骤会在操作执行 CodeQL 分析之前尝试构建代码。 与其他编译语言不同,CodeQL 在分析 Go 时不会构建代码。

如果仓库中的 C/C++、C# 或 Java 含有非标准的构建过程,autobuild 可能会失败。 如果发生这种情况,请从工作流程中删除 autobuild 操作,并取消注释 run 步骤。

run 步骤使用操作系统的 shell 运行命令行程序。 您可以修改这些命令并添加更多命令来自定义构建过程。

- run: |
  make bootstrap
  make release

有关 run 关键词的更多信息,请参阅“GitHub 操作 的工作流程语法”。

访问私有仓库

如果 代码扫描 的工作流程访问 GitHub 上的私有仓库,您需要将 Git 配置为使用个人访问令牌进行身份验证。 在执行任何 CodeQL 操作之前,请使用工作流程中的 jobs.<job_id>.steps.env 定义运行环境中的密码。 更多信息请参阅“创建用于命令行的个人访问令牌”和“创建和存储加密密码”。

例如,以下 Git 配置将 GitHub.com 上 github/foogithub/bargithub/baz 仓库的完整 URL替换为包含您存储在 ACCESS_TOKEN 环境变量中的个人访问令牌的 URL。

steps:
- name: Configure access to private repository on GitHub.com
  env:
    TOKEN: ${{ secrets.ACCESS_TOKEN }}
  run: |
    git config --global url."https://${TOKEN}@github.com/github/foo".insteadOf "https://github.com/github/foo"
    git config --global url."https://${TOKEN}@github.com/github/bar".insteadOf "https://github.com/github/bar"
    git config --global url."https://${TOKEN}@github.com/github/baz".insteadOf "https://github.com/github/baz"

使用自定义配置

您可以为 代码扫描 编写配置文件。 配置文件可指定要运行的查询和要扫描的目录。

使用 init 操作的 config-file 参数来指定配置文件。 config-file 的值是要使用的配置文件的路径。 此示例加载配置文件 ./.github/codeql/codeql-config.yml

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

配置文件必须位于本地仓库中。 For examples of configuration files, see "Example configuration files."

运行额外查询

启用 代码扫描 时,GitHub 的 CodeQL 分析引擎将从代码生成数据库并对其运行查询。 更多信息请参阅“关于 代码扫描”。

您可以在配置文件中指定额外查询以运行这些查询。 要运行的查询必须属于 QL 包,可以位于您拥有的仓库或任何公共仓库中。 更多信息请参阅“关于 QL 包”。

查询只能依赖于标准库(即查询中的 import LANGUAGE 语句引用的库)或与查询相同的 QL 包中的库。 标准库位于 github/codeql 仓库中。 更多信息请参阅“查询文件简介”。

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

要添加一个或多个查询,请在配置文件中添加 queries 部分。

queries:
  - name: DESCRIPTION OF YOUR CHOICE
    uses: PATH

You can also run additional query suites by specifying these in a configuration file. Query suites are collections of queries, usually grouped by purpose or language.

The following query suites are built into 代码扫描 and available for use in your configuration file.

Query suite描述
security-extendedQueries of lower severity and precision than the default queries
security-and-qualityQueries from security-extended, plus maintainability and reliability queries

When you specify a query suite in your configuration file, the CodeQL analysis engine will run the queries contained in the suite for you, in addition to the default set of queries.

To add one or more query suites, add a queries section to your configuration file.

queries:
 - uses: security-and-quality

We don't recommend referencing query suites for uses directly from the github/codeql repository, like github/codeql/cpp/ql/src@master. Such queries may not be compiled with the same version of CodeQL as the version used in your configuration file, which could lead to errors during analysis.

禁用默认查询

如果只想运行自定义查询,您可以通过在配置文件中添加 disable-default-queries: true 来禁用默认安全查询。

指定要扫描的目录

对于 CodeQL 支持的解释语言(Python 和 JavaScript/TypeScript),您可以通过在配置文件中使用 paths 关键字将 代码扫描 限制到特定目录中的文件。 使用 paths-ignore 关键字可在扫描中排除特定目录中的文件。

:在 代码扫描 配置文件上下文中使用的 pathspaths-ignore 关键字,不应与用于 on.<push|pull_request>.paths 的相同关键字相混淆。 当它们用于修改工作流程文件中的 on.<push|pull_request> 时,它们将决定在有人修改指定目录中的代码时是否运行操作。 更多信息请参阅“GitHub 操作 的工作流程语法”。

对于 C/C++、C# 和 Java,如果要将 代码扫描 限制到项目中的特定目录,您必须在工作流程中指定适当的构建步骤。 用于在构建过程中排除目录的命令将取决于您的构建系统。 更多信息请参阅“添加编译语言的构建步骤”。

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

Example configuration files

This configuration file adds the security-and-quality query suite to the list of queries run by CodeQL when scanning your code. For more information about the query suites available for use, see "Running additional queries."

name: "My CodeQL config"

queries:
  - uses: security-and-quality

此配置文件禁用默认查询,并指定一组要运行的自定义查询。 它还配置 CodeQL 以扫描 /src 目录中的文件,包括除 node_modules 之外的其所有子目录。

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@master
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@master
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths-ignore: 
  - '/node_modules/'
paths:
  - '/src' 

使用第三方代码扫描工具

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

问问别人

找不到要找的内容?

联系我们