例

Concert ツールキットのユーティリティをストリーミングデータ取り込みに使う例を参照してください。

環境の準備

環境を準備するには、exportコマンドを使って、ツールキットのデータ・ディレクトリを環境変数TOOLKIT_DATAにエクスポートします。 さらに、ソースコードのディレクトリを環境変数SRC_CODE_DIRにエクスポートします。
export HOST_DIR_SRC_CODE="/home/user/git/sample-app"
export HOST_DIR_TOOLKIT_DATA="/home/user/toolkit-data"
次に、ホスト・マシンにツールキット・データ・ディレクトリを作成し、すべてのユーザーに読み取り/書き込み/実行権限を与えます。
mkdir -p "${HOST_DIR_TOOLKIT_DATA}"
chmod 777 "${HOST_DIR_TOOLKIT_DATA}"

次に、exportコマンドを使って、ツールキット接頭辞コマンドを環境変数にエクスポートします。

export TOOLKIT_PREFIX_CMD="docker run \
  -v ${HOST_DIR_SRC_CODE}:/data/src \
  -v ${HOST_DIR_TOOLKIT_DATA}:/toolkit-data \
  ${TOOLKIT_IMAGE} \
  /bin/bash -c"
  • -v ${SRC_CODE_DIR}:/data/src は、ソースコードディレクトリをホストからコンテナの /data/src ディレクトリにマウントするために使われます。 これは、code-scanユーティリティがソースコードをスキャンするためにのみ必要です。
  • -v ${TOOLKIT_DIR}:/toolkit-data は、ツールキットデータの入出力ディレクトリをホストからコンテナにマウントするために使用します。 これは、ツールキットに入力yamlファイルを提供し、コマンド実行後にホスト・マシン上で生成されたファイルにアクセスするために必要です。
  • --rmは、コンテナ終了後にコンテナを削除するために使われます。 これは必須ではないが、一般的にはスペースをきれいにするためのベストプラクティスと考えられている。
  • ${TOOLKIT_IMAGE} は、公開されている IBM® Cloud Container Registry にあるツールキットコンテナのイメージ名とバージョンタグです。
  • /bin/bash -cはbashを使ってコンテナ内で指定されたコマンドを実行する。

最後に、個々のユーティリティを実行するには${TOOLKIT_PREFIX_CMD}環境変数を使う。

ソースコードリポジトリのスキャン（code-scan）

この例では、CycloneDX パッケージのSBOMファイル codescan-cyclonedx-sbom.json を、/data/src にあるコードリポジトリをスキャンして生成しています。 生成されたパッケージのSBOMファイルcodescan-cyclonedx-sbom.jsonは、ホストマシンの/home/user/toolkit-dataディレクトリに生成される。

${TOOLKIT_PREFIX_CMD} "code-scan --src /data/src"

Running command: 
cdxgen -r -o /toolkit-data/codescan-cyclonedx-sbom.json --validate
SBOM has been generated successfully at /toolkit-data/codescan-cyclonedx-sbom.json

コンテナ・イメージのスキャン（image-scan）

This example scans the image public.ecr.aws/ubuntu/ubuntu:latest and generate a CycloneDX package SBOM file, by passing the image name as input to the image-scan utility. 生成されたパッケージのSBOMファイルpublic.ecr.aws_ubuntu_ubuntu:latest-imagescan-cyclonedx-sbom.jsonは、ホストマシンの/home/user/toolkit-dataディレクトリに生成される。
${TOOLKIT_PREFIX_CMD} "image-scan --images public.ecr.aws/ubuntu/ubuntu:latest"

Scanning image: public.ecr.aws/ubuntu/ubuntu:latest
 ✔ Parsed image                                                                                                                             sha256:6a3f33c07c2bbb03c5582be3510f560431d8498ba1a157c499372612edbc8916
 ✔ Cataloged contents                                                                                                                              fdd0d58847114c72fe1db36565ccbceba55d9dd529c6ad36abb8d6fd6b46c97f
   ├── ✔ Packages                        [91 packages]  
   ├── ✔ File digests                    [2,038 files]  
   ├── ✔ File metadata                   [2,038 locations]  
   └── ✔ Executables                     [722 executables]
SBOM has been generated successfully at /toolkit-data/public.ecr.aws_ubuntu_ubuntu:latest-imagescan-cyclonedx-sbom.json

アプリケーションSBOMの生成app-sbom

この例では、Concert-defined (ConcertDef) deploy SBOM ファイルを app-sbom ユーティリティを使って生成します。 テキストエディタvimを使って、まずホストマシンの${TOOLKIT_DIR}ディレクトリにアプリ設定ファイルapp-config.yamlを作成します。

vim "${TOOLKIT_DIR}/app-config.yaml"

そして、app-sbomコマンドを実行する。 ${TOOLKIT_DIR} ディレクトリはコンテナの /toolkit-data ディレクトリにマウントされているので、/toolkit-data/app-config.yaml という値を app-sbom ユーティリティの --app-config オプションに渡します。 その結果、出力ファイルmy-application.jsonはホスト・マシンの/home/user/toolkit-dataディレクトリに生成される。

${TOOLKIT_PREFIX_CMD} "app-sbom --app-config /toolkit-data/app-config.yaml"

2024-09-24 23:59:14,191 - INFO - Reading configuration file: /toolkit-data/app-config.yaml
2024-09-24 23:59:14,193 - INFO - Processing image...
2024-09-24 23:59:14,193 - INFO - Processing repository...
2024-09-24 23:59:14,193 - INFO - Writing SBOM to output file: /toolkit-data/concert-sample-app-sbom.json

ビルドSBOMの生成build-sbom)

この例では、Concert-defined (ConcertDef) build SBOM ファイルを build-sbom ユーティリティを使って生成します。 テキストエディタvimを使って、まずホストマシンの${TOOLKIT_DIR}ディレクトリにビルド設定ファイルbuild-config.yamlを作成します。

vim "${TOOLKIT_DIR}/build-config.yaml"

そして、build-sbomコマンドを実行する。 ${TOOLKIT_DIR} ディレクトリはコンテナの /toolkit-data ディレクトリにマウントされているので、/toolkit-data/build-sbom-values.yaml という値を build-sbom ユーティリティの --build-config オプションに渡します。 結果の出力ファイルabc-frontend.jsonとabc-backend.jsonは、ホストマシンの/home/user/toolkit-dataディレクトリに生成される。

${TOOLKIT_PREFIX_CMD} "build-sbom --build-config /toolkit-data/build-config.yaml"

2024-09-25 00:00:13,180 - INFO - Reading configuration file: /toolkit-data/build-config.yaml
2024-09-25 00:00:13,182 - INFO - Processing component "concert-frontend"
2024-09-25 00:00:13,182 - INFO - Processing image...
2024-09-25 00:00:13,182 - INFO - Processing CycloneDX BOM link...
2024-09-25 00:00:13,182 - INFO - Processing repository...
2024-09-25 00:00:13,182 - INFO - Processing CycloneDX BOM link...
2024-09-25 00:00:13,183 - INFO - Writing SBOM to output file: /toolkit-data/concert-frontend-build-sbom.json

デプロイSBOMの生成deploy-sbom

この例では、deploy-sbom ユーティリティを使用して ConcertDef 配置 SBOM ファイルを生成します。 テキストエディタvimを使って、まずホストマシンの${TOOLKIT_DIR}ディレクトリにデプロイ設定ファイルdeploy-config.yamlを作成します。

vim "${TOOLKIT_DIR}/deploy-config.yaml"

そして、deploy-sbomコマンドを実行する。 ${TOOLKIT_DIR} ディレクトリはコンテナの /toolkit-data ディレクトリにマウントされているので、/toolkit-data/deploy-config.yaml という値を deploy-sbom ユーティリティの --deploy-config オプションに渡します。 その結果、出力ファイルabc-frontend.jsonはホスト・マシンの/home/user/toolkit-dataディレクトリに生成される。

${TOOLKIT_PREFIX_CMD} "deploy-sbom --deploy-config /toolkit-data/deploy-config.yaml"

2024-09-25 00:01:16,899 - INFO - Reading configuration file: /toolkit-data/deploy-config.yaml
2024-09-25 00:01:16,902 - INFO - Processing component #1 in deployments
2024-09-25 00:01:16,902 - INFO - Processing repository...
2024-09-25 00:01:16,902 - INFO - Processing runtime component: ocp-cluster-1 of type kubernetes
2024-09-25 00:01:16,902 - INFO - Processing image...
2024-09-25 00:01:16,902 - INFO - Processing runtime component: rhel-vm-1 of type vm
2024-09-25 00:01:16,902 - INFO - Processing image...
2024-09-25 00:01:16,902 - INFO - Processing runtime component: mydb of type db
2024-09-25 00:01:16,903 - INFO - Writing SBOM to output file: /toolkit-data/concert-deploy-sbom.json

SBOMファイルの検証（validate-sbom）

この例では、code-scanとimage-scanユーティリティによって生成されたSBOMファイルを検証します。 validate-sbomコマンドは2つのSBOMファイルcodescan-cyclonedx-sbom.jsonとpublic.ecr.aws_ubuntu_ubuntu:latest-imagescan-cyclonedx-sbom.jsonを入力として受け取る。

${TOOLKIT_PREFIX_CMD} "validate-sbom --files /toolkit-data/public.ecr.aws_ubuntu_ubuntu:latest-imagescan-cyclonedx-sbom.json,/toolkit-data/codescan-cyclonedx-sbom.json"

Validating SBOM file: /toolkit-data/public.ecr.aws_ubuntu_ubuntu:latest-imagescan-cyclonedx-sbom.json
Welcome to the sbom-utility! Version `v0.16.0` (sbom-utility) (linux/amd64)
===========================================================================
[INFO] Loading (embedded) default schema config file: `config.json`...
[INFO] Loading (embedded) default license policy file: `license.json`...
[INFO] Attempting to load and unmarshal data from: `/toolkit-data/public.ecr.aws_ubuntu_ubuntu:latest-imagescan-cyclonedx-sbom.json`...
[INFO] Successfully unmarshalled data from: `/toolkit-data/public.ecr.aws_ubuntu_ubuntu:latest-imagescan-cyclonedx-sbom.json`
[INFO] Determining file's BOM format and version...
[INFO] Determined BOM format, version (variant): `CycloneDX`, `1.6` (latest)
[INFO] Matching BOM schema (for validation): schema/cyclonedx/1.6/bom-1.6.schema.json
[INFO] Loading schema `schema/cyclonedx/1.6/bom-1.6.schema.json`...
[INFO] Schema `schema/cyclonedx/1.6/bom-1.6.schema.json` loaded.
[INFO] Validating `/toolkit-data/public.ecr.aws_ubuntu_ubuntu:latest-imagescan-cyclonedx-sbom.json`...
[INFO] BOM valid against JSON schema: `true`
Validation successful for /toolkit-data/public.ecr.aws_ubuntu_ubuntu:latest-imagescan-cyclonedx-sbom.json
Validating SBOM file: /toolkit-data/codescan-cyclonedx-sbom.json
Welcome to the sbom-utility! Version `v0.16.0` (sbom-utility) (linux/amd64)
===========================================================================
[INFO] Loading (embedded) default schema config file: `config.json`...
[INFO] Loading (embedded) default license policy file: `license.json`...
[INFO] Attempting to load and unmarshal data from: `/toolkit-data/codescan-cyclonedx-sbom.json`...
[INFO] Successfully unmarshalled data from: `/toolkit-data/codescan-cyclonedx-sbom.json`
[INFO] Determining file's BOM format and version...
[INFO] Determined BOM format, version (variant): `CycloneDX`, `1.5` (latest)
[INFO] Matching BOM schema (for validation): schema/cyclonedx/1.5/bom-1.5.schema.json
[INFO] Loading schema `schema/cyclonedx/1.5/bom-1.5.schema.json`...
[INFO] Schema `schema/cyclonedx/1.5/bom-1.5.schema.json` loaded.
[INFO] Validating `/toolkit-data/codescan-cyclonedx-sbom.json`...
[INFO] BOM valid against JSON schema: `true`
Validation successful for /toolkit-data/codescan-cyclonedx-sbom.json

ConcertDef SBOM ファイルの検証 (validate-concertdef-sbom)

この例では、Concert API を呼び出すことで、validate 構成ファイル ( validate-config.yaml ) で定義された SBOM ファイルを、カスタム Concert -defined ( Concert Def) スキーマに対して検証します。 テキストエディタ vim を使って、まずホストマシンの ${TOOLKIT_DIR} ディレクトリに検証コンフィギュレーションファイル validate-config.yaml を作成する。
vim "${TOOLKIT_DIR}/validate-config.yaml"
そして、validate-concertdef-sbomコマンドを実行する。 ${TOOLKIT_DIR} ディレクトリはコンテナの /toolkit-data ディレクトリにマウントされているので、/toolkit-data/validate-config.yaml という値を validate-concertdef-sbom ユーティリティの --validate-config オプションに渡します。
${TOOLKIT_PREFIX_CMD} "validate-concertdef-sbom --validate-config /toolkit-data/validate-config.yaml"
2024-12-06 15:02:45,886 - INFO - Read configuration file: /toolkit-data/validate-config.yaml
2024-12-06 15:02:47,575 - INFO - /toolkit-data/concert-deploy-sbom.json is a valid ConcertDef SBOM.
2024-12-06 15:02:47,575 - INFO - Validate call response /toolkit-data/concert-deploy-sbom.json: {'status': 'Success', 'status_message': 'Sbom validated sucessfully.No errors found'}

証明書インベントリファイルの生成（cert-inventory）

この例では、cert-inventoryユーティリティを使用してConcertDef証明書インベントリ・ファイルを生成します。 テキストエディタvim を使って、まずホスト・マシンの${TOOLKIT_DIR}ディレクトリに証明書コンフィギュレーション・ファイルcert-config.yamlを作成する。

vim "${TOOLKIT_DIR}/cert-config.yaml"
そして、cert-inventoryコマンドを実行する。 ${TOOLKIT_DIR} ディレクトリはコンテナの /toolkit-data ディレクトリにマウントされているので、/toolkit-data/cert-config.yaml という値を cert-inventory ユーティリティの --cert-config オプションに渡します。 その結果、出力ファイルcert-inventory.jsonはホスト・マシンの/home/user/toolkit-dataディレクトリに生成される。
${TOOLKIT_PREFIX_CMD} "cert-inventory --cert-config /toolkit-data/cert-config.yaml"

2024-09-07 01:48:40,077 - INFO - Reading configuration file: /app/samples/cert-config-sample.yaml
2024-09-07 01:48:40,080 - INFO - Fetching server certificate from: https://www.google.com
2024-09-07 01:48:40,203 - INFO - Parsing certificate file: /app/samples/certificates/cert.pem
2024-09-07 01:48:40,203 - INFO - Loaded file /app/samples/certificates/cert.pem as PEM certificate.
2024-09-07 01:48:40,203 - INFO - Parsing certificate file: /app/samples/certificates/cert.der
2024-09-07 01:48:40,204 - INFO - Loaded file /app/samples/certificates/cert.der as DER certificate.
2024-09-07 01:48:40,204 - INFO - Parsing certificate file: /app/samples/certificates/cert.pfx
2024-09-07 01:48:40,254 - INFO - Loaded file /app/samples/certificates/cert.pfx as PKCS#12 (PFX/P12) certificate.
2024-09-07 01:48:40,254 - INFO - Constructing certificate from properties entry with serial number: 416730047297653149520437355272553080019035
2024-09-07 01:48:40,255 - INFO - Certificates have been successfully written to /toolkit-data/certificates.json

CSVファイルからOSCALカタログJSONファイルへの変換（compliance-catalog）

この例では、compliance-catalogユーティリティを使用してOSCALカタログJSONファイルを生成します。 テキストエディタvim を使って、まずホスト・マシンの${TOOLKIT_DIR}ディレクトリにコンフィギュレーション・ファイルconfig.yamlを作成する。

vim "${TOOLKIT_DIR}/catalog-config.yaml"

入力ファイル形式

入力ファイルはCSVまたはExcel（XLSX）形式でなければなりません。 ファイルにはYAMLコンフィギュレーションにマッチするカラムが含まれていなければなりません。

表 1. 入力ファイルの例（CSVまたはExcel）
ファミリー コントロール ID コントロール名 コントロールの説明 関連コントロール
ファミリー1 AC-1 アクセス・コントロール 1 AC-11の説明 AC-2, AC-3
ファミリー1 AC-2 アクセス・コントロール 2 AC-2の説明 AC-1
ファミリー2 IA-1 識別 1 IA-1の説明  
必須の列:
  • ファミリー：コントロールファミリーを表す列で、コンフィギュレーションでは「columns.control_family」でマップされる。
  • コントロールID：各コントロールの一意な識別子（例えば'AC-1）で、'columns.control_idでマッピングされる。
  • コントロール名：columns.control_name でマップされるコントロール名。
  • コントロールの説明：columns.control_description でマップされるコントロールの説明。
オプションのコラム：
  • 関連コントロール：YAMLコンフィギュレーションの'columns.related_controlsでマップされる関連コントロールのリスト。 存在する場合、このカラムはコンマで区切られたコントロールIDのリストを含むべきである。
そして、compliance-catalogコマンドを実行する。 Since the ${TOOLKIT_DIR} directory is mounted to the container's /toolkit-data directory, pass the value /toolkit-data/config.yaml to the --config-file option of the compliance-catalog utility, and specify the path to the input file.
${TOOLKIT_PREFIX_CMD} "compliance-catalog --input-file /toolkit-data/input-file.csv --config-file /toolkit-data/config.yaml"
2024-09-09 17:13:35,590 - INFO - File saved to /toolkit-data/catalogs/Custom Catalog Test/csv/0.1/Custom_Catalog_Test_0.1.csv
2024-09-09 17:13:35,595 - INFO - Config file saved to /toolkit-data/catalogs/Custom Catalog Test/config/catalog-config.yaml
2024-09-09 17:13:35,628 - INFO - Processing group: Access Control
2024-09-09 17:13:35,667 - INFO - Processing group: Assessment, Authorization, and Monitoring
2024-09-09 17:13:35,683 - INFO - Processing group: Audit and Accountability
2024-09-09 17:13:35,702 - INFO - Processing group: Awareness and Training
2024-09-09 17:13:35,711 - INFO - Processing group: Configuration Management
2024-09-09 17:13:35,747 - INFO - Processing group: Contingency Planning
2024-09-09 17:13:35,774 - INFO - Processing group: Identification and Authentication
2024-09-09 17:13:35,795 - INFO - Processing group: Incident Response
2024-09-09 17:13:35,810 - INFO - Processing group: Maintenance
2024-09-09 17:13:35,822 - INFO - Processing group: Media Protection
2024-09-09 17:13:35,831 - INFO - Processing group: Personally Identifiable Information Processing and Transparency
2024-09-09 17:13:35,843 - INFO - Processing group: Personnel Security
2024-09-09 17:13:35,853 - INFO - Processing group: Physical and Environmental Protection
2024-09-09 17:13:35,872 - INFO - Processing group: Planning
2024-09-09 17:13:35,882 - INFO - Processing group: Program Management
2024-09-09 17:13:35,916 - INFO - Processing group: Risk Assessment
2024-09-09 17:13:35,929 - INFO - Processing group: Supply Chain Risk Management
2024-09-09 17:13:35,943 - INFO - Processing group: System and Communications Protection
2024-09-09 17:13:35,977 - INFO - Processing group: System and Information Integrity
2024-09-09 17:13:36,047 - INFO - Processing group: System and Services Acquisition
2024-09-09 17:13:36,391 - INFO - Catalog successfully generated at /toolkit-data/catalogs/Custom Catalog Test/oscal/json/0.1/Custom_Catalog_Test_0.1.json

Concertファイルをアップロードするupload-concert)

この例では、upload-concertユーティリティを使って、生成されたSBOMファイルをConcertにアップロードしています。 テキストエディタvimを使って、まずホストマシンの${TOOLKIT_DIR}ディレクトリにアップロード設定ファイルupload-config.yamlを作成します。

vim "${TOOLKIT_DIR}/upload-config.yaml"
そして、upload-concertコマンドを実行する。 ${TOOLKIT_DIR} ディレクトリはコンテナの /toolkit-data ディレクトリにマウントされているので、/toolkit-data/upload-config.yaml という値を upload-concert ユーティリティの --upload-config オプションに渡します。
${TOOLKIT_PREFIX_CMD} "upload-concert --upload-config /toolkit-data/upload-config.yaml"

2024-07-30 17:24:30,853 - INFO - Read configuration file: /toolkit-data/upload-config.yaml
2024-07-30 17:24:31,338 - INFO - Upload response for /toolkit-data/abc-frontend.json: {'record_paths': ['0000-0000-0000-0000/roja/application_sbom/2024/7/30/87104272_abc-frontend.json'], 'job_data': {'message': '200 OK'}}
2024-07-30 17:24:32,065 - INFO - Upload response for /toolkit-data/codescan-cyclonedx-sbom.json: {'record_paths': ['0000-0000-0000-0000/roja/package_sbom/2024/7/30/422159672_codescan-cyclonedx-sbom.json'], 'job_data': {'message': '200 OK'}}