Back to Guides

Generating CycloneDX BOMs

SBOM (ソフトウェア部品表) は、特定のソフトウェアディストリビューションを構成するコンポーネントを記述したマニフェストです。さらに、コンポーネント間の関係、ライセンス、来歴など、さらに多くの情報が含まれる場合もあります。 SBOM は通常、ソフトウェアセキュリティーおよびソフトウェアサプライチェーンリスク管理ツールが、脆弱性およびコンプライアンス関連の分析を実行するために使用します。

このガイドでは、 CycloneDX 仕様に準拠した Quarkus SBOM 生成機能について説明します。

Quarkus 固有ツールを使用する理由

Quarkus は、 Maven や Gradle などのビルドツールと連携しますが、Quarkus 自体が独自のコンポーネントと依存関係モデル、ビルドステップ、ビルド出力を持つビルドツールとして分類される場合もあります。Quarkus アプリケーションの重要なコンポーネントタイプの 1 つが、ランタイムとビルド時のアーティファクト、およびそれらの依存関係で構成される Quarkus エクステンションです。

Quarkus エクステンションやその他のアプリケーションの依存関係を適切に解決するために、Quarkus は独自の依存関係リゾルバーを使用します。この依存関係リゾルバーは、基盤となるビルドツール (Maven または Gradle) によって提供される依存関係リゾルバーの上に実装されています。

その結果、たとえば Maven の場合、Quarkus がアプリケーションの構築に使用するすべての依存関係は dependency:tree の結果に含まれません。プロジェクトが標準の Maven 依存関係モデルに準拠していると想定する他の依存関係分析ツールも、同様の問題から影響を受け、有効な Quarkus アプリケーション依存関係グラフをキャプチャーできません。残念ながら、これには CycloneDX Maven プラグイン の実装も含まれます。

ビルドプロセスへの入力となる依存関係のほかに、アプリケーションの最終的なディストリビューションであるビルドの出力もあります。アプリケーションユーザーは、アプリケーションのデプロイに同意する前に、依存関係 (ビルドへの入力) だけでなく最終的なディストリビューション (ビルドの出力) も明示する SBOM をリクエストする場合があります。アプリケーション開発者は、Quarkus 固有のものも含むさまざまなパッケージタイプを Quarkus でアプリケーションに対して選択できます。ディストリビューションに含まれるコンポーネントに関する Quarkus 固有の詳細を提供することで、潜在的なセキュリティー関連問題の影響をより適切に評価できるようになります。

依存関係 SBOM

この章では、ビルド前にアプリケーションの依存関係のみを明示する SBOM の生成ｂｂｂｂｂｂ方法について説明します。つまり、これらの SBOM は、ビルドへの入力を明示しており、アプリケーションのビルド前に脆弱性およびコンプライアンス関連の分析を実行するために使用できます。

Maven 依存関係 SBOM

Quarkus Maven プロジェクトの依存関係 SBOM は、 quarkus:dependency-sbom ゴールを使用して生成できます。ゴールの出力は、 target/<artifactId>-<version>-dependency-cyclonedx.json ファイルに保存されます (outputFile ゴールパラメーター、または quarkus.dependency.sbom.output-file プロパティーを設定することで変更できます)。完全な Quarkus ビルドおよびランタイム依存関係グラフは、 CycloneDX JSON 形式で記録されます。

XML 形式は、 format ゴールパラメーター (または quarkus.dependency.sbom.format プロパティー) を xml に設定することでリクエストできます。

生成された SBOM 内の各コンポーネントには quarkus:component:scope プロパティーが含まれています。これは、そのコンポーネントが実行時に使用されるのか、あるいは開発/ビルド時のみに使用されるのかを示しています。

        {
          "name" : "quarkus:component:scope",
          "value" : "runtime"
        }

デフォルトでは、 quarkus:dependency-sbom はプロダクションビルドの依存関係をキャプチャーします。Quarkus は、normal (プロダクション)、test、dev の 3 つのアプリケーションブートストラップモードをサポートしています。アプリケーションは、モードごとに異なる依存関係グラフを持つことができます。 mode パラメーターを使用して、どの依存関係グラフを記録するかを指定できます。 mode が test または dev に設定されている場合、ターゲットファイル名は target/<artifactId>-<version>-<mode>-dependency-cyclonedx.json になります。

mvn help:describe -Dcmd=quarkus:dependency-sbom -Ddetail を実行すると、完全なパラメーターセットとその説明を取得できます。

Gradle 依存関係 SBOM

Maven とは異なり、 Gradle CycloneDX プラグイン実装 は、設定済みプラグインにより登録された依存関係設定を明示するため、Quarkus プロジェクトで依存関係 SBOM を生成するために使用できます。

設定オプションについては、 Gradle CycloneDX プラグイン のドキュメントを参照してください。以下に、マニフェストの作成に関連する Quarkus 依存関係設定をリストしています:

  • quarkusProdRuntimeClasspathConfiguration - Quarkus アプリケーションのプロダクションランタイム依存関係

  • quarkusProdRuntimeClasspathConfigurationDeployment - Quarkus アプリケーションのプロダクションランタイムとビルドタイムの依存関係

  • quarkusTestRuntimeClasspathConfiguration - Quarkus アプリケーションのテストランタイム依存関係

  • quarkusTestRuntimeClasspathConfigurationDeployment - Quarkus アプリケーションのテストランタイムとビルドタイムの依存関係

  • quarkusDevRuntimeClasspathConfiguration - Quarkus アプリケーション開発モードのランタイム依存関係

  • quarkusDevRuntimeClasspathConfigurationDeployment - Quarkus アプリケーション開発モードのランタイムおよびビルドタイムの依存関係

プラグインは Quarkus がこれらの依存関係をどのように使用するかを認識しないため、コンポーネントの quarkus:component:scope プロパティーを設定することはできません。一方で、リクエストされた設定名を使用して、ターゲットとするスコープを示すことはできます。

ディストリビューション SBOM

この章では、最終的なアプリケーションディストリビューションである Quarkus ビルドの出力を明示する SBOM について説明します。

アプリケーションビルドおよびパッケージアセンブリのプロセス中に、Quarkus は生成されたディストリビューションに関する特定の詳細をキャプチャーし、SBOM ジェネレーターがその情報を SBOM 形式で使用および記録できるようにします。

現時点で Quarkus ユーザーが利用できる、アプリケーションディストリビューションのマニフェストを作成できる唯一の SBOM ジェネレーターは io.quarkus:quarkus-cyclonedx です。これをプロジェクトの依存関係として追加すると、アプリケーションがビルドされるたびに SBOM が生成されます。SBOM は、プロジェクトのビルド出力ディレクトリーに <executable-name>-cyclonedx.<format> の名前で保存されます。

  • この場合の <executable-name> は、アプリケーションを起動する実行可能ファイルの基本ファイル名 (拡張子なし) です。

  • <format> は json (デフォルト) または xml のいずれかで、 quarkus.cyclonedx.format プロパティーを使用して設定できます。両方の形式が必要な場合は、 quarkus.cyclonedx.format を all に設定します。

Fast JAR

Fast JAR パッケージングでは、Quarkus 固有のファイルシステムディレクトリーレイアウトが使用されます。これには、Quarkus によって生成されたファイルと、アプリケーションのランタイム依存関係である Maven アーティファクトが含まれています。

Fast JAR パッケージングタイプの SBOM は、実行可能な JAR ファイルをメインコンポーネントとして使用し、ランタイムとビルドタイムの Quarkus アプリケーション依存関係を記録します。

実行時コンポーネント

結果として得られる Fast JAR ディストリビューション内のすべてのファイルは、SBOM に表示されます。その場合、 quarkus:component:scope プロパティーは runtime に設定され、 evidence.occurrences.location フィールドはアプリケーションディストリビューションディレクトリー内のコンポーネントの場所を指しています。

      "purl" : "pkg:maven/org.jboss.slf4j/slf4j-jboss-logmanager@2.0.0.Final?type=jar",
      "properties" : [
        {
          "name" : "quarkus:component:scope",
          "value" : "runtime"
        }
      ],
      "evidence" : {
        "occurrences" : [
          {
            "location" : "lib/main/org.jboss.slf4j.slf4j-jboss-logmanager-2.0.0.Final.jar"
          }
        ]
      }
evidence.occurrences.location was introduced in CycloneDX schema version 1.5, for older versions the location will be indicated using the quarkus:component:location property.

系譜（Pedigree）

系譜は、特定のパッチ、または一般的な変更が特定のコンポーネントに適用されたという情報を提供するために使用されます。

Quarkus が、依存関係アーティファクトの変更されたバージョンをアプリケーションディストリビューションにコピーする場合もあります。コンポーネントの元のコンテンツを操作するとハッシュサムが変更され、元のコンポーネントハッシュサムとディストリビューションで見つかったハッシュサムを比較するツールによって疑わしいものとして強調表示される可能性があります。

Quarkus が Maven リポジトリーから解決されたアーティファクトに変更を適用した場合、生成された SBOM にこれらの変更を系譜ノートとして表示できます。 たとえばアプリケーション開発者が、以下のように依存関係から特定のクラスパスリソースを削除することにしたとします。

quarkus.class-loading.removed-resources."jakarta.transaction\:jakarta.transaction-api"=META-INF/NOTICE.md,jakarta/transaction/package.html

結果として得られる SBOM には以下が含まれます。

      "purl" : "pkg:maven/jakarta.transaction/jakarta.transaction-api@2.0.1?type=jar",
      "pedigree" : {
        "notes" : "Removed META-INF/NOTICE.md,jakarta/transaction/package.html"
      },

ビルドタイム依存関係

ビルドタイム依存関係は、 quarkus:component:scope プロパティーが development に設定されて記録されます。

      "purl" : "pkg:maven/org.apache.httpcomponents/httpclient@4.5.14?type=jar",
      "properties" : [
        {
          "name" : "quarkus:component:scope",
          "value" : "development"
        }
      ]

ディストリビューション内に見つからないため、 evidence.occurrences.location は含まれません。

Uber JAR

Uber JAR の SBOM は、Uber JAR Maven アーティファクトをメインコンポーネントとして使用します。

Uber JAR は Maven アーティファクトとして公開されるため、Uber JAR 用に生成された SBOM も自動的に Maven アーティファクトとして公開されます。ただし、 quarkus:build ゴールの attachSboms パラメーターを false に設定することで、これを無効にできます。

Gradle ユーザーが SBOM を Maven アーティファクトとしてデプロイする場合は、公開プラグインを明示的に設定する必要があります。

Uber JAR 用に生成された SBOM 内のランタイムコンポーネントに evidence.occurrences.location は含まれません。これは、コンテンツが単一の JAR ファイルにマージされるためです。

ネイティブイメージ

ネイティブイメージの SBOM は、ネイティブ実行可能ファイルをメインコンポーネントとして使用します。

現在、ネイティブ実行可能ファイルは Maven アーティファクトとしてプロジェクトにアタッチされないため、その SBOM も Maven アーティファクトとしてアタッチされません。

Uber JAR の場合と同様に、ネイティブ実行可能ファイル用に生成された SBOM 内のランタイムコンポーネントに evidence.occurrences.location は含まれません。これは、対応するコードとリソースが単一のネイティブ実行可能ファイルに含まれているためです。

Mutable JAR

Mutable JAR ディストリビューションは Fast JAR ディストリビューションと似ていますが、アプリケーションの再拡張 (再構築) をサポートするためのビルドタイム依存関係も含まれている点が異なります。

Mutable JAR ディストリビューション用に生成された SBOM は、再拡張プロセス中に使用されるコンポーネントの場所も evidence.occurrences.location を使用して記録しますが、 quarkus:component:scope プロパティー設定は development のまま保持されます。以下はその例です。

      "purl" : "pkg:maven/org.apache.httpcomponents/httpcore@4.4.16?type=jar",
      "properties" : [
        {
          "name" : "quarkus:component:scope",
          "value" : "development"
        }
      ],
      "evidence" : {
        "occurrences" : [
          {
            "location" : "lib/deployment/org.apache.httpcomponents.httpcore-4.4.16.jar"
          }
        ]
      }

Embedded Dependency SBOM

A dependency SBOM can be embedded into the application itself as a classpath resource, so that it travels with the application and can be consumed at runtime or by tools inspecting the artifact. This is enabled with:

quarkus.cyclonedx.embedded.enabled=true

The SBOM is embedded as a classpath resource at META-INF/sbom/dependency.cdx.json by default. The resource name can be customized, and its extension determines the format (.json for JSON, .xml for XML):

quarkus.cyclonedx.embedded.resource-name=META-INF/custom-sbom.json

The embedded SBOM manifests the application dependencies (the input to the build) rather than the final distribution layout. When product attribution is enabled (the default), the embedded SBOM also includes the platform-member product components.

ネイティブイメージ

When building a native executable, in addition to the classpath resource, the embedded SBOM is also baked into the native binary as the sbom and sbom_length global symbols, following the GraalVM SBOM specification. The sbom symbol references a GZIP-compressed copy of the SBOM (as required by the specification), which allows tools such as syft to extract the SBOM directly from the executable:

syft scan ./my-native-app -o cyclonedx-json

Product Attribution

Quarkus platforms (such as the Quarkus platform BOM or vendor-provided platforms) may aggregate extensions that belong to supported products, also referred to as offerings. When an application is built on such a platform, product attribution represents each supported product as a dedicated component in the generated SBOM and links the application artifacts that belong to that product to it. This lets downstream tools see which parts of an application are covered by a given product and match them against product-level vulnerability and support information, for example by CPE.

Product attribution is enabled by default and applies to every SBOM that includes the core application contribution (the dependency and distribution SBOMs). It can be disabled with:

quarkus.cyclonedx.product-attribution=false

For the quarkus:dependency-sbom Maven goal the equivalent parameter is quarkus.dependency.sbom.product-attribution.

動作原理

Attribution is driven entirely by metadata the platform provides through its platform properties; an application does not configure products directly. Each imported platform member that declares a product identity (at minimum a CPE) yields, in the generated SBOM, a single product component that:

  • has the type framework (unless the platform specifies a different type), carries the product’s CPE, and has its CycloneDX scope set to excluded, since the product itself is not a shipped artifact;

  • is a top-level component, so it appears as a direct dependency of the main application component;

  • provides the artifacts attributed to it — the application’s runtime extension artifacts that belong to the product, together with their dependencies. These are recorded as CycloneDX 1.6 dependency.provides relationships (the product provides/implements those artifacts). On schema versions older than 1.6, where provides is not available, the same artifacts are recorded as dependsOn relationships instead.

Platform members that declare the same product PURL and CPE are merged into a single product component whose attributed artifacts are the union of the members' contributions.

Only artifacts that are actually present in the application and match the coordinates the platform attributed to the product are linked. If the application overrides the version of an attributed dependency, that dependency is not attributed to the product.

A product component is emitted whenever a platform member declares a CPE, even if none of its attributed artifacts end up present in the application.

Quarkus プロパティータクソノミー

名前 値の範囲 説明

quarkus:component:scope

runtime または development

コンポーネントがアプリケーション実行時の依存関係であるか、ビルド/開発時の依存関係であるかを示します。

quarkus:component:location

パス要素として / を使用してファイルシステムパスを表す文字列

スキーマバージョン 1.4 以前の SBOM で使用されます。スキーマ 1.5 以降では、代わりに evidence.occurrences.location が使用されます。このプロパティーは、ディストリビューション内にコンポーネントが見つかった場合にのみ使用されます。値は、パス要素の区切り文字として / を使用してディストリビューション内のコンポーネントの場所を指すファイルへの相対パスです。

設定リファレンス

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

quarkus.cyclonedx.skip

Whether to skip SBOM generation

Environment variable: QUARKUS_CYCLONEDX_SKIP

Show more

boolean

false

quarkus.cyclonedx.format

SBOM file format. Supported formats are {code json} and {code xml}. The default format is JSON. If both are desired then all could be used as the value of this option.

Environment variable: QUARKUS_CYCLONEDX_FORMAT

Show more

string

json

quarkus.cyclonedx.schema-version

CycloneDX specification version. The default value be the latest supported by the integrated CycloneDX library.

Environment variable: QUARKUS_CYCLONEDX_SCHEMA_VERSION

Show more

string

quarkus.cyclonedx.include-license-text

Whether to include the license text into generated SBOMs.

Environment variable: QUARKUS_CYCLONEDX_INCLUDE_LICENSE_TEXT

Show more

boolean

false

quarkus.cyclonedx.product-attribution

When Quarkus platform members include product information (a CPE and the extensions/artifacts bound to an offering) and this option is enabled, each product is represented in the SBOM as a top-level component of type framework that provides the artifacts attributed to it (CycloneDX 1.6 dependency.provides; recorded as dependsOn on older schema versions).

Environment variable: QUARKUS_CYCLONEDX_PRODUCT_ATTRIBUTION

Show more

boolean

true

Embedded dependency SBOM configuration

タイプ

デフォルト

quarkus.cyclonedx.embedded.enabled

Whether a dependency SBOM should be embedded in the final application as a classpath resource.

Environment variable: QUARKUS_CYCLONEDX_EMBEDDED_ENABLED

Show more

boolean

false

quarkus.cyclonedx.embedded.resource-name

Classpath resource name for the embedded dependency SBOM. The SBOM format (JSON or XML) is derived from the resource name extension.

Environment variable: QUARKUS_CYCLONEDX_EMBEDDED_RESOURCE_NAME

Show more

string

META-INF/sbom/dependency.cdx.json

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license. CC by 3.0

This website was built with Roq on Quarkus, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.