依存関係スキャン

依存関係スキャンはCI/CDパイプラインに統合され、アプリケーションの依存関係におけるセキュリティ脆弱性を自動的に識別します。ブランチをマージする前にスキャンすることで、マージリクエスト内のセキュリティイシューを即座に可視化できます。これにより、コードをマージする前に潜在的な脆弱性について情報に基づいた決定を下すことができます。

デフォルトでは、依存関係スキャンはランタイム、開発、および推移的（ネストされた）依存関係を含む、コード内のすべての依存関係を分析します。オプションで、開発依存関係をスキャンから除外することができます。

• 概要については、Dependency scanning - Advanced Security Testingを参照してください。
• この依存関係スキャンドキュメントのインタラクティブな閲覧とハウツーデモについては、How to use dependency scanning tutorial hands-on GitLabアプリケーションセキュリティpart 3を参照してください。
• その他のインタラクティブな解説およびハウツーデモについては、Get Started With GitLab Application Security Playlist（GitLabアプリケーションセキュリティ入門の再生リスト）をご覧ください。

パイプライン外の脆弱性スキャンについては、継続的脆弱性スキャンを参照してください。

依存関係スキャンを有効にする

プロジェクトで依存関係スキャンを有効にするには、以下の手順に従ってください。

アナライザーを有効にするには、次のいずれかの方法を使用します:

• Auto DevOpsを有効にします。これには、依存関係スキャンが含まれます。
• 事前設定されたマージリクエストを使用します。
• 依存関係スキャンを強制するスキャン実行ポリシーを作成します。
• .gitlab-ci.ymlファイルを手動で編集します。
• CI/CDコンポーネントを使用します。

事前設定されたマージリクエストを使用する

このメソッドは、.gitlab-ci.ymlファイルに依存関係スキャンのテンプレートを含むマージリクエストを自動的に準備します。そのマージリクエストをマージすると、依存関係スキャンが有効になります。

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。
• .gitlab-ci.ymlファイルにはtestステージが必要です。
• Self-Managed GitLab Runnerの場合は、dockerまたはkubernetes executorを備えたGitLab Runner。
• GitLab.com用のホストRunnerの場合、この設定はデフォルトで有効になっています。

依存関係スキャンを有効にするには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. セキュリティ > セキュリティ設定を選択します。
3. 依存関係スキャン行で、マージリクエスト経由で設定を選択します。
4. マージリクエストの作成を選択します。
5. マージリクエストをレビューして、マージを選択します。

パイプラインに依存関係スキャンジョブが含まれるようになりました。

.gitlab-ci.ymlファイルを手動で編集する

この方法では、既存の.gitlab-ci.ymlファイルを手動で編集する必要があります。GitLab CI/CD設定ファイルが複雑な場合は、この方法を使用してください。

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。
• .gitlab-ci.ymlファイルにはtestステージが必要です。
• Self-Managed GitLab Runnerの場合は、dockerまたはkubernetes executorを備えたGitLab Runner。
• GitLab.com用のホストRunnerの場合、この設定はデフォルトで有効になっています。

依存関係スキャンを有効にするには:

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

2. ビルド > パイプラインエディタを選択します。

3. .gitlab-ci.ymlファイルが存在しない場合は、パイプラインの設定を選択し、例のコンテンツを削除します。

4. 次の内容をコピーして、.gitlab-ci.ymlファイルの末尾に貼り付けます。include行がすでに存在する場合は、その下にtemplate行のみを追加します。

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

5. 検証タブを選択し、パイプラインの検証を選択します。

   シミュレーションが正常に完了しましたというメッセージは、ファイルが有効であることを裏付けています。

6. 編集タブを選択します。

7. フィールドに入力します。ブランチフィールドにデフォルトブランチを使用しないでください。

8. これらの変更で新しいマージリクエストを開始チェックボックスをオンにし、変更をコミットするを選択します。

9. 標準のワークフローに従ってフィールドに入力し、マージリクエストの作成を選択します。

10. 標準のワークフローに従ってマージリクエストをレビューおよび編集し、マージを選択します。

パイプラインに依存関係スキャンジョブが含まれるようになりました。

CI/CDコンポーネントを使用する

CI/CD componentsを使用して、アプリケーションの依存関係スキャンを実行します。手順については、それぞれのコンポーネントのReadmeファイルを参照してください。

使用可能なCI/CDコンポーネント

https://gitlab.com/explore/catalog/components/dependency-scanningを参照してください

これらのステップを完了すると、次のことができるようになります。

• 結果の把握方法について詳しく理解する。
• 他のプロジェクトへのロールアウトを計画する。

結果について理解する

依存関係スキャンの結果は、複数の形式で利用できます。それらはパイプラインUIで直接、詳細なスキャンレポートで、またはスキャン中に生成されたソフトウェア部品表（SBOM）で表示できます。

パイプライン内の脆弱性をレビュー

パイプラインで検出された脆弱性をレビューし、マージリクエストがマージされる前に対処してください。

前提条件:

• プロジェクトのデベロッパー、メンテナー、またはオーナーロール。

パイプラインで依存関係スキャンの結果をレビューするには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 左サイドバーで、ビルド > パイプラインを選択します。
3. パイプラインを選択します。
4. セキュリティタブを選択します。
5. 脆弱性を選択して、次の詳細を表示します。
   • ステータス: 脆弱性がトリアージされたか、解決されたかを示します。
   • 説明: 脆弱性の原因、潜在的な影響、推奨される修正手順について説明しています。
   • 重大度: 影響に基づいて6つのレベルに分類されます。重大度レベルの詳細はこちらをご覧ください。
   • CVSSスコア: 重大度にマップする数値を指定します。
   • EPSS: 脆弱性が実際に悪用される可能性を示します。
   • 既知の悪用された脆弱性（KEV）: 特定の脆弱性がすでに悪用されていることを示します。
   • プロジェクト: 脆弱性が特定されたプロジェクトを強調表示します。
   • レポートタイプ/スキャナー: 出力タイプと、その出力の生成に使用されたスキャナーについて説明しています。
   • 到達可能性: コード内で脆弱な依存関係が使用されているかどうかを示します。
   • スキャナー: 脆弱性を検出したアナライザーを示します。
   • 場所: 脆弱な依存関係が存在するファイル名を示します。
   • リンク: さまざまなアドバイザリーデータベースに登録されている脆弱性の証拠です。
   • 識別子: CVE識別子など、脆弱性の分類に使用される参照の一覧です。

依存関係スキャンレポート

依存関係スキャンは、すべての脆弱性の詳細を含むレポートを出力します。レポートは内部で処理され、結果はUIに表示されます。このレポートは、依存関係スキャンジョブのアーティファクトとしてgl-dependency-scanning-report.jsonという名前で出力され、常にプロジェクトのルートに生成されます。

依存関係スキャンレポートの詳細については、依存関係スキャンレポートスキーマを参照してください。

CycloneDXソフトウェア部品表

依存関係スキャンは、検出されたサポート対象のロックファイルまたはビルドファイルごとに、CycloneDXソフトウェア部品表（SBOM）を出力します。

CycloneDX SBOMの仕様は次のとおりです:

• gl-sbom-<package-type>-<package-manager>.cdx.jsonという名前が付けられます。
• 依存関係スキャンジョブのジョブアーティファクトとして利用できます。
• 検出されたロックファイルまたはビルドファイルと同じディレクトリに保存されます。

たとえば、プロジェクトに次の構造がある場合:

.
├── ruby-project/
│   └── Gemfile.lock
├── ruby-project-2/
│   └── Gemfile.lock
├── php-project/
│   └── composer.lock
└── go-project/
    └── go.sum

Gemnasiumスキャナーは次のCycloneDX SBOMを生成します。

.
├── ruby-project/
│   ├── Gemfile.lock
│   └── gl-sbom-gem-bundler.cdx.json
├── ruby-project-2/
│   ├── Gemfile.lock
│   └── gl-sbom-gem-bundler.cdx.json
├── php-project/
│   ├── composer.lock
│   └── gl-sbom-packagist-composer.cdx.json
└── go-project/
    ├── go.sum
    └── gl-sbom-go-go.cdx.json

ロールアウトする

単一のプロジェクトの依存関係スキャン結果に確信を持てたら、その実装を他のプロジェクトにも拡張できます:

• enforced scan executionを使用して、依存関係スキャン設定をグループ全体に適用します。
• 固有の要件がある場合、SBOMを使用した依存関係スキャンはオフライン環境で実行できます。

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

依存関係スキャンでサポートされている言語とパッケージマネージャーは次のとおりです:

脚注:

1. Java 21 LTSで使用する場合、sbtのバージョンは1.9.7に制限されます。より多くのsbtバージョンのサポートは、issue 430335で追跡できます。FIPSモードが有効になっている場合はサポートされません。
2. FIPSモードが有効になっている場合、Gradleはサポートされません。
3. pnpmのロックファイルはバンドルされた依存関係を保存しないため、レポートされた依存関係はNPMやyarnとは異なる場合があります。
4. poetry.lockファイルのないプロジェクトのサポートは、issue 32774で追跡されます。
5. sbt 1.0.xのサポートはGitLab 16.8で非推奨となり、GitLab 17.0で削除されました。
6. Maven 3.8.8未満のサポートは、GitLab 16.9で非推奨となり、GitLab 17.0で削除されました。
7. Pythonの以前のバージョンのサポートはGitLab 16.9で非推奨となり、GitLab 17.0で削除されました。
8. pipとsetuptoolsはインストーラーで必要とされるため、レポートから除外します。
9. アドバイザリーなしのSBOMのみ。issue 468764を参照してください。
10. ライセンス検出なし。epic 17037を参照してください。
11. ロックファイルに異なる環境マーカーを持つ同じパッケージの複数のエントリ（例：Python <3.11の場合はnumpy==2.2.6、Python ≥3.11の場合はnumpy==2.4.1）が含まれている場合、最初のエントリのみが解析され、報告されます。

サポートされている開発依存関係

開発依存関係の検出は、以下の言語とパッケージマネージャーでサポートされています:

マージリクエストパイプラインでジョブを実行する

マージリクエストパイプラインでセキュリティスキャンツールを使用するを参照してください。

アナライザーの動作をカスタマイズする

依存関係スキャンをカスタマイズするには、CI/CD変数を使用します。

依存関係スキャンジョブをオーバーライドする

ジョブ定義をオーバーライドする（variablesやdependenciesのようなプロパティを変更する場合など）には、オーバーライドするジョブと同じ名前で新しいジョブを宣言します。テンプレートの挿入後にこの新しいジョブを配置し、その下に追加のキーを指定します。

たとえば、これによりgemnasiumアナライザーの脆弱な依存関係の自動修正が無効になります:

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

gemnasium-dependency_scanning:
  variables:
    DS_REMEDIATE: "false"

dependencies: []属性をオーバーライドするには、前述のように、この属性をターゲットとするオーバーライドジョブを追加します。

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

gemnasium-dependency_scanning:
  dependencies: ["build"]

利用可能なCI/CD変数

CI/CD変数を使用して、依存関係スキャンの動作をカスタマイズできます。

グローバルアナライザーの設定

次の変数を使用すると、グローバルな依存関係スキャンを設定できます。

アナライザー固有の設定

次の変数は、特定の依存関係スキャンアナライザーの動作を設定します。

その他の変数

上記の表は、使用できる変数をすべて網羅したリストではありません。それらには、サポートおよびテストされているすべての特定のGitLabおよびアナライザー変数が含まれています。環境変数など、他の多くの変数も渡すことができ、正しく機能します。このリストは長く、完全に文書化されていません。

たとえば、GitLab以外の環境変数HTTPS_PROXYをすべての依存関係スキャンジョブに渡すには、お使いの.gitlab-ci.ymlファイルでCI/CD変数として次のように設定します:

variables:
  HTTPS_PROXY: "https://squid-proxy:3128"

あるいは、依存関係スキャンのような特定のジョブで使用することもできます:

dependency_scanning:
  variables:
    HTTPS_PROXY: $HTTPS_PROXY

すべての変数がテストされているわけではないため、一部は機能するが、他のものは機能しない場合があります。機能しないものが必要な場合は、submitting a feature requestを行うか、コードにコントリビュートして使用できるようにしてください。

カスタムTLS認証局

依存関係スキャンでは、アナライザーコンテナイメージに付属するデフォルトの代わりに、カスタムTLS証明書をSSL/TLS接続に使用できます。

次のバージョンで、カスタム認証局のサポートが導入されました。

カスタムTLS認証局

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。

カスタムTLS認証局を使用するには:

• text representation of the X.509 PEM public-key certificateをCI/CD変数ADDITIONAL_CA_CERT_BUNDLEに割り当てます。

たとえば、.gitlab-ci.ymlファイルで証明書を設定するには、次のようにします:

variables:
  ADDITIONAL_CA_CERT_BUNDLE: |
      -----BEGIN CERTIFICATE-----
      MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
      ...
      jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
      -----END CERTIFICATE-----

プライベートMavenリポジトリで認証する

依存アナライザーがプライベートMavenリポジトリで認証することを許可するには、CI/CDパイプラインで認証情報を設定する必要があります。認証がない場合、依存アナライザーはプライベート依存関係にアクセスできず、スキャンは失敗します。

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。

依存アナライザーがプライベートMavenリポジトリで認証することを許可するには:

1. Create a project CI/CD変数をMAVEN_CLI_OPTSという名前で作成し、その値に認証情報を含めるように設定します。

   たとえば、mysettings.xmlという名前の設定ファイル、myuserというユーザー名、verysecretというパスワードを想定した場合、MAVEN_CLI_OPTSCI/CD変数を次のように設定します:

   --settings mysettings.xml -Drepository.password=verysecret -Drepository.user=myuser

2. mysettings.xml Maven設定ファイルをサーバー設定で作成します。ファイル名は、ステップ1で--settingsオプションで指定した値と一致する必要があります。

   <!-- mysettings.xml -->
   <settings>
       ...
       <servers>
           <server>
               <id>private_server</id>
               <username>${repository.user}</username>
               <password>${repository.password}</password>
           </server>
       </servers>
   </settings>

FIPS対応イメージ

GitLabは、GemnasiumイメージのFIPS対応Red Hat UBIバージョンも提供しています。GitLabインスタンスでFIPSモードが有効になっている場合、GemnasiumスキャンジョブはFIPS対応イメージを自動的に使用します。FIPS対応イメージに手動で切り替えるには、変数DS_IMAGE_SUFFIXを"-fips"に設定します。

FIPSモードでは、Gradleプロジェクトの依存関係スキャンと、Yarnプロジェクトの自動修正はサポートされていません。

FIPS対応イメージは、RedHatのUBI microに基づいています。これらには、dnfやmicrodnfなどのパッケージマネージャーがないため、ランタイムにシステムパッケージをインストールすることはできません。

オフライン環境

インターネット経由で外部リソースへのアクセスが制限されている、または不安定な環境にあるインスタンスでは、依存関係スキャンジョブを正常に実行するためにいくつかの調整が必要です。詳細については、オフライン環境を参照してください。

前提条件:

• 管理者アクセス権が必要です。
• dockerまたはkubernetesのexecutorを備えたGitLab Runner
• 依存関係スキャンアナライザーイメージのローカルコピー
• Access to the GitLab advisory database
• パッケージメタデータデータベースへのアクセス

アナライザーイメージのローカルコピー

すべてのサポート対象言語とフレームワークで依存関係スキャンを使用するには:

1. registry.gitlab.comから、次のデフォルトの依存関係スキャンアナライザーイメージをローカルのDockerコンテナレジストリにインポートします。

   registry.gitlab.com/security-products/gemnasium:6
   registry.gitlab.com/security-products/gemnasium:6-fips
   registry.gitlab.com/security-products/gemnasium-maven:6
   registry.gitlab.com/security-products/gemnasium-maven:6-fips
   registry.gitlab.com/security-products/gemnasium-python:6
   registry.gitlab.com/security-products/gemnasium-python:6-fips

   DockerイメージをローカルのオフラインDockerレジストリにインポートするプロセスは、ネットワークのセキュリティポリシーによって異なります。IT部門に相談して、外部リソースをインポートまたは一時的にアクセスするための承認済みプロセスを確認してください。これらのスキャナーは新しい定義で定期的に更新されるため、定期的にダウンロードすることをおすすめします。

2. ローカルアナライザーを使用するようにGitLab CI/CDを設定します。

   CI/CD変数SECURE_ANALYZERS_PREFIXの値をローカルのDockerレジストリに設定します。この例では、docker-registry.example.comです。

   include:
     - template: Jobs/Dependency-Scanning.gitlab-ci.yml
   
   variables:
     SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers"

GitLabアドバイザリデータベースへのアクセス

GitLab advisory databaseは、gemnasium、gemnasium-maven、およびgemnasium-pythonアナライザーによって使用される脆弱性データのソースです。これらのアナライザーのDockerイメージには、このデータベースのクローンが含まれています。アナライザーが最新の脆弱性データを使用できるように、スキャンを開始する前にクローンはデータベースと同期されます。

オフライン環境では、GitLabアドバイザリデータベースのデフォルトホストにアクセスできません。代わりに、GitLab Runnerからアクセスできる場所にデータベースをホスティングする必要があります。また、独自のスケジュールでデータベースを手動で更新する必要もあります。

データベースをホスティングするために利用可能なオプションは次のとおりです。

• Use a clone of the GitLab advisory database。
• Use a copy of the GitLab advisory database。

GitLabアドバイザリデータベースのクローンを使用する

GitLabアドバイザリデータベースのクローンを使用することは、最も効率的な方法であるため推奨されます。

GitLabアドバイザリデータベースのクローンをホストするには:

1. GitLabアドバイザリデータベースを、GitLab RunnerからHTTPでアクセス可能なホストにクローンします。
2. .gitlab-ci.ymlファイルで、CI/CD変数GEMNASIUM_DB_REMOTE_URLの値をGitリポジトリのURLに設定します。

例:

variables:
  GEMNASIUM_DB_REMOTE_URL: https://users-own-copy.example.com/gemnasium-db.git

GitLabアドバイザリデータベースのコピーを使用する

GitLabアドバイザリデータベースのコピーを使用するには、アナライザーによってダウンロードされるアーカイブファイルをホストする必要があります。

GitLabアドバイザリデータベースのコピーを使用するには:

1. GitLabアドバイザリデータベースのアーカイブを、GitLab RunnerからHTTPでアクセス可能なホストにダウンロードします。アーカイブは次の場所にあります。https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/archive/master/gemnasium-db-master.tar.gz

2. .gitlab-ci.ymlファイルを更新します。

   • データベースのローカルコピーを使用するようにCI/CD変数GEMNASIUM_DB_LOCAL_PATHを設定します。
   • データベースの更新を無効にするようにCI/CD変数GEMNASIUM_DB_UPDATE_DISABLEDを設定します。
   • スキャンが開始される前に、セキュリティアドバイザリーデータベースをダウンロードして展開します。
   variables:
     GEMNASIUM_DB_LOCAL_PATH: ./gemnasium-db-local
     GEMNASIUM_DB_UPDATE_DISABLED: "true"
   
   dependency_scanning:
     before_script:
       - wget https://local.example.com/gemnasium_db.tar.gz
       - mkdir -p $GEMNASIUM_DB_LOCAL_PATH
       - tar -xzvf gemnasium_db.tar.gz --strip-components=1 -C $GEMNASIUM_DB_LOCAL_PATH

Gradleプロジェクトでプロキシを使用する

Gradleラッパースクリプトは、HTTP(S)_PROXY環境変数を読み取りません。詳細については、Gradle issue 11065を参照してください。

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。

Gradleラッパースクリプトでプロキシを使用するには:

• GRADLE_CLI_OPTSCI/CD変数を使用してプロキシオプションを指定します:

  variables:
    GRADLE_CLI_OPTS: "-Dhttps.proxyHost=squid-proxy -Dhttps.proxyPort=3128 -Dhttp.proxyHost=squid-proxy -Dhttp.proxyPort=3128 -Dhttp.nonProxyHosts=localhost"

Mavenプロジェクトでプロキシを使用する

MavenはHTTP(S)_PROXY環境変数を読み込みません。代わりにMaven設定ファイルを使用する必要があります。

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。

Maven依存スキャナーがプロキシを使用するように設定するには:

1. プロジェクトのリポジトリにmysettings.xmlファイルを作成します。そのファイルでMavenプロキシ設定を設定します。

   プロキシ設定の指定方法の詳細については、Maven documentationを参照してください。

2. プロジェクトの.gitlab-ci.ymlファイルでMAVEN_CLI_OPTSCI/CD変数を定義し、設定ファイルmysettings.xmlを参照します。

   variables:
     MAVEN_CLI_OPTS: "--settings mysettings.xml"

言語およびパッケージマネージャー固有の設定

特定の言語とパッケージマネージャーの設定については、次のセクションを参照してください。

Python（Pip）

アナライザーの実行前にPythonパッケージをインストールする必要がある場合は、スキャンジョブのbefore_scriptでpip install --userを使用する必要があります。--userフラグを指定すると、プロジェクトの依存関係がユーザーディレクトリにインストールされます。--userオプションを指定しない場合、パッケージはグローバルにインストールされ、スキャンされず、プロジェクトの依存関係一覧にも表示されません。

Python（setuptools）

アナライザーの実行前にPythonパッケージをインストールする必要がある場合は、スキャンジョブのbefore_scriptでpython setup.py install --userを使用する必要があります。--userフラグを指定すると、プロジェクトの依存関係がユーザーディレクトリにインストールされます。--userオプションを指定しない場合、パッケージはグローバルにインストールされ、スキャンされず、プロジェクトの依存関係一覧にも表示されません。

プライベートPyPiリポジトリに自己署名証明書を使用する場合、（上記の.gitlab-ci.ymlのテンプレート以外に）追加のジョブ設定は必要ありません。ただし、プライベートリポジトリにアクセスできるように、setup.pyを更新する必要があります。設定例を次に示します。

1. setup.pyを更新して、install_requiresリストの各依存関係に対して、プライベートリポジトリを指すdependency_links属性を作成します。

   install_requires=['pyparsing>=2.0.3'],
   dependency_links=['https://pypi.example.com/simple/pyparsing'],

2. リポジトリURLから証明書をフェッチし、プロジェクトに追加します。

   printf "\n" | openssl s_client -connect pypi.example.com:443 -servername pypi.example.com | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt

3. 新しくダウンロードした証明書を参照するよう、setup.pyで指定します。

   import setuptools.ssl_support
   setuptools.ssl_support.cert_paths = ['internal.crt']

Python（Pipenv）

ネットワーク接続が制限された環境で実行する場合は、プライベートPyPiミラーを使用するようにPIPENV_PYPI_MIRROR変数を設定する必要があります。このミラーには、デフォルト依存関係と開発依存関係の両方が含まれている必要があります。

variables:
  PIPENV_PYPI_MIRROR: https://pypi.example.com/simple

または、プライベートレジストリを使用できない場合は、必要なパッケージをPipenv仮想環境キャッシュに読み込むことができます。このオプションでは、プロジェクトはPipfile.lockをリポジトリにチェックインし、デフォルトパッケージと開発パッケージの両方をキャッシュに読み込む必要があります。この手順の例については、python-pipenvプロジェクトのサンプルを参照してください。

依存関係の検出

依存関係スキャンは、リポジトリで使用されている言語を自動的に検出します。検出された言語に一致するすべてのアナライザーが実行されます。通常、アナライザーの選択をカスタマイズする必要はありません。アナライザーを指定しないでください。そうすることで、最適なカバレッジのためにすべての選択肢を自動的に使用し、非推奨化や削除があった場合の調整の必要を回避できます。なお、変数DS_EXCLUDED_ANALYZERSを使用して、アナライザーの選択をオーバーライドできます。

言語の検出は、サポートされている依存関係ファイルを検出するCIジョブrulesに依存しています。

JavaおよびPythonの場合、サポートされている依存ファイルが検出されると、依存関係スキャンはプロジェクトをビルドし、いくつかのJavaまたはPythonコマンドを実行して依存関係のリストを取得しようとします。他のすべてのプロジェクトの場合、ロックファイルはプロジェクトを最初にビルドすることなく、依存関係のリストを取得するために解析されます。

すべての直接および推移的な依存関係が分析されます。推移的な依存関係の深さに制限はありません。

アナライザー

依存関係スキャンは、以下の公式Gemnasium-basedアナライザーをサポートしています:

• gemnasium
• gemnasium-maven
• gemnasium-python

アナライザーはDockerイメージとして公開されており、依存関係スキャンはそれを使用して各分析専用のコンテナを起動します。カスタムセキュリティスキャナーを統合することもできます。

各アナライザーは、Gemnasiumの新しいバージョンがリリースされるたびに更新されます。

アナライザーが依存関係情報を取得する方法

GitLabアナライザーは、次の2つの方法のいずれかを使用して依存関係情報を取得します。

1. ロックファイルを直接解析する。
2. パッケージマネージャーまたはビルドツールを実行して、解析される依存関係情報ファイルを生成する。

ロックファイルを解析して依存関係情報を取得する

次のパッケージマネージャーは、GitLabアナライザーが直接解析できるロックファイルを使用します。

脚注:

1. NuGetバージョン2のロックファイルのサポートは、GitLab 16.2で導入されました。

2. Yarnバージョン4のサポートは、GitLab 16.11で導入されました。

   Yarn Berryでは、次の機能はサポートされていません。

   • ワークスペース
   • yarn patch

   パッチ、ワークスペース、またはその両方を含むYarnファイルは引き続き処理されますが、これらの機能は無視されます。

パッケージマネージャーを実行して解析可能なファイルを生成することにより、依存関係情報を取得する

次のパッケージマネージャーをサポートするために、GitLabアナライザーは次の2つのステップで実行されます。

1. パッケージマネージャーまたは特定のタスクを実行して、依存関係情報をエクスポートします。
2. エクスポートされた依存関係情報を解析します。

脚注:

1. このテストでは、.tool-versionsファイルで指定されたmavenのデフォルトバージョンを使用します。
2. Javaのバージョンによって、必要なGradleのバージョンが異なります。上記の表にリストされているGradleのバージョンは、アナライザーイメージにプリインストールされています。アナライザーが使用するGradleのバージョンは、プロジェクトがgradlew（Gradleラッパー）ファイルを使用するかどうかによって異なります:

   • プロジェクトがgradlewファイルを使用しない場合、アナライザーはDS_JAVA_VERSION変数で指定されたJavaのバージョン（デフォルトバージョンは17）に基づいて、プリインストールされているGradleのいずれかのバージョンに自動的に切り替わります。

     Javaバージョン8および11ではGradle 6.7.1が自動的に選択され、Java 17ではGradle 7.6.4、Java 21ではGradle 8.8が使用されます。

   • プロジェクトがgradlewファイルを使用する場合、アナライザーイメージにプリインストールされているGradleのバージョンは無視され、gradlewファイルで指定されたバージョンが代わりに使用されます。

3. このテストでは、Pipfile.lockファイルが見つかった場合、Gemnasiumによってこのファイルにリストされている正確なパッケージバージョンをスキャンするために使用されることを確認します。
4. go buildの実装のため、Goのビルドプロセスにはネットワークアクセス、go mod downloadを使用したプリロードされたmodキャッシュ、またはベンダー依存関係が必要です。詳細については、Go documentation on compilingパッケージs and依存enciesを参照してください。

アナライザーのトリガー方法

GitLabは、rules:existsに依存し、サポートされているファイルがリポジトリに存在するかどうかに基づいて検出された言語に関連するアナライザーを起動します。リポジトリのルートから最大2階層下のディレクトリまでが検索対象となります。たとえば、リポジトリにGemfile、api/Gemfile、またはapi/client/Gemfileのいずれかが存在する場合、gemnasium-dependency_scanningジョブは有効になりますが、サポートされている依存関係ファイルがapi/v1/client/Gemfileのみの場合は有効になりません。

複数ファイルの処理方法

Python

GitLabは、要求ファイルまたはロックファイルが検出されたディレクトリで1つのインストールのみを実行します。依存関係は、検出された最初のファイルについてのみgemnasium-pythonによって分析されます。ファイルは次の順序で検索されます。

1. Pipを使用するプロジェクトの場合は、requirements.txt、requirements.pip、またはrequires.txt。
2. Pipenvを使用するプロジェクトの場合は、PipfileまたはPipfile.lock。
3. Poetryを使用するプロジェクトの場合は、poetry.lock。
4. Setuptoolsを使用するプロジェクトの場合は、setup.py。

検索はルートディレクトリから開始し、ルートディレクトリにビルドが見つからなかった場合はサブディレクトリに進みます。その結果、ルートディレクトリにあるPoetryのロックファイルは、サブディレクトリにあるPipenvファイルよりも先に検出されます。

JavaとScala

GitLabは、ビルドファイルが検出されたディレクトリで1つのビルドのみを実行します。複数のGradle、Maven、またはsbtビルド、あるいはこれらの組み合わせを含む大規模なプロジェクトの場合、gemnasium-mavenは最初に検出されたビルドファイルについてのみ依存関係を分析します。ビルドファイルは次の順序で検索されます。

1. 単一モジュールまたはマルチモジュールのMavenプロジェクトの場合は、pom.xml。
2. 単一プロジェクトまたはマルチプロジェクトのGradleビルドの場合は、build.gradleまたはbuild.gradle.kts。
3. 単一プロジェクトまたはマルチプロジェクトのsbtビルドの場合は、build.sbt。

検索はルートディレクトリから開始し、ルートディレクトリにビルドが見つからなかった場合はサブディレクトリに進みます。そのため、サブディレクトリ内のGradleビルドファイルよりも、ルートディレクトリ内のsbtビルドファイルが先に検出されます。マルチモジュールのMavenプロジェクト、マルチプロジェクトのGradleおよびsbtビルドの場合、親ビルドファイルで宣言されている場合に限り、サブモジュールファイルやサブプロジェクトファイルも分析されます。

JavaScript

次のアナライザーが実行されます。複数のファイルを処理する際の動作はそれぞれ異なります。

• Gemnasium

  複数のロックファイルをサポートしています。

• Retire.js

  複数のロックファイルをサポートしていません。複数のロックファイルが存在する場合、Retire.jsはディレクトリツリーをアルファベット順に走査し、最初に検出されたロックファイルを分析します。

gemnasiumアナライザーのスキャンは、JavaScriptプロジェクト内のベンダー化されたライブラリ（プロジェクトにチェックインされているが、パッケージマネージャーによって管理されていないライブラリ）をサポートしています。

Go

複数のファイルがサポートされています。go.modファイルが検出されると、アナライザーは最小バージョン選択を使用してビルドリストを生成しようとします。これに失敗した場合、アナライザーは代わりにgo.modファイル内の依存関係を解析しようとします。

要件として、依存関係を適切に管理するために、go mod tidyコマンドを実行してgo.modファイルをクリーンアップする必要があります。このプロセスは、検出されたすべてのgo.modファイルに対して繰り返されます。

PHP、C、C++、.NET、C#、Ruby、JavaScript

これらの言語のアナライザーは、複数のロックファイルをサポートしています。

追加言語のサポート

追加の言語、依存関係マネージャー、依存関係ファイルのサポートは、次のイシューで追跡されています。

警告

すべてのコンテナの最新バージョン、およびすべてのパッケージマネージャーと言語の最新のサポートされているバージョンを使用してください。以前のバージョンを使用すると、サポートされていないバージョンはアクティブなセキュリティレポートやセキュリティ修正のバックポートの恩恵を受けられなくなる可能性があるため、セキュリティリスクが高まります。

Gradleプロジェクト

GradleプロジェクトのHTML依存関係レポートを生成するときは、reports.html.destinationまたはreports.html.outputLocationプロパティをオーバーライドしないでください。そうしないと、依存関係スキャンが正しく機能しなくなります。

Mavenプロジェクト

分離されたネットワークでは、中央リポジトリがプライベートレジストリ（<mirror>ディレクティブで明示的に設定）の場合、Mavenビルドがgemnasium-maven-plugin依存関係を見つけられない場合があります。この問題は、Mavenがデフォルトでローカルリポジトリ（/root/.m2）を検索せず、中央リポジトリからフェッチしようとするために発生します。その結果、依存関係が見つからないというエラーが発生します。

回避策

この問題を解決するには、settings.xmlファイルに<pluginRepositories>セクションを追加します。これにより、Mavenはローカルリポジトリでプラグインを見つけることができます。

はじめる前に、次の点を考慮してください。

• この回避策は、デフォルトのMavenの中央リポジトリがプライベートレジストリにミラーリングされている環境でのみ有効です。
• この回避策を適用すると、Mavenはローカルリポジトリでプラグインを検索しますが、これは一部の環境ではセキュリティに影響を与える可能性があります。この方法が組織のセキュリティポリシーに準拠していることを確認してください。

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。

次の手順に従って、settings.xmlファイルを変更します。

1. Mavenのsettings.xmlファイルを見つけます。このファイルは通常、次のいずれかの場所にあります。

   • ルートユーザー: /root/.m2/settings.xml
   • 標準ユーザー: ~/.m2/settings.xml
   • グローバル設定: ${maven.home}/conf/settings.xml

2. ファイルに既存の<pluginRepositories>セクションがあるかどうかを確認します。

3. <pluginRepositories>セクションがすでに存在する場合は、次の<pluginRepository>要素のみをその中に追加します。存在しない場合は、次の<pluginRepositories>セクション全体を追加します。

     <pluginRepositories>
       <pluginRepository>
           <id>local2</id>
           <name>local repository</name>
           <url>file:///root/.m2/repository/</url>
       </pluginRepository>
     </pluginRepositories>

4. Mavenビルドまたは依存関係スキャンプロセスを再度実行します。

Pythonプロジェクト

PIP_EXTRA_INDEX_URL環境変数を使用する場合は、CVE-2018-20225で文書化されている脆弱性を悪用される可能性があるため、特に注意が必要です。

バージョン番号の解析

場合によっては、プロジェクトの依存関係のバージョンがセキュリティ勧告の影響範囲に含まれているかどうかを判定できないことがあります。

例:

• バージョンが不明である。
• バージョンが無効である。
• バージョンの解析や範囲との比較ができない。
• バージョンがdev-masterまたは1.5.xのようなブランチである。
• 比較されるバージョンがあいまいである。たとえば、1.0.0-20241502にはタイムスタンプが含まれていますが、1.0.0-2には含まれていないため、これらのバージョンは比較できません。

このような場合、アナライザーは依存関係をスキップし、ログにメッセージを出力します。

GitLabアナライザーは、誤検出や検出漏れにつながる可能性があるため、推測は行いません。ディスカッションについては、イシュー442027を参照してください。

Swiftプロジェクトをビルドする

Swift Package Manager（SPM）は、Swiftコードの配布を管理するための公式ツールです。Swiftビルドシステムと統合されており、依存関係のダウンロード、コンパイル、リンクのプロセスを自動化します。

SPMを使用してSwiftプロジェクトをビルドするときは、次のベストプラクティスに従ってください。

1. Package.resolvedファイルを含めます。

   Package.resolvedファイルは、依存関係を特定のバージョンに固定します。さまざまな環境で一貫性を確保するために、常にこのファイルをリポジトリにコミットしてください。

   git add Package.resolved
   git commit -m "Add Package.resolved to lock dependencies"

2. Swiftプロジェクトをビルドするには、次のコマンドを実行します。

   # Update dependencies
   swift package update
   
   # Build the project
   swift build

3. CI/CDを設定するには、次のステップを.gitlab-ci.ymlファイルに追加します。

   swift-build:
     stage: build
     script:
       - swift package update
       - swift build

4. オプション。自己署名証明書を含むプライベートSwiftパッケージリポジトリを使用する場合は、証明書をプロジェクトに追加し、Swiftにそれを信頼させるための設定が必要になることがあります。

   1. 証明書をフェッチします。

      echo | openssl s_client -servername your.repo.url -connect your.repo.url:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END
      CERTIFICATE-/p' > repo-cert.crt

   2. 次の行をSwiftパッケージマニフェスト（Package.swift）に追加します。

      import Foundation
      
      #if canImport(Security)
      import Security
      #endif
      
      extension Package {
          public static func addCustomCertificate() {
              guard let certPath = Bundle.module.path(forResource: "repo-cert", ofType: "crt") else {
                  fatalError("Certificate not found")
              }
              SecCertificateAddToSystemStore(SecCertificateCreateWithData(nil, try! Data(contentsOf: URL(fileURLWithPath: certPath)) as CFData)!)
          }
      }
      
      // Call this before defining your package
      Package.addCustomCertificate()

依存関係が正しく指定され、自動的に解決されるように、常にクリーンな環境でビルドプロセスをテストしてください。

CocoaPodsプロジェクトをビルドする

CocoaPodsは、SwiftおよびObjective-CのCocoaプロジェクト向けの一般的な依存関係管理システムです。iOS、macOS、watchOS、tvOSプロジェクトで外部ライブラリを管理するための標準形式を提供します。

CocoaPodsを依存関係管理に使用するプロジェクトをビルドするときは、次のベストプラクティスに従ってください。

1. Podfile.lockファイルを含めます。

   Podfile.lockファイルは、依存関係を特定のバージョンに固定するために非常に重要です。さまざまな環境で一貫性を確保するために、常にこのファイルをリポジトリにコミットしてください。

   git add Podfile.lock
   git commit -m "Add Podfile.lock to lock CocoaPods dependencies"

2. 次のいずれかを使用してプロジェクトをビルドできます。

   • xcodebuildコマンドラインツール:

     # Install CocoaPods dependencies
     pod install
     
     # Build the project
     xcodebuild -workspace YourWorkspace.xcworkspace -scheme YourScheme build

   • Xcode IDE:

     1. Xcodeで.xcworkspaceファイルを開きます。
     2. ターゲットスキームを選択します。
     3. Product > ビルドを選択します。または、⌘+Bを押します。

   • fastlane（iOSおよびAndroidアプリのビルドとリリースを自動化するためのツール）:

     1. fastlaneをインストールします。

        sudo gem install fastlane

     2. プロジェクトで、fastlaneを設定します。

        fastlane init

     3. レーンをfastfileに追加します。

        lane :build do
          cocoapods
          gym(scheme: "YourScheme")
        end

     4. ビルドを実行します。

        fastlane build

   • プロジェクトでCocoaPodsとCarthageの両方を使用している場合は、Carthageを使用して依存関係をビルドできます。

     1. CocoaPodsの依存関係を含むCartfileを作成します。

     2. 次のコマンドを実行します。

        carthage update --platform iOS

3. 好みの方法でプロジェクトをビルドするようにCI/CDを設定します。

   たとえば、xcodebuildを使用する場合:

   cocoapods-build:
     stage: build
     script:
       - pod install
       - xcodebuild -workspace YourWorkspace.xcworkspace -scheme YourScheme build

4. オプション。プライベートCocoaPodsリポジトリを使用する場合は、それらにアクセスするためにプロジェクトの設定が必要になることがあります。

   1. プライベートspecリポジトリを追加します。

      pod repo add REPO_NAME SOURCE_URL

   2. Podfileで、ソースを指定します。

      source 'https://github.com/CocoaPods/Specs.git'
      source 'SOURCE_URL'

5. オプション。プライベートCocoaPodsリポジトリがSSLを使用している場合は、SSL証明書が正しく設定されていることを確認してください。

   • 自己署名証明書を使用する場合は、システムの信頼できる証明書に追加します。また、.netrcファイルでSSL設定を指定することもできます。

     machine your.private.repo.url
       login your_username
       password your_password

6. Podfileを更新した後、pod installを実行して依存関係をインストールし、ワークスペースを更新します。

Podfileを更新した後は、常にpod installを実行して、すべての依存関係が正しくインストールされ、ワークスペースが更新されていることを確認してください。

脆弱性データベースにコントリビュートする

脆弱性を検索するには、GitLab advisory databaseを検索します。新しい脆弱性を送信することもできます。