GitHub高级安全性中的代码扫描功能适用于Azure DevOps,它允许你分析Azure DevOps存储库中的代码,以发现安全漏洞和编码错误。 您需要为Azure DevOps启用GitHub高级安全性或者在使用独立体验时启用GitHub代码安全性。 分析发现的任何问题都会作为警报发出。 代码扫描使用 CodeQL 来识别漏洞。
CodeQL 是由GitHub开发的用于自动执行安全检查的代码分析引擎。 可以使用 CodeQL 分析代码,将结果显示为代码扫描警报。 有关 CodeQL 的更具体文档,请参阅 CodeQL 文档。
注释
你可以使用 CodeQL CLI 来分析当前已由适用于 Azure DevOps 的 GitHub Advanced Security 付费许可证涵盖的存储库。 如果使用 CodeQL CLI 作为独立工具,请按照GitHub文档从命令行进行扫描以安装和使用 CLI。 若要将生成的 SARIF 文件发布到Azure DevOps,请使用高级安全发布任务。
Azure DevOps 的 GitHub 高级安全性支持 Azure Repos。 若要将 GitHub Advanced Security 与 GitHub 存储库配合使用,请参阅 GitHub Advanced Security。
先决条件
| 类别 | 要求 |
|---|---|
| 权限 | - 若要查看存储库的所有警报的摘要:存储库的 参与者 权限。 - 若要消除高级安全性中的警报:需有项目管理员权限。 - 若要管理高级安全性中的权限:需为项目集合管理员组成员或将高级安全性:管理设置权限设置为允许。 |
| 管道任务 | - 在 组织设置>管道>设置>任务限制中,确保 禁用 Marketplace 任务 已关闭。 代码扫描和依赖项扫描依赖于通过 Visual Studio 市场分发的Azure Pipelines任务。 如果禁用 Marketplace 任务,默认设置将无法运行扫描,而高级设置流水线可能会报告缺少某个任务。 有关详细信息,请参阅任务管理。 |
有关高级安全权限的详细信息,请参阅 “管理高级安全”权限。
关于代码扫描设置类型
可通过两种主要方法为存储库设置代码扫描: 默认设置 和 高级设置。
| 默认设置 | 高级设置 | |
|---|---|---|
| 配置 | 自动,无需管道配置 | 手动,需要将 CodeQL 任务添加到流水线中。 |
| 语言检测 | 自动检测和扫描支持的语言 | 在管道任务中指定语言 |
| 分支覆盖范围 | 仅扫描默认分支 | 扫描触发管道的任何分支 |
| 构建自定义 | 没有自定义生成步骤 - 使用 none 生成模式 |
完全控制已编译语言的生成步骤 |
| 最适用于 | 快速启用、标准扫描需求 | 多分支扫描、自定义代理池或扫描频率 |
默认设置 是启用代码扫描的最快方法。 它在后台创建托管扫描配置,无需更改管道。 建议从大多数存储库的默认设置开始。
默认设置扫描以下语言:C#、C/C++、Java、JavaScript/TypeScript、Python、Ruby 和 Rust。 默认情况下不支持 Go 和 Swift。 若要扫描这些语言,请使用高级设置。
在包含 C/C++ 的存储库上启用默认设置时,C/C++ 会在其他详细信息面板中显示为受支持的语言,并在配置的默认安装程序运行过程中进行扫描。
高级设置让您通过将 CodeQL 任务直接添加到 Azure Pipelines 来实现完全控制。 在需要时使用高级设置:
- 管理不同语言或计算需求的特定代理池
- 自定义已编译语言的生成步骤
- 扫描默认分支之外的分支
- 将代码扫描集成到现有的 CI/CD 管道中
- 使用特定的 CodeQL 查询套件或自定义查询
提示
如果需要更多控制,或者同时使用这两种设置,则可以从默认设置开始,稍后切换到高级设置。 有关配置默认设置的信息,请参阅配置GitHub高级安全功能。
注释
在组织或项目级别启用 CodeQL 默认设置时,初始扫描会自动为所有受影响的存储库排队。 当每个存储库的扫描完成时,结果开始逐渐出现,而无需等待下一次计划的运行。
配置默认安装选项
启用 CodeQL 默认设置后,可以从组织设置配置 代理池 和 扫描计划 。 这些选项适用于组织中使用默认设置的所有存储库。
若要访问可配置的选项,请转到 “组织设置>存储库 ”并展开 CodeQL 默认设置可配置选项 下拉列表。
代理池
选择用于在组织中所有存储库中运行 CodeQL 默认设置扫描的代理池。 可以选择:
- Azure Pipelines - 使用Microsoft托管的代理。 使用 Azure Pipelines 代理池会消耗管道并发性。
- 自托管代理池 - 使用自己的代理。 如果存储库需要访问专用网络、特定生成工具或其他托管代理上不可用的其他资源,请选择自承载池。
- Managed DevOps Pools — 使用具有自定义VM映像的 Azure 托管池。
扫描计划
选择何时对组织中的所有存储库运行 CodeQL 默认设置扫描。 可以选择特定的某个星期几进行每周扫描。 下一个预定的运行日期显示在下拉列表下方。
注释
在组织或项目级别启用默认设置时,初始运行会自动排队,因此无需等待计划的每周运行来获取第一个结果。
取消正在运行的或排队的扫描
如果需要停止任何主动运行或排队的默认设置扫描,可以通过 组织设置>存储库手动取消它们。 对存储库具有高级安全性:管理设置权限的用户可以取消正在运行或排队的默认设置运行。
监视默认安装程序运行
您可以在代理池作业日志视图中监控并查找 CodeQL 默认设置的运行记录。
增强型日志查看器 - 当默认设置运行失败时,失败将显示在日志查看器顶部。 无需扫描整个日志即可快速调查出错的情况。
运行命名 — 默认设置运行遵循命名约定,以便于在代理池作业日志视图中一目了然地识别这些约定。
状态和存储库筛选器 - 按 状态 和 存储库 筛选作业,以便更好地了解代理池中作业发生的情况。 这些筛选条件适用于视图中的所有作业,而不仅仅是默认安装程序运行。
用于代码扫描的高级设置
CodeQL 是一种管道化工具,结果汇总在每个存储库中。
提示
代码扫描可能是一项更耗时的生成任务,因此我们建议将代码扫描任务添加到主生产管道的单独克隆管道或创建新管道。
按以下顺序添加任务:
- Advanced Security 初始化 CodeQL (AdvancedSecurity-Codeql-Init@1)
- 你的自定义构建步骤
- Advanced Security 执行 CodeQL 分析 (AdvancedSecurity-Codeql-Analyze@1)
此外,请在Initialize CodeQL任务中指定您要分析的语言。 可以使用逗号分隔列表一次性分析多种语言。 支持的语言是 csharp, cpp, go, java, javascript, python, ruby, swift。 如果使用自承载代理,则还可以添加 enableAutomaticCodeQLInstall: true 变量以自动为代理安装最新的 CodeQL 位。
下面是一个初始管道示例:
trigger:
- main
pool:
# Additional hosted image options are available: https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/hosted#software
vmImage: ubuntu-latest
steps:
- task: AdvancedSecurity-Codeql-Init@1
inputs:
languages: "java"
# Supported languages: csharp, cpp, go, java, javascript, python, ruby, swift
# You can customize the initialize task: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/advanced-security-codeql-init-v1?view=azure-pipelines
# If you're using a self-hosted agent to run CodeQL, use `enableAutomaticCodeQLInstall` to automatically use the latest CodeQL bits on your agent:
enableAutomaticCodeQLInstall: true
# Add your custom build steps here
# - Ensure that all code to be scanned is compiled (often using a `clean` command to ensure you're building from a clean state).
# - Disable the use of any build caching mechanisms as this can interfere with CodeQL's ability to capture all the necessary data during the build.
# - Disable the use of any distributed/multithreaded/incremental builds as CodeQL needs to monitor executions of the compiler to construct an accurate representation of the application.
# - For dependency scanning, ensure you have a package restore step for more accurate results.
# If you had a Maven app:
# - task: Maven@4
# inputs:
# mavenPomFile: 'pom.xml'
# goals: 'clean package'
# publishJUnitResults: true
# testResultsFiles: '**/TEST-*.xml'
# javaHomeOption: 'JDKVersion'
# jdkVersionOption: '1.17'
# mavenVersionOption: 'Default'
# Or a general script:
# - script: |
# echo "Run, Build Application using script"
# ./location_of_script_within_repo/buildscript.sh
- task: AdvancedSecurity-Dependency-Scanning@1 # More details on this task: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/advanced-security-dependency-scanning-v1?view=azure-pipelines
- task: AdvancedSecurity-Codeql-Analyze@1 # More details on this task: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/advanced-security-codeql-analyze-v1?view=azure-pipelines
此外,请在Initialize CodeQL任务中指定您要分析的语言。 如果指定 swift语言,则需要自定义生成步骤。
提示
- 使用
java分析用 Java、Kotlin 或两者编写的代码。 - 使用
javascript分析用 JavaScript 和/或 TypeScript 编写的代码。
如果您在自承载代理上运行,并且尚未手动将最新的 CodeQL 捆绑包安装到代理工具缓存中,请选择 Enable automatic CodeQL detection and installation,以便在代理上自动使用最新的 CodeQL 组件。
要生成警报,请使用包含代码扫描任务的管道运行第一次扫描。
更多代码扫描配置
语言和查询支持
GitHub专家、安全研究人员和社区参与者编写和维护用于代码扫描的默认 CodeQL 查询。 查询会定期更新,以改进分析并减少任何误报结果。 查询是开放源代码的,因此可以在 github/codeql 存储库中查看和贡献查询。
CodeQL 支持并使用以下语言标识符:
| 语言 | 标识符 |
|---|---|
| C/C++ | cpp |
| C# | csharp |
| Go | go |
| Java/Kotlin | java |
| JavaScript/TypeScript | javascript |
| Python | python |
| Ruby | ruby |
| Rust | rust |
| Swift | swift |
提示
- 使用
cpp分析用 C、C++ 或两者编写的代码。 - 使用
java分析用 Java、Kotlin 或两者编写的代码。 - 使用
javascript分析用 JavaScript 和/或 TypeScript 编写的代码。
有关详细信息,请参阅支持的语言和框架。
可以查看 CodeQL 在生成日志中执行的特定查询和任务详细信息。 使用默认设置时,增强型日志查看器提供更清晰的运行命名和新的状态和存储库筛选器,以帮助查找和查看Azure DevOps代理池作业日志视图中的特定扫描运行。
代码扫描生成模式自定义
设置管道进行扫描时,代码扫描支持两种生成模式:
-
none- CodeQL 数据库直接从代码库创建,而无需生成代码库(所有解释语言都受支持,并且还支持cppjava,以及csharp)。 -
manual- 定义用于工作流中代码库的生成步骤(支持所有编译语言)。
有关不同生成模式的详细信息,包括每种生成模式的优点比较,请参阅 用于编译语言的 CodeQL 代码扫描。
提示
生成模式none可用于其他解释语言,例如 JavaScript、Python、Ruby。
如果为 C# 指定了生成模式none,或者使用不支持生成模式的其他编译语言noneJava,则管道任务将失败。
以下代码演示了具有多种语言和 none 生成模式的有效配置示例:
trigger: none
pool:
vmImage: windows-latest
steps:
- task: AdvancedSecurity-Codeql-Init@1
displayName: Initialize CodeQL
inputs:
# build mode `none` is supported for C# and Java, and JavaScript is an interpreted language
# and build mode `none` has no impact on JavaScript analysis
languages: 'csharp, java, javascript'
buildtype: 'none'
- task: AdvancedSecurity-Codeql-Analyze@1
displayName: Perform CodeQL Analysis
以下代码演示了具有多种语言和 none 生成模式的无效配置的示例:
trigger: none
pool:
vmImage: windows-latest
steps:
- task: AdvancedSecurity-Codeql-Init@1
displayName: Initialize CodeQL
inputs:
# build mode `none` is supported for C# but build mode `none` is NOT supported for Swift
# so this pipeline definition will result in a failed run
languages: 'csharp, swift'
buildtype: 'none'
- task: AdvancedSecurity-Codeql-Analyze@1
displayName: Perform CodeQL Analysis
代码扫描警报
GitHub 用于 Azure DevOps 的高级安全性代码扫描警报包括存储库的代码扫描标志,这些标志会对代码级应用程序漏洞发出警报。
若要使用代码扫描,需要首先为 Azure DevOps 配置 GitHub 高级安全性。
Azure DevOps中Repos下的高级安全选项卡是查看代码扫描警报的中心。 选择“代码扫描”选项卡以查看扫描警报。 可以按分支、状态、管道、规则类型和严重性进行筛选。 此时,警报中心不会显示针对已为 PR 分支完成的扫描的对应警报。
重命名管道或分支不会对结果产生影响 - 最多可能需要 24 小时才能显示新名称。
如果选择运行自定义 CodeQL 查询,则默认情况下将不为不同查询包生成的警报提供单独的筛选器。 可以按规则进行筛选,该规则对每个查询都是不同的。
如果关闭了存储库的 Advanced Security,则无法访问“Advanced Security”选项卡和生成任务中的结果。 生成任务不会失败,但在禁用高级安全性的情况下运行时,任何生成结果都将被隐藏且不被保留。
警报详细信息
选择某个警报以查看更多详细信息,包括修正指南。 每个警报都包含位置、说明、示例和严重性。
| 部分 | 说明 |
|---|---|
| 位置 | 位置部分详细说明了 CodeQL 检测到漏洞的特定实例。 如果存在多个违反同一规则的代码实例,则会为每个不同位置生成一个新警报。 “位置”卡包含指向受影响代码片段的直接链接,以便你可以选择要定向到Azure DevOps Web UI 进行编辑的代码片段。 |
| 说明 | 说明由 CodeQL 工具根据问题提供。 |
| 建议 | 建议是针对给定代码扫描警报的建议修复。 |
| 示例 | 示例部分显示了代码中已识别弱点的简化示例。 |
| 严重性 | 严重性级别可以是低、中、高或严重。 严重性评分基于已识别的常见弱点枚举 (CWE) 的给定通用漏洞评分系统 (CVSS) 评分。 在这篇 GitHub 博文中了解有关如何对严重性进行评分的详细信息。 |
查看存储库的警报
具有存储库参与者权限的任何人都可以在Repos的“高级安全”选项卡中查看存储库的所有警报摘要。 选择代码扫描选项卡,以查看所有秘密扫描警报。
要显示结果,需要先运行代码扫描任务。 第一次扫描完成后,所有检测到的漏洞都会显示在“Advanced Security”选项卡中。
默认情况下,警报页显示存储库默认分支的代码扫描结果。
给定警报的状态反映默认分支和最新运行管道的状态,即使该警报存在于其他分支和管道上也是如此。
使用 Copilot Autofix 生成修复
对于受支持的警报,请选择生成修复,让Copilot Autofix提出更改并打开拉取请求。 查看、测试和合并建议的修补程序,然后再次运行代码扫描以验证结果。
Agentic Autofix 可以使用已签入代码仓库的说明和相关技能来帮助建议的修复遵循编码标准。 该功能目前为公开预览版。 有关先决条件、启用和存储库上下文指南,请参阅用于代码安全警报的 Copilot Autofix。
自动清理过时管道配置中的警报
当管道配置停止运行时,自动清理会隐藏旧的扫描结果。 它不会仅仅因为警报或其分支路径超过 90 天而隐藏警报。 此行为适用于代码扫描和依赖项扫描警报。
是什么使配置过时?
清理使用与扫描配置关联的管道阶段的最新完成时间。 默认情况下,当完成时间距今已超过 90 天时,阶段会过时。
高级安全性将管道阶段记录标记为非活动状态,但会保留其结果。 然后,仅当 与该警报关联的所有最新结果来自过时配置时,警报视图才会隐藏警报。 如果其中任一结果来自活动配置,则仍会显示警报。
| 日期或活动 | 用于 90 天的清理? |
|---|---|
| 首次检测到警报时 | No |
| 上次检测到警报时 | No |
| 分支上次被扫描的时间 | 不能单独进行。 清理会跟踪可跨分支共享的关联管道阶段。 |
| 关联的管道阶段最近的完成时间 | Yes |
为什么旧分支检测可以保持可见或重新出现?
不同的分支可以共享相同的管道阶段活动记录。 当该阶段在另一个分支上再次运行时,高级安全性会更新其完成时间并重新激活关联的配置。 因此,最近未运行的分支上的较旧检测可以保持可见或重新出现。
例如,请考虑以下序列:
- 管道阶段在
develop上检测到漏洞。 - 该阶段不会在任何分支上运行 90 天以上。 清理将其标记为非活动状态后,如果高级安全性没有来自其他活动配置的最新结果,则会隐藏该警报。
- 同一阶段在
feature/update-build上运行。 高级安全会重新激活其关联的配置,以便较旧的develop检测可以再次显示。
运行记录feature/update-build不会扫描develop。 它会更改共享管道阶段的活动状态,该状态控制高级安全性是否显示较旧的结果。
出于此原因,警报可能显示较早的首次发现日期或上次发现日期。 这些日期描述的是分支上的检测,而不是管道阶段的活动状态。 重新激活配置不会使旧结果成为新的检测,也不需要其原始首次发现日期发生更改。
应进行哪些检查?
当旧检测保持可见时,查看跨分支的同一管道阶段的运行,而不仅仅是警报中显示的分支。 若要检查该分支上是否存在漏洞,请在该分支上运行扫描。
Important
自动清理会隐藏结果。 它不会修复漏洞或消除警报。 如果关联的配置再次处于活动状态,以前隐藏的未解决警报会重新显示为未解决警报。
忽略代码扫描警报
要消除警报,需要具有适当的权限。 默认情况下,只有项目管理员可以消除 Advanced Security 警报。
要消除警报,请执行以下操作:
- 导航到要关闭的警报并选择该警报。
- 选择关闭警报下拉列表。
- 请选择“接受的风险”或“误报”作为关闭原因(如果尚未选择)。
- 在“注释”文本框中添加可选注释。
- 选择“关闭”以提交并关闭警报。
- 警报状态从开启更改为已关闭并显示您的取消原因。
此操作会关闭所有分支中的警报通知。 还将消除包含相同漏洞的其他分支。 之前已消除的任何警报都可以手动重新打开。
管理拉取请求上的代码扫描警报
如果为拉取请求中的新代码更改创建了警报,则会在拉取请求的“概述”选项卡的注释部分作为注释报告,并在“高级安全存储库”选项卡中作为警报显示。拉取请求分支有一个新的分支选择器条目。
可以查看受影响的代码行,查看结果摘要,并在概述部分解决批注问题。
要取消拉取请求警报,则必须导航到警报详情视图,关闭警报并解决批注问题。 否则,只需更改注释状态(1)即可解析批注,但不会关闭或修复基础警报。
若要查看拉取请求分支的整个结果集,请导航到 Repos>Advanced Security并选择拉取请求分支。 选择 批注上的“显示更多详细信息 ”(2)会将你定向到“高级安全”选项卡中的警报详细信息视图。
提示
只有当受影响的代码行与拉取请求的目标分支相比,拉取请求差异完全唯一时,才会创建批注。