启用分析器

你可以通过以下方式指定要扫描的API：

• OpenAPI v2或v3规范
• GraphQL架构
• HTTP存档（HAR）
• Postman集合 v2.0 或 v2.1

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）并不总是可取的。
例如，如果目标应用程序无论请求内容类型如何都执行相同的代码，则完成测试会话的时间会更长，并且可能会根据目标应用程序报告与请求正文相关的重复漏洞。

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

alternatively，变量APISEC_OPENAPI_MEDIA_TYPES用于提供将被测试的媒体类型列表。提供多个媒体类型会导致测试时间更长，因为会对选定的每个媒体类型执行测试。当环境变量APISEC_OPENAPI_MEDIA_TYPES设置为媒体类型列表时，创建请求时仅包含列出的媒体类型。

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

环境变量APISEC_OPENAPI_ALL_MEDIA_TYPES和APISEC_OPENAPI_MEDIA_TYPES允许你决定如何处理媒体类型。这些设置互斥。如果两者都启用，API安全测试会报告错误。

使用OpenAPI规范配置API安全测试

若要通过OpenAPI规范配置API安全测试扫描，请执行以下操作：

1. 在您的 .gitlab-ci.yml 文件中包含（include） API-Security.gitlab-ci.yml 模板。

2. 配置文件 定义了多个带有不同启用检查的测试配置文件。我们建议您从 Quick 配置文件开始。使用此配置文件进行测试速度更快，便于验证配置。通过向 .gitlab-ci.yml 文件添加 APISEC_PROFILE CI/CD 变量来指定该配置文件。

3. 提供OpenAPI规范的位置（作为文件或URL）。通过添加 APISEC_OPENAPI 变量来指定位置。

4. 目标API实例的base URL也是必需的。可通过 APISEC_TARGET_URL 变量或 environment_url.txt 文件提供。

   在项目根目录的 environment_url.txt 文件中添加URL非常适合在动态环境中测试。若要对GitLab CI/CD管道期间动态创建的应用运行API安全测试，让应用将其URL保存在 environment_url.txt 文件中。API安全测试会自动解析该文件以找到扫描目标。您可以查看我们的Auto DevOps CI YAML示例了解这一点。

使用OpenAPI规范的完整配置示例如下：

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_OPENAPI: test-api-specification.json
  APISEC_TARGET_URL: http://test-deployment/

这是API安全测试的最小化配置。从此处您可以：

• 运行首次扫描。
• 添加身份验证。
• 了解如何处理误报。

HTTP存档（HAR）

HTTP存档格式（HAR） 是一种用于记录HTTP事务的归档文件格式。当与GitLab API安全测试扫描仪配合使用时，HAR文件必须包含调用Web API进行测试的记录。API安全测试扫描仪会提取所有请求并利用它们执行测试。

您可以使用多种工具生成HAR文件：

• Insomnia Core：API客户端
• Chrome：浏览器
• Firefox：浏览器
• Fiddler：Web调试代理
• GitLab HAR Recorder：命令行工具

使用HAR文件的API安全测试扫描

若要配置API安全测试以使用提供待测目标API信息的HAR文件：

1. 在你的 .gitlab-ci.yml 文件中包含 API-Security.gitlab-ci.yml 模板。
   （参考：包含模板）

2. 配置文件中定义了多个带有不同启用检查的测试配置文件。我们建议从 Quick 配置文件开始。
   使用此配置文件进行测试速度更快，便于更轻松地验证配置。

   通过向 .gitlab-ci.yml 文件添加 APISEC_PROFILE CI/CD 变量来提供该配置文件。

3. 提供 HAR 文件的位置。你可以以文件路径或 URL 的形式提供位置。
   通过添加 APISEC_HAR 变量指定位置。

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

   在项目根目录下的 environment_url.txt 文件中添加URL，非常适合在动态环境中测试。
   若要在GitLab CI/CD管道期间动态创建的应用上运行API安全测试，需让应用将其URL保存在 environment_url.txt 文件中。
   API安全测试会自动解析该文件以找到扫描目标。你可在我们的 Auto DevOps CI YAML 示例 中查看相关用法。

完整的示例配置如下：

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_HAR: test-api-recording.har
  APISEC_TARGET_URL: http://test-deployment/

此示例是API安全测试的最小化配置。在此基础上你可：

• 运行首次扫描
• 添加认证
• 学习如何处理误报

GraphQL 架构

GraphQL 是用于API的查询语言，也是REST API的替代方案。
API安全测试支持以下几种方式测试GraphQL端点：

• 使用GraphQL架构进行测试。（于GitLab 15.4版本中引入）
• 使用GraphQL查询的录制（HAR）。
• 使用包含GraphQL查询的Postman集合。

本节介绍如何使用GraphQL架构进行测试。
API安全测试中的GraphQL架构支持可从支持自省的端点查询架构。
自省默认启用，以便GraphiQL等工具能正常工作。
有关如何启用自省的详细信息，请参阅你的GraphQL框架文档。

使用GraphQL端点URL进行API安全测试扫描

API安全测试中的GraphQL支持可通过GraphQL端点获取架构信息。

若要配置API安全测试以使用提供待测目标API信息的GraphQL端点URL：

1. 在你的 .gitlab-ci.yml 文件中包含 API-Security.gitlab-ci.yml 模板。
   （参考：包含模板）

2. 提供GraphQL端点的路径（例如 /api/graphql）。
   通过添加 APISEC_GRAPHQL 变量指定位置。

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

   在项目根目录下的 environment_url.txt 文件中添加URL，非常适合在动态环境中测试。
   更多信息请参阅文档中动态环境解决方案章节。

完整的示例配置如下：

stages:
  - dast

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

api_security:
  variables:
    APISEC_GRAPHQL: /api/graphql
    APISEC_TARGET_URL: http://test-deployment/

此示例是API安全测试的最小化配置。在此基础上你可：

• 运行首次扫描
• 添加认证
• 学习如何处理误报

使用 GraphQL 模式文件的 API 安全测试扫描

API 安全测试可以使用 GraphQL 模式文件来理解和测试禁用了内省功能的 GraphQL 端点。若要使用 GraphQL 模式文件，它必须采用内省 JSON 格式。可通过在线第三方工具将 GraphQL 模式转换为内省 JSON 格式：https://transform.tools/graphql-to-introspection-json。

若要配置 API 安全测试以使用提供待测目标 API 信息的 GraphQL 模式文件，请执行以下操作：

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

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

3. 提供 GraphQL 模式文件的位置。您可以将位置设置为文件路径或 URL。通过添加 APISEC_GRAPHQL_SCHEMA 变量指定该位置。

4. 还需提供目标 API 实例的基础 URL。可通过 APISEC_TARGET_URL 变量或 environment_url.txt 文件提供。

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

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

stages:
  - dast

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

api_security:
  variables:
    APISEC_GRAPHQL: /api/graphql
    APISEC_GRAPHQL_SCHEMA: test-api-graphql.schema
    APISEC_TARGET_URL: http://test-deployment/

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

stages:
  - dast

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

api_security:
  variables:
    APISEC_GRAPHQL: /api/graphql
    APISEC_GRAPHQL_SCHEMA: http://file-store/files/test-api-graphql.schema
    APISEC_TARGET_URL: http://test-deployment/

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

• 运行首次扫描。
• 添加身份验证。
• 了解如何 处理误报。

Postman 集合

Postman API 客户端 是开发人员和测试人员用来调用各种类型 API 的流行工具。API 定义可导出为 Postman 集合文件，以便用于 API 安全测试。导出时，请务必选择受支持的 Postman 集合版本：v2.0 或 v2.1。

当与 GitLab API 安全测试扫描器配合使用时，Postman 集合必须包含带有有效数据的待测 Web API 定义。API 安全测试扫描器会提取所有 API 定义并利用它们执行测试。

使用Postman集合文件进行API安全测试扫描

要配置API安全测试以使用提供待测目标API信息的Postman集合文件：

1. 包含 API-Security.gitlab-ci.yml 模板。

2. 配置文件 定义了多个带有不同检查项的测试配置文件。我们建议您从 Quick 配置文件开始。使用此配置文件的测试完成速度更快，便于更轻松地验证配置。

   通过向 .gitlab-ci.yml 文件添加 APISEC_PROFILE CI/CD 变量来提供该配置文件。

3. 提供Postman集合文件的位置（作为文件或URL）。通过添加 APISEC_POSTMAN_COLLECTION 变量来指定位置。

4. 目标API实例的 baseURL 也需要提供。可以通过使用 APISEC_TARGET_URL 变量或一个 environment_url.txt 文件来实现。

   在项目根目录下添加一个 environment_url.txt 文件来存储URL，非常适合在动态环境中进行测试。若要在GitLab CI/CD管道中针对动态创建的应用运行API安全测试，请让该应用将其URL持久化到一个 environment_url.txt 文件中。API安全测试会自动解析该文件以找到其扫描目标。您可以查看我们的Auto DevOps CI YAML中的示例。

使用Postman集合文件的完整示例配置：

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection_serviceA.json
  APISEC_TARGET_URL: http://test-deployment/

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

• 运行您的第一次扫描。
• 添加身份验证。
• 了解如何处理误报。

Postman变量

Postman客户端中的变量

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

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

之后你可以在URL、头部等部分使用这些变量：

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

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

Postman中的作用域可能是一个令人望而生畏的话题，并非所有人都熟悉它。我们强烈建议你在继续之前阅读Postman文档中的变量作用域。

如前所述，存在不同的变量作用域，每个作用域都有其用途，可用于为你的Postman文档提供更多灵活性。根据Postman文档，有关如何计算变量值的有一个重要说明：

以下是Postman客户端和API安全测试支持的变量作用域摘要：

• 全局环境（全局）作用域是一种特殊的预定义环境，在整个工作区中都可用。我们也可以将全局环境作用域称为全局作用域。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 和 _local 作用域变量的声明；_environment 作用域变量不被包含在内。

若要获取 _environment 作用域变量的声明，你必须同时导出对应的环境。每个导出文件仅包含来自所选环境的变量。

有关在不同支持的作用域中导出变量的更多详情，请参阅：

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

API 安全测试范围，自定义 JSON 文件格式

我们的自定义 JSON 文件格式是一个 JSON 对象，其中每个对象属性代表变量名，属性值代表变量值。该文件可以使用你喜欢的文本编辑器创建，也可以由管道中的前序作业生成。

此示例在 API 安全测试范围内定义了两个变量 base_url 和 token：

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

在 API 安全测试中使用作用域

作用域：_global_、_environment_、_collection_ 和 _GitLab API 安全测试_ 在 GitLab 15.1 及更高版本 中受支持。GitLab 15.0 及更早版本仅支持 _collection_ 和 _GitLab API 安全测试_ 作用域。

下表提供了将作用域文件/URL 映射到 API 安全测试配置变量的快速参考：

Postman 集合文档会自动包含任何 _collection_ 作用域变量。Postman 集合通过配置变量 APISEC_POSTMAN_COLLECTION 提供。该变量可设置为单个导出的 Postman 集合。

其他作用域的变量通过 APISEC_POSTMAN_COLLECTION_VARIABLES 配置变量提供。该配置变量在 GitLab 15.1 及更高版本 中支持以逗号（,）分隔的文件列表。GitLab 15.0 及更早版本仅支持单个文件。所提供文件的顺序并不重要，因为文件会提供所需的作用域信息。

配置变量 APISEC_POSTMAN_COLLECTION_VARIABLES 可设置为：

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

未定义的 Postman 变量

API 安全测试引擎有可能无法找到你的 Postman 集合文件使用的所有变量引用。一些情况可能是：

• 你使用了 _data_ 或 _local_ 作用域变量，而如前所述，这些作用域不受 API 安全测试支持。因此，假设这些变量的值未通过API 安全测试范围提供，则 _data_ 和 _local_ 作用域变量的值将是未定义的。
• 变量名输入有误，且名称与已定义变量不匹配。
• Postman 客户端支持新的动态变量，但 API 安全测试不支持。

在可能的情况下，API 安全测试遵循与 Postman 客户端相同的处理未定义变量的行为。变量引用的文本保持不变，不会进行文本替换。对于任何不受支持的动态变量，也适用相同的行为。

例如，如果 Postman 集合中的请求定义引用了变量 {{full_url}} 且该变量未被找到，则会保持原样，值为 {{full_url}}。

动态Postman变量

除用户可在不同作用域级别定义的变量外，Postman 还有一组预定义的变量，称为_动态_变量。_动态_变量 已预先定义，其名称以美元符号（$）为前缀，例如 $guid。_动态_变量可像其他变量一样使用，在 Postman 客户端中，它们会在请求/集合运行期间生成随机值。

API 安全测试与 Postman 之间存在一个重要差异：对于同一动态变量的每次使用，API 安全测试会返回相同值。这不同于 Postman 客户端的行为——后者在每次使用相同动态变量时会返回随机值。换言之，API 安全测试对动态变量使用静态值，而 Postman 使用随机值。

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

示例：全局范围

在这个示例中，全局范围从Postman客户端导出，作为global-scope.json提供，并通过APISEC_POSTMAN_COLLECTION_VARIABLES配置变量提供给API安全测试。

以下是使用APISEC_POSTMAN_COLLECTION_VARIABLES的示例：

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: global-scope.json
  APISEC_TARGET_URL: http://test-deployment/

示例：环境范围

在这个示例中，环境范围从Postman客户端导出，作为environment-scope.json提供，并通过APISEC_POSTMAN_COLLECTION_VARIABLES配置变量提供给API安全测试。

以下是使用APISEC_POSTMAN_COLLECTION_VARIABLES的示例：

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: environment-scope.json
  APISEC_TARGET_URL: http://test-deployment/

示例：集合范围

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

以下是使用APISEC_POSTMAN_COLLECTION的示例：

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_TARGET_URL: http://test-deployment/

示例：API安全测试范围

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

以下是使用APISEC_POSTMAN_COLLECTION_VARIABLES的示例：

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: dast-api-scope.json
  APISEC_TARGET_URL: http://test-deployment/

文件dast-api-scope.json使用了我们的自定义JSON文件格式。这个JSON是一个对象，其中键值对表示属性。键是变量的名称，值是变量的值。例如：

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

示例：多范围

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

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

Postman集合通过APISEC_POSTMAN_COLLECTION变量提供，而其他范围则通过APISEC_POSTMAN_COLLECTION_VARIABLES提供。API安全测试可以通过每个文件中提供的数据识别所提供文件匹配的范围。

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json
  APISEC_TARGET_URL: http://test-deployment/

示例：更改变量值

在使用导出的作用域时，经常需要对变量的值进行修改以用于API安全测试。例如，一个集合作用域变量可能包含名为 api_version 的变量，其值为 v2，而你的测试需要值为 v1。无需修改导出的集合来改变该值，而是可以使用API安全测试作用域来更改其值。这是因为API安全测试作用域优先于所有其他作用域。

集合作用域变量会包含在导出的Postman Collection文件中，并通过 APISEC_POSTMAN_COLLECTION 配置变量提供。

API安全测试作用域通过 APISEC_POSTMAN_COLLECTION_VARIABLES 配置变量提供，但首先我们必须创建该文件。 文件 dast-api-scope.json 使用我们的自定义JSON文件格式。此JSON是一个带有属性键值对的对象。键是变量的名称，值是变量的值。例如：

{
  "api_version": "v1"
}

我们的CI定义：

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: dast-api-scope.json
  APISEC_TARGET_URL: http://test-deployment/

示例：使用多个作用域更改变量值

在使用导出的作用域时，经常需要对变量的值进行修改以用于API安全测试。例如，一个环境作用域可能包含名为 api_version 的变量，其值为 v2，而你的测试需要值为 v1。无需修改导出的文件来改变该值，而是可以使用API安全测试作用域。这是因为API安全测试作用域优先于所有其他作用域。

在此示例中，配置了全局作用域、环境作用域、集合作用域和API安全测试作用域。第一步是导出并创建我们的各种作用域。

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

通过创建文件 dast-api-scope.json 来使用API安全测试作用域，该文件采用我们的自定义JSON文件格式。此JSON是一个带有属性键值对的对象。键是变量的名称，值是变量的值。例如：

{
  "api_version": "v1"
}

Postman Collection通过 APISEC_POSTMAN_COLLECTION 变量提供，而其他作用域则通过 APISEC_POSTMAN_COLLECTION_VARIABLES 提供。API安全测试可以通过每个文件中提供的数据识别提供的文件匹配的作用域类型。

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json,dast-api-scope.json
  APISEC_TARGET_URL: http://test-deployment/

运行首次扫描

当配置正确时，CI/CD管道包含一个 dast 阶段和一个 dast_api 任务。仅当提供无效配置时任务才会失败。在典型操作期间，即使测试中发现漏洞，任务也会始终成功。

漏洞会显示在Security（安全）流水线选项卡中，并附带套件名称。当针对仓库的默认分支进行测试时，API安全测试漏洞也会显示在“安全与合规”的漏洞报告中。

为防止报告过多漏洞，API安全测试扫描仪会限制每个操作报告的漏洞数量。

查看API安全测试漏洞

API安全测试分析器生成一份JSON报告，该报告会被收集并用于填充GitLab漏洞页面的漏洞信息。

有关如何进行配置更改以减少误报数量的信息，请参阅处理误报。

查看API安全测试漏洞的详细信息

按照以下步骤查看漏洞的详细信息：

1. 你可以在项目中或合并请求中查看漏洞：

   • 在项目中，前往项目的 Secure > Vulnerability report 页面。此页面仅显示默认分支的所有漏洞。
   • 在合并请求中，进入合并请求的 Security 部分，选择 Expand 按钮。API安全测试漏洞位于标记为 DAST检测到N个潜在漏洞 的部分中。选择标题以显示漏洞详情。

2. 选择漏洞标题以显示详情。下表描述了这些详情。

安全仪表板

安全仪表板是了解您组、项目和管道中所有安全漏洞概览的好地方。有关更多信息，请参阅安全仪表板文档。

与漏洞交互

一旦发现漏洞，您可以与之交互。阅读更多关于如何解决漏洞的信息。

处理误报

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

• 忽略该漏洞。
• 部分检查有多个检测漏洞的方法，称为_Assertions_。断言也可关闭并配置。例如，API安全测试扫描器默认通过HTTP状态码识别真实问题——若测试中API返回500错误，会触发漏洞。但这并非理想情况（因部分框架常返回500错误）。
• 关闭产生误报的检查项。这将阻止检查项生成漏洞。示例检查项包括SQL注入检查、JSON劫持检查。

关闭检查

检查执行特定类型的测试，可为特定配置文件开启或关闭。提供的配置文件定义了多个可用的配置文件。配置文件中的配置定义列出了扫描期间处于活动状态的检查。要关闭特定检查，需将其从配置文件的配置定义中移除。配置在配置文件的Profiles部分定义。

示例配置定义：

Profiles:
  - Name: Quick
    DefaultProfile: Empty
    Routes:
      - Route: *Route0
        Checks:
          - Name: ApplicationInformationCheck
          - Name: CleartextAuthenticationCheck
          - Name: FrameworkDebugModeCheck
          - Name: HtmlInjectionCheck
          - Name: InsecureHttpMethodsCheck
          - Name: JsonHijackingCheck
          - Name: JsonInjectionCheck
          - Name: SensitiveInformationCheck
          - Name: SessionCookieCheck
          - Name: SqlInjectionCheck
          - Name: TokenCheck
          - Name: XmlInjectionCheck

要关闭JSON劫持检查（Json Hijacking Check），可移除以下行：

          - Name: JsonHijackingCheck

结果如下所示：

- Name: Quick
  DefaultProfile: Empty
  Routes:
    - Route: *Route0
      Checks:
        - Name: ApplicationInformationCheck
        - Name: CleartextAuthenticationCheck
        - Name: FrameworkDebugModeCheck
        - Name: HtmlInjectionCheck
        - Name: InsecureHttpMethodsCheck
        - Name: JsonInjectionCheck
        - Name: SensitiveInformationCheck
        - Name: SessionCookieCheck
        - Name: SqlInjectionCheck
        - Name: TokenCheck
        - Name: XmlInjectionCheck

为检查关闭断言

断言用于检测检查产生的测试中的漏洞。许多检查支持多种断言，例如日志分析、响应分析和状态码。当发现漏洞时，会提供所使用的断言。若要确定哪些断言默认开启，请参阅配置文件中的检查默认配置，该部分名为Checks。

此示例展示了SQL注入检查：

- Name: SqlInjectionCheck
  Configuration:
    UserInjections: []
  Assertions:
    - Name: LogAnalysisAssertion
    - Name: ResponseAnalysisAssertion
    - Name: StatusCodeAssertion

此处可见三个断言默认开启。常见的误报来源是StatusCodeAssertion。要关闭它，需在Profiles部分修改其配置。此示例仅保留了其他两个断言（LogAnalysisAssertion和ResponseAnalysisAssertion），这可防止SqlInjectionCheck使用StatusCodeAssertion：

Profiles:
  - Name: Quick
    DefaultProfile: Empty
    Routes:
      - Route: *Route0
        Checks:
          - Name: ApplicationInformationCheck
          - Name: CleartextAuthenticationCheck
          - Name: FrameworkDebugModeCheck
          - Name: HtmlInjectionCheck
          - Name: InsecureHttpMethodsCheck
          - Name: JsonHijackingCheck
          - Name: JsonInjectionCheck
          - Name: SensitiveInformationCheck
          - Name: SessionCookieCheck
          - Name: SqlInjectionCheck
            Assertions:
              - Name: LogAnalysisAssertion
              - Name: ResponseAnalysisAssertion
          - Name: TokenCheck
          - Name: XmlInjectionCheck