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

概要

このセクションでは、REST APIを使用してOpenAPI定義を用いたDynamic Application Security Testing (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): The location (URL or path) of the generated OpenAPI file,parameters (array[OpenApiAdditionalParameters], optional): A list of API parameters extracted from the OpenAPI specification}OpenApiAdditionalParameters {path (string, optional):API エンドポイントパス（例: /login, /account/{accountNo}),name (string, optional):The name of the parameter (e.g., username, password, accountNo),location (string, optional):The location of the parameter (e.g., body, path, query)}

エラーコードについては、<uicontrol>Response Messages</uicontrol>を参照してください。

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（Object、任意）: API 認証用のキー値ペアを提供します。これらの値は DAST 設定ジョブで更新され、認証された API リクエストに使用されます。
    { "key": "string", "value": "string" }
  • parameters (Array[Object], Optional): DAST設定ジョブに設定する追加パラメータのリストを指定します。 .../openapi/specification/process API を使用することで、追加のパラメータを取得することができます。 
    [{"path": "string","name": "string","location": "string","value": "string"}]

Request body example (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)
}

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