• Web API 模糊测试配置表单
  • 在 UI 中配置 Web API 模糊测试
• OpenAPI 规范
• OpenAPI 和媒体类型
  • 使用 OpenAPI 规范配置 Web API 模糊测试
• HTTP Archive (HAR)
  • 使用 HAR 文件配置 Web API 模糊测试
• GraphQL Schema
  • 使用 GraphQL 端点 URL 进行 API 模糊测试扫描
  • 使用 GraphQL Schema 文件进行 API 模糊测试
• Postman Collection
  • 使用 Postman Collection 文件配置 Web API 模糊测试
  • Postman 变量
    • Postman 客户端中的变量
    • 从 Postman 客户端导出
    • API 模糊测试范围，自定义 JSON 文件格式
    • 在 API 模糊测试中使用范围
    • 未定义的 Postman 变量
    • 动态 Postman 变量
    • 示例：全局范围
    • 示例：环境范围
    • 示例：集合范围
    • 示例：API 模糊测试范围
    • 示例：多个范围
    • 示例：更改变量值
    • 示例：使用多个范围更改变量值
• 运行您的第一个扫描
• 查看模糊测试故障
  • 查看 API 模糊测试漏洞的详细信息
  • 安全仪表板
  • 与漏洞互动
• 处理误报
  • 关闭检查
  • 关闭检查的断言

先决条件：

• 以下 Web API 类型之一：
  • REST API
  • SOAP
  • GraphQL
  • 表单主体、JSON 或 XML
• 以下资源之一，用于提供 API 进行测试：
  • OpenAPI v2 或 v3 API 定义
  • API 请求的 HTTP Archive (HAR)
  • Postman Collection v2.0 或 v2.1

  {{< alert type=”warning” >}}

  永远不要对生产服务器进行模糊测试。因为它可以执行 API 的任何功能，还可能触发 API 中的错误。这包括修改和删除数据的操作。只能对测试服务器进行模糊测试。

  {{< /alert >}}

要启用 Web API 模糊测试，请使用 Web API 模糊测试配置表单。

• 对于手动配置说明，请根据 API 类型查看相应部分：
  • OpenAPI 规范
  • GraphQL Schema
  • HTTP Archive (HAR)
  • Postman Collection
• 否则，请参阅 Web API 模糊测试配置表单。

API 模糊测试配置文件必须位于您的仓库的 .gitlab 目录中。

Web API 模糊测试配置表单

API 模糊测试配置表单帮助您创建或修改项目的 API 模糊测试配置。该表单允许您选择最常见的 API 模糊测试选项的值，并构建一个 YAML 片段，您可以将其粘贴到极狐GitLab CI/CD 配置中。

在 UI 中配置 Web API 模糊测试

要生成 API 模糊测试配置片段：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 安全 > 安全配置。
3. 在 API 模糊测试 行中，选择 启用 API 模糊测试。
4. 完成字段。有关详细信息，请参阅 可用 CI/CD 变量。
5. 选择 生成代码片段。将打开一个模式，其中包含与您在表单中选择的选项相对应的 YAML 片段。
6. 执行以下操作之一：
   1. 要将片段复制到剪贴板，请选择 仅复制代码。
   2. 要将片段添加到项目的 .gitlab-ci.yml 文件中，请选择 复制代码并打开 .gitlab-ci.yml 文件。流水线编辑器将打开。
      1. 将片段粘贴到 .gitlab-ci.yml 文件中。
      2. 选择 Lint 选项卡以确认编辑后的 .gitlab-ci.yml 文件有效。
      3. 选择 编辑 选项卡，然后选择 提交更改。

当片段提交到 .gitlab-ci.yml 文件时，流水线将包含一个 API 模糊测试作业。

OpenAPI 规范

OpenAPI 规范（以前称为 Swagger 规范）是一种用于 REST API 的 API 描述格式。本节向您展示如何使用 OpenAPI 规范配置 API 模糊测试，以提供有关目标 API 的信息进行测试。OpenAPI 规范作为文件系统资源或 URL 提供。支持 JSON 和 YAML OpenAPI 格式。

API 模糊测试使用 OpenAPI 文档生成请求主体。当需要请求主体时，主体生成仅限于以下这些主体类型：

• application/x-www-form-urlencoded
• multipart/form-data
• application/json
• application/xml

OpenAPI 和媒体类型

媒体类型（以前称为 MIME 类型）是传输文件格式和格式内容的标识符。OpenAPI 文档允许您指定给定操作可以接受不同的媒体类型，因此给定请求可以使用不同的文件内容发送数据。例如，更新用户数据的 PUT /user 操作可以接受 XML（媒体类型 application/xml）或 JSON（媒体类型 application/json）格式的数据。OpenAPI 2.x 允许您全局或每个操作指定接受的媒体类型，OpenAPI 3.x 允许您每个操作指定接受的媒体类型。API 模糊测试检查列出的媒体类型，并尝试为每个支持的媒体类型生成示例数据。

• 默认行为是选择要使用的支持媒体类型之一。从列表中选择第一个支持的媒体类型。此行为是可配置的。

使用不同媒体类型（例如 application/json 和 application/xml）测试同一操作（例如 POST /user）并不总是可取的。例如，如果目标应用程序无论请求内容类型如何都执行相同的代码，则需要更长时间才能完成测试会话，并且可能会报告与请求主体相关的重复漏洞，具体取决于目标应用程序。

环境变量 FUZZAPI_OPENAPI_ALL_MEDIA_TYPES 允许您指定在为给定操作生成请求时是否使用所有支持的媒体类型而不是一个。当环境变量 FUZZAPI_OPENAPI_ALL_MEDIA_TYPES 设置为任何值时，API 模糊测试会尝试为给定操作的所有支持媒体类型生成请求，而不是一个。这会导致测试时间更长，因为针对每个提供的媒体类型重复测试。

或者，变量 FUZZAPI_OPENAPI_MEDIA_TYPES 用于提供每个测试的媒体类型列表。提供多个媒体类型会导致测试时间更长，因为针对每个选择的媒体类型进行测试。当环境变量 FUZZAPI_OPENAPI_MEDIA_TYPES 设置为媒体类型列表时，仅在创建请求时包含列出的媒体类型。

FUZZAPI_OPENAPI_MEDIA_TYPES 中的多个媒体类型必须用冒号 (:) 分隔。例如，要将请求生成限制为媒体类型 application/x-www-form-urlencoded 和 multipart/form-data，请将环境变量 FUZZAPI_OPENAPI_MEDIA_TYPES 设置为 application/x-www-form-urlencoded:multipart/form-data。在创建请求时仅包含此列表中的支持媒体类型，尽管始终跳过不支持的媒体类型。媒体类型文本可以包含不同的部分。例如，application/vnd.api+json; charset=UTF-8 是 type "/" [tree "."] subtype ["+" suffix]* [";" parameter] 的复合体。在请求生成时过滤媒体类型时不考虑参数。

环境变量 FUZZAPI_OPENAPI_ALL_MEDIA_TYPES 和 FUZZAPI_OPENAPI_MEDIA_TYPES 允许您决定如何处理媒体类型。这些设置是互斥的。如果同时启用，API 模糊测试会报告错误。

使用 OpenAPI 规范配置 Web API 模糊测试

要使用 OpenAPI 规范在极狐GitLab 中配置 API 模糊测试：

1. 将 fuzz 阶段添加到您的 .gitlab-ci.yml 文件中。

2. 包含 API-Fuzzing.gitlab-ci.yml 模板到您的 .gitlab-ci.yml 文件中。

3. 通过将 FUZZAPI_PROFILE CI/CD 变量添加到您的 .gitlab-ci.yml 文件来提供配置文件。配置文件指定运行的测试数量。将 Quick-10 替换为您选择的配置文件。有关详细信息，请参阅 API 模糊测试配置文件。

   variables:
     FUZZAPI_PROFILE: Quick-10
   

4. 提供 OpenAPI 规范的位置。您可以将规范作为文件或 URL 提供。通过添加 FUZZAPI_OPENAPI 变量来指定位置。

5. 提供目标 API 实例的基本 URL。使用 FUZZAPI_TARGET_URL 变量或 environment_url.txt 文件。

   在项目根目录中添加 URL 到 environment_url.txt 文件非常适合在动态环境中进行测试。要在极狐GitLab CI/CD 流水线期间动态创建的应用程序上运行 API 模糊测试，请让应用程序在 environment_url.txt 文件中保留其 URL。API 模糊测试会自动解析该文件以找到其扫描目标。您可以在 Auto DevOps CI YAML 中看到此示例。

使用 OpenAPI 规范的示例 .gitlab-ci.yml 文件：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_TARGET_URL: http://test-deployment/

这是 API 模糊测试的最小配置。从这里您可以：

• 运行您的第一个扫描。
• 添加认证。
• 了解如何 处理误报。

有关 API 模糊测试配置选项的详细信息，请参阅 可用 CI/CD 变量。

HTTP Archive (HAR)

HTTP Archive 格式 (HAR) 是一种用于记录 HTTP 事务的归档文件格式。与极狐GitLab API 模糊测试器一起使用时，HAR 必须包含调用 Web API 进行测试的记录。API 模糊测试器会提取所有请求并使用它们进行测试。

有关更多详细信息，包括如何创建 HAR 文件，请参阅 HTTP Archive 格式。

{{< alert type=”warning” >}}

HAR 文件可能包含敏感信息，如认证令牌、API 密钥和会话 Cookie。我们建议您在将 HAR 文件添加到仓库之前，先审查其内容。

{{< /alert >}}

使用 HAR 文件配置 Web API 模糊测试

要配置使用 HAR 文件的 API 模糊测试：

1. 将 fuzz 阶段添加到您的 .gitlab-ci.yml 文件中。

2. 包含 API-Fuzzing.gitlab-ci.yml 模板到您的 .gitlab-ci.yml 文件中。

3. 通过将 FUZZAPI_PROFILE CI/CD 变量添加到您的 .gitlab-ci.yml 文件来提供配置文件。配置文件指定运行的测试数量。将 Quick-10 替换为您选择的配置文件。有关详细信息，请参阅 API 模糊测试配置文件。

   variables:
     FUZZAPI_PROFILE: Quick-10
   

4. 提供 HAR 规范的位置。您可以将规范作为文件或 URL 提供。通过添加 FUZZAPI_HAR 变量来指定位置。

5. 目标 API 实例的基本 URL 也是必需的。通过使用 FUZZAPI_TARGET_URL 变量或 environment_url.txt 文件来提供它。

   在项目根目录中添加 URL 到 environment_url.txt 文件非常适合在动态环境中进行测试。要在极狐GitLab CI/CD 流水线期间动态创建的应用程序上运行 API 模糊测试，请让应用程序在 environment_url.txt 文件中保留其域。API 模糊测试会自动解析该文件以找到其扫描目标。您可以在 我们的 Auto DevOps CI YAML 示例中看到此示例。

使用 HAR 文件的示例 .gitlab-ci.yml 文件：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_HAR: test-api-recording.har
  FUZZAPI_TARGET_URL: http://test-deployment/

此示例是 API 模糊测试的最小配置。从这里您可以：

• 运行您的第一个扫描。
• 添加认证。
• 了解如何 处理误报。

有关 API 模糊测试配置选项的详细信息，请参阅 可用 CI/CD 变量。

GraphQL Schema

{{< history >}}

• 对 GraphQL Schema 的支持在极狐GitLab 15.4 中引入。

{{< /history >}}

GraphQL 是一种用于 API 的查询语言，是 REST API 的替代方案。API 模糊测试支持多种方式测试 GraphQL 端点：

• 使用 GraphQL Schema 进行测试。在极狐GitLab 15.4 中引入。
• 使用 GraphQL 查询的录制（HAR）进行测试。
• 使用包含 GraphQL 查询的 Postman Collection 进行测试。

本节记录了如何使用 GraphQL schema 进行测试。API 模糊测试中的 GraphQL schema 支持能够从支持自省的端点查询 schema。默认情况下启用自省以允许 GraphiQL 等工具正常工作。

使用 GraphQL 端点 URL 进行 API 模糊测试扫描

API 模糊测试中的 GraphQL 支持能够从 GraphQL 端点查询 schema。

{{< alert type=”note” >}}

GraphQL 端点必须支持自省查询才能使此方法正常工作。

{{< /alert >}}

要配置 API 模糊测试以使用提供有关目标 API 的 GraphQL 端点 URL 进行测试：

1. 包含 API-Fuzzing.gitlab-ci.yml 模板到您的 .gitlab-ci.yml 文件中。

2. 提供 GraphQL 端点路径，例如 /api/graphql。通过添加 FUZZAPI_GRAPHQL 变量来指定路径。

3. 目标 API 实例的基本 URL 也是必需的。通过使用 FUZZAPI_TARGET_URL 变量或 environment_url.txt 文件来提供它。

   在项目根目录中添加 URL 到 environment_url.txt 文件非常适合在动态环境中进行测试。有关更多信息，请参阅我们文档中的 动态环境解决方案 部分。

使用 GraphQL 端点 URL 的完整示例配置：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

apifuzzer_fuzz:
  variables:
    FUZZAPI_GRAPHQL: /api/graphql
    FUZZAPI_TARGET_URL: http://test-deployment/

此示例是 API 模糊测试的最小配置。从这里您可以：

• 运行您的第一个扫描。
• 添加认证。
• 了解如何 处理误报。

使用 GraphQL Schema 文件进行 API 模糊测试

API 模糊测试可以使用 GraphQL schema 文件来理解和测试已禁用自省的 GraphQL 端点。要使用 GraphQL schema 文件，它必须是自省 JSON 格式。

要配置 API 模糊测试以使用提供有关目标 API 的 GraphQL schema 文件进行测试：

1. 包含 API-Fuzzing.gitlab-ci.yml 模板到您的 .gitlab-ci.yml 文件中。

2. 提供 GraphQL 端点路径，例如 /api/graphql。通过添加 FUZZAPI_GRAPHQL 变量来指定路径。

3. 提供 GraphQL schema 文件的位置。您可以将位置作为文件路径或 URL 提供。通过添加 FUZZAPI_GRAPHQL_SCHEMA 变量来指定位置。

4. 目标 API 实例的基本 URL 也是必需的。通过使用 FUZZAPI_TARGET_URL 变量或 environment_url.txt 文件来提供它。

   在项目根目录中添加 URL 到 environment_url.txt 文件非常适合在动态环境中进行测试。有关更多信息，请参阅我们文档中的 动态环境解决方案 部分。

使用 GraphQL schema 文件的完整示例配置：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

apifuzzer_fuzz:
  variables:
    FUZZAPI_GRAPHQL: /api/graphql
    FUZZAPI_GRAPHQL_SCHEMA: test-api-graphql.schema
    FUZZAPI_TARGET_URL: http://test-deployment/

使用 GraphQL schema 文件 URL 的完整示例配置：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

apifuzzer_fuzz:
  variables:
    FUZZAPI_GRAPHQL: /api/graphql
    FUZZAPI_GRAPHQL_SCHEMA: http://file-store/files/test-api-graphql.schema
    FUZZAPI_TARGET_URL: http://test-deployment/

此示例是 API 模糊测试的最小配置。从这里您可以：

• 运行您的第一个扫描。
• 添加认证。
• 了解如何 处理误报。

Postman Collection

Postman API 客户端是开发人员和测试人员用来调用各种类型 API 的流行工具。API 定义可以导出为 Postman Collection 文件用于 API 模糊测试。导出时，请确保选择支持的 Postman Collection 版本：v2.0 或 v2.1。

与极狐GitLab API 模糊测试器一起使用时，Postman Collections 必须包含要测试的 Web API 定义的有效数据。API 模糊测试器会提取所有 API 定义并使用它们进行测试。

{{< alert type=”warning” >}}

Postman Collection 文件可能包含敏感信息，如认证令牌、API 密钥和会话 Cookie。我们建议您在将 Postman Collection 文件添加到仓库之前，先审查其内容。

{{< /alert >}}

使用 Postman Collection 文件配置 Web API 模糊测试

要配置使用 Postman Collection 文件的 API 模糊测试：

1. 将 fuzz 阶段添加到您的 .gitlab-ci.yml 文件中。

2. 包含 API-Fuzzing.gitlab-ci.yml 模板到您的 .gitlab-ci.yml 文件中。

3. 通过将 FUZZAPI_PROFILE CI/CD 变量添加到您的 .gitlab-ci.yml 文件来提供配置文件。配置文件指定运行的测试数量。将 Quick-10 替换为您选择的配置文件。有关详细信息，请参阅 API 模糊测试配置文件。

   variables:
     FUZZAPI_PROFILE: Quick-10
   

4. 提供 Postman Collection 规范的位置。您可以将规范作为文件或 URL 提供。通过添加 FUZZAPI_POSTMAN_COLLECTION 变量来指定位置。

5. 提供目标 API 实例的基本 URL。使用 FUZZAPI_TARGET_URL 变量或 environment_url.txt 文件。

   在项目根目录中添加 URL 到 environment_url.txt 文件非常适合在动态环境中进行测试。要在极狐GitLab CI/CD 流水线期间动态创建的应用程序上运行 API 模糊测试，请让应用程序在 environment_url.txt 文件中保留其域。API 模糊测试会自动解析该文件以找到其扫描目标。您可以在 我们的 Auto DevOps CI YAML 示例中看到此示例。

使用 Postman Collection 文件的示例 .gitlab-ci.yml 文件：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json
  FUZZAPI_TARGET_URL: http://test-deployment/

这是 API 模糊测试的最小配置。从这里您可以：

• 运行您的第一个扫描。
• 添加认证。
• 了解如何 处理误报。

有关 API 模糊测试配置选项的详细信息，请参阅 可用 CI/CD 变量。

Postman 变量

{{< history >}}

• 对 Postman Environment 文件格式的支持在极狐GitLab 15.1 中引入。
• 对多个变量文件的支持在极狐GitLab 15.1 中引入。
• 对 Postman 变量范围的支持：Global 和 Environment 在极狐GitLab 15.1 中引入。

{{< /history >}}

Postman 客户端中的变量

Postman 允许开发人员定义占位符，可以在请求的不同部分中使用。这些占位符称为变量，如使用变量中所述。您可以使用变量在请求和脚本中存储和重用值。例如，您可以编辑集合以将变量添加到文档中：

或者，您可以在环境中添加变量：

然后，您可以在 URL、标头和其他部分中使用变量：

Postman 已从一个具有良好用户体验的基本客户端工具发展为一个更复杂的生态系统，允许使用脚本测试 API，创建触发二次请求的复杂集合，并设置变量。并不是 Postman 生态系统中的每个功能都支持。例如，脚本不支持。Postman 支持的主要重点是摄取由 Postman 客户端使用的 Postman Collection 定义及其相关变量，这些变量是在工作空间、环境和集合中定义的。

Postman 允许在不同范围内创建变量。每个范围在 Postman 工具中具有不同级别的可见性。例如，您可以在 全局环境 范围中创建一个变量，该范围在每个操作定义和工作空间中都可以看到。您还可以在特定 环境 范围内创建一个变量，该范围仅在选择使用该特定环境时可见并使用。在 Postman 生态系统中并不是所有范围总是可用的，例如，您可以在 Postman 客户端中创建请求，这些请求没有 本地 范围，但测试脚本有。

Postman 中的变量范围可能是一个令人畏惧的话题，并不是每个人都熟悉它。我们强烈建议您在继续操作之前阅读 Postman 文档中的变量范围。

如上所述，有不同的变量范围，每个范围都有其目的，可以用于为您的 Postman 文档提供更多灵活性。关于如何计算变量值有一个重要说明，根据 Postman 文档：

如果同一名称的变量在两个不同范围内声明，则使用最窄范围的变量中存储的值。例如，如果有一个名为 username 的全局变量和一个名为 username 的本地变量，则在请求运行时使用本地值。

以下是 Postman 客户端和 API 模糊测试支持的变量范围的摘要：

• 全局环境（Global）范围 是整个工作空间中可用的特殊预定义环境。我们还可以将 全局环境 范围称为 全局 范围。Postman 客户端允许将全局环境导出到 JSON 文件中，可以与 API 模糊测试一起使用。
• 环境范围 是用户在 Postman 客户端中创建的变量命名组。Postman 客户端支持单个活动环境以及全局环境。在活动用户创建的环境中定义的变量优先于在全局环境中定义的变量。Postman 客户端允许导出您的环境为 JSON 文件，可以与 API 模糊测试一起使用。
• 集合范围 是在给定集合中声明的变量组。集合变量在声明它们的集合及其嵌套请求或集合中可用。在集合范围中定义的变量优先于 全局环境 范围和 环境 范围。Postman 客户端可以将一个或多个集合导出为 JSON 文件，此 JSON 文件包含所选集合、请求和集合变量。
• API 模糊测试范围 是由 API 模糊测试添加的新范围，允许用户提供额外的变量，或覆盖在其他支持范围中定义的变量。此范围不支持 Postman。API 模糊测试范围 变量通过 自定义 JSON 文件格式 提供。
  • 覆盖在环境或集合中定义的值
  • 从脚本中定义变量
  • 定义来自不支持的 数据范围 的单行数据
• 数据范围 是一个变量组，其名称和值来自 JSON 或 CSV 文件。像 Newman 或 Postman Collection Runner 的 Postman 集合运行器执行集合中的请求，与 JSON 或 CSV 文件中的条目一样多。这些变量的一个良好用例是使用 Postman 中的脚本自动化测试。API 模糊测试不支持从 CSV 或 JSON 文件中读取数据。
• 本地范围 是在 Postman 脚本中定义的变量。API 模糊测试不支持 Postman 脚本，并且不支持脚本中定义的变量。您仍然可以通过在支持的范围中定义它们，或我们的自定义 JSON 格式提供脚本定义变量的值。

并不是所有范围都支持 API 模糊测试，并且脚本中定义的变量不支持。下表按从最宽范围到最窄范围排序。

有关如何定义变量和导出不同范围中的变量的详细信息，请参阅：

• 定义集合变量
• 定义环境变量
• 定义全局变量

从 Postman 客户端导出

Postman 客户端允许导出不同的文件格式，例如，您可以导出 Postman 集合或 Postman 环境。导出的环境可以是全局环境（始终可用），也可以是您先前创建的任何自定义环境。当您导出 Postman Collection 时，它可能仅包含 集合 和 本地 范围的变量声明；环境 范围的变量不包括在内。

要获取 环境 范围变量的声明，您必须导出给定环境。每个导出的文件仅包含所选环境中的变量。

有关导出不同支持范围中的变量的更多详细信息，请参阅：

• 导出集合
• 导出环境
• 下载全局环境

API 模糊测试范围，自定义 JSON 文件格式

我们的自定义 JSON 文件格式是一个 JSON 对象，其中每个对象属性表示变量名称，属性值表示变量值。此文件可以使用您喜欢的文本编辑器创建，也可以由流水线中的早期作业生成。

此示例在 API 模糊测试范围中定义了两个变量 base_url 和 token：

{
  "base_url": "http://127.0.0.1/",
  "token": "Token 84816165151"
}

在 API 模糊测试中使用范围

范围：全局、环境、集合 和 极狐GitLab API 模糊测试 在极狐GitLab 15.1 及更高版本中支持。极狐GitLab 15.0 及更早版本，仅支持 集合 和 极狐GitLab API 模糊测试 范围。

下表提供了一个将范围文件/URL 映射到 API 模糊测试配置变量的快速参考：

Postman Collection 文档自动包含任何 集合 范围的变量。Postman Collection 使用配置变量 FUZZAPI_POSTMAN_COLLECTION 提供。此变量可以设置为单个导出的 Postman 集合。

其他范围的变量通过 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 配置变量提供。配置变量在极狐GitLab 15.1 及更高版本中支持以逗号 (,) 分隔的文件列表。极狐GitLab 15.0 及更早版本，仅支持单个文件。提供文件的顺序并不重要，因为文件提供所需的范围信息。

配置变量 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 可以设置为：

• 导出的全局环境
• 导出的环境
• API 模糊测试自定义 JSON 格式

未定义的 Postman 变量

API 模糊测试引擎可能没有找到 Postman 集合文件中使用的所有变量引用。有些情况下可能是：

• 您正在使用 数据 或 本地 范围变量，并且如前所述，这些范围不支持 API 模糊测试。因此，假设这些变量的值没有通过 API 模糊测试范围 提供，那么 数据 和 本地 范围变量的值是未定义的。
• 变量名称输入错误，名称与定义的变量不匹配。
• Postman 客户端支持一个新的动态变量，而 API 模糊测试不支持。

如果可能，API 模糊测试在处理未定义变量时会遵循 Postman 客户端的相同行为。变量引用的文本保持不变，没有文本替换。相同的行为也适用于任何不支持的动态变量。

例如，如果 Postman Collection 中的请求定义引用变量 {{full_url}} 并且未找到变量，则其值保持不变，为 {{full_url}}。

动态 Postman 变量

除了用户可以在各种范围级别定义的变量之外，Postman 还有一组预定义的变量称为 动态 变量。动态 变量已经定义，其名称以美元符号 ($) 为前缀，例如 $guid。动态 变量可以像任何其他变量一样使用，在 Postman 客户端中，它们在请求/集合运行期间产生随机值。

API 模糊测试和 Postman 之间的一个重要区别是，API 模糊测试为每个使用的相同动态变量返回相同的值。这与 Postman 客户端行为不同，后者在每次使用相同动态变量时返回随机值。换句话说，API 模糊测试对动态变量使用静态值，而 Postman 使用随机值。

在扫描过程中支持的动态变量如下：

示例：全局范围

在此示例中，全局范围被导出为 global-scope.json，并通过 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 配置变量提供给 API 模糊测试。

以下是使用 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 的示例：

stages:
     - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

示例：环境范围

在此示例中，环境范围被导出为 environment-scope.json，并通过 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 配置变量提供给 API 模糊测试。

以下是使用 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 的示例：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: environment-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

示例：集合范围

集合范围变量被包含在导出的 Postman Collection 文件中，并通过 FUZZAPI_POSTMAN_COLLECTION 配置变量提供。

以下是使用 FUZZAPI_POSTMAN_COLLECTION 的示例：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: variable-collection-dictionary.json

示例：API 模糊测试范围

API 模糊测试范围用于两个主要目的，定义不被 API 模糊测试支持的数据和本地范围变量，以及更改在其他范围中定义的现有变量的值。API 模糊测试范围通过 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 配置变量提供。

以下是使用 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 的示例：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: api-fuzzing-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

文件 api-fuzzing-scope.json 使用我们的自定义 JSON 文件格式。该 JSON 是一个具有属性键值对的对象。键是变量的名称，值是变量的值。例如：

{
  "base_url": "http://127.0.0.1/",
  "token": "Token 84816165151"
}

示例：多个范围

在此示例中，配置了全局范围、环境范围和集合范围。第一步是导出我们的各种范围。

• 导出全局范围为 global-scope.json
• 导出环境范围为 environment-scope.json
• 导出包含集合范围的 Postman Collection 为 postman-collection.json

Postman Collection 使用 FUZZAPI_POSTMAN_COLLECTION 变量提供，而其他范围则通过 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 提供。API 模糊测试可以识别提供的文件匹配哪个范围，使用每个文件中提供的数据。

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

示例：更改变量值

使用导出的范围时，通常需要更改变量的值以用于 API 模糊测试。例如，集合范围的变量可能包含一个名为 api_version 的变量，值为 v2，而您的测试需要 v1 的值。与其修改导出的集合来更改值，不如使用 API 模糊测试范围来更改其值。这是因为 API 模糊测试范围优先于所有其他范围。

集合范围变量被包含在导出的 Postman Collection 文件中，并通过 FUZZAPI_POSTMAN_COLLECTION 配置变量提供。

API 模糊测试范围通过 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 配置变量提供，但首先我们必须创建文件。文件 api-fuzzing-scope.json 使用我们的自定义 JSON 文件格式。该 JSON 是一个具有属性键值对的对象。键是变量的名称，值是变量的值。例如：

{
  "api_version": "v1"
}

我们的 CI 定义：

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: api-fuzzing-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

示例：使用多个范围更改变量值

使用导出的范围时，通常需要更改变量的值以用于 API 模糊测试。例如，环境范围可能包含一个名为 api_version 的变量，值为 v2，而您的测试需要 v1 的值。与其修改导出的文件来更改值，不如使用 API 模糊测试范围。这是因为 API 模糊测试范围优先于所有其他范围。

在此示例中，配置了全局范围、环境范围、集合范围和 API 模糊测试范围。第一步是导出和创建我们的各种范围。

• 导出全局范围为 global-scope.json
• 导出环境范围为 environment-scope.json
• 导出包含集合范围的 Postman Collection 为 postman-collection.json

API 模糊测试范围通过创建使用我们的自定义 JSON 文件格式的文件 api-fuzzing-scope.json 来使用。该 JSON 是一个具有属性键值对的对象。键是变量的名称，值是变量的值。例如：

{
  "api_version": "v1"
}

Postman Collection 使用 FUZZAPI_POSTMAN_COLLECTION 变量提供，而其他范围则通过 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 提供。API 模糊测试可以识别提供的文件匹配哪个范围，使用每个文件中提供的数据。

stages:
  - fuzz

include:
  - template: Security/API-Fuzzing.gitlab-ci.yml

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json,api-fuzzing-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

运行您的第一个扫描

正确配置后，CI/CD 流水线包含 fuzz 阶段和 apifuzzer_fuzz 或 apifuzzer_fuzz_dnd 作业。作业仅在提供无效配置时失败。在典型操作期间，即使在模糊测试期间识别出故障，作业也总是成功。

故障显示在 安全 流水线选项卡中，带有套件名称。当针对存储库的默认分支进行测试时，模糊测试故障也会显示在安全和合规的漏洞报告中。

为了防止报告过多故障，API 模糊测试扫描器限制其报告的故障数量。

查看模糊测试故障

API 模糊测试分析器生成一个 JSON 报告，该报告被收集并用于将故障填充到极狐GitLab 漏洞屏幕中。模糊测试故障显示为严重性未知的漏洞。

API 模糊测试发现的故障需要人工调查，并且与特定漏洞类型无关。需要调查以确定它们是否是安全问题，以及是否应该修复。有关配置更改的信息，请参见处理误报，您可以进行这些更改以限制报告的误报数量。

查看 API 模糊测试漏洞的详细信息

API 模糊测试检测到的故障发生在实时 Web 应用程序中，需要人工调查以确定它们是否是漏洞。模糊测试故障作为严重性未知的漏洞包含。为了便于调查模糊测试故障，提供了有关发送和接收的 HTTP 消息的详细信息，以及所做修改的描述。

按照以下步骤查看模糊测试故障的详细信息：

1. 您可以在项目或合并请求中查看故障：

   • 在项目中，转到项目的 安全 > 漏洞报告 页面。此页面仅显示默认分支中的所有漏洞。
   • 在合并请求中，转到合并请求的 安全 部分并选择 展开 按钮。API 模糊测试故障在一个标记为 API 模糊测试检测到 N 个潜在漏洞 的部分中可用。选择标题以显示故障详细信息。

2. 选择故障的标题以显示故障的详细信息。下表描述了这些详细信息。

   字段	描述
   描述	包括修改内容的故障描述。
   项目	检测到漏洞的命名空间和项目。
   方法	用于检测漏洞的 HTTP 方法。
   URL	检测到漏洞的 URL。
   请求	导致故障的 HTTP 请求。
   未修改的响应	来自未修改请求的响应。这是典型工作响应的样子。
   实际响应	从模糊请求接收到的响应。
   证据	我们如何确定发生故障。
   标识符	用于发现此故障的模糊测试检查。
   严重性	发现的严重性始终为未知。
   扫描器类型	用于执行测试的扫描器。

安全仪表板

模糊测试故障显示为严重性未知的漏洞。安全仪表板是概览您群组、项目和流水线中所有安全漏洞的好地方。有关更多信息，请参阅安全仪表板文档。

与漏洞互动

模糊测试故障显示为严重性未知的漏洞。一旦发现故障，您可以与其互动。阅读更多关于如何解决漏洞。

处理误报

误报可以通过两种方式处理：

• 关闭产生误报的检查。这可以防止检查生成任何故障。示例检查包括 JSON 模糊测试检查和表单主体模糊测试检查。
• 模糊测试检查有几种方法可以检测何时识别出故障，称为 断言。断言也可以关闭和配置。例如，API 模糊测试器默认使用 HTTP 状态码来帮助识别何时出现真正的问题。如果 API 在测试期间返回 500 错误，则会创建故障。这并不总是需要的，因为某些框架经常返回 500 错误。

关闭检查

检查执行特定类型的测试，可以为特定配置文件打开和关闭。默认配置文件定义了几个配置文件，您可以使用这些配置文件。配置文件定义在配置文件中的 Profiles 部分中列出了在扫描期间活动的所有检查。要关闭特定检查，请将其从配置文件定义中删除。配置文件在配置文件中的 Profiles 部分定义。

配置文件定义示例：

Profiles:
  - Name: Quick-10
    DefaultProfile: Quick
    Routes:
      - Route: *Route0
        Checks:
          - Name: FormBodyFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: GeneralFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: JsonFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: XmlFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true

要关闭 General Fuzzing 检查，您可以删除以下行：

- Name: GeneralFuzzingCheck
  Configuration:
    FuzzingCount: 10
    UnicodeFuzzing: true

这会导致以下 YAML：

- Name: Quick-10
  DefaultProfile: Quick
  Routes:
    - Route: *Route0
      Checks:
        - Name: FormBodyFuzzingCheck
          Configuration:
            FuzzingCount: 10
            UnicodeFuzzing: true
        - Name: JsonFuzzingCheck
          Configuration:
            FuzzingCount: 10
            UnicodeFuzzing: true
        - Name: XmlFuzzingCheck
          Configuration:
            FuzzingCount: 10
            UnicodeFuzzing: true

关闭检查的断言

断言检测检查产生的测试中的故障。许多检查支持多个断言，例如日志分析、响应分析和状态码。当发现故障时，提供使用的断言。要识别默认打开哪些断言，请参阅配置文件中的检查默认配置。该部分称为 Checks。

此示例显示了 FormBody 模糊测试检查：

Checks:
  - Name: FormBodyFuzzingCheck
    Configuration:
      FuzzingCount: 30
      UnicodeFuzzing: true
    Assertions:
      - Name: LogAnalysisAssertion
      - Name: ResponseAnalysisAssertion
      - Name: StatusCodeAssertion

在这里可以看到默认打开了三个断言。误报的常见来源是 StatusCodeAssertion。要关闭它，请在 Profiles 部分中修改其配置。此示例仅提供其他两个断言（LogAnalysisAssertion，ResponseAnalysisAssertion）。这可以防止 FormBodyFuzzingCheck 使用 StatusCodeAssertion：

Profiles:
  - Name: Quick-10
    DefaultProfile: Quick
    Routes:
      - Route: *Route0
        Checks:
          - Name: FormBodyFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
            Assertions:
              - Name: LogAnalysisAssertion
              - Name: ResponseAnalysisAssertion
          - Name: GeneralFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: JsonFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: XmlInjectionCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true