CLIコマンド・アーキテクチャ

collect-evidence の機能は2つのインターフェイスから利用できる：

1. シェルスクリプトラッパー (collect-evidence)：後方互換性を提供する伝統的な bash スクリプトインターフェース
2. ダイレクトCLIコマンド (cocoa locker evidence collect)：全機能にアクセスできるネイティブCLIインターフェイス

使用法

スクリプト collect-evidence には、以下のパラメーターが必要です。

• --tool-type エビデンス・データを提供するツールの ID。 以下に例を示します。 「owasp-zap-ui」、「cra」
• --evidence-type 証拠タイプのID。 以下に例を示します。 com.ibm.image_vulnerability_scan, com.ibm.unit_tests
• --asset-key pipelinectl 資産内のキー。 以下のコマンドについて説明します。 load_artifact <key> または load_repo <key>
• --asset-type pipelinectl の資産タイプ。以下のいずれかのタイプにすることができます。 repo, artifact
• --status 証拠のステータスは、以下のいずれかになります： success, pending, failure
• --assets 複数の資産キーと資産タイプのペアを指定してください。 例えば、 --assets asset-key1:asset-type1 --assets asset-key2:asset-type2 を使用できます。 このオプションを使用する場合は、asset-key と asset-type を別々に指定しないでください。

以下のパラメータは省略可能です：

• --attachment 結果として処理され、エビデンスに添付されるファイル。 このパラメーターは、複数のファイルに対して複数回指定できます。 画像署名の場合、--attachmentパラメータを使用して署名ファイルが添付されていることを確認する。 署名ファイルには、鍵ID、アルゴリズム、署名済みダイジェストなど、署名の詳細を含める必要がある。 一般的なフォーマットにはJSONやTXTがある。
• --meta エビデンスに追加する任意のメタデータ。 このパラメーターは「キー = 値」のペアを受け入れ、複数回指定できます。 署名環境や署名中に使用された特定の設定など、イメージ署名プロセスに関連するメタデータを含めることができます。
• --additional-comment パイプラインが失敗した場合に問題に追加されるコメント。

ヘルプを表示するには、次のコマンドを実行してください：

collect-evidence --help

# example on how to read the output into a variable in bash
read -r status < <(collect-evidence "${evidence_params[@]}")
echo $status # success

collect-evidence-version=v2

cocoa locker evidence collect \
  --tool-type "sonarqube" \
  --evidence-type "com.ibm.static_scan" \
  --assets "app-repo:repo" \
  --status "success" \
  --attachment ./sonarqube-result.json \
  --pipeline-run-id "${PIPELINE_RUN_ID}" \
  --pipeline-namespace "ci" \
  --incident-org "my-org" \
  --incident-repo "compliance-issues"

cocoa locker evidence collect \
  --tool-type "detect-secrets" \
  --evidence-type "com.ibm.detect_secrets" \
  --assets "app-repo:repo" \
  --status "success" \
  --pipeline-run-id "${PIPELINE_RUN_ID}" \
  --pipeline-namespace "ci" \
  --incident-org "my-org" \
  --incident-repo "compliance-issues"

cocoa locker evidence collect \
  --tool-type "va" \
  --evidence-type "com.ibm.cloud.image_vulnerability_scan" \
  --assets "image-0:artifact" \
  --status "success" \
  --pipeline-run-id "${PIPELINE_RUN_ID}" \
  --attachment image-0_va-report.json \
  --pipeline-namespace "ci" \
  --incident-org "my-org" \
  --incident-repo "compliance-issues"

collect-evidence \
  --tool-type "sonarqube" \
  --evidence-type "com.ibm.static_scan" \
  --asset-type "repo" \
  --asset-key "app-repo" \
  --status "success" \
  --attachment ./sonarqube-result-1.json \
  --attachment ./sonarqube-result-2.json \
  --meta environment=staging

collect-evidence \
  --tool-type "ciso-code-signing" \
  --evidence-type "com.ibm.cloud.image_signing" \
  --asset-type "artifact" \
  --asset-key "signed-image" \
  --status "success" \
  --attachment ./signature.json \   # The signature details in JSON format
  --attachment "./${artifact}.fingerprint" \ #  The fingerprint is a hash value generated from the artifact, ensuring integrity and authenticity.
  --meta environment=production

cocoa locker evidence collect \
  --tool-type "sonarqube" \
  --evidence-type "com.ibm.static_scan" \
  --assets "app-repo:repo" \
  --status "success" \
  --attachment ./sonarqube-result.json \
  --pipeline-run-id "${PIPELINE_RUN_ID}" \
  --pipeline-namespace "ci" \
  --incident-org "my-org" \
  --incident-repo "compliance-issues"

サポートされるツール・フォーマット

現在の実装では、以下のツール ( --tool-type パラメーターとして提供) が現在サポートされています。

CycloneDX metadataでは、課題管理にツール検出機能を利用しています。

サポートされていないツール・タイプを指定して collect-evidence スクリプトを呼び出した場合、スクリプトは添付ファイルの処理を試行しません。 さらに、問題の処理はスキップされ、エビデンス収集は停止されません。

スクリプトがサポートされているツールから添付ファイルを提供しているが、添付ファイルを処理できない場合、問題の処理はスキップされ、エビデンス・コレクションは停止されません。

エビデンス・タイプ

--evidence-type パラメーターを使用して、エビデンス・タイプを設定できます。 任意のタイプを設定できますが、 IBM Cloud® Compliance Manager は以下のエビデンス・タイプをサポートします。

• com.ibm.unit_tests
• com.ibm.detect_secrets
• com.ibm.branch_protection
• com.ibm.static_scan
• com.ibm.code_vulnerability_scan
• com.ibm.code_bom_check
• com.ibm.code_cis_check
• com.ibm.cloud.image_vulnerability_scan
• com.ibm.cloud.image_signing
• com.ibm.dynamic_scan
• com.ibm.cloud.image_signing
• com.ibm.acceptance_tests
• com.ibm.prod_change_request
• com.ibm.close_change_reques

証拠収集とツールマッピング

スキャンに失敗した場合、または添付ファイルが解析できない場合、ツールは自動的にインシデントではない問題を作成し、失敗を追跡します。

資産要件

このツールで収集されるエビデンスは、 V2 エビデンス収集作業および関連するエビデンス・ロッカー更新の一部です。

この新しいメソッドは、アセット・ベースのエビデンスに焦点を当てます。つまり、エビデンスは、それらの成果物またはリポジトリーで実行されるスキャンおよびテストを介して成果物およびリポジトリーに接続され、エビデンスの結果を生成します。 以下に例を示します。

• 特定のコミットを持つリポジトリーはコミット・アセットになり、スキャンされて、コミット・アセットのエビデンスが作成されます。
• 同じリポジトリーとコミットを使用して、イメージが作成されます。 イメージは、ソース・アセット、リポジトリー、およびコミットに関連するアセットになります。
• 画像がスキャンされ、証拠が作成されます。 すべてのスキャン結果は、エビデンス、そのアセット、および関連するアセットを介して接続されます。

これらをすべて一緒に機能させるには、パラメーター --asset-type および --asset-key で提供される資産がいくつかの要件に準拠している必要があります。

収集中の複数の資産-エビデンス

証拠収集を使用することで、複数の資産に対する証拠の同時収集を構成できます。 複数の資産キーと資産タイプのペアを指定する --assets フラグを使用して、証拠収集を開始します。 例えば、input --assets asset-key1:asset-type1 --assets asset-key2:asset-type2 です。 このオプションを選択する場合は、asset-key と asset-type を個別に指定しないでください。

マルチアセット・コレクションに関する以下のキーポイントに留意してください。

• status、 attachment、 tool-type、 evidence-type、および upload-logs は、すべての資産にわたって一定です。
• デフォルトでは、複数の資産を指定すると、エビデンス処理はレガシー・フローに従います。 単一の資産を指定すると、そのツールまたは添付ファイルに固有のフローを介してエビデンス処理が行われます。
• 障害が発生した場合は、資産ごとに問題が作成されます。 これらの問題は、証拠収集が正常に再実行されるとクローズされます。 クロージャーは、指定した資産と相関関係にあります。
• 結合されたすべての資産を含む ID を含む単一のエビデンス・ファイルが生成されます。