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

前提要件:

• 次のWeb APIタイプのうちの1つ:

  • REST API
  • SOAP
  • GraphQL
  • フォームの本文、JSON、またはXML

• テストするAPIを提供するための次のアセットのいずれか:

  • OpenAPI v2またはv3 API定義
  • テスト対象のAPIリクエストのHTTPアーカイブ（HAR）
  • Postman Collection v2.0またはv2.1
  一度もない本番環境サーバーに対してファズテストを実行しないでください。APIが実行できる機能を実行できるだけでなく、APIでバグをトリガーする可能性もあります。これには、データを変更および削除するなどのアクションが含まれます。テストサーバーに対してのみファジングを実行してください。

Web APIファジングを有効にするには、Web APIファジング設定フォームを使用します。

• 手動での設定手順については、APIタイプに応じて、それぞれのセクションを参照してください:
  • OpenAPI仕様
  • GraphQLスキーマ
  • HTTPアーカイブ（HAR）
  • Postman Collection
• それ以外の場合は、Web APIファジング設定フォームを参照してください。

ファジング設定ファイルは、リポジトリの.gitlabディレクトリに存在する必要があります。

Web APIファジング設定フォーム

ファジング設定フォームを使用すると、プロジェクトのファジング設定を作成または変更できます。このフォームを使用すると、最も一般的なファジングオプションの値を選択し、GitLab CI/CD設定に貼り付けることができるYAMLスニペットを作成できます。

UIでWeb APIファジングを設定する

ファジングスニペットを生成するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. セキュリティ > セキュリティ設定を選択します。
3. APIファジング行で、Enable API Fuzzing（APIファジング）を有効にする]を選択します。
4. フィールドに入力します。詳細については、利用可能なCI/CD変数を参照してください。
5. コードスニペットの生成を選択します。フォームで選択したオプションに対応するYAMLスニペットがモーダルで開きます。
6. 次のいずれかを実行します:
   1. スニペットをクリップボードにコピーするには、コードのコピーのみを選択します。
   2. あなたのプロジェクトの.gitlab-ci.ymlファイルにスニペットを追加するには、コードをコピーして.gitlab-ci.ymlファイルを開くを選択してください。パイプラインエディタが開きます。
      1. スニペットを.gitlab-ci.ymlファイルに貼り付けます。
      2. Lintタブを選択して、編集した.gitlab-ci.ymlファイルが有効であることを確認します。
      3. 編集タブを選択し、次に変更をコミットするを選択します。

スニペットが.gitlab-ci.ymlファイルにコミットされると、パイプラインにファジングジョブが含まれます。

仕様

OpenAPI仕様（以前のSwagger仕様）は、REST APIのAPI記述形式です。このセクションでは、仕様を使用してファジングを設定し、テスト対象のターゲットAPIに関する情報を提供する方法について説明します。仕様は、ファイルシステムの参照またはURLとして提供されます。JSON形式とYAML形式の両方のOpenAPI形式がサポートされています。

ファジングは、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では、操作ごとに受け入れられるメディアタイプを指定できます。ファジングは、リストされたメディアタイプをチェックし、サポートされている各メディアタイプのサンプルデータを生成しようとします。

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

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

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

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

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

環境変数FUZZAPI_OPENAPI_ALL_MEDIA_TYPESとFUZZAPI_OPENAPI_MEDIA_TYPESを使用すると、メディアタイプの処理方法を決定できます。これらの設定は相互に排他的です。両方が有効になっている場合、ファジングはエラーをレポートします。

仕様でWeb APIファジングを設定する

仕様を使用してGitLabでファジングを構成するには、次の手順に従います:

1. fuzzステージングを.gitlab-ci.ymlファイルに追加します。

2. 次のものを含めます API-Fuzzing.gitlab-ci.ymlテンプレートを.gitlab-ci.ymlファイルに追加します。

3. FUZZAPI_PROFILECI/CD変数を.gitlab-ci.ymlファイルに追加して、プロファイルを提供します。プロファイルでは、実行するテストの回数を指定します。選択したプロファイルのQuick-10を代入します。詳細については、ファジングプロファイルを参照してください。

   variables:
     FUZZAPI_PROFILE: Quick-10

4. 仕様の場所を指定します。仕様は、ファイルまたはURLとして指定できます。FUZZAPI_OPENAPI変数を追加して場所を指定します。

5. ターゲットAPIインスタンスのベースURLを指定します。FUZZAPI_TARGET_URL変数またはenvironment_url.txtファイルのいずれかを使用します。

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加すると、動的な環境でテストするのに最適です。GitLab CI/CDパイプライン中に動的に作成されたアプリケーションに対してファジングを実行するには、アプリケーションがenvironment_url.txtファイルにURLを保持するようにします。ファジングは、そのファイルを自動的に解析中して、スキャンターゲットを見つけます。Auto DevOps CI YAMLにその例があります。

仕様を使用した.gitlab-ci.ymlファイルの例:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_TARGET_URL: http://test-deployment/

これは、ファジングの最小限の設定です。ここから、次のことができます:

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

ファジング設定オプションの詳細については、利用可能なCI/CD変数を参照してください。

HTTPアーカイブ（HAR）

HTTPアーカイブ形式（HAR）は、HTTPトランザクションを記録するためのアーカイブファイル形式です。GitLab API fuzzerとともに使用する場合、HARには、テストするWeb APIの呼び出しの記録が含まれている必要があります。API fuzzerは、すべてのリクエストを抽出し、それらを使用してテストを実行します。

HARファイルの作成方法など、詳細については、HTTPアーカイブ形式を参照してください。

HARファイルでWeb APIファジングを構成する

HARファイルを使用するようにファジングを設定するには、次の手順に従います:

1. fuzzステージングを.gitlab-ci.ymlファイルに追加します。

2. 次のものを含めます API-Fuzzing.gitlab-ci.ymlテンプレートを.gitlab-ci.ymlファイルに追加します。

3. FUZZAPI_PROFILECI/CD変数を.gitlab-ci.ymlファイルに追加して、プロファイルを提供します。プロファイルでは、実行するテストの回数を指定します。選択したプロファイルのQuick-10を代入します。詳細については、ファジングプロファイルを参照してください。

   variables:
     FUZZAPI_PROFILE: Quick-10

4. HAR仕様の場所を指定します。仕様は、ファイルまたはURLとして指定できます。FUZZAPI_HAR変数を追加して場所を指定します。

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

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加すると、動的な環境でテストするのに最適です。GitLab CI/CDパイプライン中に動的に作成されたアプリケーションに対してファジングを実行するには、アプリケーションがenvironment_url.txtファイルにドメインを保持するようにします。ファジングは、そのファイルを自動的に解析中して、スキャンターゲットを見つけます。Auto DevOps CI YAMLのこの例を参照してください。

HARファイルを使用した.gitlab-ci.ymlファイルの例:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_HAR: test-api-recording.har
  FUZZAPI_TARGET_URL: http://test-deployment/

この例は、ファジングの最小限の設定です。ここから、次のことができます:

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

ファジング設定オプションの詳細については、利用可能なCI/CD変数を参照してください。

GraphQLスキーマ

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

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

このセクションでは、GraphQLスキーマを使用したテスト方法について説明します。ファジングのGraphQLスキーマサポートは、イントロスペクションをサポートするエンドポイントからスキーマをクエリできます。イントロスペクションは、GraphiQLなどのツールが動作するようにデフォルトで有効になっています。

GraphQLエンドポイントURLを使用したファジングスキャン

ファジングのGraphQLサポートにより、GraphQLエンドポイントにスキーマをクエリできます。

ターゲットAPIに関する情報を提供するGraphQLエンドポイントURLを使用するようにファジングを設定するには、次の手順に従います:

1. 次のものを含めます API-Fuzzing.gitlab-ci.ymlテンプレートを.gitlab-ci.ymlファイルに追加します。

2. GraphQLエンドポイントのパス（/api/graphqlなど）を指定します。FUZZAPI_GRAPHQL変数を追加して、パスを指定します。

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

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加すると、動的な環境でテストするのに最適です。詳細については、ドキュメントの動的な環境ソリューションセクションを参照してください。

GraphQLエンドポイントURLを使用した構成の完了例:

stages:
  - fuzz

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

apifuzzer_fuzz:
  variables:
    FUZZAPI_GRAPHQL: /api/graphql
    FUZZAPI_TARGET_URL: http://test-deployment/

この例は、ファジングの最小限の設定です。ここから、次のことができます:

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

GraphQLスキーマファイルを使用したファジング

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

ターゲットAPIに関する情報を提供するGraphQlスキーマファイルを使用するようにファジングを設定するには、次の手順に従います:

1. 次のものを含めます API-Fuzzing.gitlab-ci.ymlテンプレートを.gitlab-ci.ymlファイルに追加します。

2. GraphQLエンドポイントのパス（/api/graphqlなど）を指定します。FUZZAPI_GRAPHQL変数を追加して、パスを指定します。

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

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

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加すると、動的環境でのテストに最適です。詳細については、ドキュメントの動的環境ソリューションのセクションを参照してください。

GraphQLのスキーマファイルを使用した完全な構成例:

stages:
  - fuzz

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

apifuzzer_fuzz:
  variables:
    FUZZAPI_GRAPHQL: /api/graphql
    FUZZAPI_GRAPHQL_SCHEMA: test-api-graphql.schema
    FUZZAPI_TARGET_URL: http://test-deployment/

GraphQLのスキーマファイルURLを使用した完全な構成例:

stages:
  - fuzz

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

apifuzzer_fuzz:
  variables:
    FUZZAPI_GRAPHQL: /api/graphql
    FUZZAPI_GRAPHQL_SCHEMA: http://file-store/files/test-api-graphql.schema
    FUZZAPI_TARGET_URL: http://test-deployment/

これは、APIファジングの最小構成です。ここから、次のことができます:

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

Postmanコレクション

Postman APIクライアントは、デベロッパーやテスターがさまざまな種類のAPIを呼び出すためによく使用するツールです。APIファジングで使用するために、API定義をPostmanコレクションファイルとしてエクスポートできます。エクスポートするときは、サポートされているバージョンのPostmanコレクション（v2.0またはv2.1）を選択してください。

GitLab APIアナライザーで使用する場合、Postmanコレクションには、有効なデータでテストするWeb APIの定義を含める必要があります。APIアナライザーは、すべてのAPI定義を抽出し、それらを使用してテストを実行します。

Postmanコレクションファイルを使用したWeb APIファジングの構成

Postmanコレクションファイルを使用するようにAPIファジングを構成するには:

1. .gitlab-ci.ymlファイルにfuzzステージングを追加します。

2. .gitlab-ci.ymlファイルにテンプレートであるAPI-Fuzzing.gitlab-ci.ymlを含めます。

3. .gitlab-ci.ymlファイルにFUZZAPI_PROFILE CI/CD変数を追加して、プロファイルを指定します。プロファイルは、実行するテストの数を指定します。選択したプロファイルにQuick-10を代入します。詳細については、APIファジングプロファイルを参照してください。

   variables:
     FUZZAPI_PROFILE: Quick-10

4. Postmanコレクションの仕様の場所を指定します。ファイルのURLとして仕様を指定できます。FUZZAPI_POSTMAN_COLLECTION変数を追加して、場所を指定します。

5. ターゲットAPIインスタンスのベースURLを指定します。FUZZAPI_TARGET_URL変数またはenvironment_url.txtファイルのいずれかを使用します。

   プロジェクトのルートにあるenvironment_url.txtファイルにURLを追加すると、動的環境でのテストに最適です。GitLab CI/CDパイプライン中に動的に作成されたアプリに対してAPIファジングを実行するには、アプリにenvironment_url.txtファイルにそのドメインを永続化させます。APIファジングは、そのファイルを自動的に解析中して、スキャンターゲットを検索します。当社のAuto DevOps CI YAMLの例を参照してください。

Postmanコレクションファイルを使用する.gitlab-ci.ymlファイルの例:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json
  FUZZAPI_TARGET_URL: http://test-deployment/

これは、APIファジングの最小構成です。ここから、次のことができます:

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

APIファジング構成オプションの詳細については、利用可能なCI/CD変数を参照してください。

Postman変数

Postmanクライアントの変数

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

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

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

Postmanは、優れたユーザーエクスペリエンスを備えた基本的なクライアントツールから、スクリプトでAPIをテストしたり、2次リクエストをトリガーする複雑なコレクションを作成したり、途中で変数を設定したりできる、より複雑なエコシステムに成長しました。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ファジングで使用できます。
• コレクションスコープは、特定のコレクションで宣言された変数のグループです。コレクション変数は、宣言されたコレクションとネストされたリクエストまたはコレクションで使用できます。コレクションスコープで定義された変数は、グローバル環境スコープと環境スコープよりも優先されます。Postmanクライアントは、1つ以上のコレクションをJSONファイルにエクスポートできます。このJSONファイルには、選択したコレクション、リクエスト、およびコレクション変数が含まれています。
• API fuzzing scope（APIファジングスコープ）は、ユーザーが追加の変数を提供したり、サポートされている他のスコープで定義されている変数をオーバーライドしたりできるように、APIファジングによって追加された新しいスコープです。このスコープは、Postmanではサポートされていません。APIファジングスコープ変数は、カスタムJSONファイル形式を使用して提供されます。
  • 環境またはコレクションで定義された値をオーバーライドします
  • スクリプトから変数を定義する
  • サポートされていない_データスコープ_からデータの単一行を定義する
• Data scope（データスコープ）は、名前と値がJSONまたはCSVファイルからのものである変数のグループです。NewmanやPostmanコレクションRunnerなどの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コレクションは、構成変数FUZZAPI_POSTMAN_COLLECTIONで提供されます。この変数は、エクスポートされた単一のPostmanコレクションに設定できます。

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

構成変数FUZZAPI_POSTMAN_COLLECTION_VARIABLESは、以下に設定できます:

• エクスポートされたグローバル環境
• エクスポートされた環境
• APIファジングカスタムJSON形式

未定義のPostman変数

APIファジングエンジンが、Postmanコレクションファイルで使用されているすべての変数参照を検出するとは限りません。考えられるケースは次のとおりです:

• データまたはローカルスコープの変数を使用していますが、前述のように、これらのスコープはAPIファジングではサポートされていません。したがって、これらの変数の値がAPIファジングのスコープを介して提供されていないと仮定すると、データとローカルスコープの変数の値は未定義になります。
• 変数名が誤って入力され、その名前が定義された変数と一致しません。
• Postman Clientは、APIファジングでサポートされていない新しい動的変数をサポートしています。

可能な場合、APIファジングは、未定義の変数を処理する際に、Postman Clientと同じ動作に従います。変数参照のテキストは同じままであり、テキストの置換はありません。同じ動作は、サポートされていない動的変数にも適用されます。

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

動的Postman変数

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

APIファジングとPostmanの重要な違いは、APIファジングが同じ動的変数のそれぞれの使用に対して同じ値を返すことです。これは、同じ動的変数を使用するたびにランダムな値を返すPostman Clientの動作とは異なります。つまり、Postmanがランダムな値を使用するのに対し、APIファジングは動的変数に静的な値を使用します。

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

例: グローバルスコープ

この例では、Postman Clientからグローバルスコープがエクスポートされます（global-scope.json）。これは、FUZZAPI_POSTMAN_COLLECTION_VARIABLES設定変数を介してAPIファジングに提供されます。

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

stages:
     - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

例: 環境範囲

この例では、Postman Clientから環境スコープがエクスポートされます（environment-scope.json）。これは、FUZZAPI_POSTMAN_COLLECTION_VARIABLES設定変数を介してAPIファジングに提供されます。

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

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: environment-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

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

コレクションのスコープ変数は、エクスポートされたPostmanコレクションファイルに含められ、FUZZAPI_POSTMAN_COLLECTION設定変数を介して提供されます。

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

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: variable-collection-dictionary.json

例: APIファジングのスコープ

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

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

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: api-fuzzing-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

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

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

例: 複数のスコープ

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

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

PostmanコレクションはFUZZAPI_POSTMAN_COLLECTION変数を使用して提供されますが、他のスコープはFUZZAPI_POSTMAN_COLLECTION_VARIABLESを使用して提供されます。APIファジングは、各ファイルで提供されるデータを使用して、提供されたファイルがどのスコープに一致するかを識別できます。

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

例: 変数の値を変更する

エクスポートされたスコープを使用する場合、多くの場合、APIファジングで使用するために変数の値を変更する必要があります。たとえば、_コレクション_のスコープを持つ変数に、値v2のapi_versionという名前の変数が含まれている場合でも、テストでは値v1が必要です。値を変更するためにエクスポートされたコレクションを変更する代わりに、APIファジングのスコープを使用して値を変更できます。これは、APIファジングのスコープが他のすべてのスコープよりも優先されるために機能します。

コレクションのスコープ変数は、エクスポートされたPostmanコレクションファイルに含められ、FUZZAPI_POSTMAN_COLLECTION設定変数を介して提供されます。

APIファジングのスコープは、FUZZAPI_POSTMAN_COLLECTION_VARIABLES設定変数を介して提供されますが、最初にファイルを作成する必要があります。ファイルapi-fuzzing-scope.jsonは、カスタムJSONファイル形式を使用します。このJSONは、プロパティのキーと値のペアを持つオブジェクトです。キーは変数の名前で、値は変数の値です。例:

{
  "api_version": "v1"
}

CI定義:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: api-fuzzing-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

例: 複数のスコープを使用して変数の値を変更する

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

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

• global-scope.jsonとしてグローバルスコープをエクスポートします
• environment-scope.jsonとして環境スコープをエクスポートします
• コレクションのスコープを含むPostmanコレクションをpostman-collection.jsonとしてエクスポートします

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

{
  "api_version": "v1"
}

PostmanコレクションはFUZZAPI_POSTMAN_COLLECTION変数を使用して提供されますが、他のスコープはFUZZAPI_POSTMAN_COLLECTION_VARIABLESを使用して提供されます。APIファジングは、各ファイルで提供されるデータを使用して、提供されたファイルがどのスコープに一致するかを識別できます。

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json,api-fuzzing-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

最初のスキャンの実行

正しく設定されている場合、CI/CDパイプラインには、fuzzステージングとapifuzzer_fuzzまたはapifuzzer_fuzz_dndのジョブが含まれます。このジョブは、無効な設定が提供されている場合にのみ失敗します。通常の操作中、ファジングテスト中にフォールトが識別された場合でも、ジョブは常に成功します。

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

報告されるフォールトの数が過剰になるのを防ぐため、APIファジングスキャナーは、報告するフォールトの数を制限します。

ファジングのフォールトの表示

APIファジングアナライザーは、収集および使用されるJSONレポートを生成し、GitLabの脆弱性画面にフォールトを入力した状態にします。ファジングのフォールトは、重大度が「不明」の脆弱性として表示されます。

APIファジングで見つかったフォールトには手動調査が必要であり、特定の脆弱性タイプに関連付けられていません。セキュリティ上の問題であるかどうか、および修正が必要かどうかを判断するには、調査が必要です。報告される誤検出の数を制限するために行える設定の変更については、誤検出の処理を参照してください。

APIファジングの脆弱性の詳細を表示する

APIファジングによって検出されたフォールトは、ライブWebアプリケーションで発生し、脆弱性であるかどうかを判断するために手動調査が必要です。ファジングのフォールトは、重大度が「不明」の脆弱性として含まれています。ファジングのフォールトの調査を容易にするために、送受信されたHTTPメッセージに関する詳細情報と、行われた変更の説明が提供されます。

ファジングのフォールトの詳細を表示するには、次の手順に従います:

1. プロジェクトまたはマージリクエストでフォールトを表示できます:

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

2. フォールトのタイトルを選択して、フォールトの詳細を表示します。次の表に、これらの詳細を示します。

   フィールド	説明
   説明	何が変更されたかなど、フォールトの説明。
   プロジェクト	脆弱性が検出されたネームスペースとプロジェクト。
   Method	脆弱性の検出に使用されたHTTPメソッド。
   URL	脆弱性が検出されたURL。
   Request	フォールトを引き起こしたHTTPリクエスト。
   変更されていないレスポンス	変更されていないリクエストからのレスポンス。これは、典型的な作業レスポンスがどのように見えるかです。
   実際のレスポンス	ファジングされたリクエストから受信したレスポンス。
   エビデンス	フォールトの発生をどのように判断したか。
   識別子:	このフォールトの発見に使用されたファジングチェック。
   重大度	調査結果の重大度は常に不明です。
   スキャナータイプ	テストの実行に使用されるスキャナー。

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

ファジングのフォールトは、重大度が「不明」の脆弱性として表示されます。セキュリティダッシュボードは、グループ、プロジェクト、パイプラインのすべてのセキュリティ脆弱性の概要を把握するのに適した場所です。詳細については、セキュリティダッシュボードのドキュメントを参照してください。

脆弱性の操作

ファジングのフォールトは、重大度が「不明」の脆弱性として表示されます。フォールトが見つかったら、それを操作できます。脆弱性に対処する方法の詳細をお読みください。

誤検出の処理

誤検出は、次の2つの方法で処理できます:

• 誤検出を生成しているチェックをオフにします。これにより、チェックによるフォールトの生成が防止されます。チェックの例としては、JSONFuzzingCheckとFormBodyFuzzingCheckがあります。
• ファジングチェックには、フォールトが識別されたタイミングを検出するいくつかのメソッドがあり、「アサート」と呼ばれます。アサートもオフにして設定できます。たとえば、APIファジングでは、デフォルトでHTTPステータスコードを使用して、何が実際の問題であるかを識別します。APIがテスト中に500エラーを返すと、フォールトが作成されます。一部のフレームワークは500エラーを頻繁に返すため、これは必ずしも望ましいとは限りません。

チェックをオフにする

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

プロファイルの定義例:

Profiles:
  - Name: Quick-10
    DefaultProfile: Quick
    Routes:
      - Route: *Route0
        Checks:
          - Name: FormBodyFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: GeneralFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: JsonFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: XmlFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true

GeneralFuzzingCheckをオフにするには、次の行を削除します:

- Name: GeneralFuzzingCheck
  Configuration:
    FuzzingCount: 10
    UnicodeFuzzing: true

これにより、次のYAMLが得られます:

- Name: Quick-10
  DefaultProfile: Quick
  Routes:
    - Route: *Route0
      Checks:
        - Name: FormBodyFuzzingCheck
          Configuration:
            FuzzingCount: 10
            UnicodeFuzzing: true
        - Name: JsonFuzzingCheck
          Configuration:
            FuzzingCount: 10
            UnicodeFuzzing: true
        - Name: XmlFuzzingCheck
          Configuration:
            FuzzingCount: 10
            UnicodeFuzzing: true

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

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

この例は、FormBodyFuzzingCheckを示しています:

Checks:
  - Name: FormBodyFuzzingCheck
    Configuration:
      FuzzingCount: 30
      UnicodeFuzzing: true
    Assertions:
      - Name: LogAnalysisAssertion
      - Name: ResponseAnalysisAssertion
      - Name: StatusCodeAssertion

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

Profiles:
  - Name: Quick-10
    DefaultProfile: Quick
    Routes:
      - Route: *Route0
        Checks:
          - Name: FormBodyFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
            Assertions:
              - Name: LogAnalysisAssertion
              - Name: ResponseAnalysisAssertion
          - Name: GeneralFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: JsonFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: XmlInjectionCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true