正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

APIセキュリティテストジョブのトラブルシューティング

APIセキュリティテストジョブがN時間後にタイムアウトする

大規模なリポジトリの場合、APIセキュリティテストジョブはデフォルトで設定されているsmall hosted runner on Linuxでタイムアウトする可能性があります。この問題がジョブで発生した場合は、larger runnerにスケールする必要があります。

以下のドキュメントセクションを参照してください:

APIセキュリティテストジョブの完了に時間がかかりすぎる

Performance Tuning and Testing Speedを参照してください

エラー: Error waiting for DAST API 'http://127.0.0.1:5000' to become available

v1.6.196以前のAPIセキュリティテストアナライザーのバージョンには、特定の条件下でバックグラウンドプロセスが失敗する原因となるバグが存在します。解決策は、より新しいAPIセキュリティテストアナライザーのバージョンに更新することです。

バージョン情報は、dast_apiジョブのジョブ詳細で見つけることができます。

バージョンv1.6.196以降で問題が発生している場合は、サポートに連絡し、以下の情報を提供してください:

  1. このトラブルシューティングセクションを参照し、イシューを動的な解析チームにエスカレートするよう依頼してください。
  2. ジョブの完全なコンソール出力。
  3. ジョブアーティファクトとして利用可能なgl-api-security-scanner.logファイル。ジョブ詳細ページの右側のパネルで、閲覧を選択します。
  4. dast_apiジョブの定義を.gitlab-ci.ymlファイルから。

Failed to start scanner session (version header not found)

APIセキュリティテストエンジンは、スキャナーアプリケーションコンポーネントとの接続を確立できない場合にエラーメッセージを出力します。エラーメッセージは、dast_apiジョブのジョブ出力ウィンドウに表示されます。このイシューの一般的な原因は、変数APISEC_APIをデフォルトから変更することです。

エラーメッセージ

  • Failed to start scanner session (version header not found).

解決策

  • .gitlab-ci.ymlファイルから変数APISEC_APIを削除します。この値は、APIセキュリティテストCI/CDテンプレートから継承されます。手動で値を設定する代わりに、この方法を使用してください。
  • 変数の削除が不可能な場合は、API security testing CI/CD templateの最新バージョンでこの値が変更されていないか確認してください。もしそうであれば、.gitlab-ci.ymlファイルの値を更新してください。

Failed to start session with scanner. Please retry, and if the problem persists reach out to support.

APIセキュリティテストエンジンは、スキャナーアプリケーションコンポーネントとの接続を確立できない場合にエラーメッセージを出力します。エラーメッセージは、dast_apiジョブのジョブ出力ウィンドウに表示されます。このイシューの一般的な原因は、バックグラウンドコンポーネントが、すでに使用中の選択されたポートを使用できないことです。このエラーは、タイミングが関係する場合(競合状態)、断続的に発生する可能性があります。このイシューは、他のサービスがコンテナにマップされ、ポート競合を引き起こすKubernetes環境で最も頻繁に発生します。

解決策に進む前に、エラーメッセージがポートがすでに使用されていたために生成されたことを確認することが重要です。これが原因であったことを確認するには:

  1. ジョブコンソールに移動します。

  2. アーティファクトgl-api-security-scanner.logを探します。ダウンロードを選択してすべてのアーティファクトをダウンロードし、ファイルを検索するか、閲覧を選択して直接検索を開始できます。

  3. テキストエディタでgl-api-security-scanner.logファイルを開きます。

  4. ポートがすでに使用されていたためにエラーメッセージが生成された場合、ファイルに次のようなメッセージが表示されます:

    Failed to bind to address http://127.0.0.1:5500: address already in use.

前のメッセージのテキストhttp://[::]:5000は、あなたのケースでは異なる可能性があり、たとえばhttp://[::]:5500またはhttp://127.0.0.1:5500である可能性があります。エラーメッセージの残りの部分が同じである限り、ポートがすでに使用されていたと安全に推測できます。

ポートがすでに使用されていたという証拠が見つからない場合は、ジョブコンソールの出力に表示される同じエラーメッセージに対処する他のトラブルシューティングセクションを確認してください。他に選択肢がない場合は、適切なチャンネルを通じてget support or request an improvementしてください。

ポートがすでに使用中であったために問題が発生したことを確認できる場合は、CI/CD変数APISEC_API_PORTを使用して、スキャナーバックグラウンドコンポーネントに別のポートを指定します。

解決策

  1. .gitlab-ci.ymlファイルが設定変数APISEC_API_PORTを定義していることを確認してください。
  2. APISEC_API_PORTの値を1024より大きい利用可能なポート番号に更新します。提案されたポート番号がGitLabによって使用されていないことを確認する必要があります。GitLabが使用するポートの全リストは、Package defaultsを参照してください。

Application cannot determine the base URL for the target API

APIセキュリティテストエンジンは、OpenAPIドキュメントを検査した後、ターゲットAPIを特定できない場合にエラーメッセージを出力します。このエラーメッセージは、ターゲットAPIが.gitlab-ci.ymlファイルに設定されておらず、environment_url.txtファイルで利用できず、OpenAPIドキュメントを使用して計算できなかった場合に表示されます。

APIセキュリティテストエンジンが異なるソースをチェックする際にターゲットAPIを取得しようとする優先順位があります。まず、APISEC_TARGET_URLを使用しようとします。環境変数が設定されていない場合、APIセキュリティテストエンジンはenvironment_url.txtファイルを使用しようとします。environment_url.txtファイルがない場合、APIセキュリティテストエンジンはOpenAPIドキュメントの内容とAPISEC_OPENAPIで提供されたURL(URLが提供されている場合)を使用して、ターゲットAPIを計算しようとします。

最適な解決策は、ターゲットAPIが各デプロイごとに変更されるかどうかによって異なります。静的環境では、ターゲットAPIは各デプロイで同じであるため、この場合はstatic environment solutionを参照してください。ターゲットAPIが各デプロイで変更される場合は、dynamic environment solutionを適用する必要があります。

APIセキュリティテストジョブが一部のパスを操作から除外する

一部のパスが操作から除外されていることに気付いた場合は、以下のことを確認してください:

  • 変数DAST_API_EXCLUDE_URLSがテストしたい操作を除外するように設定されていないこと。

  • consumes配列が定義されており、ターゲット定義JSONファイルに有効な型が設定されていること。

    定義例については、example project target definition fileを参照してください。

静的環境解決策

この解決策は、ターゲットAPI URLが変更されない(静的である)パイプラインを対象としています。

Add environmental variable

ターゲットAPIが同じである環境では、APISEC_TARGET_URL環境変数を使用してターゲットURLを指定します。あなたの.gitlab-ci.ymlに、変数APISEC_TARGET_URLを追加します。変数は、APIテストターゲットのベースURLに設定する必要があります。例:

stages:
  - dast

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

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

動的環境解決策

動的環境では、ターゲットAPIはデプロイごとに変更されます。この場合、複数の可能な解決策があります。environment_url.txtファイルは動的環境を扱う際に使用します。

Use environment_url.txt

ターゲットAPI URLが各パイプライン中に変更される動的環境をサポートするために、APIセキュリティテストエンジンは、使用するURLを含むenvironment_url.txtファイルの使用をサポートしています。このファイルはリポジトリにチェックインされず、代わりにテストターゲットをデプロイするジョブによってパイプライン中に作成され、その後のパイプラインのジョブで使用できるアーティファクトとして収集されます。environment_url.txtファイルを作成するジョブは、APIセキュリティテストエンジンジョブの前に実行する必要があります。

  1. プロジェクトのルートにあるenvironment_url.txtファイルにベースURLを追加して、テストターゲットデプロイメントジョブを変更します。
  2. environment_url.txtをアーティファクトとして収集するようにテストターゲットデプロイメントジョブを変更します。

例:

deploy-test-target:
  script:
    # Perform deployment steps
    # Create environment_url.txt (example)
    - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.example.org > environment_url.txt

  artifacts:
    paths:
      - environment_url.txt

不正な形式のスキーマを持つOpenAPIの使用

OpenAPIドキュメントは、不正なスキーマで自動生成される場合や、タイムリーに手動で編集できない場合があります。このようなシナリオでは、変数APISEC_OPENAPI_RELAXED_VALIDATIONを設定することで、APIセキュリティテストが緩和された検証を実行できます。予期しない動作を防ぐために、完全に準拠したOpenAPIドキュメントを提供してください。

非準拠のOpenAPIファイルを編集する

OpenAPI仕様に準拠していない要素を検出して修正するには、エディタを使用します。エディタは通常、ドキュメントの検証と、スキーマ準拠のOpenAPIドキュメントを作成するための提案を提供します。推奨されるエディタは以下のとおりです:

エディタOpenAPI 2.0OpenAPI 3.0.xOpenAPI 3.1.x
Stoplight Studiocheck-circle YAML, JSONcheck-circle YAML, JSONcheck-circle YAML, JSON
Swagger Editorcheck-circle YAML, JSONcheck-circle YAML, JSONdotted-circle YAML, JSON

OpenAPIドキュメントが手動で生成された場合は、エディタにドキュメントを読み込み、準拠していないものをすべて修正してください。ドキュメントが自動生成された場合は、エディタに読み込み、スキーマ内の問題を特定します。その後、使用しているフレームワークに基づいてアプリケーションの問題を修正します。

OpenAPIの緩和された検証を有効にする

緩和された検証は、OpenAPIドキュメントがOpenAPI仕様を満たせない場合でも、異なるツールで消費できる十分なコンテンツを持っているケースを対象としています。検証は実行されますが、ドキュメントスキーマに関しては厳密ではありません。

APIセキュリティテストは、OpenAPI仕様に完全に準拠していないOpenAPIドキュメントでも消費しようとすることができます。APIセキュリティテストに緩和された検証を実行させるには、変数APISEC_OPENAPI_RELAXED_VALIDATIONを任意の値に設定します。例:

stages:
  - dast

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

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

No operation in the OpenAPI document is consuming any supported media type

APIセキュリティテストは、OpenAPIドキュメントで指定されたメディアタイプを使用してリクエストを生成します。サポートされているメディアタイプがないためにリクエストを作成できない場合、エラーがスローされます。

エラーメッセージ

  • Error, no operation in the OpenApi document is consuming any supported media type. Check 'OpenAPI Specification' to check the supported media types.

解決策

  1. OpenAPI Specificationセクションでサポートされているメディアタイプを確認してください。
  2. OpenAPIドキュメントを編集し、少なくとも指定された操作がサポートされているメディアタイプのいずれかを受け入れるようにします。あるいは、サポートされているメディアタイプをOpenAPIドキュメントレベルで設定し、すべての操作に適用することもできます。このステップでは、サポートされているメディアタイプがアプリケーションによって受け入れられるように、アプリケーションに変更を加える必要がある場合があります。

エラー: The SSL connection could not be established, see inner exception.

APIセキュリティテストは、古いプロトコルや暗号を含む幅広いTLS設定と互換性があります。幅広いサポートにもかかわらず、次のような接続エラーが発生する可能性があります:

Error, error occurred trying to download `<URL>`:
There was an error when retrieving content from Uri:' <URL>'.
Error:The SSL connection could not be established, see inner exception.

このエラーは、APIセキュリティテストが、指定されたURLのサーバーとのセキュアな接続を確立できなかったために発生します。

この問題を解決するには、以下の手順に従います:

エラーメッセージのホストが非TLS接続をサポートしている場合は、設定でhttps://http://に変更します。例えば、以下の設定でエラーが発生した場合:

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: https://test-deployment/
  APISEC_OPENAPI: https://specs/openapi.json

APISEC_OPENAPIのプレフィックスをhttps://からhttp://に変更します:

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: https://test-deployment/
  APISEC_OPENAPI: http://specs/openapi.json

非TLS接続を使用してURLにアクセスできない場合は、サポートチームに連絡して支援を求めてください。

testssl.shツールを使用して調査を迅速化できます。bash Shellが搭載され、影響を受けるサーバーに接続できるマシンから:

  1. 最新のリリースzipまたはtar.gzファイルをhttps://github.com/drwetter/testssl.sh/releasesからダウンロードして展開します。
  2. ./testssl.sh --log https://specsを実行します。
  3. ログファイルをサポートチケットに添付してください。

ERROR: Job failed: failed to pull image

このエラーメッセージは、アクセスに認証が必要な(公開されていない)コンテナレジストリからイメージをプルする際に発生します。

ジョブコンソールの出力では、エラーは次のようになります:

Running with gitlab-runner 15.6.0~beta.186.ga889181a (a889181a)
  on blue-2.shared.runners-manager.gitlab.com/default XxUrkriX
Resolving secrets
00:00
Preparing the "docker+machine" executor
00:06
Using Docker executor with image registry.gitlab.com/security-products/api-security:2 ...
Starting service registry.example.com/my-target-app:latest ...
Pulling docker image registry.example.com/my-target-app:latest ...
WARNING: Failed to pull image with policy "always": Error response from daemon: Get https://registry.example.com/my-target-app/manifests/latest: unauthorized (manager.go:237:0s)
ERROR: Job failed: failed to pull image "registry.example.com/my-target-app:latest" with specified policies [always]: Error response from daemon: Get https://registry.example.com/my-target-app/manifests/latest: unauthorized (manager.go:237:0s)

エラーメッセージ

  • GitLab 15.9以前では、ERROR: Job failed: failed to pull imageの後にError response from daemon: Get IMAGE: unauthorizedが続きます。

解決策

認証認証情報は、Access an image from a privateコンテナレジストリドキュメントセクションに概説されている方法を使用して提供されます。使用される方法は、コンテナレジストリプロバイダーとその設定によって決定されます。サードパーティ(クラウドプロバイダー(Azure、Google Cloud (GCP)、AWSなど))によって提供されるコンテナレジストリを使用している場合は、それらのコンテナレジストリに認証する方法に関する情報について、プロバイダーのドキュメントを確認してください。

次の例では、statically defined認証情報認証方法を使用しています。この例では、コンテナレジストリはregistry.example.comで、イメージはmy-target-app:latestです。

  1. DOCKER_AUTH_CONFIGの変数値を計算する方法を理解するために、Determine your DOCKER_AUTH_CONFIG dataを読んでください。設定変数DOCKER_AUTH_CONFIGには、適切な認証情報を提供するためのDocker JSON設定が含まれています。例えば、認証情報abcdefghijklmnを使用してプライベートコンテナレジストリregistry.example.comにアクセスする場合、Docker JSONは次のようになります:

    {
        "auths": {
            "registry.example.com": {
                "auth": "abcdefghijklmn"
            }
        }
    }
  2. DOCKER_AUTH_CONFIGをCI/CD変数として追加します。設定変数をあなたの.gitlab-ci.ymlファイルに直接追加する代わりに、プロジェクトのCI/CD variableを作成する必要があります。

  3. ジョブを再実行すると、静的に定義された認証情報がプライベートコンテナレジストリregistry.example.comにサインインするために使用され、イメージmy-target-app:latestをプルできるようになります。成功すると、ジョブコンソールに次のような出力が表示されます:

    Running with gitlab-runner 15.6.0~beta.186.ga889181a (a889181a)
      on blue-4.shared.runners-manager.gitlab.com/default J2nyww-s
    Resolving secrets
    00:00
    Preparing the "docker+machine" executor
    00:56
    Using Docker executor with image registry.gitlab.com/security-products/api-security:2 ...
    Starting service registry.example.com/my-target-app:latest ...
    Authenticating with credentials from $DOCKER_AUTH_CONFIG
    Pulling docker image registry.example.com/my-target-app:latest ...
    Using docker image sha256:139c39668e5e4417f7d0eb0eeb74145ba862f4f3c24f7c6594ecb2f82dc4ad06 for registry.example.com/my-target-app:latest with digest registry.example.com/my-target-
    app@sha256:2b69fc7c3627dbd0ebaa17674c264fcd2f2ba21ed9552a472acf8b065d39039c ...
    Waiting for services to be up and running (timeout 30 seconds)...

連続するスキャン間での脆弱性結果の相違

連続したスキャンでは、コードや設定の変更がない場合でも、異なる脆弱性の検出結果が返される可能性があります。これは主に、ターゲット環境とその状態に関連する予測不能性、およびスキャナーによって送信されるリクエストの並列化によるものです。複数のリクエストがスキャナーによって並列で送信され、スキャン時間を最適化します。これは、ターゲットサーバーがリクエストに応答する正確な順序が事前に決定されていないことを意味します。

OSコマンドインジェクションやSQLインジェクションなど、リクエストと応答の間の時間長によって検出されるタイミング攻撃の脆弱性は、サーバーが負荷状態にあり、指定されたしきい値内でテストへの応答を処理できない場合に検出される可能性があります。サーバーが負荷状態にない場合の同じスキャン実行では、これらの脆弱性に対して肯定的な検出結果が返されない可能性があり、結果が異なることにつながります。ターゲットサーバーのプロファイリング、Performance tuning and testing speed、およびテスト中の最適なサーバーパフォーマンスのベースライン確立は、前述の要因によって誤検出が発生する可能性がある場所を特定するのに役立つ場合があります。

エラー: sudo: The "no new privileges" flag is set, which prevents sudo from running as root.

アナライザーのv5以降、デフォルトではroot以外のユーザーが使用されます。これは、特権操作を実行する際にsudoの使用を必要とします。

このエラーは、実行中のコンテナが新しい権限を取得できないようにする特定のコンテナデーモン設定で発生します。ほとんどの設定では、これはデフォルトの設定ではなく、セキュリティ強化ガイドの一部として具体的に設定されたものです。

エラーメッセージ

このイシューは、before_scriptまたはAPISEC_PRE_SCRIPTが実行されたときに生成されるエラーメッセージによって特定できます:

$ sudo apk add nodejs

sudo: The "no new privileges" flag is set, which prevents sudo from running as root.

sudo: If sudo is running in a container, you may need to adjust the container configuration to disable the flag.

解決策

このイシューは、次の方法で回避策できます:

  • コンテナをrootユーザーとして実行します。すべての場合で機能するとは限らないため、この設定をテストする必要があります。これは、CICD設定を変更し、ジョブの出力をチェックして、whoamirootを返し、gitlabを返さないことを確認することによって行うことができます。gitlabが表示される場合は、別の回避策を使用してください。テストにより変更が成功したことが確認された後、before_scriptを削除できます。

    api_security:
      image:
        name: $SECURE_ANALYZERS_PREFIX/$APISEC_IMAGE:$APISEC_VERSION$APISEC_IMAGE_SUFFIX
        docker:
          user: root
     before_script:
       - whoami

    ジョブコンソール出力例:

    Executing "step_script" stage of the job script
    Using docker image sha256:8b95f188b37d6b342dc740f68557771bb214fe520a5dc78a88c7a9cc6a0f9901 for registry.gitlab.com/security-products/api-security:5 with digest registry.gitlab.com/security-products/api-security@sha256:092909baa2b41db8a7e3584f91b982174772abdfe8ceafc97cf567c3de3179d1 ...
    $ whoami
    root
    $ /peach/analyzer-api-security
    17:17:14 [INF] API Security: Gitlab API Security
    17:17:14 [INF] API Security: -------------------
    17:17:14 [INF] API Security:
    17:17:14 [INF] API Security: version: 5.7.0
  • コンテナをラップし、ビルド時に依存関係を追加します。このオプションには、rootよりも低い権限で実行できるという利点があり、一部の顧客にとっては要件となる場合があります。

    1. 既存のイメージをラップする新しいDockerfileを作成します。

      ARG SECURE_ANALYZERS_PREFIX
      ARG APISEC_IMAGE
      ARG APISEC_VERSION
      ARG APISEC_IMAGE_SUFFIX
      FROM $SECURE_ANALYZERS_PREFIX/$APISEC_IMAGE:$APISEC_VERSION$APISEC_IMAGE_SUFFIX
      USER root
      
      RUN pip install ...
      RUN apk add ...
      
      USER gitlab
    2. 新しいイメージをビルドし、APIセキュリティテストジョブが開始される前に、ローカルのコンテナレジストリにプッシュします。api_securityジョブが完了した後、イメージを削除する必要があります。

      TARGET_NAME=apisec-$CI_COMMIT_SHA
      docker build -t $TARGET_IMAGE \
        --build-arg "SECURE_ANALYZERS_PREFIX=$SECURE_ANALYZERS_PREFIX" \
        --build-arg "APISEC_IMAGE=$APISEC_IMAGE" \
        --build-arg "APISEC_VERSION=$APISEC_VERSION" \
        --build-arg "APISEC_IMAGE_SUFFIX=$APISEC_IMAGE_SUFFIX" \
        .
      docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
      docker push $TARGET_IMAGE
    3. api_securityジョブを拡張し、新しいイメージ名を使用します。

      api_security:
        image: apisec-$CI_COMMIT_SHA
    4. 一時的なコンテナをレジストリから削除します。コンテナイメージの削除に関する情報については、this documentation pageを参照してください。

  • GitLab Runnerの設定を変更し、no-new-privilegesフラグを無効にします。これはセキュリティ上の影響を及ぼす可能性があるため、運用チームおよびセキュリティチームと話し合う必要があります。

Index was outside the bounds of the array. at Peach.Web.Runner.Services.RunnerOptions.GetHeaders()

このエラーメッセージは、APIセキュリティテストアナライザーが、APISEC_REQUEST_HEADERSまたはAPISEC_REQUEST_HEADERS_BASE64設定変数の値を解析することができないことを示しています。

エラーメッセージ

このイシューは2つのエラーメッセージによって特定できます。最初のエラーメッセージはジョブコンソールの出力に表示され、2番目のエラーメッセージはgl-api-security-scanner.logファイルに表示されます。

ジョブコンソールからのエラーメッセージ:

05:48:38 [ERR] API Security: Testing failed: An unexpected exception occurred: Index was outside the bounds of the array.

gl_api_security-scanner.logからのエラーメッセージ:

08:45:43.616 [ERR] <Peach.Web.Core.Services.WebRunnerMachine> Unexpected exception in WebRunnerMachine::Run()
System.IndexOutOfRangeException: Index was outside the bounds of the array.
   at Peach.Web.Runner.Services.RunnerOptions.GetHeaders() in /builds/gitlab-org/security-products/analyzers/api-fuzzing-src/web/PeachWeb/Runner/Services/[RunnerOptions.cs:line 362
   at Peach.Web.Runner.Services.RunnerService.Start(Job job, IRunnerOptions options) in /builds/gitlab-org/security-products/analyzers/api-fuzzing-src/web/PeachWeb/Runner/Services/RunnerService.cs:line 67
   at Peach.Web.Core.Services.WebRunnerMachine.Run(IRunnerOptions runnerOptions, CancellationToken token) in /builds/gitlab-org/security-products/analyzers/api-fuzzing-src/web/PeachWeb/Core/Services/WebRunnerMachine.cs:line 321
08:45:43.634 [WRN] <Peach.Web.Core.Services.WebRunnerMachine> * Session failed: An unexpected exception occurred: Index was outside the bounds of the array.
08:45:43.677 [INF] <Peach.Web.Core.Services.WebRunnerMachine> Finished testing. Performed a total of 0 requests.

解決策

このイシューは、不正な形式のAPISEC_REQUEST_HEADERSまたはAPISEC_REQUEST_HEADERS_BASE64変数が原因で発生します。予期される形式は、Header: value構造の1つまたは複数のヘッダーをコンマで区切ったものです。解決策は、予期されるものと一致するように構文を修正することです。

有効な例:

  • Authorization: Bearer XYZ
  • X-Custom: Value,Authorization: Bearer XYZ

無効な例:

  • Header:,value
  • HeaderA: value,HeaderB:,HeaderC: value
  • Header