Arquitetura de comandos da CLI

A funcionalidade do collect-evidence está disponível por meio de duas interfaces:

1. Shell Script Wrapper (collect-evidence): Interface tradicional de script bash que oferece compatibilidade com versões anteriores
2. Comando direto da CLI (cocoa locker evidence collect): Interface CLI nativa com acesso a todos os recursos

Uso

O script collect-evidence requer os seguintes parâmetros:

• --tool-type O ID da ferramenta que fornece dados de evidência. Por exemplo: "owasp-zap-ui", "cra"
• --evidence-type O ID do tipo de prova. Por exemplo: com.ibm.image_vulnerability_scan, com.ibm.unit_tests
• --asset-key A chave em ativos de pipelinectl. Para os seguintes comandos load_artifact <key> ou load_repo <key>
• --asset-type O tipo de ativo a partir de pipelinectl e pode ser um dos seguintes tipos: repo, artifact
• --status O status da evidência pode ser um dos seguintes: success, pending, failure
• --assets Especifique diversos pares de chave de ativo e de tipo de ativo Por exemplo, é possível usar o --assets asset-key1:asset-type1 --assets asset-key2:asset-type2 Se você usar essa opção, não especifique asset-key e asset-type separadamente.

O parâmetro a seguir é opcional:

• --attachment O arquivo a ser processado como um resultado e anexado à evidência O parâmetro pode ser especificado várias vezes para vários arquivos. Para assinatura de imagem, certifique-se de que o arquivo de assinatura esteja anexado usando o parâmetro --attachment. O arquivo de assinatura deve incluir os detalhes da assinatura, como a ID da chave, o algoritmo e o resumo assinado. Os formatos comuns incluem JSON ou TXT.
• --meta Metadados arbitrários a serem adicionados às evidências. O parâmetro aceita pares de valor 'key = value' e pode ser especificado várias vezes. Você pode incluir metadados relevantes para o processo de assinatura de imagem, como o ambiente de assinatura ou qualquer configuração específica usada durante a assinatura.
• --additional-comment O comentário que é incluído em um problema se um pipeline falhou.

Use o comando a seguir para obter ajuda:

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"

Formatos de ferramentas suportados

A implementação atual suporta atualmente as seguintes ferramentas (fornecidas como o parâmetro --tool-type ):

CycloneDX O Metadata utiliza a detecção de ferramentas para o gerenciamento de problemas.

Se o script collect-evidence for chamado com um tipo de ferramenta que não é suportado, o script não tentem processar os anexos. Adicionalmente, o tratamento de emissão é ignorado, e a coleta de provas não é interrompida.

Se o seu script fornece um anexo a partir de uma ferramenta suportada, mas o anexo não pode ser processado, o tratamento de emissão é ignorado e a coleta de evidências não é interrompida.

Tipo de evidência

Você pode configurar o tipo de evidência usando o parâmetro --evidence-type. Você pode configurar qualquer tipo, mas o IBM Cloud® Compliance Manager suporta os seguintes tipos de evidência:

• 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

Coleta de tipos de evidências e mapeamento de ferramentas

Quando uma varredura falha ou quando os anexos não podem ser analisados, a ferramenta cria automaticamente um problema não relacionado a incidentes para rastrear a falha.

Requisitos de ativos

As provas que são coletadas com esta ferramenta fazem parte do trabalho de coleta de provas do V2 e das atualizações de armário de provas relacionadas.

Este novo método focaliza-se em evidências baseadas em ativos, significando que as evidências estão conectadas ao artefato e repo através das varreduras e testes que executam sobre esses artefatos ou repos, e produziram resultados para provas. Por exemplo:

• Um repo com um determinado commit torna-se um ativo commit, que é escaneado, criando evidências para o ativo commit.
• Usando o mesmo repo e commit, uma imagem é construída. A imagem se torna um ativo que está relacionado com o ativo de origem, o repo e commit.
• A imagem é escaneada, e evidências são criadas. Todos os resultados da varredura estão conectados através das evidências, seu ativo e os ativos relacionados.

Para fazer todo esse trabalho em conjunto, os ativos que são fornecidos com os parâmetros --asset-type e --asset-key devem obedecer a alguns requisitos:

Diversos ativos em coletar-evidência

Ao usar a evidência de coleta, é possível configurar a coleção simultânea de evidências para diversos ativos Você inicia a coleção de evidências usando a sinalização --assets, que especifica vários pares de chave de ativo e de tipo de ativo Por exemplo, input --assets asset-key1:asset-type1 --assets asset-key2:asset-type2. Se você escolher essa opção, não indique chave de ativo e tipo de ativo separadamente.

Lembre-se destes pontos-chave sobre a coleção de diversos ativos:

• status, attachment, tool-type, evidence-type e upload-logs são constantes em todos os ativos.
• Por padrão, quando você designa diversos ativos, o processamento de evidência segue o fluxo anterior Se você especificar um único ativo, o processamento de evidência ocorrerá por meio de um fluxo específico para a ferramenta ou anexo.
• No caso de falha, os problemas são criados por ativo Esses problemas são encerrados após uma nova execução bem-sucedida da coleção de evidências O encerramento está correlacionado com os ativos que você especificou.
• Um arquivo de evidência singular é gerado, que apresenta um ID que abrange todos os ativos combinados.