REST API を使用した OpenAPI 定義による DAST スキャンの構成

概要

このセクションでは、REST API を使用して、OpenAPI 定義を使用した動的アプリケーション・セキュリティ・テスト (DAST) スキャンを構成する方法について説明します。

この方法は、ファイル・ベース (JSON、YAML、YML) および URL ベースの OpenAPI 定義の両方をサポートし、API スキャンの認証および追加パラメーターを構成するための新しいサポートを追加します。

以下の 2 ステップのプロセスに従います。
  • ステップ 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 ジョブが必要です。パフォーマンスの問題を回避するために、「標準スキャン (Regular scan)」テンプレートを使用することをお勧めします。以下のいずれかの API を使用して、DASTConfig ジョブを作成できます。
    • POST/jobs/{templateId}/dastconfig/createjob
    • POST/jobs/createjobBasedOnTemplateFile
    • POST/jobs
  • DASTConfig ジョブの jobId が必要です。これは、GET /folders/{folderId}/jobs API エンドポイントを使用して取得できます。
  • API リクエスト認証用の有効な asc_xsrf_token が必要です。これは、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 (整数、必須): 構成を適用する DASTConfig ジョブのパス・パラメーター。

リクエスト本文パラメーター (JSON):

  • openApiFileLocation (文字列、必須): 標準化された OpenAPI ドキュメント (.json、.yaml、.yml) を指す一般公開されている URI、またはファイル・ベースの構成の場合は .../openapi/specification/process API によって返されたファイル・パスを指定します。
  • baseUrl (文字列、必須): OpenAPI 記述内のすべての API エンドポイントに共通するパス接頭辞を定義するルート URL を指定します。
  • additionalDomains (文字列、オプション): テスト対象のその他のドメインをコンマ区切りの値として指定します。
  • authorization (オブジェクト、オプション): API 認証用のキーと値のペアを指定します。これらの値は DAST 構成ジョブで更新され、認証された API リクエストに使用されます。 
    { "key": "string", "value": "string" }
  • parameters (配列[オブジェクト]、オプション): DAST 構成ジョブに設定する追加パラメーターのリストを指定します。.../openapi/specification/process API を使用して、追加パラメーターを取得できます。 
    
              [
              {
              "path": "string",
              "name": "string",
              "location": "string",
              "value": "string"
              }
              ]

リクエスト本文の例 (JSON):


          {
          "openApiFileLocation": "string",
          "baseUrl": "string",
          "additionalDomains": "string",
          "authorization": {
          "key": "string",
          "value": "string"
          },
          "parameters": [
          {
          "path": "string",
          "name": "string",
          "location": "string",
          "value": "string"
          }
          ]
          }
注:
構成に URL ではなくローカルの JSON または YAML 記述ファイルを追加する場合、仕様ファイルをテンプレートに含めることができないため、SCANT (テンプレート) ファイルとしてエクスポートすることはできません。仕様ファイルを削除するか、SCAN ファイルとして保存する必要があります。

成功レスポンス (200 OK):

  • 成功すると、API は HTTP ステータス・コード 200 OK を返します。

エラー・レスポンス・クラス (モデル):


          ErrorMessage {
          errorMessage (string)
          }

その他のエラー・コードについては、「レスポンス・メッセージ」を参照してください。