• 要件
• サポートされる言語とパッケージマネージャ
• 依存関係の検出
  • 依存関係アナライザ
  • アナライザが依存性情報を取得する方法
    • ロックファイルの解析による依存情報の取得
    • 解析可能なファイルを生成するためにパッケージマネージャを実行することによる依存情報の取得
  • アナライザの起動方法
  • 複数ファイルの処理方法
    • Python
    • Java と Scala
    • ジャバスクリプト
    • Go
    • PHP、C、C++、.NET、C#、Ruby、JavaScript
    • 追加言語のサポート
• スキャナに貢献する
• 設定
  • 自動マージリクエストによる依存関係スキャンの有効化
  • 依存関係スキャン設定のカスタマイズ
  • 依存関係スキャンジョブの上書き
  • 利用可能な CI/CD 変数
    • 依存関係スキャンの設定
    • 依存性スキャンで使用する特定のアナライザの設定
    • その他の変数
  • カスタムSSL CA認証局の使用
  • 非公開Mavenリポジトリの使用
    • FIPS対応イメージ
• レポートのJSON形式
  • CycloneDXソフトウェア部品表
  • 複数のCycloneDX SBOMのマージ
• バージョンアップとリリースプロセス
• 脆弱性データベースへの貢献者
• オフライン環境での依存性スキャンの実行
  • オフライン依存関係スキャンの要件
  • Dockerレジストリ内でGitLab依存性スキャンアナライザーイメージを利用できるようにします。
    • カスタム認証局のサポート
  • CI/CDジョブ変数に依存性スキャンを設定することで、ローカル依存性スキャンアナライザを使用できるようになりました。
  • 言語とパッケージ・マネージャの固有設定
    • Python (pip)
    • Python (setuptools)
    • Python (Pipenv)
• gemnasium_db アドバイザリデータベースのコピーのホスティング
  • アドバイザリ・データベースのコピーをホスト
  • ローカルクローンを使う
• Gradle プロジェクトでのプロキシの使用
• 警告
  • Python プロジェクト
• トラブルシューティング
  • デバッグレベルのロギング
  • 特定の言語やパッケージマネージャのサポート不足を回避する方法
  • Error response from daemon: error processing tar file: docker-tar: relocation error
  • 警告メッセージgl-dependency-scanning-report.json: no matching files
  • rules:exists を使うときの制限
  • エラー：dependency_scanning is used for configuration only, and its script should not be executed
  • Java ベースのプロジェクトで複数の証明書をインポートするには
  • 依存関係スキャンのジョブはメッセージで失敗します。strconv.ParseUint: parsing "0.0": invalid syntax
  • メッセージ<file> does not exist in <commit SHA>
  • DS_MAJOR_VERSION またはDS_ANALYZER_IMAGE
  • setuptools プロジェクトの依存関係スキャンがuse_2to3 is invalid エラーで失敗します。
  • psycopg2 を使用しているプロジェクトの依存関係スキャンがpg_config executable not found エラーで失敗します。
  • NoSuchOptionException でpoetry config http-basic を使用している場合は、 パッケージをインストールしてください。CI_JOB_TOKEN
  • エラー：プロジェクトに<number> 未解決の依存関係があります。
  • Goプロジェクトをスキャンするときのビルド制約の設定
  • Goプロジェクトの依存関係スキャンが誤検出を返します。

依存関係のスキャン

依存関係スキャンは、アプリケーションの依存関係に既知の脆弱性がないか分析します。ネストされた依存関係として知られる推移的依存関係を含む、すべての依存関係がスキャンされます。

依存関係スキャンは、しばしば、ソフトウェア構成分析（Software Composition Analysis）(SCA) の一部とみなされます。SCA は、コードが使用する項目を検査する側面を含むことができます。これらの項目には、通常、アプリケーションやシステムの依存関係が含まれます。これらの依存関係は、ほとんどの場合、自分で書いた項目からではなく、外部ソースからインポートされます。

依存関係スキャンは、アプリケーションのライフサイクルの開発フェーズで実行することができます。パイプラインが実行されるたびに、脆弱性が特定され、ソースブランチとターゲットブランチの間で比較されます。脆弱性とその深刻度はマージリクエストにリストされ、コード変更がコミットされる前に、アプリケーションのリスクに積極的にアドレスすることができます。

GitLabは依存関係スキャンとコンテナスキャンの両方を提供し、これらの依存関係の種類すべてを確実にカバーします。可能な限り多くのリスク領域をカバーするために、全てのセキュリティスキャナーを利用することをお勧めします。これらの機能の比較については、依存関係スキャンとコンテナスキャナの比較をご覧ください。

概要については、依存関係スキャニングを参照してください。

要件

依存関係スキャンは、デフォルトで利用可能なtest ステージで実行されます。.gitlab-ci.yml ファイルでステージを再定義すると、test ステージが必要になります。

依存性スキャンのジョブを実行するには、デフォルトでは、docker またはkubernetes の Executor を持つ GitLab Runner が必要です。GitLab.comの共有Runnerを使っている場合、これはデフォルトで有効になっています。提供されているアナライザーイメージはLinux/amd64アーキテクチャ用です。

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

以下の言語と依存性マネージャーがサポートされています：

1. Android用Kotlinプロジェクトのサポートはイシュー336866で追跡されています。

2. Java 21 EA はMavenを使用する場合にのみ利用可能で、FIPS モードが有効な場合はサポートされません。

3. FIPSモードが有効な場合、Gradleはサポートされません。

4. pnpmlockfiles のサポートはGitLab 15.11 で導入されました。pnpmlockfiles はバンドルされた依存関係を保存しないため、報告される依存関係はnpmやyarn と異なる可能性があります。

5. Python 3.10をサポートするには、GitLab CI/CD設定ファイルに以下のスタンザを追加します。これは、デフォルトのPython 3.9ではなく、Python 3.10のイメージを使用することを指定します。

   gemnasium-dependency_scanning:   イメージ:     名前: $CI_TEMPLATE_REGISTRY_HOST/security-products/gemnasium-python:4-python-3.10

6. poetry.lockファイルを持つPoetryプロジェクトのサポートがGitLab 15.0 で追加されました。 poetry.lockファイルがないプロジェクトのサポートはイシューで追跡されています： Poetry の pyproject.toml による依存性スキャンのサポート。

7. sbt1.3 以上のサポートが GitLab 13.9 で追加されました。

依存関係の検出

依存性スキャンは、リポジトリで使用されている言語を自動的に検出します。検出された言語にマッチするすべてのアナライザーが実行されます。通常、解析器の選択をカスタマイズする必要はありません。アナライザーを指定しないことを推奨します。そうすることで、自動的に全選択項目を使用して最適なカバレッジを実現し、廃止予定や削除があったときに調整する必要がなくなります。ただし、DS_EXCLUDED_ANALYZERSという変数を使って、選択をオーバーライドすることができます。

言語検出は CI ジョブrules に依存し、リポジトリのルートから最大 2 つのディレクトリレベルを検索します。たとえば、gemnasium-dependency_scanning ジョブは、リポジトリにGemfile、api/Gemfile、api/client/Gemfileのいずれかが含まれている場合に有効になりますが、サポートされている依存ファイルがapi/v1/client/Gemfileのみである場合は有効になりません。

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

サポートされている依存関係ファイルが検出されると、推移的依存関係を含むすべての依存関係が解析されます。分析されるネスト依存関係や推移的依存関係の深さに制限はありません。

依存関係アナライザ

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

• gemnasium
• gemnasium-maven
• gemnasium-python

これらの Gemnasium ベースの Dependency Scanning アナライザは、それぞれ以下のプロジェクトに存在します：

• gemnasium

分析器はDockerイメージとして公開され、Dependency Scanningはこのイメージを使って各分析専用のコンテナを起動します。カスタムセキュリティスキャナをインテグレーションすることもできます。

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

GitLab アナライザは、以下の二つの方法のどちらかを使って依存情報を取得します：

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

ロックファイルの解析による依存情報の取得

以下のパッケージマネージャは、GitLab アナライザが直接解析できる lockfile を使っています：

1. 依存関係スキャンは、Go プロジェクトが使用するビルド リストを生成できない場合にのみgo.sumを解析します。

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

3. lockfileVersion = 3のサポートは GitLab 15.7 で導入されました。

4. Yarnv2とv3のサポートはGitLab 15.11で導入されました。ただし、この機能はGitLab 15.0以降のバージョンでも利用可能です。

   以下の機能はYarnv2またはv3には対応していません：

   • ワークスペース
   • ヤーンパッチ

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

解析可能なファイルを生成するためにパッケージマネージャを実行することによる依存情報の取得

以下のパッケージマネージャをサポートするために、GitLabアナライザは2つのステップを踏みます：

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

1. このテストでは、`.tool-versions`ファイルによって指定されたMavenのデフォルトバージョンを使用します。

2. Javaのバージョンが異なると、Gradleのバージョンも異なります。上記の表に記載されているGradleのバージョンは、アナライザーイメージにプリインストールされています。アナライザが使用するGradleのバージョンは、プロジェクトがgradlew（Gradleラッパー）ファイルを使用しているかどうかに依存します：

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

     Javaバージョン8と 11では、Gradle6.7.1が自動的に選択され、Javaバージョン17では、Gradle7.3.3が自動的に選択されます。

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

3. このテストは、Pipfile.lockファイルが見つかった場合、Gemnasiumがこのファイルに記載されているパッケージのバージョンを正確にスキャンするために使用されることを確認します。

4. go build の実装のため、Go のビルドプロセスにはネットワークアクセス、go mod download によるあらかじめロードされた mod キャッシュ、または vendored 依存関係が必要です。詳細については、パッケージと依存関係のコンパイルに関するGoのドキュメントを参照してください。

アナライザの起動方法

GitLabはrules:exists 、リポジトリ内のSupported files の存在によって検出された言語に関連するアナライザーを上の表のように起動します。

現在の検出ロジックでは、最大検索深度を2レベルに制限しています。例えば、gemnasium-dependency_scanning ジョブは、リポジトリにGemfile.lock 、api/Gemfile.lock 、api/client/Gemfile.lock のいずれかが含まれている場合に有効になりますが、サポートされている依存ファイルがapi/v1/client/Gemfile.lock のみである場合は有効になりません。

サポートされている依存関係ファイルが検出されると、推移的依存関係を含むすべての依存関係が分析されます。分析されるネストされた依存関係や推移的依存関係の深さに制限はありません。

複数ファイルの処理方法

Python

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

1. requirements.txtPip を使用しているプロジェクトでは、requirements.pip 、またはrequires.txt の順にファイルが検索されます。
2. Pipfile Pipenv を使用するプロジェクトについてはPipfile.lock を参照してください。
3. poetry.lock Poetryを使用するプロジェクトの場合は、以下のURLを参照してください。
4. setup.py Setuptoolsを使用したプロジェクトの場合。

検索はルートディレクトリから始まり、ルートディレクトリでビルドが見つからなければサブディレクトリから続きます。その結果、ルートディレクトリの Poetry Lock ファイルはサブディレクトリの Pipenv ファイルよりも先に検出されます。

Java と Scala

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

1. pom.xml 単一または複数モジュールのMaven プロジェクト。
2. build.gradle またはbuild.gradle.kts で単一または複数プロジェクトのGradle ビルドを行います。
3. build.sbt 単一または複数プロジェクトのsbt ビルドの場合。

検索はルートディレクトリから始まり、ルートディレクトリでビルドが見つからなければサブディレクトリを検索します。その結果、ルートディレクトリのsbtビルドファイルは、サブディレクトリのGradleビルドファイルよりも先に検出されます。

ジャバスクリプト

以下のアナライザが実行され、それぞれ複数のファイルを処理する際の動作が異なります：

• ジェムナジウム

  複数のロックファイルをサポート

• 引退.js

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

GitLab 14.8 以降、gemnasium アナライザーはサポートされている JavaScript プロジェクトを vendored ライブラリ (プロジェクトにチェックされているがパッケージマネージャーによって管理されていないライブラリ) についてスキャンします。

Go

複数のファイルに対応しています。go.mod ファイルが検出されると、アナライザはMinimal Version Selection を使用してビルド リストの生成を試みます。致命的でないエラーが発生した場合、アナライザは使用可能なgo.sum ファイルの解析に戻ります。このプロセスは、検出されたすべてのgo.mod およびgo.sum ファイルに対して繰り返されます。

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

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

追加言語のサポート

追加言語、依存性マネージャー、依存性ファイルのサポートは以下のイシューで追跡されています：

スキャナに貢献する

他のセキュリティスキャナをGitLabにインテグレーションする方法については、セキュリティスキャナのインテグレーションドキュメントをご覧ください。

設定

GitLab 11.9以降で依存性スキャンを有効にするには、GitLabインストールの一部として提供されるDependency-Scanning.gitlab-ci.yml テンプレート を含める必要があります。GitLabのバージョンが11.9より前の場合は、そのテンプレートで定義されたジョブをコピーして使用することができます。

.gitlab-ci.yml ファイルに以下を追加します：

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

このテンプレートは、CI/CDパイプラインに依存関係スキャンジョブを作成し、プロジェクトのソースコードに脆弱性がないかスキャンします。結果は、後でダウンロードして分析できる依存関係スキャンレポートアーティファクトとして保存されます。実装上の制限により、常に利用可能な最新の依存関係スキャン アーティファクトを使用します。

自動マージリクエストによる依存関係スキャンの有効化

• GitLab 14.1 でsec_dependency_scanning_ui_enable というフラグで導入されました。デフォルトで有効です。
• GitLab 14.1ではセルフマネージドで有効。
• 機能フラグsec_dependency_scanning_ui_enable を GitLab 14.2 で削除しました。

プロジェクトで依存性スキャンを有効にするには、マージリクエストを作成します：

1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
2. セキュア > セキュリティ設定を選択します。
3. 依存関係のスキャン] の行で、[マージリクエストで設定] を選択します。
4. マージリクエストをレビューしてマージし、依存関係スキャンを有効にします。

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

依存関係スキャン設定のカスタマイズ

依存性スキャンの設定は、.gitlab-ci.yml のvariables パラメータを使用してCI/CD 変数で変更できます。例えば

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

variables:
  SECURE_LOG_LEVEL: error

テンプレートはパイプライン設定の前に評価されるので、変数の最後の記述が優先されます。

依存関係スキャンジョブの上書き

ジョブ定義をオーバーライドするには (例えば、variables やdependencies のようなプロパティを変更するには)、オーバーライドするジョブと同じ名前の新しいジョブを宣言します。この新しいジョブをテンプレートインクルードの後に置き、その下に追加のキーを指定します。例えば、これはgemnasium アナライザーに対してDS_REMEDIATE を無効にします：

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

gemnasium-dependency_scanning:
  variables:
    DS_REMEDIATE: "false"

dependencies: [] 属性をオーバーライドするには、上記のように、この属性を対象とするオーバーライド・ジョブを追加します：

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

gemnasium-dependency_scanning:
  dependencies: ["build"]

利用可能な CI/CD 変数

依存関係のスキャンは環境変数を使って設定できます。

依存関係スキャンの設定

以下の変数により、グローバルな依存関係スキャン設定を構成できます。

依存性スキャンで使用する特定のアナライザの設定

以下の変数は、特定のアナライザ (特定の言語/フレームワークで使用) を設定するために使用します。

その他の変数

これまでの表は、使用できるすべての変数を網羅しているわけではありません。私たちがサポートし、テストしている GitLab とアナライザーの変数が含まれています。環境変数のように、渡せば動作する変数もたくさんあります。これは大きなリストであり、私たちが知らないものも多くあります。

たとえば、GitLab 以外の環境変数HTTPS_PROXY をすべての依存性スキャンのジョブに渡すには、.gitlab-ci.yml](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) ファイルで[CI/CD 変数として次のように設定します：

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

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

dependency_scanning:
  variables:
    HTTPS_PROXY: $HTTPS_PROXY

すべての変数をテストしたわけではないので、動く変数と動かない変数があるかもしれません。動作しない変数があり、それが必要な場合は、機能要求を提出するか、それを使えるようにするためにコードに貢献することをお勧めします。

カスタムSSL CA認証局の使用

ADDITIONAL_CA_CERT_BUNDLE CI/CD 変数を使用して、カスタム SSL CA 認証局を設定 ADDITIONAL_CA_CERT_BUNDLEすることができます。ADDITIONAL_CA_CERT_BUNDLE この ADDITIONAL_CA_CERT_BUNDLE値には、X.509 PEM公開鍵証明書のテキスト表現を含める必要があります。例えば、.gitlab-ci.yml ファイルでこの値を設定するには、次のようにします：

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

ADDITIONAL_CA_CERT_BUNDLE 値は、UI のカスタム変数として設定することもできます。file として設定する場合は証明書へのパスが必要で、変数として設定する場合は証明書のテキスト表現が必要です。

非公開Mavenリポジトリの使用

非公開 Maven リポジトリにログイン認証が必要な場合は、MAVEN_CLI_OPTS CI/CD 変数を使用できます。

非公開 Maven リポジトリの使用方法の詳細をお読みください。

FIPS対応イメージ

GitLab 14.10 で導入されました。GitLabチームメンバーはこちらのイシューをご覧ください： https://gitlab.com/gitlab-org/gitlab/-/issues/354796

GitLab はFIPS 対応の Red Hat UBI版 Gemnasium イメージも提供しています。そのため、標準イメージを FIPS 対応イメージに置き換えることができます。

GitLabインスタンスでFIPSモードが有効になっている場合、Gemnasiumスキャンジョブは自動的にFIPS対応イメージを使用します。(GitLab 15.0で導入されました)。

手動でFIPS対応イメージに切り替えるには、変数DS_IMAGE_SUFFIX を"-fips" に設定します。

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

レポートのJSON形式

依存関係スキャンツールは JSON レポートファイルを出力します。詳細については、このレポートのスキーマを参照してください。

依存関係スキャン・レポートの例を示します：

{
  "version": "2.0",
  "vulnerabilities": [
    {
      "id": "51e83874-0ff6-4677-a4c5-249060554eae",
      "category": "dependency_scanning",
      "name": "Regular Expression Denial of Service",
      "message": "Regular Expression Denial of Service in debug",
      "description": "The debug module is vulnerable to regular expression denial of service when untrusted user input is passed into the `o` formatter. It takes around 50k characters to block for 2 seconds making this a low severity issue.",
      "severity": "Unknown",
      "solution": "Upgrade to latest versions.",
      "scanner": {
        "id": "gemnasium",
        "name": "Gemnasium"
      },
      "location": {
        "file": "yarn.lock",
        "dependency": {
          "package": {
            "name": "debug"
          },
          "version": "1.0.5"
        }
      },
      "identifiers": [
        {
          "type": "gemnasium",
          "name": "Gemnasium-37283ed4-0380-40d7-ada7-2d994afcc62a",
          "value": "37283ed4-0380-40d7-ada7-2d994afcc62a",
          "url": "https://deps.sec.gitlab.com/packages/npm/debug/versions/1.0.5/advisories"
        }
      ],
      "links": [
        {
          "url": "https://nodesecurity.io/advisories/534"
        },
        {
          "url": "https://github.com/visionmedia/debug/issues/501"
        },
        {
          "url": "https://github.com/visionmedia/debug/pull/504"
        }
      ]
    },
    {
      "id": "5d681b13-e8fa-4668-957e-8d88f932ddc7",
      "category": "dependency_scanning",
      "name": "Authentication bypass via incorrect DOM traversal and canonicalization",
      "message": "Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js",
      "description": "Some XML DOM traversal and canonicalization APIs may be inconsistent in handling of comments within XML nodes. Incorrect use of these APIs by some SAML libraries results in incorrect parsing of the inner text of XML nodes such that any inner text after the comment is lost prior to cryptographically signing the SAML message. Text after the comment, therefore, has no impact on the signature on the SAML message.\r\n\r\nA remote attacker can modify SAML content for a SAML service provider without invalidating the cryptographic signature, which may allow attackers to bypass primary authentication for the affected SAML service provider.",
      "severity": "Unknown",
      "solution": "Upgrade to fixed version.\r\n",
      "scanner": {
        "id": "gemnasium",
        "name": "Gemnasium"
      },
      "location": {
        "file": "yarn.lock",
        "dependency": {
          "package": {
            "name": "saml2-js"
          },
          "version": "1.5.0"
        }
      },
      "identifiers": [
        {
          "type": "gemnasium",
          "name": "Gemnasium-9952e574-7b5b-46fa-a270-aeb694198a98",
          "value": "9952e574-7b5b-46fa-a270-aeb694198a98",
          "url": "https://deps.sec.gitlab.com/packages/npm/saml2-js/versions/1.5.0/advisories"
        },
        {
          "type": "cve",
          "name": "CVE-2017-11429",
          "value": "CVE-2017-11429",
          "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-11429"
        }
      ],
      "links": [
        {
          "url": "https://github.com/Clever/saml2/commit/3546cb61fd541f219abda364c5b919633609ef3d#diff-af730f9f738de1c9ad87596df3f6de84R279"
        },
        {
          "url": "https://github.com/Clever/saml2/issues/127"
        },
        {
          "url": "https://www.kb.cert.org/vuls/id/475445"
        }
      ]
    }
  ],
  "remediations": [
    {
      "fixes": [
        {
          "id": "5d681b13-e8fa-4668-957e-8d88f932ddc7",
        }
      ],
      "summary": "Upgrade saml2-js",
      "diff": "ZGlmZiAtLWdpdCBhL...OR0d1ZUc2THh3UT09Cg==" // some content is omitted for brevity
    }
  ]
}

CycloneDXソフトウェア部品表

• GitLab 14.8ベータ版で導入されました。
• GitLab 15.7で一般的に利用可能。

GemnasiumDependency Scanningツールは、JSONレポート・ファイルに加え、検出されたサポートされたロック・ファイルやビルド・ファイルごとにCycloneDXSoftware Bill of Materials(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は、他のジョブのアーティファクトと同じ方法でダウンロードできます。

複数のCycloneDX SBOMのマージ

CI/CD ジョブを使用して、複数の CycloneDX SBOM を単一の SBOM にマージできます。たとえば

stages:
  - test
  - merge-cyclonedx-sboms

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

merge cyclonedx sboms:
  stage: merge-cyclonedx-sboms
  image:
    name: cyclonedx/cyclonedx-cli:0.24.2
    entrypoint: [""]
  script:
    - apt-get update && apt-get install -y jq
    - find . -name "gl-sbom-*.cdx.json" -exec cyclonedx merge --output-file gl-sbom-all.cdx.json --input-files "{}" +
    # remove duplicates from merged file. See https://github.com/CycloneDX/cyclonedx-cli/issues/188 for details.
    - |
      jq '. |
      {
        "bomFormat": .bomFormat,
        "specVersion": .specVersion,
        "serialNumber": .serialNumber,
        "version": .version,
        "metadata": {
          "tools": [
            (.metadata.tools | unique[])
          ]
        },
        "components": [
          (.components | unique[])
        ]
      }' "gl-sbom-all.cdx.json" > gl-sbom-all.cdx.json.tmp && mv gl-sbom-all.cdx.json.tmp gl-sbom-all.cdx.json
    # 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

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

バージョンアップとリリースプロセス

リリースプロセスのドキュメントをご覧ください。

脆弱性データベースへの貢献者

脆弱性を見つけるには、GitLab Advisory Database を検索してください。 また、新しい脆弱性を投稿することもできます。

オフライン環境での依存性スキャンの実行

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

オフライン依存関係スキャンの要件

以下は、オフライン環境で依存関係スキャンを使用するための要件です：

• GitLab Runner with thedocker orkubernetes executor.
• Dockerコンテナレジストリ。依存性スキャンアナライザーイメージのローカルで利用可能なコピー。

• アクセスが制限されている環境では、プロキシを使用するなどして、アドバイザリデータベースへのアクセスを許可する必要がありますhttps://gitlab.com/gitlab-org/security-products/gemnasium-db.git。へのアクセスを許可できない https://gitlab.com/gitlab-org/security-products/gemnasium-db.git場合は、このgit リポジトリのオフラインコピーをホストし、GEMNASIUM_DB_REMOTE_URL CI/CD 変数をこのリポジトリの URL に設定する必要があります。設定変数の詳細については、依存関係スキャンを参照してください。

  この勧告データベースは常に更新されているので、定期的にローカルコピーを GitLab と同期する必要があります。

GitLab Runnerのデフォルトのpull policy はalways、つまりランナーはGitLabコンテナレジストリからDockerイメージを引き出そうとします、たとえ内部コピーが利用可能であっても。ローカルで利用可能なDockerイメージのみを使用したい場合は、オフライン環境でGitLab Runnerpull_policy をif-not-present に設定することができます。しかし、オフライン環境でない場合は、CI/CDパイプラインで更新されたスキャナを使用できるようにするため、プルポリシー設定をalways に保つことをお勧めします。

Dockerレジストリ内でGitLab依存性スキャンアナライザーイメージを利用できるようにします。

サポートされているすべての言語とフレームワークで依存性スキャンを行うには、registry.gitlab.com から以下のデフォルトの依存性スキャンアナライザーイメージをローカルの Docker コンテナレジストリにインポートしてください：

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

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

Dockerイメージをファイルとして保存して転送する方法の詳細については、docker save、docker load、docker export、docker importのDockerドキュメントを参照してください。

カスタム認証局のサポート

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

CI/CDジョブ変数に依存性スキャンを設定することで、ローカル依存性スキャンアナライザを使用できるようになりました。

.gitlab-ci.yml ファイルに以下の設定を追加します。SECURE_ANALYZERS_PREFIX の値をローカルのDockerコンテナレジストリを参照するように変更する必要があります。また、GEMNASIUM_DB_REMOTE_URL の値を、gemnasium-db 勧告データベース のオフライン Git コピーの場所に変更する必要があります：

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

variables:
  SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers"
  GEMNASIUM_DB_REMOTE_URL: "gitlab.example.com/gemnasium-db.git"

設定セクションの上記の変数の説明を参照してください。

言語とパッケージ・マネージャの固有設定

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

Python (pip)

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

Python (setuptools)

アナライザの実行前に Python パッケージをインストールする必要がある場合は、スキャンジョブのbefore_script でpython setup.py install --user を使用します。この--user フラグを指定すると、プロジェクトの依存関係がユーザーディレクトリにインストール --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)

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

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

あるいは、非公開レジストリを使用できない場合は、必要なパッケージを Pipenv 仮想環境キャッシュにロードすることもできます。このオプションの場合、プロジェクトはPipfile.lock をリポジトリにチェックインし、デフォルトと開発用のパッケージをキャッシュにロードする必要があります。Python-pipenvプロジェクトの例を参照してください。

gemnasium_db アドバイザリデータベースのコピーのホスティング

gemnasium_db Git リポジトリはgemnasium,gemnasium-maven,gemnasium-python で脆弱性データのソースとして使われています。このリポジトリはスキャン時に更新され、最新のアドバイザリを取得します。しかし、ネットワーク環境が制限されているため、この更新を実行できないことがあります。この場合、ユーザーは次のいずれかを実行できます：

• アドバイザリ・データベースのコピーをホスト
• ローカルクローンを使用

アドバイザリ・データベースのコピーをホスト

gemnasium-dbに環境からアクセスできない場合、ユーザーは自分のGitコピーをホストすることができます。そして、GEMNASIUM_DB_REMOTE_URL を使って、ユーザーのコピーからデータベースを更新するようにアナライザに指示することができます：

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

...

ローカルクローンを使う

ホスティングされたコピーが不可能な場合、ユーザーはスキャン前にgemnasium-dbをクローンするかアーカイブを作成し、そのディレクトリをアナライザに指定します(使用法:GEMNASIUM_DB_LOCAL_PATH)。アナライザの自己更新機構をオフにします(使用法:GEMNASIUM_DB_UPDATE_DISABLED)。この例では、gemnasium アナライザのスキャンジョブの前に、before_script にデータベースディレクトリが作成されます：

...

gemnasium-dependency_scanning:
  variables:
    GEMNASIUM_DB_LOCAL_PATH: ./gemnasium-db-local
    GEMNASIUM_DB_UPDATE_DISABLED: "true"
  before_script:
    - mkdir $GEMNASIUM_DB_LOCAL_PATH
    - tar -xzf gemnasium_db.tar.gz -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"

警告

すべてのコンテナで最新のバージョンを、すべてのパッケージマネージャと言語で最新のサポートバージョンを使用することをお勧めします。以前のバージョンを使用すると、セキュリティ上のリスクが高まります。なぜなら、サポートされていないバージョンでは、セキュリティに関する積極的なレポートやセキュリティ修正のバックポートが行われなくなる可能性があるからです。

Python プロジェクト

CVE-2018-20225 により悪用される可能性があるため、PIP_EXTRA_INDEX_URL 環境変数を使用する際には特に注意が必要です：

pip (全てのバージョン) で、ユーザーが非公開パッケージを非公開インデックスから取得するつもりであったとしても、最も高いバージョン番号のバージョンをインストールしてしまうというイシューが発見されました。この問題は、PIP_EXTRA_INDEX_URL オプションの使用にのみ影響し、公開インデックスにそのパッケージが既に存在しない (つまり、攻撃者が任意のバージョン番号でパッケージをそこに置くことができる) ことを必要とします。

トラブルシューティング

デバッグレベルのロギング

デバッグ・レベルのロギングは、トラブルシューティングの際に役立ちます。詳細については、デバッグレベルロギングを参照してください。

特定の言語やパッケージマネージャのサポート不足を回避する方法

サポートされている言語」で述べたように、一部の依存関係定義ファイルはまだサポートされていません。しかし、言語、パッケージマネージャ、またはサードパーティツールが定義ファイルをサポートされている形式に変換することができれば、依存関係スキャンを行うことができます。

一般的には、以下のようなアプローチになります：

1. .gitlab-ci.yml ファイルに専用の変換ジョブを定義します。適切なDockerイメージ、スクリプト、またはその両方を使用して変換を促進します。
2. そのジョブは、変換されサポートされたファイルをアーティファクトとしてアップロードさせます。
3. 変換された定義ファイルを利用するために、dependencies: [<your-converter-job>] をdependency_scanning ジョブに追加してください。

例えば、pyproject.toml _ファイルしか_ない Poetry プロジェクトでは、poetry.lock ファイルを以下のように生成できます。

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

stages:
  - test

gemnasium-python-dependency_scanning:
  # Work around https://gitlab.com/gitlab-org/gitlab/-/issues/32774
  before_script:
    - pip install "poetry>=1,<2"  # Or via another method: https://python-poetry.org/docs/#installation
    - poetry update --lock # Generates the lock file to be analyzed.

Error response from daemon: error processing tar file: docker-tar: relocation error

このエラーは、依存関係スキャンジョブを実行するDockerのバージョンが19.03.0 の場合に発生します。Docker19.03.1 以上へのアップデートを検討してください。古いバージョンは影響を受けません。この問題の。

警告メッセージgl-dependency-scanning-report.json: no matching files

これについては、一般的なアプリケーションセキュリティのトラブルシューティングのセクションを参照してください。

rules:exists を使うときの制限

依存性スキャン CI テンプレートは rules:exists 構文を使用します。このディレクティブは 10000 個までのチェックに制限されており、この数に達すると常にtrue を返します。このため、リポジトリ内のファイル数によっては、スキャナがプロジェクトをサポートしていなくても、依存関係スキャンのジョブが起動することがあります。

エラー：dependency_scanning is used for configuration only, and its script should not be executed

これについては、GitLab Secureのトラブルシューティングを参照してください。

Java ベースのプロジェクトで複数の証明書をインポートするには

gemnasium-maven アナライザは、ADDITIONAL_CA_CERT_BUNDLE 変数の内部を読み込み、keytool単一の証明書または証明書チェーンをインポート keytoolします。keytool無関係な複数の証明書は無視され、最初の証明書だけが .NET によってインポート keytoolされます。

無関係な複数の証明書をアナライザに追加するには、gemnasium-maven-dependency_scanning ジョブの定義で次のようにbefore_script を宣言します：

gemnasium-maven-dependency_scanning:
  before_script:
    - . $HOME/.bashrc # make the java tools available to the script
    - OIFS="$IFS"; IFS=""; echo $ADDITIONAL_CA_CERT_BUNDLE > multi.pem; IFS="$OIFS" # write ADDITIONAL_CA_CERT_BUNDLE variable to a PEM file
    - csplit -z --digits=2 --prefix=cert multi.pem "/-----END CERTIFICATE-----/+1" "{*}" # split the file into individual certificates
    - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions)
    - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import

依存関係スキャンのジョブはメッセージで失敗します。strconv.ParseUint: parsing "0.0": invalid syntax

Docker-in-Dockerの起動がこのエラーの原因と考えられます。Docker-in-Dockerは：

• GitLab 13.0以降ではデフォルトで無効になっています。
• GitLab 13.4以降では未サポート。

このエラーを修正するには、依存関係のスキャンでDocker-in-Dockerを無効にしてください。CI/CD パイプラインで実行するアナライザーごとに、個別の<analyzer-name>-dependency_scanning ジョブが作成されます。

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

variables:
  DS_DISABLE_DIND: "true"

メッセージ<file> does not exist in <commit SHA>

ファイル内の依存関係のLocation が表示されると、リンクのパスが特定の Git SHA に移動します。

しかし、依存関係スキャンツールがレビューしたロックファイルがキャッシュされていた場合、そのリンクを選択するとリポジトリルートにリダイレクトされ、メッセージが表示されます：<file> does not exist in <commit SHA>.

ロックファイルはビルド段階でキャッシュされ、スキャンが実行される前に依存関係スキャンジョブに渡されます。キャッシュはアナライザーの実行前にダウンロードされるため、CI_BUILDS_DIR ディレクトリにロックファイルが存在すると、依存関係スキャンジョブがトリガーされます。

この警告を防ぐために、ロック・ファイルをコミットすることをお勧めします。

DS_MAJOR_VERSION またはDS_ANALYZER_IMAGE

特定の理由で手動でDS_MAJOR_VERSION またはDS_ANALYZER_IMAGE を設定した後、設定を更新して最新のパッチが適用されたバージョンのアナライザを取得する必要がある場合は、.gitlab-ci.yml ファイルを編集してください：

• DS_MAJOR_VERSION を現在の依存関係スキャン・テンプレートにある最新バージョンに合わせます。

• DS_ANALYZER_IMAGE 変数を直接ハードコードした場合は、現在の依存関係スキャンテンプレートにある最新の行と一致するように変更してください。行番号は編集したスキャンジョブによって異なります。

  例えば、DS_ANALYZER_IMAGE が"$SECURE_ANALYZERS_PREFIX/gemnasium-maven:$DS_MAJOR_VERSION" に設定されているため、gemnasium-maven-dependency_scanning ジョブは最新のgemnasium-maven Docker イメージをプルします。

setuptools プロジェクトの依存関係スキャンがuse_2to3 is invalid エラーで失敗します。

2to3のサポートはsetuptools バージョンv58.0.0 で削除されました。Dependency Scanning (runningpython 3.9) はsetuptools バージョン58.1.0+ を使用していますが、これは2to3をサポートしていません。したがって、lib2to3 に依存するsetuptools 依存関係は、このメッセージで失敗します：

error in <dependency name> setup command: use_2to3 is invalid

このエラーを回避するには、setuptools (たとえば、v57.5.0) のアナライザーのバージョンをダウングレードします：

gemnasium-python-dependency_scanning:
  before_script:
    - pip install setuptools==57.5.0

psycopg2 を使用しているプロジェクトの依存関係スキャンがpg_config executable not found エラーで失敗します。

psycopg2 に依存している Python プロジェクトのスキャンは、このメッセージで失敗することがあります：

Error: pg_config executable not found.

psycopg2depends on thelibpq-dev Debian package, which is not installed in thegemnasium-python Docker image.このエラーを回避するには、libpq-dev パッケージをbefore_script ：

gemnasium-python-dependency_scanning:
  before_script:
    - apt-get update && apt-get install -y libpq-dev

NoSuchOptionException でpoetry config http-basic を使用している場合は、 パッケージをインストールしてください。CI_JOB_TOKEN

このエラーは、自動生成されたCI_JOB_TOKEN がハイフン (-) で始まっている場合に発生することがあります。このエラーを回避するには、Poetryの設定アドバイスに従ってください。

エラー：プロジェクトに<number> 未解決の依存関係があります。

エラーメッセージProject has <number> unresolved dependencies は、gradle.build またはgradle.build.kts ファイルに起因する依存関係解決の問題を示しています。現在のリリースでは、gemnasium-maven 未解決の依存関係が発生した場合に処理を続行する gemnasium-mavenことはできません。gemnasium-maven ただし gemnasium-maven、未解決の依存関係エラーから回復して依存関係グラフを作成gemnasium-maven できるようにするためのイシューが未解決 gemnasium-mavenです。このイシューが解決されるまで、gradle.build ファイルを修正する方法の詳細については、Gradle の依存関係解決に関するドキュメントを参照してください。

Goプロジェクトをスキャンするときのビルド制約の設定

依存関係のスキャンはコンテナ内で実行されますlinux/amd64 。その結果、Go プロジェクト用に生成されるビルド リストには、この環境と互換性のある依存関係が含まれます。デプロイ環境がそうでない場合 linux/amd64、最終的な依存関係リストには互換性のないモジュールが追加される可能性があります。また、デプロイ環境としか互換性のないモジュールが依存関係リストから除外される可能性もあります。このイシューを防ぐには、.gitlab-ci.yml ファイルのGOOS とGOARCH 環境変数を設定することで、デプロイ環境のオペレーティング システムとアーキテクチャをターゲットにビルド プロセスを設定できます。

使用例：

variables:
  GOOS: "darwin"
  GOARCH: "arm64"

GOFLAGS 変数を使用して、ビルドタグ制約を指定することもできます：

variables:
  GOFLAGS: "-tags=test_feature"

Goプロジェクトの依存関係スキャンが誤検出を返します。

このgo.sum ファイルには、プロジェクトのビルド リストを生成するときに考慮されたすべてのモジュールのエントリが含まれて go.sumいます。ファイルgo.sum には複数のバージョンのモジュールが含まれて go.sumいますが、go build で使用されるMVSアルゴリズムは 1 つしか選択しません。その結果、依存関係のスキャンでgo.sum を使用すると、誤検出を報告する可能性があります。

誤検出を防ぐために、gemnasiumはGoプロジェクトのビルドリストを生成できない場合にのみgo.sum 。go.sum が選択された場合、警告が発生します：

[WARN] [Gemnasium] [2022-09-14T20:59:38Z] ▶ Selecting "go.sum" parser for "/test-projects/gitlab-shell/go.sum". False positives may occur. See https://gitlab.com/gitlab-org/gitlab/-/issues/321081.