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

静的到達可能性分析

  • プラン: Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated
  • ステータス: 限定提供

依存関係スキャンは、プロジェクト内のすべての脆弱な依存関係を特定します。ただし、すべての脆弱性が同等のリスクをもたらすわけではありません。静的到達可能性分析は、到達可能な脆弱なパッケージ、つまりアプリケーションによってインポートされるパッケージを特定することで、修正の優先順位付けに役立ちます。到達可能な脆弱性に焦点を当てることで、静的到達可能性分析は、理論的なリスクではなく、実際の脅威への曝露に基づいて修正の優先順位を付けることを可能にします。

静的到達可能性分析は、プロジェクトのソースcodeコードを分析し、SBOMからのどの依存が到達可能であるかを判断することで機能します。依存関係スキャンは、すべてのコンポーネントとその推移的な依存を特定するSBOMレポートを生成します。次に、静的到達可能性分析はSBOM内の各依存をチェックし、到達可能性の値を追加して、実際の使用データをレポートを充実させます。この充実したSBOMは、GitLabによってインジェストされ、脆弱性の検出結果を補完します。

SBOMは、SBOMファイルとソースcodeコードファイルの両方が同じプロジェクトディレクトリツリーに属している場合にのみ充実されます。複数のネストされたプロジェクトが存在する場合、システムは最も近い（最も深い）プロジェクトパスを選択して充実を決定します。静的到達可能性分析は、SBOMからのパッケージ名をPythonおよびJavaパッケージの対応するcodeコードインポートパスにマップするメタデータに依存します。このメタデータは毎週更新され、メンテナンスされています。

静的到達可能性分析は本番環境対応です。ただし、依存関係スキャン（SBOMによる）に依存しているため、提供は限定的であり、これも同じステータスです。

イシュー535498でフィードバックを共有してください。

静的到達可能性分析を有効にする

前提条件:

  • プロジェクトのデベロッパー、メンテナー、またはオーナーロール。
  • プロジェクトはサポートされている言語とパッケージマネージャーを使用しています。
  • 依存関係スキャンアナライザーバージョン0.39.0以降（以前のバージョンは特定の言語をサポートする場合があります。Historyを参照）。
  • プロジェクトでSBOMを使用した依存関係スキャンが有効になっていること。Gemnasiumアナライザーはサポートされていません。
  • 言語固有の前提条件:
    • Python:
      • 依存関係グラフファイルは、buildジョブのアーティファクトとしてパイプラインステージで提供する必要があります。Pipまたはpipenvの手順を参照してください。その他のサポートされているPythonパッケージマネージャーについては、依存関係スキャンアナライザードキュメントを参照してください。
    • JavaScriptおよびTypeScript:
      • リポジトリには、依存関係スキャンアナライザーによってサポートされているロックファイルが含まれている必要があります。
    • Java:
      • 依存関係グラフファイルは、buildジョブのアーティファクトとしてパイプラインステージで提供する必要があります。MavenまたはGradleの手順を参照してください。

静的到達可能性分析はジョブの実行時間を増加させます。

プロジェクトで静的到達可能性分析を有効にするには:

  1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。

  2. コード > リポジトリを選択します。

  3. .gitlab-ci.ymlファイルを選択します。

  4. 編集 > 単一のファイルを編集を選択します。

  5. 次の設定を追加します:

    include:
- template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml

variables:
  DS_STATIC_REACHABILITY_ENABLED: true

  6. 変更をコミットするを選択します。

依存関係スキャンが実行され、SBOMを出力すると、その結果は静的到達可能性分析によって補完されます。

到達可能性の値

ひとつの依存には、次のいずれかの到達可能性の値があります。はいとマークされた依存のトリアージと修正を優先してください。これは、これらの依存がcodeコードで使用されていることが確認されているためです。

はい : この脆弱性にリンクされているパッケージは、codeコードで到達可能であることが確認されています。直接の依存関係が到達可能とマークされている場合、その推移的な依存も到達可能とマークされます。

未検出 : 静的到達可能性分析は正常に実行されましたが、脆弱なパッケージの使用は検出されませんでした。

利用不可 : 静的到達可能性分析は実行されなかったため、到達可能性データは存在しません。

脆弱な依存関係の到達可能性の値を見つけるには:

  • 脆弱性レポートで、重大度の値にカーソルを合わせます。
  • 脆弱性の詳細ページで、Reachableの値を確認します。
  • GraphQLのクエリを使用して、到達可能な脆弱性を一覧表示します。

「未検出」の結果

Not Foundの到達可能性の値は、依存が使用されていないことを保証するものではありません。静的到達可能性分析では、パッケージの使用状況を常に明確に判断できるわけではないためです。

依存は、次の場合に未検出とマークされます:

  • ロックファイルには表示されるものの、codeコードでインポートされていない場合。
  • 除外されたディレクトリにある場合（たとえば、DS_EXCLUDED_PATHSで設定されている場合）。
  • ローカルでの使用のみを目的としたツールである場合（カバレッジテストやLintするパッケージなど）。

除外されたディレクトリの次の例を考慮してください。あなたはCI/CD変数DS_EXCLUDED_PATHS="test"を定義しました。プロジェクトのリポジトリ構造は次のとおりです。

.
├── pipdeptree.json  // contains "requests" dependency
└── test/
    └── app.py       // imports "requests" dependency

この例では、codeグラフファイルpipdeptree.jsonは除外されたディレクトリの外にあり、ファイルにリストされている依存を特定するために分析されます。ただし、requests依存をインポートするソースcodeコードは除外されたディレクトリ内にあるため、静的到達可能性分析はその到達可能性をチェックしません。その結果、requests依存はお探しのページが見つかりませんでしたとしてラベル付けされます。言い換えれば、ロックファイルが除外されたディレクトリの外にあるが、依存をインポートするcodeコードがその中にある場合にこれが発生します。

サポートされている言語とパッケージマネージャー

サポートは言語の成熟度によって異なり、各言語に固有のパッケージマネージャーとファイルタイプが含まれます。

言語成熟度サポートされているパッケージマネージャーサポートされているファイルタイプ
Python1ベータ版pip、pipenv2、poetry、uv.py
JavaScript/TypeScript3ベータ版npm、pnpm、yarn.js、.ts
Java4ベータ版maven5、gradle6.java

脚注:

  1. pipdeptreeで依存関係スキャンを使用する場合、オプションの依存は推移的な依存ではなく、直接の依存関係としてマークされます。静的到達可能性分析では、それらのパッケージが使用中であると識別できない場合があります。たとえば、passlib[bcrypt]を要求すると、passlibがin_useとマークされ、bcryptがnot_foundとマークされる可能性があります。詳細については、Pipを参照してください。
  2. Python pipenvの場合、静的到達可能性分析はPipfile.lockファイルをサポートしていません。依存関係グラフをサポートしているため、pipenv.graph.jsonのみがサポートされます。
  3. フロントエンドフレームワークのサポートはありません。
  4. Javaの動的な特性により、最新のフレームワークを使用するプロジェクトでは誤検出の割合が高くなる可能性のある、次の問題が発生します:
    • 静的到達可能性分析は、ソースcodeコード内の直接のインポート、Javaリフレクションパターン、およびJavaデータベース接続文字列を介した明示的な使用状況を検出します。ランタイム時に動的に読み込まれる依存（Spring Bootのような依存性インジェクションフレームワークを使用するものなど）を特定することはできません。
    • カバレッジは、GitLabアドバイザリデータベース内のパッケージと、Maven Centralで最も広く依存されているパッケージに限定されます。
  5. Mavenの手順で説明されているように、maven.graph.jsonファイルを使用します。
  6. Gradleの手順で説明されているように、依存ロックファイルを使用します。

オフライン環境

オフライン環境で静的到達可能性分析を実行するには、初期設定と継続的なメンテナンスを行う必要があります。

初期設定:

継続的なメンテナンス:

  • 新しいバージョンがリリースされるたびに、ローカルの依存関係スキャン（SBOM）イメージを更新してください。

PythonおよびJavaパッケージの場合、静的到達可能性分析は、SBOMからのパッケージ名を対応するcodeコードインポートパスにマップするためにメタデータを使用します。このメタデータは、依存関係スキャンアナライザーのイメージに含まれています。古いメタデータは、不完全または不正確な到達可能性分析につながる可能性があります。