Aide Code Risk Analyzer

La commande suivante affiche la liste des commandes Code Risk Analyzer :

ibmcloud cra --help

Aide sur la commande Code Risk Analyzer

La commande suivante affiche les détails des indicateurs qui sont utilisés avec une commande. Utilisez ibmcloud cra --help pour afficher les commandes disponibles.

ibmcloud cra <command> --help

Exigences liées à la commande BOM

La commande bom-generate dépend de certaines commandes externes :

• Si le chemin contient des fichiers Docker, cette commande extrait les images de base et construit des images pour chaque étape de génération dans chaque fichier Docker. Dans ce scénario, la commande bom-generate requiert que les commandes Docker cli et tar soient disponibles.
• Si le chemin contient des fichiers Maven, cette commande utilise mvn pour générer une liste de dépendances. Dans ce scénario, la commande bom-generate requiert que la commande mvn soit disponible.
• Si le chemin contient des fichiers Gradle, cette commande utilise gradle pour générer une liste de dépendances. Dans ce scénario, la commande bom-generate requiert que la commande gradle soit disponible.
• Si le chemin contient des fichiers Node.js package-json et que cette commande est utilisée pour générer un fichier package-lock.json correspondant, la commande bom-generate utilise npm pour générer le fichier package-lock.json. Dans ce scénario, la commande requiert que la commande npm soit disponible.
• Si le chemin contient les fichiers Python requirements.txt ou pyproject.toml, la commande utilise pip pour générer les dépendances du paquet. Dans ce scénario, la commande bom-generate nécessite que la commande pip soit disponible. Python version 2 et Python version 3 sont pris en charge.

Si vous utilisez des fichiers Docker, connectez-vous à votre registre de conteneurs à partir duquel les images de base doivent être extraites.

Si votre fichier Docker requiert ARGS, définissez un ARG individuel comme variable d'environnement avant d'exécuter la commande. Par exemple, si le fichier Docker utilise un ARG IAM_USER, exportez une variable d'environnement nommée IAM_USER : export IAM_USER='value'. L'interface de ligne de commande transmet automatiquement ces variables d'environnement à la commande docker build.

Vous pouvez également spécifier explicitement l'indicateur DOCKERBUILDFLAGS. Pour exporter DOCKERBUILDFLAGS avec l'indicateur ARGS Docker, entrez la commande suivante :

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

Options de la commande BOM

Le tableau suivant répertorie les options de commande que vous pouvez utiliser pour générer une nomenclature à l'aide de la commande bom-generate.

Ignorer les fichiers

Si le chemin contient le fichier .cra/.fileignore, les fichiers spécifiés dans le fichier .fileignore ne sont pas analysés pour les dépendances. Le fichier .fileignore doit respecter les règles des fichiers .gitignore. Comme le fichier .gitignore, le fichier .fileignore peut contenir des commentaires, des répertoires à ignorer, des fichiers à ignorer et d'autres motifs.

L'exemple de fichier .fileignore suivant montre comment exclure les scripts bash, les modules de noeud node_module et le fichier 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

Définition de plusieurs contextes de construction Docker

Lorsque vous travaillez avec plusieurs Dockerfiles au sein d'un même projet, vous pouvez vouloir définir des contextes de construction distincts pour chaque Dockerfile. Ceci peut être réalisé en utilisant un fichier .cra/.dockerbuildcontext, qui est un fichier JSON qui fait correspondre les chemins des Dockerfiles aux contextes de construction correspondants.

Si un fichier .cra/.dockerbuildcontext existe dans le répertoire de votre projet, les commandes de construction CRA Docker utiliseront les chemins spécifiés dans ce fichier comme contextes de construction pour les Dockerfiles associés. Les clés de l'objet JSON représentent les chemins relatifs vers les Dockerfiles, tandis que les valeurs spécifient les chemins relatifs vers les contextes de construction respectifs.

Voici un exemple de fichier .dockerbuildcontext qui définit différents contextes de construction pour plusieurs Dockerfiles :

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

Exemple

Les fragments de code suivants montrent comment utiliser la commande 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

Options de la commande d'analyse de vulnérabilité

Le tableau suivant répertorie les options d'utilisation de la commande vulnerability-scan.

Ignorer les vulnérabilités

Si le paramètre -c ou --cveignore est indiqué, la commande recherche ce fichier et ne rapporte pas les CVE spécifiés dans le fichier. Vous pouvez configurer les CVE pour les omettre indéfiniment jusqu'à ce qu'une résolution soit disponible ou jusqu'à une date d'expiration spécifiée.

L'exemple suivant montre un schéma JSON pour le fichier .cveignore :

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

Les propriétés suivantes sont prises en charge pour chaque entrée du fichier .cveignore :

• cve - La vulnérabilité à omettre. La valeur de cette propriété est un identifiant CVE.
• alwaysOmit - Si cette propriété est définie sur true, la vulnérabilité est omise jusqu'à ce qu'elle soit modifiée. Cette propriété est prioritaire sur les autres valeurs de propriété.
• untilRemediationAvailable - Si cette propriété est définie sur true, la vulnérabilité est omise jusqu'à ce qu'un chemin de résolution soit disponible. Si une résolution devient disponible, la vulnérabilité n'est pas omise et un message s'affiche. Cette propriété est prioritaire sur la valeurs de la propriété d'arrivée à expiration.
• expiration - Si cette propriété est définie sur true et que la date d'expiration n'est pas atteinte, la vulnérabilité est omise. Si la date d'arrivée à expiration est atteinte, la vulnérabilité n'est pas omise et un message s'affiche. Utilisez le format d'heure RFC3339 (yyyy-MM-ddTHH:mm:ss[+-]Z) pour définir cette propriété.

Code Risk Analyzer utilise uniquement ces propriétés définies. Vous pouvez ajouter des propriétés sans effet sur les fonctions. Si une vulnérabilité définie dans .cveignore n'est pas omise, un journal est généré pour en expliquer la raison. Si une vulnérabilité définie dans le fichier .cveignore est omise, aucun journal individuel n'est affiché. Le nombre d'omissions et la liste des ID de vulnérabilité, avec le nom du package, qui sont omis sont consignés après l'achèvement d'un rapport.

Le fragment de code suivant montre un exemple de fichier .cveignore :

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

Exemple

Les fragments de code suivants montrent comment utiliser la commande 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

Options de la commande de déploiement

Le tableau suivant répertorie les options de commande que vous pouvez utiliser pour la commande deployment-analyze.

Exemple

Les fragments de code suivants montrent comment utiliser la commande 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 options de la commande d'analyse

Le tableau suivant répertorie les options de commande que vous pouvez utiliser pour la commande netpol-analyze.

Exemple

Les exemples de code suivants montrent comment vous pouvez utiliser la commande 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

Image de l'analyseur de configuration réseau

La commande netpol-analyze est exécutée dans le cadre de l'analyseur de configuration réseau(NCA) de IBM. Comme cette commande exécute NCA en tant qu'image Docker, vous devez l'installer sur votre ordinateur Docker sur votre ordinateur.

L' URL s d'image pour l'analyseur de stratégie réseau sont les suivantes icr.io/continuous-delivery/cra/nca:.

Si l'image de l'analyseur ne se trouve pas déjà dans votre registre local, la commande netpol-analyze extrait la dernière image de l'analyseur (y compris les corrections de toutes les vulnérabilités) de la base de données globale IBM Cloud® Container Registry.

Exemples de scripts personnalisés pour DevSecOps

Si votre fichier Docker requiert ARGS, vous pouvez utiliser le paramètre cra-custom-script-path pour définir un ARG individuel comme variable d'environnement avant d'exécuter la commande. Le chemin de script personnalisé est le chemin d'accès à un script qui réside dans le projet de l'utilisateur. Par exemple, si le fichier Docker utilise IAM_USER ARG, exportez une variable d'environnement dans le script nommé IAM_USER: export IAM_USER='value'. Si l'ARG requis par votre fichier Docker est défini en tant que propriété d'environnement dans les chaînes d'outils, vous pouvez utiliser get_env pour obtenir la valeur. Dans ce cas, vous pouvez exporter une variable d'environnement dans le script IAM_USER: export IAM_USER=$(get_env iam_user_environment_property_name). La tâche run-cra sélectionne automatiquement ces variables d'environnement et les transmet aux commandes de génération Docker.

L'exemple suivant montre comment utiliser le cra-custom-script pour exporter la variable 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)

Vous pouvez également utiliser le paramètre cra-custom-script-path pour les scénarios dans lesquels les versions de l'outil d'image de base DevSecOps peuvent être obsolètes, en fonction de votre projet. Par exemple, vous pouvez mettre à jour des commandes telles que pip/pip3 pour la reconnaissance des packages Python qui nécessitent une version pip ultérieure.

L'exemple suivant montre comment utiliser le cra-custom-script pour mettre à jour la version 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

Si votre fichier Docker utilise une image d'un registre Docker privé, vous pouvez utiliser le paramètre cra-custom-script-path pour vous authentifier auprès d'un registre Docker privé avant d'exécuter Code Risk Analyzer et de lui permettre d'extraire cette image pour l'analyse.

L'exemple suivant montre comment utiliser le cra-custom-script pour s'authentifier auprès du registre de conteneur ibmcloud :

#!/usr/bin/env bash

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

ibmcloud cr login

Débogage de Code Risk Analyzer dans DevSecOps

Pour faciliter le débogage, vous pouvez exécuter Code Risk Analyzer localement en tant qu'interface de ligne de commande (CLI) sur votre propre machine locale. Pour plus d'informations sur l'exécution de la commande ibmcloud cra bom-generate pour générer une nomenclature, voir Nomenclature. Après avoir généré la nomenclature, utilisez la commande ibmcloud cra cve pour dresser la liste des vulnérabilités. Pour plus d'informations sur l'exécution de la commande ibmcloud cra cve, voir Analyse de vulnérabilité.

Assurez-vous que la tâche run-cra ne contient aucune erreur. Si la tâche contient des erreurs, vérifiez si votre pipeline utilise la version actuelle de DevSecOps. Si le problème n'est pas résolu en vérifiant la version de DevSecOps, les exemples suivants fournissent des erreurs courantes et proposent des solutions.

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

Vous pouvez vérifier que vous avez accès au registre privé. Si vous n'y avez pas accès, vous pouvez utiliser le paramètre cra-custom-script-path et indiquer le chemin d'accès à un script personnalisé qui s'exécute avant Code Risk Analyzer pour vous authentifier auprès du registre privé.

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

Si votre fichier Docker requiert ARGS, la commande docker build pour les étapes de génération échoue en raison de l'ARGS manquant. cra-custom-script-path est requis pour configurer les ARGS comme variables d'environnement. Pour plus d'informations sur la configuration du script personnalisé, voir Exemples de scripts personnalisés pour 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

Par défaut, la commande Code Risk Analyzer bom-generate génère les fichiers Docker à partir du contexte de l'emplacement du fichier Docker lui-même. Si vous souhaitez générer les fichiers Docker à partir du contexte du répertoire racine du projet, utilisez le paramètre cra-docker-build-context pour permettre à Code Risk Analyzer de générer les fichiers Docker à partir de ce contexte.

Comment puis-je déterminer la raison de l'échec de l'interface de ligne de commande ?

Avant d'appeler l'interface de ligne de commande Code Risk Analyzer, définissez la variable d'environnement IBMCLOUD_TRACE sur true pour activer le journal de débogage.

export IBMCLOUD_TRACE=true

Observez les appels d'API et les réponses affichées dans le journal pour déterminer la raison exacte de l'échec.

Comment puis-je déboguer une commande BOM qui ne parvient pas à extraire une image de base d'un registre privé ?

Assurez-vous que vous êtes authentifié auprès du registre dans lequel réside l'image de base à l'aide de la commande ibmcloud cr login ou de la commande docker login.

Comment puis-je déboguer une commande BOM qui n'est pas en mesure d'analyser un fichier Docker ?

• Vérifiez que le fichier Docker ne présente aucun problème en exécutant la commande docker build et en vous assurant qu'elle aboutit.
• Si votre fichier Docker requiert la transmission d'ARG, assurez-vous que l'ARG est défini comme variable d'environnement. Vous pouvez également utiliser la variable d'environnement DOCKERBUILDFLAG.
• Authentifiez-vous auprès du registre qui contient les images de base.

Je constate des résultats faussement positifs inattendus. Que dois-je faire ?

Exécuter le pipeline de déploiement continu (CD) DevSecOps pour générer un SBOM mis à jour dans l'armoire à archives. Cela pourrait permettre de remédier à une cause potentielle de faux positifs résultant de la présence d'un ancien SBOM généré par le pipeline de conformité continue (CC) de DevSecOps.

Pourquoi la gravité du rapport ou du problème diffère-t-elle de celle du lien de vulnérabilité associé?

Comme notre source d'informations sur les vulnérabilités a changé récemment, il se peut que la gravité associée à une vulnérabilité particulière ait changé. Code Risk Analyzer déterminera la sévérité optimale sur la base d'un calcul de toutes les sources de vulnérabilités.