配置代码扫描

4 分钟

可以配置 GitHub 如何扫描项目代码中的漏洞和错误。选择自己的配置时，你可以节省时间并确定项目的代码扫描最佳频率。本单元将介绍代码扫描配置的基本知识。还将介绍如何配置扫描频率和安排扫描时间，以便最适合你的存储库和开发需求。

如之前单元所述，可以使用 GitHub Actions 或通过持续集成 (CI) 系统在 GitHub 上运行代码扫描。选择 GitHub 上的“高级”设置选项后，将生成一个可自定义的工作流文件，你可以直接将该文件提交到存储库。通常不需要编辑此工作流。但如有必要，你也可以自定义一些设置。

例如，可以编辑 GitHub 的 CodeQL 分析工作流以指定扫描频率、要扫描的语言或目录，以及 CodeQL 代码扫描在代码中查找的内容。如果使用一组特定的命令来编译代码，你可能还需要编辑 CodeQL 分析工作流。 CodeQL 分析只是可在 GitHub 中执行的其中一种代码扫描。 GitHub Marketplace 包含其他几种代码扫描工作流。

从默认设置切换到高级代码扫描设置

如果你已经将存储库设置为使用默认设置方法进行代码扫描，则可以切换为使用设置中的“高级”设置。导航到 Settings Code security and analysis（设置>代码安全和分析）下的 Code scanning 部分，然后选择三个点溢出图标（...）。在下拉列表中，选择 Switch to advanced （切换到高级）。然后，按照提示禁用 CodeQL，并使用高级设置生成的工作流程文件重新启用它。

编辑代码扫描工作流

GitHub 将工作流文件保存在存储库的 .github/workflows 目录中。可搜索文件名来查找已添加的工作流。例如，默认情况下，CodeQL 代码扫描的工作流文件名为 codeql-analysis. docker-compose.override.yml。

按照以下步骤编辑工作流文件：

若要打开工作流编辑器，请选择文件视图右上角的“编辑”图标。
进行编辑。
编辑文件后，选择“提交更改”并完成“提交更改”窗体。可以选择直接提交到当前分支，也可以创建一个新分支，并发起拉取请求。

请查看以下部分，了解一些常见的代码扫描配置选项。

配置频率

对工作流文件的常见编辑是调整代码扫描的频率。可以将 CodeQL 分析工作流配置为按计划或在存储库中发生特定事件时扫描代码。您还可以编辑工作流程文件，以便在有人推送更改和创建拉取请求时扫描代码。调整此频率可防止开发人员将新的漏洞和错误引入代码。按计划扫描代码时，你会得知 GitHub、安全研究人员和社区发现的最新漏洞和错误。即使开发人员没有主动维护存储库。

推送时扫描

默认情况下，CodeQL 分析工作流使用 on:push 事件，在每次推送到存储库的默认分支和任何受保护的分支时触发代码扫描。若要在指定的分支上触发代码扫描，该工作流必须存在于该分支中。如果在推送时进行扫描，结果会显示在存储库的“安全性”选项卡中。

此外，当 on:push 扫描返回可映射到打开的拉取请求的结果时，这些警报会自动出现在拉取请求中，与其他拉取请求警报位于同一位置。警报是通过比较对分支头的现有分析与对目标分支的分析来确定的。

PR 时扫描

默认的 CodeQL 分析工作流使用 pull_request 事件触发针对默认分支的拉取请求的代码扫描。如果拉取请求来自专用分支，则只有在存储库设置中选择了“从分支拉取请求运行工作流”选项时才会触发 pull_request 事件。如果扫描拉取请求，结果将在拉取请求检查中显示为警报。

如果使用 pull_request 触发器（配置为扫描拉取请求的合并提交，而不是头提交），那么与每次推送时扫描分支头相比，这可产生更高效且准确的结果。但是，如果你使用的 CI/CD 系统无法配置为对拉取请求触发，你仍然可以使用 on:push 触发器，这样的话，代码扫描会将结果映射到分支上待处理的拉取请求，并将警报作为注释添加到拉取请求。

定义导致拉取请求检查失败的严重性

默认情况下，只有严重性级别为 Error 或安全严重性级别为 Critical 或 High 的警报才会导致拉取请求检查失败。拉取请求失败不会停止代码扫描，但表示尝试合并代码时存在阻止程序。在存储库“安全性”下的“代码扫描警报”选项卡中，你可以找到拉取请求失败列表。在存储库设置中，可以更改导致拉取请求检查失败的警报严重性和安全严重性级别。

在 GitHub.com 上，导航到存储库的主页。在存储库名称下，选择“设置”。
在左侧边栏中，选择 “代码安全性和分析”。
在“保护规则”下的“代码扫描”部分中，使用下拉菜单选择要触发拉取请求检查失败的严重性级别。

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

你可能希望避免触发针对默认分支的特定拉取请求的代码扫描，而不考虑哪些文件已更改。你可以通过在代码扫描工作流中指定 on:pull_request:paths-ignore 或 on:pull_request:paths 来配置此设置。例如，如果拉取请求中仅更改了文件扩展名为 .md 或 .txt 的文件，你可以使用以下 paths-ignore 数组。

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

调整扫描计划

如果使用默认的 CodeQL 分析工作流，则除了由事件触发的扫描之外，该工作流还会每周扫描一次存储库中的代码，日期和时间随机生成。若要调整此计划，请在工作流中编辑 cron 值。

下面的示例演示了一个存储库的 CodeQL 分析工作流，该存储库有一个名为 main 的默认分支和一个名为 protected 的受保护分支：

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

此工作流扫描：

对默认分支和受保护分支的每次推送
对默认分支的每个拉取请求
默认分支（每周一 14:20 UTC）