阅读(2940) (1)

GitHub 配置代码扫描

2020-08-19 15:39:41 更新

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

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

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

关于 代码扫描 配置

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

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

编辑代码扫描工作流程

GitHub将工作流程文件保存在.github/workflows您的存储库目录中。您可以通过搜索工作流的文件名来找到它。例如,用于CodeQL代码扫描的默认工作流程文件称为codeql-analysis.yml

  1. 在仓库中,浏览至要编辑的工作流程文件。

  1. 要打开工作流程编辑器,在文件视图右上角单击 edit

编辑工作流程文件按钮

  1. 编辑文件后,单击 Start commit 并完成“提交更改”表单。您可以选择直接提交到当前分支,也可以创建一个新分支并启动拉取请求。

Commit update to codeql.yml workflow

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

配置频率

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

例如,以下配置在推送、创建拉取请求时扫描以及按计划扫描。

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

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

按推送扫描

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

我们不建议使用 branches 关键字将 on.push 限制到指定分支。 如果为 on.push 指定分支,代码扫描 将只针对您在工作流程中指定的推送分支而运行。

扫描拉取请求

默认 代码扫描 工作流程在拉取请求的 HEAD 提交时使用 pull_request 事件触发代码扫描。 如果从私有复刻打开拉取请求,则基于 pull_request 事件的扫描不起作用。

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

按时间表扫描

如果使用默认工作流程,则除了事件触发的扫描之外,代码扫描 还会每周扫描一次仓库代码。 要调整此时间表,请编辑工作流程中的 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

Configuring 代码扫描 for compiled languages

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

autobuild过程仅尝试为存储库构建一种编译语言。自动选择进行分析的语言是大多数文件使用的语言。

如果存储库中的C / C ++,C#或Java代码具有非标准的构建过程,或者以多种编译语言编写,则autobuild可能会失败。您将需要autobuild从工作流程中删除该步骤,并手动添加构建步骤。有关如何为编译语言配置代码扫描的更多信息,请参见“ 为编译语言配置代码扫描 ”。

访问私有仓库

如果 代码扫描 的工作流程访问 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

配置文件必须位于本地仓库中。 有关配置文件的示例,请参阅“配置文件示例”。

运行额外查询

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

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

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

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

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

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

您也可以在配置文件中指定额外查询套件以运行它们。 查询套件是查询的集合,通常按目的或语言分组。

以下查询套件内置于 代码扫描,可用于您的配置文件。

查询套件 描述
security-extended 严重性和精度低于默认查询的查询
security-and-quality 来自 security-extended 的查询,加上可维护性和可靠性查询

在配置文件中指定查询套件时,CodeQL 分析引擎将运行套件中包含的查询,以及默认查询集。

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

queries:
 - uses: security-and-quality

不建议直接从 github/codeql 仓库引用 uses 的查询套件,如 github/codeql/cpp/ql/src@master。 此类查询不可使用与配置文件所用版本相同的 CodeQL 版本编译,否则可能导致分析过程中出错。

禁用默认查询

如果只想运行自定义查询,您可以通过在配置文件中添加 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. 使用 paths-ignorepaths 关键字。

配置文件示例

当您扫描代码时,此配置文件将 security-and-quality 查询套件添加到 CodeQL 运行的查询列表。 有关可供使用的查询套件的更多信息,请参阅“运行其他查询”。

name: "My CodeQL config"


queries:
  - uses: security-and-quality

此配置文件禁用默认查询,并指定一组要运行的自定义查询。它还将CodeQL配置为扫描 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@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
  - '**/*.test.js'
paths:
  - src

注意**字符只能在行的开头或结尾,或者由斜杠包围,并且不能**与其他字符混合。例如foo/****/foofoo/**/bar都是允许的语法,但**foo并非如此。但是,可以将单颗星与其他字符一起使用,如示例中所示。您需要引用任何包含单个*字符的内容。

使用第三方代码扫描工具

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