collect-evidence script

CLI Command Architecture

The collect-evidence functionality is available through two interfaces:

1. Shell Script Wrapper (collect-evidence): Traditional bash script interface that provides backward compatibility
2. Direct CLI Command (cocoa locker evidence collect): Native CLI interface with full feature access

Usage

The script collect-evidence requires the following parameters:

• --tool-type The ID of the tool that provides evidence data. For example: "owasp-zap-ui", "cra"
• --evidence-type The ID of the evidence type. For example: com.ibm.image_vulnerability_scan, com.ibm.unit_tests
• --asset-key The key in pipelinectl assets. For the following commands load_artifact <key> or load_repo <key>
• --asset-type The asset type from pipelinectl and can be one of the following types: repo, artifact
• --status The evidence status and can be one of the following: success, pending, failure
• --assets Specify multiple asset-key and asset-type pairs. For example, you can use --assets asset-key1:asset-type1 --assets asset-key2:asset-type2. If you use this option, do not specify asset-key and asset-type separately.

The following parameter is optional:

• --attachment The file to be processed as a result and attached to the evidence. The parameter can be specified multiple times for multiple files. For image signing, ensure that the signature file is attached using the --attachment parameter. The signature file must include the signature details, such as key ID, algorithm, and signed digest. Common formats include JSON or TXT.
• --meta Arbitrary metadata to be added to the evidence. The parameter accepts 'key=value' pairs and can be specified multiple times. You can include metadata relevant to the image signing process, such as the signing environment or any specific configurations used during the signing.
• --additional-comment The comment that is added to an issue if a pipeline has failed.

Use the following command to get help:

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"

Supported tool formats

The current implementation currently supports the following tools (provided as the --tool-type parameter):

CycloneDX metadata is Tool detection for issue management

If the collect-evidence script is called with a tool type that is not supported, the script doesn't attempt to process the attachments. Additionally, the issue handling is skipped, and the evidence collection is not stopped.

If your script provides an attachment from a supported tool, but the attachment cannot be processed, the issue handling is skipped, and the evidence collection is not stopped.

Evidence type

You can set the evidence type by using the --evidence-type parameter. You can set any type, but the IBM Cloud® Compliance Manager supports the following evidence types:

• 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

Evidence type collection and tool mapping

When a scan fails or when attachments cannot be parsed, the tool automatically creates a non-incident issue to track the failure.

Asset requirements

Evidence that is collected with this tool is part of the V2 evidence collection work and the related evidence locker updates.

This new method focuses on asset-based evidence, meaning that evidence is connected to the artifact and repo through the scans and tests that run on those artifacts or repos, and produced results for evidence. For example:

• A repo with a certain commit becomes a commit asset, which is scanned, creating evidence for the commit asset.
• Using the same repo and commit, an image is built. The image becomes an asset that is related to the source asset, the repo and commit.
• The image is scanned, and evidence is created. All scan results are connected through the evidence, its asset, and the related assets.

To make all this work together, the assets that are provided with the parameters --asset-type and --asset-key must comply with some requirements:

`collect-evidence --tool-type toolType --evidence-type  artifact --asset-key artifact-1 ...`

Multiple assets in collect-evidence

By using collect-evidence, you can configure the simultaneous collection of evidence for multiple assets. You initiate evidence collection by using the --assets flag, which specifies multiple asset-key and asset-type pairs. For example, input --assets asset-key1:asset-type1 --assets asset-key2:asset-type2. If you choose this option, don't indicate asset-key and asset-type separately.

Remember these key points about the multi-asset collection:

• status, attachment, tool-type, evidence-type, and upload-logs are constant across all assets.
• By default, when you designate multiple assets, evidence processing follows the legacy flow. If you specify a single asset, evidence processing occurs through a flow that is specific to the tool or attachment.
• In case of failure, issues are created per asset. These issues are closed upon successful rerun of evidence collection. Closure correlates with the assets that you specified.
• A singular evidence file is generated, which features an ID that encompasses all combined assets.