Architecture des commandes CLI

La fonctionnalité collect-evidence est disponible via deux interfaces :

1. Shell Script Wrapper (collect-evidence): Interface de script bash traditionnelle qui assure la compatibilité ascendante
2. Commande CLI directe (cocoa locker evidence collect): Interface CLI native avec accès à toutes les fonctionnalités

Utilisation

Le script collect-evidence requiert les paramètres suivants:

• --tool-type ID de l'outil qui fournit les données d'informations collectées. Exemple : « owasp-zap-ui », « cra »
• --evidence-type L'identifiant du type de preuve. Exemple : com.ibm.image_vulnerability_scan, com.ibm.unit_tests
• --asset-key Clé dans les actifs pipelinectl. Pour les commandes suivantes load_artifact <key> ou load_repo <key>
• --asset-type Le type d'actif de pipelinectl peut être l'un des types suivants: repo, artifact
• --status Le statut d'une preuve peut être l'un des suivants : success, pending, failure
• --assets Spécifiez plusieurs paires actif-clé et actif-type. Par exemple, vous pouvez utiliser --assets asset-key1:asset-type1 --assets asset-key2:asset-type2. Si vous utilisez cette option, ne spécifiez pas la clé d'actif et le type d'actif séparément.

Le paramètre suivant est facultatif :

• --attachment Fichier à traiter en tant que résultat et joint aux informations collectées. Le paramètre peut être spécifié plusieurs fois pour plusieurs fichiers. Pour la signature d'images, assurez-vous que le fichier de signature est joint à l'aide du paramètre --attachment. Le fichier de signature doit inclure les détails de la signature, tels que l'identifiant de la clé, l'algorithme et le condensé signé. Les formats courants sont JSON ou TXT.
• --meta Métadonnées arbitraires à ajouter aux informations collectées. Le paramètre accepte les paires'key = value'et peut être spécifié plusieurs fois. Vous pouvez inclure des métadonnées relatives au processus de signature de l'image, telles que l'environnement de signature ou toute configuration spécifique utilisée lors de la signature.
• --additional-comment Commentaire ajouté à un problème si un pipeline a échoué.

Pour obtenir de l'aide, utilisez la commande suivante :

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"

Formats d'outil pris en charge

L'implémentation en cours prend actuellement en charge les outils suivants (fournis en tant que paramètre --tool-type ):

CycloneDX Metadata utilise la détection des outils pour la gestion des incidents.

Si le script collect-evidence est appelé avec un type d'outil non pris en charge, le script ne tente pas de traiter les pièces jointes. En outre, le traitement des problèmes est ignoré et la collecte des informations collectées n'est pas arrêtée.

Si votre script fournit une pièce jointe à partir d'un outil pris en charge, mais que la pièce jointe ne peut pas être traitée, le traitement des problèmes est ignoré et la collecte des informations collectées n'est pas arrêtée.

Type d'informations collectées

Vous pouvez définir le type d'informations collectées à l'aide du paramètre --evidence-type. Vous pouvez définir n'importe quel type, mais IBM Cloud® Compliance Manager prend en charge les types d'informations collectées suivants:

• 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

Collecte de données probantes et cartographie des outils

Lorsqu'une analyse échoue ou que les pièces jointes ne peuvent pas être analysées, l'outil crée automatiquement un problème non incident pour suivre l'échec.

Exigences relatives aux actifs

Les informations collectées collectées qui sont collectées à l'aide de cet outil font partie du travail de collecte d'informations collectées V2 et des mises à jour de casier d'informations collectées associées.

Cette nouvelle méthode met l'accent sur les informations collectées basées sur des actifs, ce qui signifie que les informations collectées sont connectées à l'artefact et au référentiel via les analyses et les tests qui s'exécutent sur ces artefacts ou référentiels, et ont produit des résultats pour les informations collectées. Exemple :

• Un référentiel avec une certaine validation devient un actif de validation, qui est analysé, créant des informations collectées pour l'actif de validation.
• A l'aide du même référentiel et de la même validation, une image est générée. L'image devient un actif lié à l'actif source, au référentiel et à la validation.
• L'image est analysée et des informations collectées sont créées. Tous les résultats d'analyse sont connectés via les informations collectées, son actif et les actifs associés.

Pour que tout cela fonctionne ensemble, les actifs qui sont fournis avec les paramètres --asset-type et --asset-key doivent être conformes à certaines exigences:

Plusieurs actifs en collection-informations collectées

A l'aide de la fonction de collecte d'informations collectées, vous pouvez configurer la collecte simultanée d'informations collectées pour plusieurs actifs. Vous lancez la collecte d'informations collectées à l'aide de l'indicateur --assets, qui spécifie plusieurs paires actif-clé et actif-type. Par exemple, input --assets asset-key1:asset-type1 --assets asset-key2:asset-type2. Si vous choisissez cette option, n'indiquez pas la clé d'actif et le type d'actif séparément.

Gardez à l'esprit les points clés suivants concernant la collection multi-actifs:

• status, attachment, tool-type, evidence-type et upload-logs sont constants dans tous les actifs.
• Par défaut, lorsque vous désignez plusieurs actifs, le traitement des informations collectées suit le flux existant. Si vous spécifiez un actif unique, le traitement des informations collectées s'effectue via un flux spécifique à l'outil ou à la pièce jointe.
• En cas d'échec, des problèmes sont créés par actif. Ces problèmes sont fermés lors de la réexécution réussie de la collecte d'informations collectées. La fermeture est en corrélation avec les actifs que vous avez spécifiés.
• Un fichier d'informations collectées unique est généré, qui comporte un ID englobant tous les actifs combinés.