アナライザーを有効にする

スキャンするAPIを次のように指定できます:

• OpenAPI v2またはv3仕様
• GraphQLのスキーマ
• HTTP Archive (HAR)
• Postman Collection v2.0またはv2.1

OpenAPI仕様

The OpenAPI仕様 (旧Swagger仕様) は、REST APIのAPI記述フォーマットです。このセクションでは、APIセキュリティテストのスキャンを構成して、OpenAPI仕様を使用してターゲットAPIのテストに関する情報を提供する方法を説明します。OpenAPI仕様は、ファイルシステムリソースまたはURLとして提供されます。JSONとYAMLの両方のOpenAPI形式がサポートされています。

APIセキュリティテストでは、OpenAPIドキュメントを使用してリクエストボディを生成します。リクエストボディが必要な場合、ボディの生成は次のボディタイプに制限されます:

• application/x-www-form-urlencoded
• multipart/form-data
• application/json
• application/xml

OpenAPIとメディアタイプ

メディアタイプ（旧MIMEタイプ）は、ファイル形式および送信される形式コンテンツの識別子です。OpenAPIドキュメントを使用すると、特定の操作が異なるメディアタイプを受け入れるように指定でき、したがって、特定のリクエストで異なるファイルコンテンツを使用してデータを送信できます。例えば、PUT /user操作は、XML (メディアタイプapplication/xml) またはJSON (メディアタイプapplication/json) 形式のいずれかでユーザーデータを受け入れることができます。OpenAPI 2.xでは、メディアタイプをグローバルまたは操作ごとに指定でき、OpenAPI 3.xでは、操作ごとにメディアタイプを指定できます。APIセキュリティテストは、リストされたメディアタイプをチェックし、サポートされている各メディアタイプに対してサンプルデータを生成しようとします。

• デフォルトの動作は、使用するサポートされているメディアタイプのいずれかを選択することです。リストから最初にサポートされているメディアタイプが選択されます。この動作は構成可能です。

異なるメディアタイプ（例えば、application/jsonとapplication/xml）を使用して同じ操作（例えば、POST /user）をテストすることは、常に望ましいとは限りません。例えば、ターゲットアプリケーションがリクエストコンテンツタイプに関わらず同じコードを実行する場合、テストセッションの完了に時間がかかり、ターゲットアプリによってはリクエストボディに関連する重複した脆弱性を報告する可能性があります。

環境変数APISEC_OPENAPI_ALL_MEDIA_TYPESを使用すると、特定の操作に対するリクエストを生成する際に、サポートされているすべてのメディアタイプを使用するかどうかを指定できます。環境変数APISEC_OPENAPI_ALL_MEDIA_TYPESが任意の値に設定されている場合、APIセキュリティテストは、特定の操作で単一のメディアタイプの代わりにサポートされているすべてのメディアタイプに対してリクエストを生成しようとします。これにより、提供された各メディアタイプに対してテストが繰り返されるため、テストに時間がかかります。

あるいは、変数APISEC_OPENAPI_MEDIA_TYPESを使用して、それぞれテストされるメディアタイプのリストを提供します。複数のメディアタイプを提供すると、選択された各メディアタイプに対してテストが実行されるため、テストに時間がかかります。環境変数APISEC_OPENAPI_MEDIA_TYPESがメディアタイプのリストに設定されている場合、リクエストの作成時にはリストされたメディアタイプのみが含まれます。

APISEC_OPENAPI_MEDIA_TYPES内の複数のメディアタイプはコロン (:) で区切られます。例えば、リクエストの生成をメディアタイプapplication/x-www-form-urlencodedとmultipart/form-dataに制限するには、環境変数APISEC_OPENAPI_MEDIA_TYPESをapplication/x-www-form-urlencoded:multipart/form-dataに設定します。このリストでサポートされているメディアタイプのみがリクエストの作成時に含まれ、サポートされていないメディアタイプは常にスキップされます。メディアタイプのテキストには、異なるセクションが含まれる場合があります。例えば、application/vnd.api+json; charset=UTF-8はtype "/" [tree "."] subtype ["+" suffix]* [";" parameter]の複合です。リクエスト生成時にメディアタイプのフィルタリングを実行する際、パラメータは考慮されません。

環境変数APISEC_OPENAPI_ALL_MEDIA_TYPESとAPISEC_OPENAPI_MEDIA_TYPESを使用すると、メディアタイプの処理方法を決定できます。これらの設定は相互に排他的です。両方が有効な場合、APIセキュリティテストはエラーをレポートします。

OpenAPI仕様を使用してAPIセキュリティテストを構成する

OpenAPI仕様を使用してAPIセキュリティテストのスキャンを構成するには:

1. ご自身の.gitlab-ci.ymlファイルにAPI-Security.gitlab-ci.ymlテンプレートをインクルードします。

2. The 設定ファイルには、異なるチェックが有効化された複数のテストプロファイルが定義されています。Quickプロファイルから始めます。このプロファイルでのテストは迅速に完了し、設定の検証を容易にします。.gitlab-ci.ymlファイルにAPISEC_PROFILE CI/CD変数を追加してプロファイルを提供します。

3. OpenAPI仕様の場所をファイルまたはURLとして提供します。APISEC_OPENAPI変数を追加して場所を指定します。

4. ターゲットAPIインスタンスのベースURLも必要です。APISEC_TARGET_URL変数またはenvironment_url.txtファイルを使用して提供します。

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加することは、動的環境でのテストに非常に役立ちます。GitLab CI/CDパイプライン中に動的に作成されたアプリに対してAPIセキュリティテストを実行するには、アプリのURLをenvironment_url.txtファイルに保持させます。APIセキュリティテストは、そのファイルを自動的に解析して、スキャンターゲットを見つけます。この例は、GitLabのAuto DevOps CI YAMLで確認できます。

OpenAPI仕様を使用する完全な設定例:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_OPENAPI: test-api-specification.json
  APISEC_TARGET_URL: http://test-deployment/

これは、APIセキュリティテストの最小設定です。ここから、次のことができます:

• 最初のスキャンを実行します。
• 認証を追加します。
• 誤検出の処理について学びます。

HTTP Archive (HAR)

The HTTP Archive format (HAR)は、HTTPトランザクションをログに記録するためのアーカイブファイル形式です。GitLab APIセキュリティテストスキャナーで使用する場合、HARファイルにはテスト対象のWeb APIを呼び出す記録が含まれている必要があります。APIセキュリティテストスキャナーは、すべてのリクエストを抽出して、テストを実行するために使用します。

HARファイルを生成するために、さまざまなツールを使用できます:

• Insomnia Core: APIクライアント
• Chrome: ブラウザ
• Firefox: ブラウザ
• Fiddler: Webデバッグプロキシ
• GitLab HAR Recorder: コマンドライン

HARファイルを使用したAPIセキュリティテストのスキャン

ターゲットAPIのテストに関する情報を提供するHARファイルを使用するようにAPIセキュリティテストを構成するには:

1. ご自身の.gitlab-ci.ymlファイルにAPI-Security.gitlab-ci.ymlテンプレートをインクルードします。

2. The 設定ファイルには、異なるチェックが有効化された複数のテストプロファイルが定義されています。Quickプロファイルから始めます。このプロファイルでのテストは迅速に完了し、設定の検証を容易にします。

   .gitlab-ci.ymlファイルにAPISEC_PROFILE CI/CD変数を追加してプロファイルを提供します。

3. HARファイルの場所を提供します。場所はパスまたはURLとして提供できます。APISEC_HAR変数を追加して場所を指定します。

4. ターゲットAPIインスタンスのベースURLも必要です。APISEC_TARGET_URL変数またはenvironment_url.txtファイルを使用して提供します。

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加することは、動的環境でのテストに非常に役立ちます。GitLab CI/CDパイプライン中に動的に作成されたアプリに対してAPIセキュリティテストを実行するには、アプリのURLをenvironment_url.txtファイルに保持させます。APIセキュリティテストは、そのファイルを自動的に解析して、スキャンターゲットを見つけます。この例は、GitLabのAuto DevOps CI YAMLで確認できます。

HARファイルを使用する完全な設定例:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_HAR: test-api-recording.har
  APISEC_TARGET_URL: http://test-deployment/

これは、APIセキュリティテストの最小設定です。ここから、次のことができます:

• 最初のスキャンを実行します。
• 認証を追加します。
• 誤検出の処理について学びます。

GraphQLのスキーマ

GraphQLは、ご自身のAPIのクエリ言語であり、REST APIに代わるものです。APIセキュリティテストは、GraphQLエンドポイントを複数の方法でテストすることをサポートします:

• GraphQLのスキーマを使用してテストします。GitLab 15.4で導入されました。
• GraphQLクエリの記録 (HAR) を使用してテストします。
• Postman Collectionに含まれるGraphQLクエリを使用してテストします。

このセクションでは、GraphQLのスキーマを使用してテストする方法をドキュメント化します。APIセキュリティテストにおけるGraphQLのスキーマのサポートは、イントロスペクションをサポートするエンドポイントからスキーマをクエリすることができます。イントロスペクションは、GraphiQLのようなツールが機能するようにデフォルトで有効になっています。イントロスペクションを有効にする方法の詳細については、ご自身のGraphQLフレームワークドキュメントを参照してください。

GraphQLエンドポイントURLを使用したAPIセキュリティテストのスキャン

APIセキュリティテストにおけるGraphQLのサポートは、GraphQLエンドポイントからスキーマをクエリすることができます。

ターゲットAPIのテストに関する情報を提供するGraphQLエンドポイントURLを使用するようにAPIセキュリティテストを構成するには:

1. ご自身の.gitlab-ci.ymlファイルにAPI-Security.gitlab-ci.ymlテンプレートをインクルードします。

2. GraphQLエンドポイントへのパスを提供します（例: /api/graphql）。APISEC_GRAPHQL変数を追加して場所を指定します。

3. ターゲットAPIインスタンスのベースURLも必要です。APISEC_TARGET_URL変数またはenvironment_url.txtファイルを使用して提供します。

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加することは、動的環境でのテストに非常に役立ちます。詳細については、動的環境ソリューションを参照してください。

GraphQLエンドポイントパスを使用する完全な設定例:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

api_security:
  variables:
    APISEC_GRAPHQL: /api/graphql
    APISEC_TARGET_URL: http://test-deployment/

これは、APIセキュリティテストの最小設定です。ここから、次のことができます:

• 最初のスキャンを実行します。
• 認証を追加します。
• 誤検出の処理について学びます。

GraphQLのスキーマファイルを使用したAPIセキュリティテストのスキャン

APIセキュリティテストでは、イントロスペクションが無効になっているGraphQLエンドポイントを理解しテストするために、GraphQLのスキーマファイルを使用できます。GraphQLのスキーマファイルを使用するには、イントロスペクションJSON形式である必要があります。GraphQLのスキーマは、オンラインのサードパーティツール (https://transform.tools/graphql-to-introspection-json) を使用して、イントロスペクションJSON形式に変換できます。

ターゲットAPIのテストに関する情報を提供するGraphQLのスキーマファイルを使用するようにAPIセキュリティテストを構成するには:

1. ご自身の.gitlab-ci.ymlファイルにAPI-Security.gitlab-ci.ymlテンプレートをインクルードします。

2. GraphQLエンドポイントのパスを提供します（例: /api/graphql）。APISEC_GRAPHQL変数を追加してパスを指定します。

3. GraphQLのスキーマファイルの場所を提供します。場所はパスまたはURLとして提供できます。APISEC_GRAPHQL_SCHEMA変数を追加して場所を指定します。

4. ターゲットAPIインスタンスのベースURLも必要です。APISEC_TARGET_URL変数またはenvironment_url.txtファイルを使用して提供します。

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加することは、動的環境でのテストに非常に役立ちます。詳細については、動的環境ソリューションを参照してください。

GraphQLのスキーマファイルを使用する完全な設定例:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

api_security:
  variables:
    APISEC_GRAPHQL: /api/graphql
    APISEC_GRAPHQL_SCHEMA: test-api-graphql.schema
    APISEC_TARGET_URL: http://test-deployment/

GraphQLのスキーマファイルURLを使用する完全な設定例:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

api_security:
  variables:
    APISEC_GRAPHQL: /api/graphql
    APISEC_GRAPHQL_SCHEMA: http://file-store/files/test-api-graphql.schema
    APISEC_TARGET_URL: http://test-deployment/

これは、APIセキュリティテストの最小設定です。ここから、次のことができます:

• 最初のスキャンを実行します。
• 認証を追加します。
• 誤検出の処理について学びます。

Postman Collection

The Postman API Clientは、開発者やテスターがさまざまな種類のAPIを呼び出すために使用する人気のツールです。API定義は、APIセキュリティテストで使用するために、Postman Collectionファイルとしてエクスポートすることができます。エクスポートする際は、サポートされているPostman Collectionのバージョン（v2.0またはv2.1）を選択してください。

GitLab APIセキュリティテストスキャナーで使用する場合、Postman Collectionには、有効なデータでテストするWeb APIの定義が含まれている必要があります。APIセキュリティテストスキャナーは、すべてのAPI定義を抽出し、それらを使用してテストを実行します。

Postman Collectionファイルを使用したAPIセキュリティテストのスキャン

ターゲットAPIのテストに関する情報を提供するPostman Collectionファイルを使用するようにAPIセキュリティテストを構成するには:

1. API-Security.gitlab-ci.ymlテンプレートをインクルードします。

2. The 設定ファイルには、異なるチェックが有効化された複数のテストプロファイルが定義されています。Quickプロファイルから始めます。このプロファイルでのテストは迅速に完了し、設定の検証を容易にします。

   .gitlab-ci.ymlファイルにAPISEC_PROFILE CI/CD変数を追加してプロファイルを提供します。

3. Postman Collectionファイルの場所をファイルまたはURLとして提供します。APISEC_POSTMAN_COLLECTION変数を追加して場所を指定します。

4. ターゲットAPIインスタンスのベースURLも必要です。APISEC_TARGET_URL変数またはenvironment_url.txtファイルを使用して提供します。

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加することは、動的環境でのテストに非常に役立ちます。GitLab CI/CDパイプライン中に動的に作成されたアプリに対してAPIセキュリティテストを実行するには、アプリのURLをenvironment_url.txtファイルに保持させます。APIセキュリティテストは、そのファイルを自動的に解析して、スキャンターゲットを見つけます。この例は、GitLabのAuto DevOps CI YAMLで確認できます。

Postman Collectionを使用する完全な設定例:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection_serviceA.json
  APISEC_TARGET_URL: http://test-deployment/

これは、APIセキュリティテストの最小設定です。ここから、次のことができます:

• 最初のスキャンを実行します。
• 認証を追加します。
• 誤検出の処理について学びます。

Postman変数

Postman Clientの変数

Postmanでは、開発者がリクエストのさまざまな部分で使用できるプレースホルダーを定義できます。これらのプレースホルダーは、変数の使用で説明されているように変数と呼ばれます。変数を使用して、リクエストとスクリプトで値を保存および再利用できます。例えば、Collectionを編集してドキュメントに変数を追加できます:

または、Environmentに変数を追加することもできます:

その後、URL、ヘッダーなどのセクションで変数を使用できます:

Postmanは、優れたUXエクスペリエンスを持つ基本的なクライアントツールから、スクリプトでAPIをテストしたり、二次リクエストをトリガーする複雑なCollectionを作成したり、途中で変数を設定したりできる、より複雑なエコシステムへと成長しました。Postmanエコシステムのすべての機能がサポートされているわけではありません。例えば、スクリプトはサポートされていません。Postmanサポートの主な焦点は、Postman Clientで使用されるPostman Collectionの定義と、ワークスペース、環境、およびCollection自体で定義されている関連変数をインジェストすることです。

Postmanでは、異なるスコープで変数を作成できます。各スコープは、Postmanツールで異なる表示レベルを持ちます。例えば、すべての操作定義とワークスペースから参照できる_グローバル環境_スコープで変数を作成できます。また、特定の_環境_スコープで変数を作成することもできます。これは、特定の環境が使用するために選択された場合にのみ表示され、使用されます。一部のスコープは常に利用できるわけではありません。例えば、PostmanエコシステムではPostman Clientでリクエストを作成できますが、これらのリクエストには_ローカル_スコープはありませんが、テストスクリプトにはあります。

Postmanの変数スコープは、難しいトピックであり、誰もが精通しているわけではありません。先に進む前に、PostmanドキュメントのVariable Scopesをお読みください。

前述のとおり、さまざまな変数スコープがあり、それぞれに目的があり、Postmanドキュメントにさらなる柔軟性をもたらすために使用できます。Postmanドキュメントによると、変数の値がどのように計算されるかについて重要な注意点があります:

以下は、Postman ClientとAPIセキュリティテストによってサポートされている変数スコープの概要です:

• Global Environment (Global) scopeは、ワークスペース全体で利用できる特殊な事前定義済み環境です。_グローバル環境_スコープを_グローバル_スコープと呼ぶこともできます。Postman Clientでは、グローバル環境をJSONファイルにエクスポートでき、これはAPIセキュリティテストで使用できます。
• 環境スコープは、Postman Clientでユーザーが作成した変数の名前付きグループです。Postman Clientは、グローバル環境と共に単一のアクティブな環境をサポートします。アクティブなユーザー作成環境で定義された変数は、グローバル環境で定義された変数よりも優先されます。Postman Clientでは、ご自身の環境をJSONファイルにエクスポートでき、これはAPIセキュリティテストで使用できます。
• Collection scopeは、特定のCollectionで宣言された変数のグループです。Collection変数は、宣言されているCollectionと、ネストされたリクエストまたはCollectionで利用できます。Collectionスコープで定義された変数は、_グローバル環境_スコープおよび_環境_スコープよりも優先されます。Postman Clientは1つまたは複数のCollectionをJSONファイルにエクスポートでき、このJSONファイルには選択されたCollection、リクエスト、およびCollection変数が含まれます。
• API security testing scopeは、APIセキュリティテストによって追加された新しいスコープで、ユーザーが追加の変数を提供したり、他のサポートされているスコープで定義された変数をオーバーライドしたりできるようにします。このスコープはPostmanではサポートされていません。_APIセキュリティテストスコープ_変数は、カスタムJSONファイル形式を使用して提供されます。
  • 環境またはCollectionで定義された値をオーバーライドする
  • スクリプトから変数を定義する
  • サポートされていない_データ_スコープから単一のデータ行を定義する
• Data scopeは、名前と値がJSONまたはCSVファイルから取得される変数のグループです。NewmanやPostman Collection RunnerのようなPostman Collection Runnerは、JSONまたはCSVファイルにエントリがある回数だけ、Collection内のリクエストを実行します。これらの変数の優れたユースケースは、Postmanのスクリプトを使用してテストを自動化することです。APIセキュリティテストは、CSVまたはJSONファイルからのデータ読み取りをnot。
• Local scopeは、Postmanスクリプトで定義される変数です。APIセキュリティテストは、Postmanスクリプト、および拡張してスクリプトで定義された変数をnot。スクリプトで定義された変数の値は、サポートされているいずれかのスコープまたはカスタムJSON形式で定義することで、引き続き提供できます。

すべてのスコープがAPIセキュリティテストでサポートされているわけではなく、スクリプトで定義された変数はサポートされていません。次の表は、最も広いスコープから最も狭いスコープの順に並べられています。

異なるスコープで変数を定義およびエクスポートする方法の詳細については、以下を参照してください:

• Collection変数の定義
• 環境変数の定義
• グローバル変数の定義

Postman Clientからのエクスポート

Postman Clientでは、さまざまなファイル形式をエクスポートできます。例えば、Postman CollectionやPostman Environmentをエクスポートできます。エクスポートされた環境は、グローバル環境（常に利用可能）であることも、以前に作成したカスタム環境であることもできます。Postman Collectionをエクスポートする場合、_Collection_と_ローカル_スコープの変数の宣言のみが含まれる場合があります。 _環境_スコープの変数は含まれません。

_環境_スコープの変数の宣言を取得するには、その時点で特定の環境をエクスポートする必要があります。エクスポートされた各ファイルには、選択された環境の変数のみが含まれます。

異なるサポートされているスコープでの変数のエクスポートの詳細については、以下を参照してください:

• Collectionのエクスポート
• 環境のエクスポート
• グローバル環境のダウンロード

APIセキュリティテストスコープ、カスタムJSONファイル形式

カスタムJSONファイル形式は、各オブジェクトプロパティが変数名を表し、プロパティ値が変数値を表すJSONオブジェクトです。このファイルは、ご自身の好きなテキストエディタを使用して作成することも、パイプライン内の以前のジョブによって生成することもできます。

この例では、APIセキュリティテストスコープで2つの変数base_urlとtokenを定義しています:

{
  "base_url": "http://127.0.0.1/",
  "token": "Token 84816165151"
}

APIセキュリティテストでのスコープの使用

スコープ (グローバル、環境、Collection、および_GitLab APIセキュリティテスト_) は、GitLab 15.1以降でサポートされています。GitLab 15.0以前では、_Collection_と_GitLab APIセキュリティテスト_のスコープのみがサポートされています。

次の表は、スコープファイル/URLをAPIセキュリティテストの設定変数にマッピングするためのクイック参照を提供します:

Postman Collectionドキュメントには、_Collection_スコープの変数が自動的に含まれます。Postman Collectionは、設定変数APISEC_POSTMAN_COLLECTIONを使用して提供されます。この変数は、単一のエクスポートされたPostman Collectionに設定できます。

他のスコープの変数は、APISEC_POSTMAN_COLLECTION_VARIABLES設定変数を介して提供されます。この設定変数は、GitLab 15.1以降でカンマ (,) 区切りのファイルリストをサポートします。GitLab 15.0以前では、単一のファイルのみをサポートしていました。提供されるファイルの順序は重要ではありません。ファイルがスコープ情報を提供するためです。

設定変数APISEC_POSTMAN_COLLECTION_VARIABLESは、以下に設定できます:

• エクスポートされたGlobal environment
• エクスポートされた環境
• API security testingカスタムJSON形式

未定義のPostman変数

APIセキュリティテストエンジンが、ご自身のPostman Collectionファイルが使用しているすべての変数参照を見つけられない可能性があります。いくつかのケースが考えられます:

• ご自身が_データ_スコープまたは_ローカル_スコープの変数を使用しており、前述のとおりこれらのスコープはAPIセキュリティテストでサポートされていません。したがって、これらの変数の値がAPIセキュリティテストスコープを介して提供されていないと仮定すると、_データ_スコープと_ローカル_スコープの変数の値は未定義です。
• 変数名が正しく入力されておらず、定義された変数と一致しません。
• Postman Clientは、APIセキュリティテストでサポートされていない新しい動的変数をサポートしています。

可能な場合、APIセキュリティテストは、未定義の変数を扱う際にPostman Clientと同じ動作に従います。変数参照のテキストは同じままで、テキスト置換は行われません。同じ動作は、サポートされていないすべての動的変数にも適用されます。

例えば、Postman Collection内のリクエスト定義が変数{{full_url}}を参照し、その変数が見つからない場合、値{{full_url}}のまま変更されません。

動的Postman変数

ユーザーがさまざまなスコープレベルで定義できる変数に加えて、Postmanには_動的_変数と呼ばれる事前定義された変数のセットがあります。_動的_変数はすでに定義されており、その名前にはドル記号 ($) がプレフィックスとして付けられています（例: $guid）。_動的_変数は他の変数と同様に使用でき、Postman Clientでは、リクエスト/Collectionの実行中にランダムな値を生成します。

APIセキュリティテストとPostmanの重要な違いは、APIセキュリティテストが同じ動的変数の各使用に対して同じ値を返すことです。これは、同じ動的変数を使用するたびにランダムな値を返すPostman Clientの動作とは異なります。言い換えれば、APIセキュリティテストは動的変数に静的な値を使用し、Postmanはランダムな値を使用します。

スキャンプロセス中にサポートされる動的変数は次のとおりです:

例: グローバルスコープ

この例では、Postman Clientから_グローバル_スコープがエクスポートされ、global-scope.jsonとしてAPIセキュリティテストにAPISEC_POSTMAN_COLLECTION_VARIABLES設定変数を介して提供されます。

APISEC_POSTMAN_COLLECTION_VARIABLESの使用例を以下に示します:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: global-scope.json
  APISEC_TARGET_URL: http://test-deployment/

例: Environment Scope

この例では、Postman Clientから_環境_スコープがエクスポートされ、environment-scope.jsonとしてAPIセキュリティテストにAPISEC_POSTMAN_COLLECTION_VARIABLES設定変数を介して提供されます。

APISEC_POSTMAN_COLLECTION_VARIABLESの使用例を以下に示します:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: environment-scope.json
  APISEC_TARGET_URL: http://test-deployment/

例: Collection Scope

_Collection_スコープの変数は、エクスポートされたPostman Collectionファイルに含まれ、APISEC_POSTMAN_COLLECTION設定変数を介して提供されます。

APISEC_POSTMAN_COLLECTIONの使用例を以下に示します:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_TARGET_URL: http://test-deployment/

例: API security testing scope

APIセキュリティテストスコープは、APIセキュリティテストでサポートされていない_データ_スコープと_ローカル_スコープの変数を定義すること、および別のスコープで定義された既存の変数の値を変更することという2つの主な目的で使用されます。APIセキュリティテストスコープは、APISEC_POSTMAN_COLLECTION_VARIABLES設定変数を介して提供されます。

APISEC_POSTMAN_COLLECTION_VARIABLESの使用例を以下に示します:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: dast-api-scope.json
  APISEC_TARGET_URL: http://test-deployment/

ファイルdast-api-scope.jsonは、カスタムJSONファイル形式を使用します。このJSONは、プロパティ用のキー/バリューペアを持つオブジェクトです。キーは変数の名前であり、値は変数の値です。例:

{
  "base_url": "http://127.0.0.1/",
  "token": "Token 84816165151"
}

例: 複数のスコープ

この例では、_グローバル_スコープ、_環境_スコープ、および_Collection_スコープが構成されています。最初のステップは、さまざまなスコープをエクスポートすることです。

• _グローバル_スコープをエクスポートしてglobal-scope.jsonとして保存します
• _環境_スコープをエクスポートしてenvironment-scope.jsonとして保存します
• _Collection_スコープを含むPostman Collectionをエクスポートしてpostman-collection.jsonとして保存します

Postman CollectionはAPISEC_POSTMAN_COLLECTION変数を使用して提供され、他のスコープはAPISEC_POSTMAN_COLLECTION_VARIABLESを使用して提供されます。APIセキュリティテストは、各ファイルで提供されたデータを使用して、提供されたファイルがどのスコープに一致するかを識別できます。

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json
  APISEC_TARGET_URL: http://test-deployment/

例: 変数の値の変更

エクスポートされたスコープを使用する場合、APIセキュリティテストで使用するために変数の値を変更する必要があることがよくあります。例えば、_Collection_スコープの変数にv2という値を持つapi_versionという名前の変数が含まれている場合でも、テストにはv1の値が必要です。エクスポートされたCollectionを変更して値を変更する代わりに、APIセキュリティテストスコープを使用してその値を変更できます。これは、_APIセキュリティテスト_スコープが他のすべてのスコープよりも優先されるため機能します。

_Collection_スコープの変数は、エクスポートされたPostman Collectionファイルに含まれ、APISEC_POSTMAN_COLLECTION設定変数を介して提供されます。

APIセキュリティテストスコープは、APISEC_POSTMAN_COLLECTION_VARIABLES設定変数を介して提供されます。ただし、まずファイルを作成します。ファイルdast-api-scope.jsonは、カスタムJSONファイル形式を使用します。このJSONは、プロパティ用のキー/バリューペアを持つオブジェクトです。キーは変数の名前であり、値は変数の値です。例:

{
  "api_version": "v1"
}

CI定義:

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: dast-api-scope.json
  APISEC_TARGET_URL: http://test-deployment/

例: 複数のスコープを持つ変数の値を変更する

エクスポートされたスコープを使用する場合、APIセキュリティテストで使用するために変数の値を変更する必要があることがよくあります。例えば、_環境_スコープにv2という値を持つapi_versionという名前の変数が含まれている場合でも、テストにはv1の値が必要です。エクスポートされたファイルを変更して値を変更する代わりに、APIセキュリティテストスコープを使用できます。これは、_APIセキュリティテスト_スコープが他のすべてのスコープよりも優先されるため機能します。

この例では、_グローバル_スコープ、_環境_スコープ、_Collection_スコープ、および_APIセキュリティテスト_スコープが構成されています。最初のステップは、さまざまなスコープをエクスポートして作成することです。

• _グローバル_スコープをエクスポートしてglobal-scope.jsonとして保存します
• _環境_スコープをエクスポートしてenvironment-scope.jsonとして保存します
• _Collection_スコープを含むPostman Collectionをエクスポートしてpostman-collection.jsonとして保存します

APIセキュリティテストスコープは、カスタムJSONファイル形式を使用してファイルdast-api-scope.jsonを作成することで使用されます。このJSONは、プロパティ用のキー/バリューペアを持つオブジェクトです。キーは変数の名前であり、値は変数の値です。例:

{
  "api_version": "v1"
}

Postman CollectionはAPISEC_POSTMAN_COLLECTION変数を使用して提供され、他のスコープはAPISEC_POSTMAN_COLLECTION_VARIABLESを使用して提供されます。APIセキュリティテストは、各ファイルで提供されたデータを使用して、提供されたファイルがどのスコープに一致するかを識別できます。

stages:
  - dast

include:
  - template: Security/API-Security.gitlab-ci.yml

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json,dast-api-scope.json
  APISEC_TARGET_URL: http://test-deployment/

最初のスキャンの実行

正しく構成されている場合、CI/CDパイプラインにはdastステージとdast_apiジョブが含まれます。ジョブは、無効な設定が提供された場合にのみ失敗します。通常の操作中、テスト中に脆弱性が識別されたとしても、ジョブは常に成功します。

脆弱性は、セキュリティパイプラインタブにスイート名とともに表示されます。リポジトリのデフォルトブランチに対してテストを実行すると、APIセキュリティテストの脆弱性は、セキュリティおよびコンプライアンスの脆弱性レポートにも表示されます。

過剰な数の脆弱性がレポートされるのを防ぐために、APIセキュリティテストスキャナーは、操作ごとにレポートする脆弱性の数を制限します。

APIセキュリティテストの脆弱性を表示する

APIセキュリティテストアナライザーは、収集されてGitLab脆弱性画面に脆弱性を取り込むために使用されるJSONレポートを生成します。

誤検出の処理に関する情報については、誤検出の数を制限するために行うことができる設定変更を参照してください。

APIセキュリティテストの脆弱性の詳細を表示する

脆弱性の詳細を表示するには、次の手順に従います:

1. プロジェクトまたはマージリクエストで脆弱性を表示できます:

   • プロジェクトで、プロジェクトのセキュリティ > 脆弱性レポートページに移動します。このページには、デフォルトブランチからの脆弱性のみが表示されます。
   • マージリクエストで、マージリクエストのセキュリティセクションに移動し、全て展開ボタンを選択します。APIセキュリティテストの脆弱性は、DAST detected N potential vulnerabilitiesとラベル付けされたセクションで利用できます。タイトルを選択して脆弱性の詳細を表示します。

2. 脆弱性のタイトルを選択して詳細を表示します。以下の表にこれらの詳細を示します。

   フィールド	説明
   説明	変更された内容を含む脆弱性の説明。
   プロジェクト	脆弱性が検出されたネームスペースとプロジェクト。
   方法	脆弱性の検出に使用されたHTTPメソッド。
   URL	脆弱性が検出されたURL。
   リクエスト	脆弱性を引き起こしたHTTPリクエスト。
   変更されていないレスポンス	変更されていないリクエストからのレスポンス。典型的な動作中のレスポンスは、変更されていないレスポンスのように見えます。
   実際のレスポンス	テストリクエストから受信したレスポンス。
   証拠	GitLabが脆弱性が発生したと判断した方法。
   識別子	この脆弱性を見つけるために使用されたAPIセキュリティテストチェック。
   重大度	脆弱性の重大度。
   スキャナータイプ	テストの実行に使用されるスキャナー。

セキュリティダッシュボード

セキュリティダッシュボードは、グループ、プロジェクト、パイプライン内のすべての脆弱性の概要を把握するのに適した場所です。詳細については、セキュリティダッシュボードドキュメントを参照してください。

脆弱性との対話

脆弱性が見つかったら、それと対話できます。脆弱性への対処方法の詳細を読み取ります。

誤検出の処理

誤検出は、いくつかの方法で処理できます:

• 脆弱性を無視する。
• 一部のチェックには、脆弱性が識別されたときに検出するいくつかの方法があり、これらは_アサーション_と呼ばれます。アサーションは、オフにして構成することもできます。例えば、APIセキュリティテストスキャナーは、デフォルトでHTTPステータスcodeを使用して、何かが実際の問題であるかどうかを特定するのに役立てます。テスト中にAPIが500エラーを返すと、これは脆弱性を作成します。これは、一部のフレームワークが頻繁に500エラーを返すため、常に望ましいとは限りません。
• 誤検出を生成しているチェックをオフにします。これにより、チェックが脆弱性を生成するのを防ぎます。チェックの例には、SQLインジェクションチェックとJSON Hijackingチェックがあります。

チェックをオフにする

チェックは特定のタイプのテストを実行し、特定の設定プロファイルでオン/オフを切り替えることができます。提供された設定ファイルは、使用できるいくつかのプロファイルを定義しています。設定ファイル内のプロファイル定義には、スキャン中にアクティブなすべてのチェックがリストされています。特定のチェックをオフにするには、設定ファイル内のプロファイル定義から削除します。プロファイルは、設定ファイルのProfilesセクションで定義されています。

プロファイル定義の例:

Profiles:
  - Name: Quick
    DefaultProfile: Empty
    Routes:
      - Route: *Route0
        Checks:
          - Name: ApplicationInformationCheck
          - Name: CleartextAuthenticationCheck
          - Name: FrameworkDebugModeCheck
          - Name: HtmlInjectionCheck
          - Name: InsecureHttpMethodsCheck
          - Name: JsonHijackingCheck
          - Name: JsonInjectionCheck
          - Name: SensitiveInformationCheck
          - Name: SessionCookieCheck
          - Name: SqlInjectionCheck
          - Name: TokenCheck
          - Name: XmlInjectionCheck

JSON Hijacking Checkをオフにするには、これらの行を削除します:

          - Name: JsonHijackingCheck

これにより、次のYAMLになります:

- Name: Quick
  DefaultProfile: Empty
  Routes:
    - Route: *Route0
      Checks:
        - Name: ApplicationInformationCheck
        - Name: CleartextAuthenticationCheck
        - Name: FrameworkDebugModeCheck
        - Name: HtmlInjectionCheck
        - Name: InsecureHttpMethodsCheck
        - Name: JsonInjectionCheck
        - Name: SensitiveInformationCheck
        - Name: SessionCookieCheck
        - Name: SqlInjectionCheck
        - Name: TokenCheck
        - Name: XmlInjectionCheck

チェックのアサーションをオフにする

アサーションは、チェックによって生成されたテスト内の脆弱性を検出します。多くのチェックは、ログ分析、レスポンス分析、ステータスcodeなど、複数のアサーションをサポートしています。脆弱性が見つかると、使用されたアサーションが提供されます。どのAssertationがデフォルトでオンになっているかを識別するには、設定ファイルのChecksデフォルト設定を参照してください。セクションはChecksと呼ばれます。

この例は、SQLインジェクションチェックを示しています:

- Name: SqlInjectionCheck
  Configuration:
    UserInjections: []
  Assertions:
    - Name: LogAnalysisAssertion
    - Name: ResponseAnalysisAssertion
    - Name: StatusCodeAssertion

ここでは、3つのアサーションがデフォルトでオンになっていることがわかります。誤検出の一般的な原因はStatusCodeAssertionです。これをオフにするには、Profilesセクションでその設定を変更します。この例では、他の2つのアサーション（LogAnalysisAssertion、ResponseAnalysisAssertion）のみを提供します。これにより、SqlInjectionCheckがStatusCodeAssertionを使用するのを防ぎます:

Profiles:
  - Name: Quick
    DefaultProfile: Empty
    Routes:
      - Route: *Route0
        Checks:
          - Name: ApplicationInformationCheck
          - Name: CleartextAuthenticationCheck
          - Name: FrameworkDebugModeCheck
          - Name: HtmlInjectionCheck
          - Name: InsecureHttpMethodsCheck
          - Name: JsonHijackingCheck
          - Name: JsonInjectionCheck
          - Name: SensitiveInformationCheck
          - Name: SessionCookieCheck
          - Name: SqlInjectionCheck
            Assertions:
              - Name: LogAnalysisAssertion
              - Name: ResponseAnalysisAssertion
          - Name: TokenCheck
          - Name: XmlInjectionCheck