使用 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 配置，您必須在呼叫 .../configure 之前使用此 API 上傳檔案。
對於基於 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 (Object, Optional): 提供用於 API 授權的鍵值對。這些值在 DAST 配置作業中更新，並用於已驗證的 API 請求。
```
{ "key": "string", "value": "string" }
```
參數 (Array[Object], 可選): 提供額外參數清單以在 DAST 配置作業中設定。您可以透過使用 .../openapi/specification/process API 來擷取額外的參數。
```
[{
"path": "string",

"name": "string",

"位置": "字串",

"值": "string"
}]
```

請求主體範例 (JSON)：

{
"openApiFileLocation": "string",

"baseUrl": "string",

"additionalDomains": "string",

"authorization": {

"鍵": "字串",

"值": "string"
},
"parameters": [
{
"路徑": "字串",

"name": "string",

"location": "string",

"value": "string"
}]}

註：

如果您在配置中新增本地 JSON 或 YAML 描述檔案而非 URL，您將無法將其匯出為 SCANT（範本）檔案，因為規格檔案無法包含在範本中。您必須移除規格檔案或將其儲存為 SCAN 檔案。

成功回應 (200 OK)：

成功時，API 會傳回 HTTP 狀態碼 200 OK。

錯誤回應類別（模型）：

ErrorMessage {errorMessage (string)}

請參閱「回應訊息」以了解其他錯誤代碼。