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

次の方法でAPIのスキャン対象を指定できます:

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

OpenAPI仕様

OpenAPI仕様（以前のSwagger仕様）は、REST API用のAPI記述フォーマットです。このセクションでは、OpenAPI仕様を使用してAPIセキュリティテストスキャンを構成し、テスト対象の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セキュリティテストでは、リストされたメディアタイプをチェックし、サポートされている各メディアタイプのサンプルデータを生成しようとします。

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

異なるメディアタイプ（たとえば、application/jsonやapplication/xml）を使用して同じオペレーション（たとえば、POST /user）をテストすることは、必ずしも望ましいとは限りません。たとえば、ターゲットアプリケーションがリクエストコンテンツタイプに関係なく同じコードを実行する場合、テストセッションの完了に時間がかかり、ターゲットアプリに応じてリクエスト本文に関連する重複した脆弱性がレポートされる可能性があります。

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

または、変数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. 次のものを含めます API-Security.gitlab-ci.ymlテンプレートあなたの.gitlab-ci.ymlファイル。

2. 設定ファイルには、さまざまなチェックが有効になっている複数のテストプロファイルが定義されています。Quickプロファイルから開始することをお勧めします。このプロファイルを使用したテストはより迅速に完了するため、構成の検証が容易になります。APISEC_PROFILE CI/CD変数を.gitlab-ci.ymlファイルに追加して、プロファイルを指定します。

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

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

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加すると、動的な環境でのテストに最適です。GitLab CI/CDパイプライン中に動的に作成されたアプリに対してAPIセキュリティテストを実行するには、environment_url.txtファイルにURLを永続化させます。APIセキュリティテストは、そのファイルを自動的に解析中して、スキャンターゲットを見つけます。Autoデブオプス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)

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セキュリティテストを構成して、テストするターゲットAPIに関する情報を提供するHARファイルを使用するには、次の手順を実行します:

1. 次のものを含めます API-Security.gitlab-ci.ymlテンプレートあなたの.gitlab-ci.ymlファイル。

2. 設定ファイルには、さまざまなチェックが有効になっている複数のテストプロファイルが定義されています。Quickプロファイルから開始することをお勧めします。このプロファイルを使用したテストはより迅速に完了するため、構成の検証が容易になります。

   変数APISEC_PROFILEを.gitlab-ci.ymlファイルに追加してプロファイルを指定します。

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

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

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加すると、動的な環境でのテストに最適です。GitLab CI/CDパイプライン中に動的に作成されたアプリに対してAPIセキュリティテストを実行するには、environment_url.txtファイルにURLを永続化させます。APIセキュリティテストは、そのファイルを自動的に解析中して、スキャンターゲットを見つけます。Autoデブオプス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 Schema

GraphQLは、APIのクエリ言語であり、従来のREST APIの代替手段です。APIセキュリティテストは、複数の方法でGraphQLエンドポイントのテストをサポートしています:

• GraphQLスキーマを使用したテスト。GitLab 15.4で導入されました。
• GraphQLクエリのレコーディング（HAR）を使用したテスト。
• GraphQLクエリを含むPostman Collectionを使用したテスト。

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

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

APIセキュリティテストのGraphQLサポートにより、スキーマのGraphQLエンドポイントをクエリできます。

APIセキュリティテストを構成して、テストするターゲットAPIに関する情報を提供するGraphQLエンドポイントURLを使用するには、次の手順を実行します:

1. 次のものを含めます API-Security.gitlab-ci.ymlテンプレートあなたの.gitlab-ci.ymlファイル。

2. /api/graphqlなどの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スキーマは、オンラインのサードパーティツールを使用して、イントロスペクションJSON形式に変換できます。https://transform.tools/graphql-to-introspection-json。

APIセキュリティテストを構成して、テストするターゲットAPIに関する情報を提供するGraphQLスキーマファイルを使用するには、次の手順を実行します:

1. 次のものを含めます API-Security.gitlab-ci.ymlテンプレートあなたの.gitlab-ci.ymlファイル。

2. /api/graphqlなどの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

Postman APIクライアントは、さまざまなタイプのAPIを呼び出すためにデベロッパーとテスターが使用する一般的なツールです。API定義は、APIセキュリティテストで使用するためにPostman Collectionファイルとしてエクスポートできます。エクスポートするときは、サポートされているバージョンのPostman Collection（v2.0またはv2.1）を選択してください。

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

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

APIセキュリティテストを構成して、テストするターゲットAPIに関する情報を提供するPostman Collectionファイルを使用するには、次の手順を実行します:

1. 含める API-Security.gitlab-ci.ymlテンプレート。

2. 設定ファイルには、さまざまなチェックが有効になっている複数のテストプロファイルが定義されています。Quickプロファイルから開始することをお勧めします。このプロファイルを使用したテストはより迅速に完了するため、構成の検証が容易になります。

   変数APISEC_PROFILEを.gitlab-ci.ymlファイルに追加してプロファイルを指定します。

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

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

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加すると、動的な環境でのテストに最適です。GitLab CI/CDパイプライン中に動的に作成されたアプリに対してAPIセキュリティテストを実行するには、environment_url.txtファイルにURLを永続化させます。APIセキュリティテストは、そのファイルを自動的に解析中して、スキャンターゲットを見つけます。Autoデブオプス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クライアントの変数

Postmanでは、デベロッパーがさまざまなリクエストのさまざまな部分で使用できるプレースホルダーを定義できます。これらのプレースホルダーは、変数の使用で説明されているように、変数と呼ばれます。変数を使用すると、リクエストとスクリプトで値を保存して再利用できます。たとえば、ドキュメントに変数を追加するために、コレクションをエディタで編集できます:

または、代わりに、環境に変数を追加することもできます:

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

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

Postmanでは、さまざまなスコープで変数を作成できます。各スコープには、Postmanツールで異なるレベルの表示レベルがあります。たとえば、すべてのオペレーション定義とワークスペースに表示される_グローバル環境スコープ_で変数を作成できます。また、特定環境が使用するために選択されている場合にのみ表示および使用される、特定の_環境スコープ_で変数を作成することもできます。一部のスコープは常に利用できるとは限りません。たとえば、Postmanエコシステムでは、Postmanクライアントでリクエストを作成できますが、これらのリクエストには_ローカル_スコープはありませんが、テストスクリプトはあります。

Postmanの変数スコープは、非常に難しいトピックになる可能性があり、誰もが精通しているわけではありません。先に進む前に、Postmanのドキュメントから変数のスコープを読むことを強くお勧めします。

前述のように、さまざまな変数スコープがあり、それぞれに目的があり、Postmanドキュメントに柔軟性を提供するために使用できます。Postmanドキュメントごとの変数の値の計算方法に関する重要な注意事項があります:

以下は、PostmanクライアントとAPIセキュリティテストでサポートされている変数スコープの要約です:

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

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

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

• コレクション変数を定義する
• 環境変数を定義する
• グローバル変数を定義する

Postmanクライアントからエクスポートする

Postmanクライアントを使用すると、さまざまなファイル形式をエクスポートできます。たとえば、PostmanコレクションまたはPostman環境をエクスポートできます。エクスポートされた環境は、（常に利用可能な）グローバル環境、または以前に作成したカスタム環境にすることができます。Postmanコレクションをエクスポートすると、_コレクション_および_ローカル_スコープの変数の宣言のみが含まれる場合があります。_環境_スコープの変数は含まれていません。

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

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

• コレクションをエクスポートする
• 環境をエクスポートする
• グローバル環境をダウンロード

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

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

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

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

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

スコープ：グローバル、環境、コレクション、および_GitLab APIセキュリティテスト_は、GitLab 15.1以降でサポートされています。GitLab 15.0以前は、_コレクション_と_GitLab APIセキュリティテスト_スコープのみをサポートしています。

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

Postmanコレクションドキュメントには、_コレクション_スコープの変数が自動的に含まれます。Postmanコレクションは、APISEC_POSTMAN_COLLECTION設定変数で提供されます。この変数は、単一のエクスポートされたPostmanコレクションに設定できます。

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

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

• エクスポートされたグローバル環境
• エクスポートされた環境
• APIセキュリティテストカスタムJSON形式

未定義Postman変数

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

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

可能であれば、APIセキュリティテストは、未定義の変数を処理する場合と同様の動作に従います。変数参照のテキストは同じままであり、テキストの置換はありません。同じ動作は、サポートされていない動的変数にも適用されます。

たとえば、Postmanコレクションのリクエスト定義が変数{{full_url}}を参照しており、変数が見つからない場合、値{{full_url}}で変更されずに残ります。

動的なPostman変数

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

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

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

例: グローバルスコープ

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

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/

例: 環境

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

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/

例: コレクションスコープ

_コレクション_スコープ変数は、エクスポートされたPostmanコレクションファイルに入力された状態で含まれており、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セキュリティのスコープ

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"
}

例: 複数のスコープ

この例では、_グローバル_スコープ、_環境_スコープ、および_コレクション_スコープが設定されています。最初の手順は、さまざまなスコープをエクスポートすることです。

• _グローバル_スコープをエクスポートする（global-scope.json）
• _環境_スコープをエクスポートする（environment-scope.json）
• _コレクション_スコープを含むPostmanコレクションをエクスポートする（postman-collection.json）

Postmanコレクションは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セキュリティテストで使用するために変数の値を変更する必要があることがよくあります。たとえば、_コレクション_スコープ変数には、api_versionという名前の変数が含まれており、値はv2ですが、テストではv1の値が必要です。エクスポートされたコレクションを変更して値を変更する代わりに、APIセキュリティテストスコープを使用して値を変更できます。これは、_APIセキュリティテスト_スコープが他のすべてのスコープよりも優先されるためです。

_コレクション_スコープ変数は、エクスポートされたPostmanコレクションファイルに入力された状態で含まれており、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セキュリティテストで使用するために変数の値を変更する必要があることがよくあります。たとえば、_環境_スコープに、api_versionという名前の変数が含まれており、値はv2ですが、テストではv1の値が必要です。エクスポートされたファイルを変更して値を変更する代わりに、APIセキュリティテストスコープを使用できます。これは、_APIセキュリティテスト_スコープが他のすべてのスコープよりも優先されるためです。

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

• _グローバル_スコープをエクスポートする（global-scope.json）
• _環境_スコープをエクスポートする（environment-scope.json）
• _コレクション_スコープを含むPostmanコレクションをエクスポートする（postman-collection.json）

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

{
  "api_version": "v1"
}

Postmanコレクションは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セキュリティテストアナライザーは、収集および使用されるJSONレポートを生成し、GitLab脆弱性画面に脆弱性を入力します。

報告される誤検出の数を制限するために行える設定の変更については、誤検出の処理を参照してください。

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

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

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

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

2. 脆弱性のタイトルを選択して詳細を表示します。次の表では、これらの詳細について説明します。

   フィールド	説明
   説明	変更された内容を含む脆弱性の説明。
   プロジェクト	脆弱性が検出されたネームスペースとプロジェクト。
   メソッド	脆弱性の検出に使用されたHTTPメソッド。
   URL	脆弱性が検出されたURL。
   リクエスト	脆弱性を引き起こしたHTTPリクエスト。
   未変更のレスポンス	未変更のリクエストからのレスポンス。これは、一般的な作業応答がどのように見えるかです。
   実際の結果	テストリクエストから受信したレスポンス。
   エビデンス	脆弱性が発生したと判断した方法。
   識別子	この脆弱性を見つけるために使用されるAPIセキュリティテストチェック。
   重大度	脆弱性の重大度。
   スキャナーの種類	テストの実行に使用されるスキャナー。

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

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

脆弱性の操作

脆弱性が見つかったら、操作できます。詳細については、脆弱性に対処する方法をお読みください。

誤検出の処理

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

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

チェックをオフにする

チェックは特定の種類のテストを実行し、特定の設定プロファイルに対してオンとオフを切り替えることができます。指定された設定ファイルは、使用できるいくつかのプロファイルを定義します。設定ファイルのプロファイル定義には、スキャン中にアクティブになっているすべてのチェックがリストされています。特定のチェックをオフにするには、設定ファイルのプロファイル定義から削除します。プロファイルは、設定ファイルの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ハイジャックチェックをオフにするには、次の行を削除します:

          - 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

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

アサーションは、チェックによって生成されたテストで脆弱性を検出します。多くのチェックは、ログ分析、レスポンス分析、ステータスコードなどの複数のアサーションをサポートしています。脆弱性が見つかった場合、使用されたアサーションが提供されます。どの主張がデフォルトでオンになっているかを識別するには、設定ファイルでチェックのデフォルト設定を参照してください。セクションは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