Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

为存储库配置代码扫描

可以为存储库配置 code scanning 以查找代码中的安全漏洞。

Who can use this feature

If you have write permissions to a repository, you can configure code scanning for that repository.

Code scanning 可用于 GitHub.com 上的所有公共存储库。 若要在组织拥有的专用存储库中使用 code scanning,必须具有 GitHub Advanced Security 许可证。 有关详细信息,请参阅“关于 GitHub Advanced Security”。

用于配置 code scanning 的选项

在仓库级别决定如何生成 code scanning 警报,以及使用哪些工具。 GitHub Enterprise Cloud 对 CodeQL 分析提供完全集成的支持,还支持使用第三方工具进行分析。 有关详细信息,请参阅下面的要点和“关于 code scanning”。

自动配置 code scanning

code scanning 的默认设置将自动使用存储库的最佳设置来配置 code scanning。 如果存储库使用 GitHub Actions 并且仅包含以下 CodeQL 支持的语言,则其符合使用默认设置的条件:JavaScript/TypeScript、Python 或 Ruby。 可以在存储库包含 CodeQL 不支持的语言(例如 R)时使用默认设置,但如果包含 CodeQL 支持的语言,而这些语言不属于之前列出的语言,则必须使用高级设置。 有关 CodeQL 支持的语言的详细信息,请参阅“关于 code scanning 和 CodeQL”。

启用默认设置是为存储库配置 code scanning 的最快方法。 此外,默认设置不需要对 CodeQL 工作流文件进行任何维护。 在启用默认设置之前,可看到该设置将分析的语言和运行的查询套件,以及将触发新扫描的事件。

如果不需要运行额外的查询、更改扫描计划或扫描默认设置当前不支持的语言,请尝试默认设置。

  1. 在 GitHub.com 上,导航到存储库的主页。 1. 在存储库名称下,单击 “设置”。 “存储库设置”按钮

  2. 在侧边栏的“安全性”部分中,单击“ 代码安全性和分析”。

  3. 在“Code scanning”部分中,选择“设置”,然后单击“默认” 。

    “Code scanning”部分的屏幕截图,其中突出显示“默认”设置选项

  4. 在显示的 CodeQL 默认配置窗口中,查看存储库的设置,然后单击“启用 CodeQL”。

    “CodeQL 默认配置”弹出窗口的屏幕截图,其中突出显示“启用 CodeQL”按钮

    注意:

    • CodeQL 默认配置窗口显示默认设置的详细信息,包括要分析的语言、要运行的查询套件以及触发新扫描的事件。 如果要更改将运行的查询套件、将触发新扫描的事件或其他 code scanning 功能,则需要使用高级设置。 有关详细信息,请参阅“创建高级设置”。
    • 如果要从高级设置切换到默认设置,则可看到一条警告,通知你默认设置将替代现有配置。 启用 CodeQL 后,请务必删除或禁用现有的工作流文件。 否则,工作流将继续定期运行,而不会使用 GitHub Actions 分钟数上传任何 code scanning 结果。
    • 如果要在配置后查看默认 CodeQL 设置,请选择 ,然后单击 “查看 CodeQL 配置”。

创建高级设置

需要自定义 code scanning 时,code scanning 的高级设置非常有用。 通过创建和编辑工作流文件,可以选择要运行的查询、更改扫描计划、扫描任何 CodeQL 支持的语言、使用矩阵生成等。

使用初学者工作流配置 code scanning

注意:Advanced Security 的初始工作流已合并到存储库的“操作”选项卡中的“安全”类别中。 这种新配置目前处于 beta 版本,可能会有变动。

GitHub Enterprise Cloud 为 code scanning 等安全功能提供起始工作流。 您可以使用这些建议的工作流程来构建 code scanning 工作流程,而不是从头开始。 Code scanning 入门工作流仅在启用了 code scanning 时才可用于您的存储库。

使用操作运行 code scanning 将消耗分钟数。 有关详细信息,请参阅“关于 GitHub Actions 的计费”。

  1. 在 GitHub.com 上,导航到存储库的主页。 1. 在你的存储库名称下,单击 “操作”。 主存储库导航中的“操作”选项卡
  2. 如果存储库已配置并运行至少一个工作流,请单击“新建工作流”,然后转到步骤 5。 如果当前没有为存储库配置工作流程,请转到下一步。 “新建工作流”按钮的屏幕截图
  3. 向下滚动到“安全性”类别,然后在要配置的工作流下单击“配置”,或单击“查看全部”以查看所有可用的安全工作流 。 Actions 工作流安全性部分的屏幕截图
  4. 在工作流页面的右窗格中,单击“文档”,然后根据需要按屏幕上的说明定制工作流。 初学者工作流的“文档”选项卡的屏幕截图 有关详细信息,请参阅“使用初学者工作流”和“自定义 code scanning”。

手动配置 code scanning

可以通过创建和编辑工作流文件来自定义 code scanning。 高级设置会生成一个基本工作流文件供你自定义。

使用操作运行 code scanning 将消耗分钟数。 有关详细信息,请参阅“关于 GitHub Actions 的计费”。

  1. 在 GitHub.com 上,导航到存储库的主页。 1. 在存储库名称下,单击 “设置”。 “存储库设置”按钮

  2. 在侧边栏的“安全性”部分中,单击“ 代码安全性和分析”。

  3. 在“Code scanning”部分中,选择“设置”,然后单击“高级” 。

    注意:如果要从默认设置切换到高级 code scanning 设置,请在“Code scanning”部分中,选择 ,然后单击 “切换到高级” 。 在出现的弹出窗口中,单击“禁用 CodeQL”。

    “Code scanning”部分的屏幕截图,其中突出显示“高级”设置选项

  4. 要自定义 code scanning 扫描代码的方式,请编辑工作流程。

    通常,可以提交 CodeQL analysis workflow 而无需对其进行任何更改。 但是,许多第三方工作流需要额外的配置,因此请在提交之前读取工作流中的注释。

    有关详细信息,请参阅“自定义 code scanning”。

  5. 使用“开始提交”下拉列表,然后键入提交消息。 开始提交

  6. 选择是直接提交到默认分支,还是创建新分支并启动拉取请求。 选择提交位置

  7. 单击“提交新文件”或“建议新文件”。

在建议的 CodeQL analysis workflow 中,code scanning 配置为在每次将更改推送到默认分支或任何受保护分支或者对默认分支提出拉取请求时分析代码。 因此,code scanning 将立即开始。

用于代码扫描的 on:pull_requeston:push 触发器各自用于不同的目的。 有关详细信息,请参阅“自定义 code scanning”。

批量配置 code scanning

可以使用脚本在多个存储库中一次配置 code scanning。 如果要使用脚本发起将 GitHub Actions 工作流添加到多个存储库的拉取请求,请参阅 jhutchings1/Create-ActionsPRs 存储库,了解使用 PowerShell 的示例,或者对于没有 PowerShell 但希望改用 NodeJS 的团队,请参阅 nickliffen/ghas-enablement

查看来自 code scanning 的日志记录输出

为存储库配置 code scanning 后,可以监视操作运行时的输出。

  1. 在你的存储库名称下,单击 “操作”。 主存储库导航中的“操作”选项卡

    You can view the run status of code scanning and get notifications for completed runs. For more information, see "Managing a workflow run" and "Configuring notifications." 条目的文本是提交消息的标题。

    显示 code scanning 工作流的操作列表

  2. 单击 code scanning 工作流程的项目。

  3. 单击左侧的作业名称。 例如,“分析(语言)”。

    code scanning 工作流程的日志输出

  4. 查看此工作流运行时操作的日志记录输出。

  5. 在所有作业完成后,您可以查看已识别的任何 code scanning 警报的详细信息。 有关详细信息,请参阅“管理存储库的 code scanning 警报”。

注意:如果发起将 code scanning 工作流添加到存储库的拉取请求,则在合并拉取请求之前,来自该拉取请求的警报不会直接显示在 Code scanning 页面上。 如果发现任何警报,可以在合并拉取请求之前查看这些警报,方法是在 Code scanning 页面的横幅中单击“发现 NUMBER 条警报”链接。

单击“发现的 n 条警报”链接

了解拉取请求检查

设置在拉取请求上运行的每个 code scanning 工作流程始终有至少两个条目列在拉取请求的检查部分中。 工作流程中每个分析作业有一个条目,最后还有一个对应于分析结果的条目。

code scanning 分析检查的名称采用形式:"TOOL NAME / JOB NAME (TRIGGER)"。 例如,对于 CodeQL,C++ 代码的分析有条目 "CodeQL / Analyze (cpp) (pull_request)"。 可单击 code scanning 分析条目上的“详细信息”来查看日志记录数据。 这允许您在分析作业失败时调试问题。 例如,对于编译的语言的 code scanning 分析,如果操作无法生成代码,则可能会发生这种情况。

code scanning 拉取请求检查

当 code scanning 作业完成后, GitHub 检查拉取请求是否添加了任何警报,并将“Code scanning 结果/工具名称”条目添加到检查列表中。 在执行至少一次 code scanning 后,可单击“详细信息”查看分析结果。

后续步骤

配置 code scanning 并允许其操作完成后,你可以: