使用 REST API 配置具有 OpenAPI 定义的 DAST 扫描

概述

本节解释了如何使用REST API通过OpenAPI定义来配置动态应用安全测试（DAST）扫描。您可以通过提供一个公开可访问的URL，或者直接上传一个JSON、YAML或YML格式的OpenAPI规范文件来提供这些定义。这种基于API的方法为您的API安全测试工作流程提供自动化，直接在AppScan Enterprise中进行，取代了以前通常涉及AppScan Standard的手动配置步骤。本主题涵盖了专用于基于OpenAPI的扫描配置的两个API端点。
注：
  • 这些API专门用于DASTConfig作业，不能用于Content-Scan作业。
  • 如果一个DASTConfig作业已经有一个OpenAPI配置（来自URL或文件），使用这些API将替换现有的配置。

OpenAPI配置的API端点

  • POST /jobs/{jobId}/dastconfig/openapi/url/add – 向DASTConfig作业添加一个公共OpenAPI URL。
  • POST /jobs/{jobId}/dastconfig/openapi/add – 将 OpenAPI 文件上传到 DASTConfig 作业。

先决条件

  • 您将需要一个现有的DASTConfig作业。您可以使用以下任何现有的API创建DASTConfig作业：
    • POST/工作/{templateId}/dastconfig/创建工作
    • 根据模板文件创建工作
    • POST/工作
  • DASTConfig工作的jobId是必需的。这可以通过使用 GET /folders/{folderId}/jobs API 端点来检索。
  • 进行API请求认证需要一个有效的asc_xsrf_token，可以从POST /login API端点获取。此令牌应作为请求头发送。
  • 我们建议使用“常规扫描”模板进行DASTConfig作业，以避免任何性能问题。

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

目的：此API端点允许您在AppScan Enterprise中配置现有的DASTConfig作业，以使用通过公开可访问的URL提供的OpenAPI定义。

HTTP 方法和端点： POST /jobs/{jobId}/dastconfig/openapi/url/add

路径参数：

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

请求主体参数（JSON）： 请求必须包含一个具有以下参数的JSON主体：

  • openApiUrl（字符串，必需）：指向 OpenAPI 规范文档的公开可访问 URL（例如，http://example.com/openapi.json）。
  • baseUrl（字符串，必需）：在 OpenAPI 文档中定义的所有 API 端点的根 URL 前缀（例如，https://demo.testfire.net/api/）。
  • additionalDomains（字符串，可选）：一个以逗号分隔的其他域名列表，除了包含在baseUrl中的域名之外，还包括在扫描范围内（例如，api.example.org, static.example.com）。
注：
  • 确保您的 OpenAPI 文档正确指定扫描 API 所需的任何身份验证，因为 AppScan Enterprise 将依赖于安全要求的定义。
  • 配置 API 认证（如有需要）。根据您的规范文件，通过登录管理配置身份验证（记录登录或使用自动登录）以确保更好的扫描覆盖，涵盖大多数端点并避免请求失败。
  • 配置API密钥认证不被AppScan Enterprise支持。

响应：

  • 成功时，API 返回 HTTP 状态码 200 OK。
  • 要了解错误详情，请参阅API的Swagger文档。

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

目的：此API端点允许您将OpenAPI规范文件直接上传到AppScan Enterprise中的现有DASTConfig作业。

HTTP 方法和端点： POST /jobs/{jobId}/dastconfig/openapi/add

路径参数：

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

请求参数（multipart/form-data）： 此 API 期望一个包含以下部分的 multipart/form-data 请求：

  • openAPIDescriptionFile（文件，必需）：OpenAPI 规范文件。
    • 支持的格式：.json、.yaml 或 .yml。
    • 最大文件大小：90 MB。
  • baseUrl（字符串，必需）：OpenAPI 文件中定义的所有 API 端点的根 URL 前缀（例如，https://demo.testfire.net/api/）。 （可能以此名称作为表单字段发送）。
  • additionalDomains（字符串，可选）：一个以逗号分隔的其他域名列表，除了包含在baseUrl中的域名之外，还包括在扫描范围内（例如，api.example.org, static.example.com）。 （可能作为具有此名称的表单字段发送）。
注：
  • 确认 API 的 Swagger 文档中 baseUrl 和 additionalDomains 的确切表单字段名称是否需要。
  • 上传的 OpenAPI 文件应定义任何必要的 API 安全方案以进行身份验证。
  • 配置 API 认证（如果需要）。根据您的规范文件，通过登录管理配置身份验证（记录登录或使用自动登录），以确保更好的扫描覆盖，涵盖大多数端点并避免请求失败。
  • 在AppScan Enterprise中不支持配置API密钥认证。
  • 如果您在配置中添加本地 JSON 或 YAML 描述文件而不是 URL，则无法将其导出为 SCANT（模板）文件，因为规范文件无法包含在模板中。您必须删除规范文件或将其保存为SCAN文件。

响应：

  • 成功时，API 返回 HTTP 状态码 200 OK。
  • 有关错误详情，请参阅API的Swagger文档。