依存関係スキャン

依存関係スキャンは、本番環境に移行する前に、アプリケーションの依存関係にあるセキュリティの脆弱性を特定します。この特定により、ユーザーの信頼やビジネスの評判を損なう可能性のある潜在的なエクスプロイトやデータ漏洩からアプリケーションを保護します。パイプラインの実行中に脆弱性が検出された場合は、コードがコミットされる前にセキュリティ上の問題をすぐに確認できるように、マージリクエストに直接表示されます。

推移的な（ネストされた）依存関係を含むコード内のすべての依存関係は、パイプラインの実行中に自動的に分析されます。この分析により、手動レビュープロセスでは見落とす可能性のあるセキュリティ上の問題が検出されます。依存関係スキャンは、最小限の設定変更で既存のCI/CDワークフローに統合されるため、初日から安全な開発プラクティスを簡単に実装できます。

脆弱性は、継続的脆弱性スキャンによってパイプラインの外部で識別することもできます。

GitLabは、これらのすべての依存関係タイプを確実に網羅するために、依存関係スキャンとコンテナスキャンの両方を提供しています。リスク領域をできるだけ広くカバーするために、すべてのセキュリティスキャナーを使用することをおすすめします。これらの機能の比較については、依存関係スキャンとコンテナスキャンの比較を参照してください。

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

はじめに

依存関係スキャンを開始するにあたり、プロジェクトの依存関係スキャンを有効にする手順は次のとおりです。

前提要件:

• .gitlab-ci.ymlファイルにはtestステージが必要です。
• Self-Managed Runnerを使用する場合、dockerまたはkubernetes executorを備えたGitLab Runnerが必要です。
• GitLab.comでSaaS Runnerを使用している場合、これはデフォルトで有効になっています。

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

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

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

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

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

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. セキュリティ > セキュリティ設定を選択します。
3. 依存関係スキャン行で、マージリクエスト経由で設定を選択します。
4. マージリクエストを作成を選択します。
5. マージリクエストをレビューして、マージを選択します。

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

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

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

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

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。

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

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

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

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

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

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

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

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

8. Start a new merge request with these changes（これらの変更で新しいマージリクエストを開始）チェックボックスをオンにし、変更をコミットするを選択します。

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

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

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

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

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

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

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

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

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

結果を把握する

パイプラインの脆弱性を確認できます:

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

依存関係スキャンは、次の出力を生成します:

• Dependency scanning report（依存関係スキャンレポート）: 依存関係で検出されたすべての脆弱性の詳細が含まれています。
• CycloneDX Software Bill of Materials（CycloneDXソフトウェア部品表）: 検出されたサポートされているロックファイルまたはビルドファイルごとのソフトウェア部品表（SBOM）。

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

依存関係スキャンは、すべての脆弱性の詳細を含むレポートを出力します。レポートは内部で処理され、結果は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

複数のCycloneDX SBOMをマージする

CI/CDジョブを使用して、複数のCycloneDX SBOMを単一のSBOMにマージできます。GitLabはCycloneDXプロパティを使用して、各CycloneDX SBOMのメタデータに、ビルドファイルやロックファイルの場所など、実装に固有の詳細情報を保存します。複数のCycloneDX SBOMをマージすると、この情報はマージ後のファイルから削除されます。

たとえば、次の.gitlab-ci.ymlの抜粋は、複数のCyclone SBOMファイルをマージし、結果として生成されるファイルを検証する方法を示しています。

stages:
  - test
  - merge-cyclonedx-sboms

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

merge cyclonedx sboms:
  stage: merge-cyclonedx-sboms
  image:
    name: cyclonedx/cyclonedx-cli:0.25.1
    entrypoint: [""]
  script:
    - find . -name "gl-sbom-*.cdx.json" -exec cyclonedx merge --output-file gl-sbom-all.cdx.json --input-files "{}" +
    # optional: validate the merged sbom
    - cyclonedx validate --input-version v1_4 --input-file gl-sbom-all.cdx.json
  artifacts:
    paths:
      - gl-sbom-all.cdx.json

ロールアウトする

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

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

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

次の言語と依存関係マネージャーが、依存関係スキャンでサポートされています:

Footnotes（脚注）:

1. Java 21 LTSで使用する場合、sbtのバージョンは1.9.7に制限されます。より多くのsbtバージョンのサポートは、イシュー430335で追跡できます。FIPSFIPSモードが有効になっている場合はサポートされません。
2. Gradleは、FIPSFIPSモードが有効になっている場合はサポートされません。
3. pnpmのロックファイルはバンドルされた依存関係を保存しないため、レポートされる依存関係はNPMまたはyarnと異なる場合があります。
4. poetry.lockイシュー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のみ。イシュー468764を参照してください。
10. ライセンス検出は未対応です。エピック17037を参照してください。

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

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

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

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

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

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

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

すべての変数をテストしたわけではないため、機能するものもあれば、機能しないものもあります。必要な変数が機能しない場合は、機能リクエストを送信するか、コードにコントリビュートしてその機能を使用できるようにすることをおすすめします。

カスタムTLS認証局

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

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

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

カスタムTLS認証局を使用するには、CI/CD変数ADDITIONAL_CA_CERT_BUNDLEにX.509 PEM公開キー証明書のテキスト表現を割り当てます。

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

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

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

認証が必要なプライベートMavenリポジトリを使用するには、認証情報をCI/CD変数に保存し、Maven設定ファイルでそれらを参照する必要があります。.gitlab-ci.ymlファイルに認証情報を追加しないでください。

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

1. MAVEN_CLI_OPTS CI/CD変数をプロジェクトの設定に追加し、値に認証情報を含めます。

   例: ユーザー名がmyuserでパスワードがverysecretの場合:

   型	キー	値
   変数	MAVEN_CLI_OPTS	--settings mysettings.xml -Drepository.password=verysecret -Drepository.user=myuser

2. サーバー設定を含むMaven設定ファイルを作成します。

   たとえば、次の内容を設定ファイルmysettings.xmlに追加します。このファイルは、MAVEN_CLI_OPTS CI/CD変数で参照されます。

   <!-- 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
• 依存関係スキャンアナライザーイメージのローカルコピー
• 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レジストリにインポートするプロセスは、your network security policy（ネットワークのセキュリティポリシー）によって異なります。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 Advisory Databaseへのアクセス

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

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

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

• GitLab Advisory Databaseのクローンを使用する。
• GitLab Advisory Databaseのコピーを使用する。

GitLab Advisory Databaseのクローンを使用する

最も効率的な方法であるため、GitLab Advisory Databaseのクローンを使用することをおすすめします。

GitLab Advisory Databaseのクローンを読み込むには:

1. GitLab RunnerからHTTPでアクセスできるホストにGitLab Advisory Databaseのクローンを作成します。
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 Advisory Databaseのコピーを使用する

GitLab Advisory Databaseのコピーを使用するには、アナライザーによってダウンロードされたアーカイブファイルをホスティングする必要があります。

GitLab Advisory Databaseのコピーを使用するには:

1. GitLab RunnerからHTTPでアクセスできるホストにGitLab Advisory Databaseのアーカイブをダウンロードします。アーカイブは次の場所にあります。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ラッパースクリプトでプロキシを使用するには、GRADLE_CLI_OPTS CI/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依存関係スキャナーでプロキシを使用するには、settings.xmlファイルを使用して設定し（Mavenドキュメントを参照）、MAVEN_CLI_OPTS CI/CD変数を使用してこの設定を使用するようMavenに指示します:

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ベースアナライザーをサポートしています:

• gemnasium
• gemnasium-maven
• gemnasium-python

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

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

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

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

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

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

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

Footnotes（脚注）:

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

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

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

   • ワークスペース
   • yarn patch

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

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

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

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

Footnotes（脚注）:

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

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

     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言語のドキュメントを参照してください。

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

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

複数ファイルの処理方法

Python

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

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

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

JavaとScala

ビルドファイルが検出されたディレクトリで、ビルドを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 > Build（製品 > ビルド）を選択します。または、⌘+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を検索します。新しい脆弱性を送信することもできます。