GitHub 配置代码扫描
您可以配置 GitHub 如何扫描项目代码以查找漏洞和错误。
拥有仓库写入权限的人可配置仓库的 代码扫描。
注意:代码扫描 目前处于测试阶段,可能会更改。 要申请访问测试版,请加入等待列表。
关于 代码扫描 配置
代码扫描 使用 GitHub 操作。 在为仓库配置 代码扫描 之前,必须将 GitHub 操作 工作流程添加到仓库中以启用 代码扫描。 更多信息请参阅“启用 代码扫描”。
一般情况下无需编辑 代码扫描 的默认工作流程。 但是,如果需要,您可以编辑工作流程以指定扫描频率,要扫描的语言或目录以及代码扫描在代码中查找的内容。 如果使用一组特定的命令来编译代码,或者存储库中使用了多种编译语言,则可能还需要编辑工作流。
编辑代码扫描工作流程
GitHub将工作流程文件保存在.github/workflows
您的存储库目录中。您可以通过搜索工作流的文件名来找到它。例如,用于CodeQL代码扫描的默认工作流程文件称为codeql-analysis.yml
。
- 在仓库中,浏览至要编辑的工作流程文件。
- 要打开工作流程编辑器,在文件视图右上角单击 。
- 编辑文件后,单击 Start commit 并完成“提交更改”表单。您可以选择直接提交到当前分支,也可以创建一个新分支并启动拉取请求。
有关编辑工作流程文件的更多信息,请参阅“配置工作流程”。
配置频率
您可以按时间表或在仓库中发生特定事件时扫描代码。
例如,以下配置在推送、创建拉取请求时扫描以及按计划扫描。
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
操作。 受支持语言的关键字是 cpp
、csharp
、go
、java
、javascript
和 python
。
例如,以下配置可将 代码扫描 限制到 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/foo
、github/bar
和 github/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
关键字可在扫描中排除特定目录中的文件。
注:在 代码扫描 配置文件上下文中使用的
paths
和paths-ignore
关键字,不应与用于on.<push|pull_request&.paths
的相同关键字相混淆。 当它们用于修改工作流程文件中的on.<push|pull_request&
时,它们将决定在有人修改指定目录中的代码时是否运行操作。 更多信息请参阅“GitHub 操作 的工作流程语法”。
对于 C/C++、C# 和 Java,如果要将 代码扫描 限制到项目中的特定目录,您必须在工作流程中指定适当的构建步骤。 用于在构建过程中排除目录的命令将取决于您的构建系统。 更多信息请参阅“添加编译语言的构建步骤”。
在修改特定目录中的代码时,您可以快速分析单个仓库中的小部分。 您需要在构建步骤中排除目录并在工作流程文件中对 on.
使用 paths-ignore
和 paths
关键字。
配置文件示例
当您扫描代码时,此配置文件将 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/**
,**/foo
和foo/**/bar
都是允许的语法,但**foo
并非如此。但是,可以将单颗星与其他字符一起使用,如示例中所示。您需要引用任何包含单个*
字符的内容。
使用第三方代码扫描工具
通过在工作流程中添加 upload-sarif
操作,您可以在 GitHub 中显示第三方工具的代码分析。 更多信息请参阅“将 SARIF 文件上传到 GitHub”。