Guida all'analizzatore di rischio del codice

Il comando seguente visualizza l'elenco dei comandi di Code Risk Analyzer:

ibmcloud cra --help

Guida al comando Code Risk Analyzer

Il seguente comando visualizza i dettagli dei flag utilizzati con un comando. Utilizzare ibmcloud cra --help per visualizzare i comandi disponibili.

ibmcloud cra <command> --help

Requisiti del comando della distinta base

Il comando bom-generate dipende da alcuni comandi esterni:

• Se il percorso contiene file Docker, questo comando estrae le immagini di base e le immagini di compilazione per ogni fase di compilazione in ogni file Docker. In questo scenario, il comando bom-generate richiede che siano disponibili i comandi Docker cli e tar.
• Se il percorso contiene file Maven, questo comando usa mvn per costruire un elenco di dipendenze. In questo scenario, il comando bom-generate richiede che il comando mvn sia disponibile.
• Se il percorso contiene i file Gradle, questo comando usa gradle per costruire un elenco di dipendenze. In questo scenario, il comando bom-generate richiede che il comando gradle sia disponibile.
• Se il percorso contiene i file Node.js package-json e questo comando viene usato per generare un file package-lock.json corrispondente, il comando bom-generate utilizza npm per costruire il file package-lock.json. In questo scenario, il comando richiede che sia disponibile il comando npm.
• Se il percorso contiene i file Python requirements.txt o pyproject.toml, il comando utilizza pip per generare le dipendenze del pacchetto. In questo scenario, il comando bom-generate richiede che il comando pip sia disponibile. Sono supportate sia la versione 2 di Python che la versione 3 di Python.

Se si usa Dockerfiles, assicurarsi di accedere al registro dei container da cui estrarre le immagini di base.

Se il file Docker richiede ARGS, impostare un singolo ARG come variabile d'ambiente prima di eseguire il comando. Ad esempio, se il file Docker utilizza un ARG IAM_USER, esportare una variabile d'ambiente denominata IAM_USER: export IAM_USER='value'. La CLI passa automaticamente queste variabili d'ambiente al comando docker build.

È anche possibile specificare esplicitamente il flag DOCKERBUILDFLAGS. Per esportare DOCKERBUILDFLAGS con il flag ARGS Docker, digitate il seguente comando:

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

Opzioni del comando BOM

La tabella seguente elenca le opzioni di comando che si possono utilizzare per generare una distinta base con il comando bom-generate.

Ignorare i file

Se il percorso contiene il file .cra/.fileignore, i file specificati nel file .fileignore non vengono analizzati per le dipendenze. Il file .fileignore deve seguire le regole dei file .gitignore. Simile al file .gitignore, il file .fileignore può includere commenti, directory da ignorare, file da ignorare e altri schemi.

Il seguente esempio di file .fileignore mostra come escludere gli script bash, i node_modules e il 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

Impostazione di contesti di costruzione multipli Docker

Quando si lavora con più file Docker all'interno di un singolo progetto, si potrebbe voler definire contesti di compilazione separati per ogni file Docker. Questo si può ottenere usando un file .cra/.dockerbuildcontext, che è un file JSON che mappa i percorsi dei file Docker con i corrispondenti contesti di compilazione.

Se nella cartella del progetto esiste un file .cra/.dockerbuildcontext, i comandi di compilazione di CRA Docker useranno i percorsi specificati in questo file come contesti di compilazione per i file Docker associati. Le chiavi dell'oggetto JSON rappresentano i percorsi relativi ai file Docker, mentre i valori specificano i percorsi relativi ai rispettivi contesti di compilazione.

Ecco un esempio di file .dockerbuildcontext che definisce contesti di compilazione diversi per più file Docker:

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

Esempio

I seguenti frammenti di codice mostrano come utilizzare il 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

Opzioni del comando di scansione delle vulnerabilità

La tabella seguente elenca le opzioni per l'utilizzo del comando vulnerability-scan.

Ignorare le vulnerabilità

Se viene specificato il parametro -c o --cveignore, il comando cerca quel file e non riporta le CVE specificate nel file. È possibile configurare i CVE in modo da ometterli a tempo indeterminato fino a quando non sarà disponibile un rimedio o fino a una data di scadenza specificata.

L'esempio seguente mostra uno schema JSON per il file .cveignore:

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

Per ogni voce del file .cveignore sono supportate le seguenti proprietà:

• cve- La vulnerabilità da omettere. Il valore di questa proprietà è un ID CVE.
• alwaysOmit- Se questa proprietà è impostata su true, la vulnerabilità viene omessa finché non viene modificata. Questa proprietà ha la precedenza sui valori delle altre proprietà.
• untilRemediationAvailable- Se questa proprietà è impostata su true, la vulnerabilità viene omessa finché non è disponibile un percorso di correzione. Se è disponibile un rimedio, la vulnerabilità non viene omessa e viene visualizzato un messaggio. Questa proprietà ha la precedenza sul valore della proprietà di scadenza.
• expiration- Se questa proprietà è impostata su true e la data di scadenza non è stata raggiunta, la vulnerabilità viene omessa. Se la data di scadenza viene raggiunta, la vulnerabilità non viene omessa e viene visualizzato un messaggio. Per definire questa proprietà, utilizzare il formato orario RFC3339 (yyyy-MM-ddTHH:mm:ss[+-]Z).

Il Code Risk Analyzer utilizza solo queste proprietà definite. È possibile aggiungere proprietà senza alcun effetto sulle funzioni. Se una vulnerabilità definita in .cveignore non viene omessa, viene generato un log che ne spiega il motivo. Se una vulnerabilità definita nel file .cveignore viene omessa, non viene visualizzata alcuna registrazione individuale. Il numero di omissioni e l'elenco degli ID delle vulnerabilità, con il nome del pacchetto, che sono stati omessi, vengono registrati al termine di un report.

Il seguente frammento di codice mostra un esempio di file .cveignore:

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

Esempio

I seguenti frammenti di codice mostrano come utilizzare il 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

Opzioni del comando di distribuzione

La tabella seguente elenca le opzioni di comando che si possono utilizzare per il comando deployment-analyze.

Esempio

I seguenti frammenti di codice mostrano come utilizzare il 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 opzioni del comando di analisi

La tabella seguente elenca le opzioni di comando che si possono utilizzare per il comando netpol-analyze.

Esempio

I seguenti esempi di codice mostrano come utilizzare il 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

Immagine dell'analizzatore di rete

Il comando netpol-analyze viene eseguito come parte di IBM 's Network Config Analyzer(NCA). Poiché questo comando esegue NCA come immagine di Docker, è necessario installare Docker sul computer.

L'immagine URL per il Network Policy Analyzer è icr.io/continuous-delivery/cra/nca.

Se l'immagine dell'analizzatore non è già presente nel registro locale, il comando netpol-analyze estrae l'immagine più recente dell'analizzatore (comprese le correzioni per eventuali vulnerabilità) dal sito globale IBM Cloud® Container Registry.

Esempi di script personalizzati per DevSecOps

Se il vostro file Docker richiede ARGS, potete usare il parametro cra-custom-script-path per impostare un singolo ARG come variabile d'ambiente prima di eseguire il comando. Il percorso dello script personalizzato è il percorso di uno script che risiede nel progetto dell'utente. Ad esempio, se il file Docker utilizza IAM_USER ARG, esportare una variabile d'ambiente all'interno dello script denominata IAM_USER: export IAM_USER='value'. Se l'ARG richiesto dal file Docker è impostato come proprietà dell'ambiente all'interno della toolchain, si può usare get_env per ottenere il valore. In questo caso, è possibile esportare una variabile d'ambiente all'interno dello script IAM_USER: export IAM_USER=$(get_env iam_user_environment_property_name). Il task run-cra acquisisce automaticamente queste variabili d'ambiente e le passa ai comandi di compilazione di Docker.

L'esempio seguente mostra come utilizzare la variabile cra-custom-script per esportare la variabile 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)

È inoltre possibile utilizzare il parametro cra-custom-script-path per scenari in cui le versioni dello strumento immagine di base DevSecOps potrebbero essere obsolete, in base al progetto. Ad esempio, è possibile aggiornare comandi come pip/pip3 per scoprire i pacchetti Python che richiedono una versione successiva di pip.

L'esempio seguente mostra come utilizzare cra-custom-script per aggiornare la versione di 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 il file Docker utilizza un'immagine da un registro privato Docker, è possibile usare il parametro cra-custom-script-path per autenticarsi a un registro privato Docker prima di eseguire Code Risk Analyzer e consentire a Code Risk Analyzer di prelevare l'immagine per la scansione.

L'esempio seguente mostra come utilizzare cra-custom-script per autenticarsi al registro del contenitore ibmcloud:

#!/usr/bin/env bash

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

ibmcloud cr login

Debug dell'analizzatore di rischio del codice in DevSecOps

Per facilitare il debug, è possibile eseguire il Code Risk Analyzer localmente come interfaccia a riga di comando (CLI) sul proprio computer locale. Per informazioni sull'esecuzione del comando ibmcloud cra bom-generate per generare una distinta base, vedere Distinta base(BOM). Dopo aver generato la distinta base, utilizzare il comando ibmcloud cra cve per elencare eventuali vulnerabilità. Per ulteriori informazioni sull'esecuzione del comando ibmcloud cra cve, vedere Scansione delle vulnerabilità.

Assicurarsi che il task run-cra non contenga errori. Se il task contiene errori, verificare se la pipeline utilizza la versione corrente di DevSecOps. Se il problema non si risolve controllando la versione di DevSecOps,, gli esempi seguenti forniscono alcuni errori comuni e le soluzioni proposte.

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

È possibile verificare l'accesso al registro privato. Se non si dispone dell'accesso, è possibile utilizzare il parametro cra-custom-script-path e specificare il percorso di uno script personalizzato che viene eseguito prima che Code Risk Analyzer si autentichi al registro privato.

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

Se il file Docker richiede ARGS, il comando docker build per le fasi di compilazione fallisce a causa della mancanza di ARGS. Il sito cra-custom-script-path è necessario per impostare gli ARGS come variabili d'ambiente. Per ulteriori informazioni sull'impostazione dello script personalizzato, vedere Esempi di script personalizzati per 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

Per impostazione predefinita, il comando Code Risk Analyzer bom-generate costruisce i file Docker dal contesto della posizione del file Docker stesso. Se si desidera costruire i file Docker dal contesto della directory principale del progetto, usare il parametro cra-docker-build-context per consentire a Code Risk Analyzer di costruire i file Docker da questo contesto.

Come si può determinare il motivo del fallimento della CLI?

Prima di chiamare la CLI di Code Risk Analyzer, impostare la variabile d'ambiente IBMCLOUD_TRACE su true per attivare il log di debug.

export IBMCLOUD_TRACE=true

Osservare le chiamate API e le risposte visualizzate nel log per determinare il motivo esatto del fallimento.

Come si può eseguire il debug di un comando BOM che non riesce a estrarre un'immagine di base da un registro privato.

Assicurarsi di essersi autenticati con il registro in cui risiede l'immagine di base usando il comando ibmcloud cr login o il comando docker login.

Come si può eseguire il debug di un comando BOM che non riesce ad analizzare un file Docker?

• Verificate che il file Docker non abbia problemi eseguendo il comando docker build e verificando che passi.
• Se il file Docker richiede il passaggio di ARG, assicurarsi che ARG sia impostato come variabile d'ambiente. È anche possibile utilizzare la variabile d'ambiente DOCKERBUILDFLAG.
• Autenticare con il registro che contiene le immagini di base.

Vedo risultati falsi positivi inaspettati. Cosa devo fare?

Eseguire la pipeline DevSecOps Continuous Deployment (CD) per generare una SBOM aggiornata nell'armadietto delle prove. In questo modo si potrebbe risolvere una potenziale causa di falsi positivi derivante dalla presenza di un SBOM più vecchio generato dalla pipeline DevSecOps Continuous Compliance (CC).

Perché la gravità della segnalazione o del problema è diversa da quella del link di vulnerabilità associato?

Poiché la nostra fonte di informazioni sulle vulnerabilità è cambiata di recente, potreste notare che la gravità associata a una particolare vulnerabilità è cambiata. Code Risk Analyzer determina la gravità ottimale in base al calcolo di tutte le fonti di vulnerabilità.