使用 REST API 通过 OpenAPI 定义配置 DAST 扫描

概述

本节说明如何使用 REST API 通过 OpenAPI 定义配置动态应用程序安全测试 (DAST) 扫描。

此方法支持基于文件的（JSON、YAML、YML）和基于 URL 的 OpenAPI 定义，并为您的 API 扫描配置授权和附加参数增加了新的支持。

您将遵循两步流程：
  • 步骤 1：使用 POST /jobs/{jobId}/dastconfig/openapi/specification/process 上传 OpenAPI 文件或处理 OpenAPI URL。此 API 从定义中提取并返回文件路径和可用参数列表。
  • 步骤 2：使用 POST /jobs/{jobId}/dastconfig/openapi/configure 应用配置。您传递文件/URL 的位置以及 baseUrl 和任何可选的授权或参数值。
注：
  • 您只能将这些 API 用于 DASTConfig 作业。您不能将它们与 Content-Scan 作业一起使用。
  • 如果 DASTConfig 作业已经有 OpenAPI 配置，使用 .../configure API 会替换现有配置。

基于 OpenAPI 配置的 API 端点

  • POST /jobs/{jobId}/dastconfig/openapi/specification/process – 上传 OpenAPI 描述文件或处理 URL 以供稍后在配置和参数检索中使用。
  • POST /jobs/{jobId}/dastconfig/openapi/configure – 使用 OpenAPI 定义创建或更新 DAST 配置。

先决条件

  • 您需要一个现有的 DASTConfig 作业。我们建议您使用"常规扫描"模板以避免性能问题。您可以使用以下任一 API 创建 DASTConfig 作业：
    • POST/jobs/{templateId}/dastconfig/createjob
    • POST/jobs/createjobBasedOnTemplateFile
    • POST/jobs
  • 您需要 DASTConfig 作业的 jobId。您可以通过使用 GET /folders/{folderId}/jobs API 端点获取此信息。
  • 您需要一个有效的 asc_xsrf_token 用于 API 请求身份验证。您可以从 POST /login API 端点获取此令牌。您必须将此令牌作为请求标头发送。

API 参考：POST /jobs/{jobId}/dastconfig/openapi/specification/process

用途：使用此 API 上传 OpenAPI 描述文件或 OpenAPI URL，然后您可以通过 .../configure API 引用它。此 API 还会提取并返回上传文件或提供的 URL 中可用的附加参数列表。

HTTPS 方法和端点： POST /jobs/{jobId}/dastconfig/openapi/specification/process

路径参数：

  • jobId（整数，必需）：DASTConfig 作业的唯一标识符。

请求参数（multipart/form-data）：

  • openApiDescriptionFile（文件，可选）：.json、.yaml 或 .yml 格式的 OpenAPI 规范文件。
  • openApiUrl（字符串，可选）：指向 .json、.yaml 或 .yml 格式 OpenAPI 文档的公开可访问 URL。
注：
  • 对于基于文件的 OpenAPI 配置，您必须使用此 API 上传文件，然后才能调用 .../configure。
  • 对于基于URL的配置，使用此API是可选的。您可以使用它在配置之前预览和检索URL中的可用参数。

成功响应（200 OK）：

  • API在成功时返回200 OK，包含文件路径（如果已上传）或URL（如果已提供），以及从OpenAPI规范中提取的参数。

响应类（模型）： 

OpenApiProcessResponse {openApiFileLocation (string): 生成的OpenAPI文件的位置（URL或路径），parameters (array[OpenApiAdditionalParameters], optional): 从OpenAPI规范中提取的API参数列表}OpenApiAdditionalParameters {path (string, optional):API端点路径（例如，/login, /account/{accountNo}），name (string, optional):参数名称（例如，username, password, accountNo），location (string, optional):参数位置（例如，body, path, query）}

有关错误代码，请参阅响应消息。

API参考：POST /jobs/{jobId}/dastconfig/openapi/configure

目的：使用此API为OpenAPI配置DAST作业。您不能将此配置添加到Content-Scan作业。如果存在现有配置，此API调用将替换它。

HTTPS方法和端点： POST /jobs/{jobId}/dastconfig/openapi/configure

路径参数：

  • jobId (Integer, Required): 您要应用配置的DASTConfig作业的路径参数。

请求正文参数（JSON）：

  • openApiFileLocation (String, Required): 提供一个指向标准化OpenAPI文档（.json、.yaml、.yml）的公开可访问URI，或者提供由.../openapi/specification/process API返回的用于基于文件配置的文件路径。
  • baseUrl（字符串，必需）：指定根 URL，该 URL 定义 OpenAPI 描述中所有 API 端点的通用路径前缀。
  • additionalDomains (String, Optional): 指定要测试的其他域，用逗号分隔的值。
  • authorization（对象，可选）：为API授权提供键值对。 这些值在DAST配置作业中进行更新，用于已认证的API请求。 
    
{ "key": "string", "value": "string" }
  • parameters (Array[Object], Optional): 提供一个附加参数列表，用于在 DAST 配置作业中设置。 您可以通过使用 .../openapi/specification/process API 来检索其他参数。 
    [{
"path": "string",

"name": "string",

"location": "string",

"值": "字符串"
}]

请求正文示例 (JSON): 

{
"openApiFileLocation": "string",

"baseUrl": "字符串",

"additionalDomains": "字符串",

"authorization": {

"键": "字符串",

"值": "字符串"
},
"参数": [
{
"path": "string",

"name": "string",

"location": "string",

"值": "字符串"
}]}
注：
如果您向配置中添加本地 JSON 或 YAML 描述文件而非 URL，则无法将其导出为 SCANT（模板）文件，因为规范文件无法包含在模板中。您必须删除规范文件或将其保存为 SCAN 文件。

成功响应（200 OK）：

  • 成功时，API 返回 HTTP 状态码 200 OK。

错误响应类（模型）： 

ErrorMessage {errorMessage (string)}

有关其他错误代码，请参阅响应消息。