使用 REST API 配置具有 OpenAPI 定義的 DAST 掃描

概觀

此部分說明如何使用 REST API 透過 OpenAPI 定義來配置動態應用安全測試（DAST）掃描。您可以通過提供一個公開可訪問的URL，或者直接上傳一個JSON、YAML或YML格式的OpenAPI規範文件來提供這些定義。這種以API為驅動的方法直接在AppScan Enterprise中為您的API安全測試工作流程提供自動化，取代了以前通常涉及AppScan Standard的手動配置步驟。此主題涵蓋了專門用於基於OpenAPI的掃描配置的兩個API端點。
註：
  • 這些 API 專門用於 DASTConfig 工作，不能用於 Content-Scan 工作。
  • 如果一個 DASTConfig 工作已經有 OpenAPI 配置（來自 URL 或文件），使用這些 API 將會替換現有的配置。

用於 OpenAPI 配置的 API 端點

  • POST /jobs/{jobId}/dastconfig/openapi/url/add – 將公共 OpenAPI URL 添加到 DASTConfig 工作中。
  • POST /jobs/{jobId}/dastconfig/openapi/add – 將 OpenAPI 文件上傳到 DASTConfig 工作。

必備項目

  • 您將需要一個現有的 DASTConfig 工作。您可以使用以下任何現有的 API 來創建 DASTConfig 作業：
    • POST/jobs/{templateId}/dastconfig/createjob
    • POST/工作/根據模板文件創建工作
    • POST/工作
  • DASTConfig 工作的 jobId 是必需的。這可以通過使用 GET /folders/{folderId}/jobs API 端點來檢索。
  • 進行 API 請求驗證需要有效的 asc_xsrf_token，可以從 POST /login API 端點獲取。這個令牌應該作為請求標頭發送。
  • 我們建議使用「Regular scan」模板來進行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（String，必需）：指向 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（String，可選）：除了包含在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 文檔。