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, pythonConfiguring 代码扫描 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”。