代码扫描

项目
04/16/2024

通过适用于 Azure DevOps 的 GitHub Advanced Security 中的代码扫描，可以分析 Azure DevOps 存储库中的代码，查找安全漏洞和编码错误。分析发现的任何问题都会作为警报引发。代码扫描使用 CodeQL 来识别漏洞。

CodeQL 是 GitHub 开发的代码分析引擎，用于自动执行安全检查。可以使用 CodeQL 分析代码，将结果显示为代码扫描警报。

适用于 Azure DevOps 的 GitHub Advanced Security 可与 Azure Repos 配合使用。如果要将 GitHub Advanced Security 与 GitHub 存储库配合使用，请参阅 GitHub Advanced Security。

CodeQL 警报

GitHub 专家、安全研究人员和社区参与者编写和维护用于代码扫描的默认 CodeQL 查询。查询会定期更新，以改进分析并减少任何误报结果。这些查询是开源查询，因此可以在 github/codeql 存储库中查看它们并向其贡献内容。

有关 CodeQL 的更具体文档，请访问 GitHub 上的 CodeQL 文档。

CodeQL 支持编译型和解释型语言，并且可以在使用支持的语言编写的代码中发现漏洞和错误。

C/C++
C#
Go
Java
JavaScript/TypeScript
Kotlin（beta 版本）
Python
Ruby
Swift

有关详细信息，请参阅 CodeQL 网站上的文档，了解支持的语言和框架。

可以通过查看生成日志（类似于依赖项扫描）来查看 CodeQL 使用的特定查询和任务详细信息。

代码扫描发布结果任务的屏幕截图

代码扫描警报

适用于 Azure DevOps 的 GitHub Advanced Security 的代码扫描警报包括存储库的代码扫描标志，用于发出代码级应用程序漏洞的警报。

要使用代码扫描，需要先配置适用于 Azure DevOps 的 GitHub Advanced Security。

Azure DevOps 中 Repos 下的“Advanced Security”选项卡是查看代码扫描警报的中心。选择“代码扫描”选项卡以查看扫描警报。可以按分支、状态、管道、规则类型和严重性进行筛选。此时，警报中心不会显示针对已为 PR 分支完成的扫描的对应警报。

重命名管道或分支不会对结果产生影响 - 最多可能需要 24 小时才能显示新名称。

如果选择运行自定义 CodeQL 查询，则默认情况下不会为不同查询包生成的警报提供单独的筛选器。可以按规则进行筛选，该规则对每个查询都是不同的。

存储库代码扫描警报的屏幕截图

如果关闭了存储库的 Advanced Security，则无法访问“Advanced Security”选项卡和生成任务中的结果。生成任务不会失败，但在禁用了 Advanced Security 的情况下，与该任务一起运行的生成的任何结果都会隐藏，并且不会保留。

警报详细信息

选择某个警报以查看更多详细信息，包括修正指南。每个警报都包含位置、说明、示例和严重性。

代码扫描警报详细信息的屏幕截图

部分	说明
位置	“位置”部分详细说明了 CodeQL 检测到漏洞的特定实例。如果存在多个违反同一规则的代码实例，则会为每个不同位置生成一个新警报。 “位置”卡包含指向受影响代码片段的直接链接，因此可以选择要定向到 Azure DevOps Web UI 的代码片段以进行编辑。
说明	说明由 CodeQL 工具根据问题提供。
建议	建议是针对给定代码扫描警报的建议修复。
示例	示例部分显示了代码中已识别弱点的简化示例。
严重性	严重性级别可以是低、中、高或严重。严重性评分基于已识别的常见弱点枚举 (CWE) 的给定通用漏洞评分系统 (CVSS) 评分。在这篇 GitHub 博文中了解有关如何对严重性进行评分的详细信息。

管理代码扫描警报

查看存储库的警报

任何拥有存储库参与者权限的人都可以在“Repos”下的“Advanced Security”中查看存储库所有警报的摘要。选择“代码扫描”选项卡以查看所有扫描警报。

要显示结果，需要先运行代码扫描任务。第一次扫描完成后，所有检测到的漏洞都会显示在“Advanced Security”选项卡中。

默认情况下，警报页显示存储库默认分支的依赖项扫描结果。

给定警报的状态反映默认分支和最新运行管道的状态，即使该警报存在于其他分支和管道上也是如此。

消除代码扫描警报

要消除警报，需要具有适当的权限。默认情况下，只有项目管理员可以消除 Advanced Security 警报。

消除警报：

导航到要关闭的警报并选择该警报。
选择“关闭警报”下拉列表。
请选择“接受的风险”或“误报”作为关闭原因（如果尚未选择）。
在“注释”文本框中添加可选注释。
选择“关闭”以提交并关闭警报。
警报状态从打开更改为已关闭并显示消除原因。

显示如何消除代码扫描警报的屏幕截图

这只会消除所选分支的警报。包含相同漏洞的其他分支保持活动状态，直到被消除。之前已消除的任何警报都可以手动重新打开。

在 CodeQL 中使用自定义查询

默认情况下，如果没有在管道设置中指定自定义配置文件，CodeQL 将运行 security-extended 查询包来分析代码。可以利用自定义 CodeQL 查询来编写自己的查询，以查找特定的漏洞和错误。还需要创建一个自定义配置文件，来修改 CodeQL 的默认分析。

若要查找现有的自定义查询或参与自己的自定义查询，请参阅参与 CodeQL。

使用自定义查询进行分析

开始使用自定义查询的最快方法是编写查询，并将其保存在本地 Azure DevOps 存储库中。可以根据需要对自定义查询的详细信息进行自定义，但它必须至少有一个规则 ID。若要详细了解如何编写自己的 CodeQL 查询，请参阅编写 CodeQL 查询。还可以将多个查询捆绑到查询套件中，或者利用其他人发布的包。若要了解详细信息，请参阅发布及使用 CodeQL 包。

使用自定义配置文件

自定义配置文件是管理 CodeQL 对代码进行分析期间运行哪些查询的一种方式。可以指定要运行的其他查询或查询包，并更改或禁用默认 CodeQL 查询。

若要包含想要包含的特定查询，请使用查询文件 (.ql) 在存储库中的位置的名称和路径来指定查询。

若要包含想要包含的特定包，请指定包名称。可以在配置文件中指定任意数量的 CodeQL 查询包来运行。

提示

配置文件中的 packs 筛选器支持从 GitHub 中托管的存储库下载包，但 queries 筛选器不支持。如果包在 GitHub 中是私有的，则需要通过 AdvancedSecurity-Codeql-Init@1 任务提供一个 GitHub 访问令牌作为环境变量，且变量名称为 GITHUB_TOKEN，令牌的作用域为 read:packages。

下面是一个示例配置文件：

name: "Run custom queries"

# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
 
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
  - name: Use security-extended query suite
    uses: security-extended
  - name: Use local custom query (single query)
    uses: ./customQueries/javascript/FindTestFunctions.ql
  - name: Use local custom query (directory of queries)
    uses: ./customQueries/javascript/MemoryLeakQueries  
 
packs:
 - mygithuborg/mypackname
 
paths:
 - src
 
paths-ignore:
  - src/node_modules
  - '**/*.test.js'
 
query-filters:
 - include:
    kind: problem
 - include:
     precision: medium
 - exclude:
    id:
      - js/angular/disabling-sce
      - js/angular/insecure-url-allowlist

提示

配置文件规范会忽略，并优先于 AdvancedSecurity-Codeql-Init@1 任务的管道级别配置。 includepaths / ignorepaths 将被忽略，或者如果 paths/paths-ignore 存在，则用来自 paths/paths-ignore 的值覆盖。 querysuite 将被用 queries 或 packs 配置文件中指定的值覆盖。

有关配置文件的更具体建议和配置选项，请参阅自定义高级设置进行代码扫描。

一旦有了配置文件，就需要自定义运行 CodeQL 分析的管道，以利用新文件。下面是指向配置文件的示例管道：

trigger: none
 
pool:
  vmImage: windows-latest

# You can either specify your CodeQL variables in a variable block... 
variables:
# `configfilepath` must be an absolute file path relative to the repository root
  advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' 

# Or you can specify variables as variables for the task. You do not need both definitions. 
steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
    languages: 'javascript'
    loglevel: '2'
    configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
  env:
    GITHUB_TOKEN: $(githubtoken)
 
- task: AdvancedSecurity-Codeql-Autobuild@1
  displayName: AutoBuild
 
- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis

代码扫描疑难解答

通常，如果遇到 CodeQL 执行错误，CodeQL CLI 则会报告它作为退出代码而运行的每个命令的状态。退出代码可为后续命令或依赖于 CodeQL CLI 的其他工具提供信息。有关退出代码详细信息的详细信息，请参阅退出代码。

错误：'database finalize' CodeQL 命令 (32)

此错误表示完成 CodeQL 数据库创建时出现问题，而这可能源于提取错误或缺少生成步骤。

故障排除步骤：

验证代码是否存在并已编译
- 对于已编译的语言，请验证生成流程是否正在编译代码，且正在 AdvancedSecurity-Codeql-Init 与 AdvancedSecurity-Codeql-Analyze 任务之间进行。你可在指定生成命令中找到常见生成命令和所需的标志（例如，“干净且无缓存/无守护程序”）。
- 对于已解释的语言，请确认项目中存在针对指定语言的某些源代码。
检查提取错误
- 验证提取错误是否会影响 CodeQL 数据库的运行状况。
- 查看日志文件，了解提取错误和警告，以便评估总体数据库运行状况。
调查严重错误
- 如果大多数文件遇到提取程序错误，则请进一步调查以了解提取不当的根本原因。

错误：自动生成脚本 (1)

此错误描述了某一自动生成故障，并表明代码扫描设置或配置出现问题。

故障排除步骤：

配置生成步骤
- 删除“自动生成”步骤，并在管道中为已编译语言配置特定的生成步骤。
- 请参阅配置适用于 Azure DevOps 的 GitHub Advanced Security 中提供的设置准则。

错误：在代理工具缓存中未找到 CodeQL 目录

此错误表示安装适用于自托管代理的 CodeQL 时出现问题。

故障排除步骤：

请参阅配置适用于 Azure DevOps 的 GitHub Advanced Security 中提供的设置准则或配置脚本。

错误：未设置语言管道变量

尝试运行 CodeQL 而未设置用于指定要扫描哪个语言的管道变量时，会出现此错误。

故障排除步骤：

设置语言管道变量
- 确保正确配置语言管道变量。请参阅配置适用于 Azure DevOps 的 GitHub Advanced Security 中提供的设置准则。
- 支持的语言包括 csharp、cpp、go、java、javascript、python、ruby 和 swift。

未返回任何结果的 CodeQL

本节提供针对 CodeQL 分析未生成任何结果的情况的相关指导。

故障排除步骤：

检查是否存在已检测到的漏洞
- 请考虑代码可能真无漏洞的可能性。如果预计存在漏洞但未检测到，这请继续进行验证。
查看查询套件配置
- 确认正在使用的查询套件，并在必要时考虑切换到更全面的套件。
- 或者，也可创建自定义查询套件以进行定制分析。
调整用于查看结果的权限
- 确保已授予适当的权限（至少为参与者级别）以访问分析结果。有关详细信息，请参阅 Advanced Security 权限。

代码扫描任务权限

代码扫描生成任务使用管道标识来调用高级安全 REST API。默认情况下，同一项目中的管道有权上传通过运行 CodeQL 分析生成的 SARIF 文件。如果从生成服务帐户中删除这些权限，或者拥有自定义设置（例如，托管在与存储库不同的项目中的管道），则必须手动授予这些权限。

故障排除步骤：

向管道中使用的生成服务帐户授予 Advanced Security: View alerts 和 Advanced Security: Manage and dismiss alerts 权限。对于项目范围的管道，该帐户为 [Project Name] Build Service ([Organization Name])；对于集合范围的管道，该帐户为 Project Collection Build Service ([Organization Name])。

代码扫描

CodeQL 警报

代码扫描警报

警报详细信息

管理代码扫描警报

查看存储库的警报

消除代码扫描警报

在 CodeQL 中使用自定义查询

使用自定义查询进行分析

使用自定义配置文件

代码扫描疑难解答

错误：'database finalize' CodeQL 命令 (32)

错误：自动生成脚本 (1)

错误：在代理工具缓存中未找到 CodeQL 目录

错误：未设置语言管道变量

未返回任何结果的 CodeQL

代码扫描任务权限

反馈

反馈

其他资源