CycloneDX BOM の生成
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 は CycloneDX スキーマバージョン 1.5 で導入されました。古いバージョンでは、場所は quarkus:component:location プロパティーを使用して示されます。
|
系譜（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"
}
]
}Quarkus プロパティータクソノミー
| 名前 | 値の範囲 | 説明 |
|---|---|---|
|
|
コンポーネントがアプリケーション実行時の依存関係であるか、ビルド/開発時の依存関係であるかを示します。 |
|
パス要素として |
スキーマバージョン 1.4 以前の SBOM で使用されます。スキーマ 1.5 以降では、代わりに |
