CLI-Befehlsarchitektur

Die Funktionalität von collect-evidence ist über zwei Schnittstellen verfügbar:

1. Shell Script Wrapper (collect-evidence): Traditionelle Bash-Skript-Schnittstelle, die Abwärtskompatibilität bietet
2. Direkte CLI-Befehle (cocoa locker evidence collect): Native CLI-Schnittstelle mit vollem Funktionszugang

Verwendung

Das Script collect-evidence erfordert die folgenden Parameter:

• --tool-type Die ID des Tools, das Angabendaten bereitstellt. Zum Beispiel: „owasp-zap-ui“, „cra“
• --evidence-type Die ID des Beweis-Typs. Zum Beispiel: com.ibm.image_vulnerability_scan, com.ibm.unit_tests
• --asset-key Der Schlüssel in pipelinectl Assets. Für die folgenden Befehle load_artifact <key> oder load_repo <key>
• --asset-type Der Anlagentyp aus pipelinectl. Folgende Typen sind möglich: repo, artifact
• --status Der Status der Beweismittel kann einer der folgenden sein: success, pending, failure
• --assets Geben Sie mehrere Assetschlüssel-und Assettyppaare an. Sie können beispielsweise --assets asset-key1:asset-type1 --assets asset-key2:asset-type2 verwenden. Wenn Sie diese Option verwenden, geben Sie den Assetschlüssel und den Assettyp nicht separat an.

Der folgende Parameter ist optional:

• --attachment Die Datei, die als Ergebnis verarbeitet und an die Angaben angehängt werden soll. Der Parameter kann für mehrere Dateien mehrfach angegeben werden. Stellen Sie beim Signieren von Bildern sicher, dass die Signaturdatei mit dem Parameter --attachment angehängt wird. Die Signaturdatei muss die Signaturdetails wie Schlüssel-ID, Algorithmus und signierten Digest enthalten. Gängige Formate sind beispielsweise JSON oder TXT.
• --meta Beliebige Metadaten, die den Angaben hinzugefügt werden sollen Der Parameter akzeptiert 'key = value' -Paare und kann mehrmals angegeben werden. Sie können für den Image-Signaturvorgang relevante Metadaten einschließen, z. B. die Signaturumgebung oder bestimmte während der Signierung verwendete Konfigurationen.
• --additional-comment Der Kommentar, der zu einem Problem hinzugefügt wird, wenn eine Pipeline fehlgeschlagen ist.

Verwenden Sie den folgenden Befehl, um Hilfe zu erhalten:

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"

Unterstützte Toolformate

Die aktuelle Implementierung unterstützt derzeit die folgenden Tools (bereitgestellt als Parameter --tool-type ):

CycloneDX Metadata nutzt die Tool-Erkennung für das Problemmanagement.

Wenn das Script collect-evidence mit einem nicht unterstützten Tooltyp aufgerufen wird, versucht das Script nicht, die Anhänge zu verarbeiten. Außerdem wird die Problembehandlung übersprungen und die Angabensammlung wird nicht gestoppt.

Wenn Ihr Script einen Anhang aus einem unterstützten Tool bereitstellt, der Anhang jedoch nicht verarbeitet werden kann, wird die Problembehandlung übersprungen und die Angabensammlung nicht gestoppt.

Angabentyp

Sie können den Angabentyp mit dem Parameter --evidence-type festlegen. Sie können jeden Typ festlegen, aber IBM Cloud® Compliance Manager unterstützt die folgenden Angabentypen:

• 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

Sammlung von Belegen und Zuordnung von Instrumenten

Wenn ein Scan fehlschlägt oder Anhänge nicht geparst werden können, erstellt das Tool automatisch ein nicht-vorfallbezogenes Problem, um den Fehler zu verfolgen.

Assetanforderungen

Angaben, die mit diesem Tool erfasst werden, sind Teil der V2-Angabensammlung und der zugehörigen Angabenlockaktualisierungen.

Diese neue Methode konzentriert sich auf assetbasierte Angaben, d. h., dass Angaben über die Scans und Tests, die für diese Artefakte oder Repositorys ausgeführt werden, mit dem Artefakt und dem Repository verbunden sind und Ergebnisse für Angaben liefern. Zum Beispiel:

• Ein Repository mit einer bestimmten Festschreibung wird zu einem Festschreibungsasset, das gescannt wird und Angaben für das Festschreibungsasset erstellt.
• Mit demselben Repository und derselben Festschreibung wird ein Image erstellt. Das Bild wird zu einem Asset, das sich auf das Quellenasset, das Repository und das Commit bezieht.
• Das Bild wird gescannt und die Angaben werden erstellt. Alle Scanergebnisse werden über die Angaben, das zugehörige Asset und die zugehörigen Assets verbunden.

Damit dies funktioniert, müssen die Assets, die mit den Parametern --asset-type und --asset-key bereitgestellt werden, einige Anforderungen erfüllen:

Mehrere Assets in collect-evidence

Durch die Verwendung der Erfassung von Angaben können Sie die gleichzeitige Erfassung von Angaben für mehrere Assets konfigurieren. Sie leiten die Angabensammlung mithilfe des Flags --assets ein, das mehrere Assetschlüssel/Assettyp-Paare angibt. Beispiel: input --assets asset-key1:asset-type1 --assets asset-key2:asset-type2. Wenn Sie diese Option auswählen, geben Sie Assetschlüssel und Assettyp nicht separat an.

Denken Sie an die folgenden wichtigen Punkte zur Sammlung mit mehreren Assets:

• status, attachment, tool-type, evidence-type und upload-logs sind über alle Assets hinweg konstant.
• Wenn Sie mehrere Assets festlegen, folgt die Angabenverarbeitung standardmäßig dem traditionellen Ablauf. Wenn Sie ein einzelnes Asset angeben, erfolgt die Angabenverarbeitung über einen Ablauf, der für das Tool oder den Anhang spezifisch ist.
• Im Fehlerfall werden Probleme pro Asset erstellt. Diese Probleme werden nach einer erfolgreichen erneuten Ausführung der Angabensammlung geschlossen. Der Abschluss entspricht den Anlagen, die Sie angegeben haben.
• Es wird eine einzelne Angabendatei generiert, die eine ID enthält, die alle kombinierten Assets umfasst.