Ajuda do Code Risk Analyzer

O comando a seguir exibe a lista de comandos do Code Risk Analyzer:

ibmcloud cra --help

Ajuda de comando do Code Risk Analyzer

O comando a seguir exibe os detalhes de sinalizadores usados com um comando. Use o ibmcloud cra --help para exibir os comandos disponíveis.

ibmcloud cra <command> --help

Requisitos de comando BOM

O comando bom-generate depende de determinados comandos externos:

• Se o caminho contém Dockerfiles, este comando suspende imagens de base e constrói imagens para cada estágio de construção em cada Dockerfile. Neste cenário, o comando bom-generate requer que os comandos Docker cli e tar estejam disponíveis.
• Se o caminho contém arquivos Maven, este comando usa mvn para construir uma lista de dependências. Neste cenário, o comando bom-generate requer que o comando mvn esteja disponível.
• Se o caminho contiver arquivos Gradle, este comando usará gradle para construir uma lista de dependências. Neste cenário, o comando bom-generate requer que o comando gradle esteja disponível.
• Se o caminho contiver arquivos Node.js package-json e este comando for usado para gerar um arquivo package-lock.json correspondente, o comando bom-generate usará o npm para construir o arquivo package-lock.json. Neste cenário, o comando requer que o comando npm esteja disponível.
• Se o caminho contiver os arquivos Python requirements.txt ou pyproject.toml, o comando usará pip para gerar as dependências do pacote. Nesse cenário, o comando bom-generate exige que o comando pip esteja disponível. Tanto Python versão 2 quanto Python versão 3 são suportados.

Caso você esteja usando Dockerfiles, certifique-se de efetuar login no seu registro de contêiner a partir de onde as imagens de base devem ser puxadas.

Se o seu Dockerfile requer ARGS, configure um ARG individual como variável de ambiente antes de executar o comando. Por exemplo, se o Dockerfile estiver usando um ARG IAM_USER, exporte uma variável de ambiente denominada IAM_USER: export IAM_USER='value'. A CLI passa automaticamente essas variáveis de ambiente para o comando docker build.

Também é possível especificar a sinalização DOCKERBUILDFLAGS explicitamente. Para exportar o DOCKERBUILDFLAGS com a sinalização ARGS Docker, digite o seguinte comando:

export DOCKERBUILDFLAGS="--build-arg IAM_USER --build-arg API_KEY"

Opções de comando BOM

A tabela a seguir lista as opções de comando que você pode usar para gerar uma lista técnica com o comando bom-generate.

Ignorando arquivos

Se o caminho contiver o arquivo .cra/.fileignore, arquivos especificados no arquivo .fileignore não serão escaneados para dependências. O arquivo .fileignore deve seguir as regras dos arquivos .gitignore. Semelhante a um arquivo .gitignore, o arquivo .fileignore pode incluir comentários, diretórios a serem ignorados, arquivos a serem ignorados e outros padrões.

O arquivo .fileignore de exemplo a seguir mostra como excluir scripts bash, node_modules e o Dockerfile.

# Ignore nested functional_tests directory
**/functional_tests

# Ignore bash scripts
**/*.sh

# This should allow this one file
!test/gatling_tests/loginTobx.sh

# Ignore node_modules
node_modules

# Exclude the dockerfile from scanning
Dockerfile

Configuração de vários contextos de compilação em Docker

Ao trabalhar com vários Dockerfiles em um único projeto, talvez você queira definir contextos de compilação separados para cada Dockerfile. Isso pode ser feito usando um arquivo .cra/.dockerbuildcontext, que é um arquivo JSON que mapeia os caminhos do Dockerfile para seus contextos de compilação correspondentes.

Se houver um arquivo .cra/.dockerbuildcontext no diretório do seu projeto, os comandos de compilação do CRA Docker usarão os caminhos especificados nesse arquivo como contextos de compilação para os Dockerfiles associados. As chaves no objeto JSON representam os caminhos relativos para os Dockerfiles, enquanto os valores especificam os caminhos relativos para os respectivos contextos de compilação.

Aqui está um exemplo de um arquivo .dockerbuildcontext que define diferentes contextos de compilação para vários Dockerfiles:

{
  "Dockerfile": "./",
  "path/to/different/Dockerfile": "./another/Path"
}

Exemplo

Os fragmentos de código a seguir mostram como usar o comando bom-generate:

ibmcloud cra bom-generate --path PATH --report REPORT [--asset-type ASSET-TYPE] [--dockerbuildcontext] [--dockerbuildflags DOCKERBUILDFLAGS] [--dockerfilepattern DOCKERFILEPATTERN] [--gradle.excludeconfigurations GRADLE.EXCLUDECONFIGURATIONS] [--maven.excludescopes MAVEN.EXCLUDESCOPES] [--nodejs.createpackagelock] [--prev-report PREV-REPORT] [--region REGION] [--toolchainid TOOLCHAINID] [--verbose]

ibmcloud cra bom --path . --report bomreport.json

Opções de comando de varredura de vulnerabilidades

A tabela a seguir lista as opções para usar o comando vulnerability-scan.

Ignorando vulnerabilidades

Se o parâmetro -c ou --cveignore for especificado, o comando procurará esse arquivo e não relatará os CVEs especificados no arquivo. É possível configurar os CVEs para omiti-los indefinidamente até que uma correção esteja disponível, ou até uma data de expiração especificada.

O exemplo a seguir mostra um esquema JSON para o arquivo .cveignore:

[
    {
        "cve": "string",
	    "alwaysOmit": "bool",
	    "untilRemediationAvailable": "bool",
	    "expiration": "string"
    }
]

As propriedades a seguir são suportadas para cada entrada no arquivo .cveignore:

• cve - a vulnerabilidade a ser omitida. O valor dessa propriedade é uma ID CVE.
• alwaysOmit - se esta propriedade for configurada como true, a vulnerabilidade será omitida até que seja alterada. Esta propriedade tem precedência sobre outros valores da propriedade.
• untilRemediationAvailable - se esta propriedade for configurada como true, a vulnerabilidade será omitida até que um caminho de correção esteja disponível. Se uma correção for disponibilizada, a vulnerabilidade não será omitida e uma mensagem será exibida. Esta propriedade tem precedência sobre o valor da propriedade de expiração.
• expiração - se essa propriedade for definida como true e a data de expiração não for atingida, a vulnerabilidade será omitida. Se a data de expiração for atingida, a vulnerabilidade não será omitida e uma mensagem será exibida. Use o formato de hora RFC3339 (yyyy-MM-ddTHH:mm:ss[+-]Z) para definir esta propriedade.

O Code Risk Analyzer usa apenas essas propriedades definidas. É possível incluir propriedades sem efeito em funções. Caso uma vulnerabilidade definida em .cveignore não seja omitida, será gerado um log explicando o motivo. Se uma vulnerabilidade definida no arquivo .cveignore for omitida, não haverá nenhuma criação de log individual. O número de omissões e uma lista dos IDs de vulnerabilidade, com o nome do pacote, que são omitidos são registrados após a conclusão de um relatório.

O trecho de código a seguir mostra um arquivo .cveignore de amostra:

[
    {
        "cve": "CVE-2021-27290",
        "alwaysOmit": true
    },
    {
        "cve": "CVE-2020-8244",
        "untilRemediationAvailable": true,
    }
]

Exemplo

Os fragmentos de código a seguir mostram como usar o comando vulnerability-scan:

ibmcloud cra vulnerability-scan --bom BOM [--cveignore CVEIGNORE] [--report REPORT] [--excludedev] [--include-nofix app,os,all,none] [--region REGION] [--strict] [--toolchainid TOOLCHAINID] [--output OUTPUTFILE]

ibmcloud cra cve --bom ./bom-file.json --cveignore ./cveignore-example.json --report ./output-vulnerability-report.json --excludedev --include-nofix all --strict

Opções do comando de implementação

A tabela a seguir lista as opções de comandos aplicáveis para o comando deployment-analyze.

Exemplo

Os fragmentos de código a seguir mostram como usar o comando deployment-analyze:

ibmcloud cra deployment-analyze --path PATH --report REPORT [--fileignore FILE_IGNORE] [--strict]

ibmcloud cra depl --path ./sampleDir --report deployment-report.json --strict

NetworkPolicy opções de comando de análise

A tabela a seguir lista as opções de comandos aplicáveis para o comando netpol-analyze.

Exemplo

Os exemplos de trechos de código a seguir mostram como você pode usar o comando netpol-analyze:

ibmcloud cra netpol-analyze --path PATH --report REPORT [--connectivity CONNFILE] [--lint LINTFILE] [--strict]

ibmcloud cra np --path ./sampleDir --report netpol-report.json --strict

Imagem do analisador de configuração de rede

O comando netpol-analyze é executado como parte do Network Config Analyzer(NCA ) do IBM. Como esse comando executa o NCA como uma imagem Docker, você deve instalar o Docker em seu computador.

A imagem URL para o analisador de políticas de rede é icr.io/continuous-delivery/cra/nca.

Se a imagem do analisador ainda não estiver no seu registro local, o comando netpol-analyze extrai a imagem mais recente do analisador (incluindo correções para quaisquer vulnerabilidades) do site global IBM Cloud® Container Registry.

Exemplo de scripts customizados para DevSecOps

Caso o seu Dockerfile exija ARGS, use o parâmetro cra-custom-script-path para configurar um ARG individual como variável de ambiente antes de executar o comando. O caminho de script customizado é o caminho para um script que reside no projeto do usuário. Por exemplo, se o Dockerfile usar IAM_USER ARG, exporte uma variável de ambiente dentro do script denominado IAM_USER: export IAM_USER='value'. Se o ARG exigido pelo seu Dockerfile for configurado como uma propriedade de ambiente dentro das cadeias de ferramentas, use get_env para obter o valor. Nesta instância, é possível exportar uma variável de ambiente dentro do script do IAM_USER: export IAM_USER=$(get_env iam_user_environment_property_name). A tarefa run-cra capta automaticamente essas variáveis de ambiente e as passa para os comandos de construção do Docker.

O exemplo a seguir mostra como usar o cra-custom-script para exportar a variável ENV:

#!/usr/bin/env bash

if [[ "${PIPELINE_DEBUG:-0}" == 1 ]]; then
    trap env EXIT
    env | sort
    set -x
fi

export IAM_USER=$(get_env iam_user_environment_property_name)

Também é possível usar o parâmetro cra-custom-script-path para cenários cujas versões da ferramenta de imagem base do DevSecOps podem estar ultrapassadas, com base em seu projeto. Por exemplo, é possível atualizar comandos como pip/pip3 para descobrir pacotes Python que requerem uma versão pip posterior.

O exemplo a seguir mostra como usar o cra-custom-script para atualizar a versão pip:

#!/usr/bin/env bash

if [[ "${PIPELINE_DEBUG:-0}" == 1 ]]; then
    trap env EXIT
    env | sort
    set -x
fi

python3 -m pip install --upgrade pip

Se o seu Dockerfile usar uma imagem a partir de um registro privado do Docker, use o parâmetro cra-custom-script-path para autenticar em um registro privado do Docker antes de executar o Code Risk Analyzer e para permitir que o Code Risk Analyzer faça o pull desta imagem para varredura.

O exemplo a seguir mostra como usar o cra-custom-script para autenticação no registro de contêiner ibmcloud:

#!/usr/bin/env bash

if [[ "${PIPELINE_DEBUG:-0}" == 1 ]]; then
    trap env EXIT
    env | sort
    set -x
fi

ibmcloud cr login

Depurando o Code Risk Analyzer em DevSecOps

Para ajudar com a depuração, execute o Code Risk Analyzer localmente como interface de linha de comandos (CLI) em sua própria máquina local. Para obter informações sobre como executar o ibmcloud cra bom-generate comando para gerar uma BOM, veja Lista de materiais(BOM). Depois de gerar a lista técnica, use o comando ibmcloud cra cve para listar todas as vulnerabilidades. Para mais informações sobre como executar o comando ibmcloud cra cve, consulte Varredura de vulnerabilidade.

Certifique-se de que a tarefa run-cra não contenha erros. Se a tarefa contiver erros, verifique se o seu pipeline usa a versão atual do DevSecOps. Caso o problema não seja resolvido verificando a versão do DevSecOps, os exemplos a seguir fornecem alguns erros comuns e soluções propostas.

FAILED
Error executing docker pull cmd: [docker pull us.icr.io/opentoolchain/ibmnode:14ubisecure]

É possível verificar se você tem acesso ao registro privado. Caso você não tenha acesso, use o parâmetro cra-custom-script-path e especifique o caminho para um script customizado executado antes de o Code Risk Analyzer autenticar no registro privado.

FAILED
Error executing docker build cmd for stage-0: exit status 1

Caso o seu Dockerfile exija ARGS, o comando docker build para os estágios de construção falhará ao construir devido ao ARGS ausente. O cra-custom-script-path é necessário para configurar o ARGS como variáveis de ambiente. Para mais informações sobre como configurar o script customizado, consulte Exemplos de scripts customizados para DevSecOps.

FAILED
Error executing docker build cmd for stage-0: exit status 1
...
COPY file-to-copy.js file-to-copy.js:
------
failed to compute cache key: "/file-to-copy.js" not found: not found

Por padrão, o comando bom-generate do Code Risk Analyzer constrói os Dockerfiles a partir do contexto da localização do próprio Dockerfile. Ao construir os Dockerfiles a partir do contexto do diretório do projeto raiz, use o parâmetro cra-docker-build-context para permitir que o Code Risk Analyzer construa os Dockerfiles a partir deste contexto.

Como posso determinar por que a CLI falhou?

Antes de chamar a CLI do Code Risk Analyzer, configure a variável de ambiente IBMCLOUD_TRACE para true para ativar o log de depuração.

export IBMCLOUD_TRACE=true

Observe as chamadas de API e as respostas mostradas no log para determinar a razão exata da falha.

Como posso depurar um comando BOM que falha ao fazer pull de uma imagem base a partir de um registro privado.

Certifique-se de estar autenticado com o registro onde reside a imagem base usando o comando ibmcloud cr login ou o comando docker login.

Como posso depurar um comando BOM que está falhando ao analisar um Dockerfile?

• Verifique se o Dockerfile não tem nenhum problema executando o comando docker build e certificando-se de que ele seja aprovado.
• Caso o seu Dockerfile exija que o ARG seja aprovado, certifique-se de que o ARG esteja configurado como uma variável de ambiente. Também é possível usar a variável de ambiente DOCKERBUILDFLAG.
• Autentique com o registro que contenha as imagens de base.

Estou vendo resultados falsos positivos inesperados. O que devo fazer?

Execute o pipeline de implantação contínua (CD) do site DevSecOps para gerar um SBOM atualizado no armário de evidências. Isso pode abordar uma possível causa de falsos positivos que resulta da presença de um SBOM mais antigo gerado pelo pipeline de conformidade contínua (CC) do site DevSecOps.

Por que a gravidade do relatório ou do problema é diferente da gravidade do link de vulnerabilidade associado?

Como nossa fonte de informações sobre vulnerabilidades mudou recentemente, você poderá ver que a gravidade associada a uma determinada vulnerabilidade foi alterada. O Code Risk Analyzer determinará a gravidade ideal com base em um cálculo de todas as fontes de vulnerabilidades.