Guide de référence Snyk CLI

Snyk CLI est un outil puissant qui permet de rechercher et d’analyser les failles de sécurité susceptibles de se loger en tant que code dans vos applications, conteneurs et infrastructures. Vous trouverez dans ce guide de référence les fonctionnalités les plus puissantes de notre interface en ligne de commande (CLI). Vous pouvez utiliser la CLI à des fins d’analyse et de surveillance sur votre machine locale, mais vous pouvez également l’intégrer à votre pipeline. Quel que soit l’usage que vous souhaitez en faire, Snyk CLI est l’outil incontournable pour détecter, analyser et corriger les failles connues de vos applications.

Notre engagement à améliorer continuellement notre CLI rend impossible l’examen de toutes ses fonctionnalités dans un seul guide de référence. Toutefois, vous en trouverez une présentation plus détaillée dans nos ressources Snyk CLI. Si vous souhaitez en savoir plus sur les capacités de notre CLI pour un langage ou un système de build spécifique, consultez notre page sur les langages informatiques pris en charge. Ces langages sont les suivants :

• JavaScript (npm, yarn)

• Java et Kotlin (maven | Gradle)

• .Net (Nuget, Paket)

• Python (Pip, Poetry)

• PHP (composer)

• Ruby (Bundler)

• Go (dep, govendor)

• Et bien d’autres…

Télécharger le guide de référence

Installation

Commençons par le commencement. Si vous n’avez pas encore installé Snyk CLI, c’est la première chose à faire. Vous pouvez installer Snyk CLI à l’aide de npm, Homebrew ou Scoop, ou en téléchargeant un binaire spécifique à partir de GitHub.

npm

npm install snyk -g

Homebrew

brew tap snyk/tap && brew install snyk

Scoop

scoop bucket add snyk https://github.com/snyk/scoop-snyk
scoop install snyk

Installation manuelle

Un paquet pour installation manuelle est disponible sur la page GitHub de Snyk.

Authentification

Une fois la CLI installée, vous devez vous authentifier à l’aide de votre compte Snyk. Vous avez le choix entre plusieurs méthodes.

Lorsque vous appelez snyk auth, le navigateur vous redirige vers la page d’inscription ou de connexion.

Vous pouvez aussi exécuter snyk auth [api-token] en fournissant un argument de jeton API Snyk, que vous pouvez récupérer sur la page de votre compte.

La dernière option, particulièrement recommandée pour les tests CI, consiste à créer une variable d’environnement appelée SNYK_TOKEN. Toutes les commandes Snyk CLI l’utiliseront sans exécuter explicitement snyk auth.

Conseil : pensez à régulièrement mettre à jour et à réinstaller la CLI. Nous publions très souvent des versions corrigées de la CLI. Ne passez pas à côté des nouvelles fonctionnalités et améliorations !

Commandes de la CLI

Snyk CLI accepte une commande, suivie de plusieurs options. Veillez à exécuter les commandes CLI au sein du dossier du projet. Voyons à quoi sert chacune de ces commandes.

Snyk test

La commande snyk test analyse un projet local afin de détecter des vulnérabilités connues. Elle apporte des informations précieuses sur ces failles : type, degré de gravité, description, nombre de chemins vulnérables, solutions, etc. Snyk CLI détecte automatiquement vos fichiers de manifeste et analyse le premier qu’elle trouve. Snyk recherche les dépendances locales pour en analyser les failles. Vous devez donc exécuter les étapes nécessaires pour télécharger votre arborescence de dépendances avant d’exécuter snyk test, comme npm install, mvn install, dotnet restore ou dep ensure.

Snyk test est également utile dans un pipeline CI. L’exécution de snyk test lors de la génération du binaire permet de savoir immédiatement si le projet contient des vulnérabilités. Si vous le souhaitez, vous pouvez même interrompre le pipeline et demander son arrêt complet. Lorsque vous appelez snyk test à partir d’un script, il suffit de vérifier le code de sortie. Si le code de sortie est 0, tout va bien, aucune faille n’a été détectée. Si un code de sortie autre que 0 s’affiche, vous avez du pain sur la planche !

Si votre projet contient plusieurs manifestes, vous pouvez en analyser un en particulier. Utilisez l’indicateur --file pour spécifier le fichier à analyser.

$ snyk [cmd] --file=package.json

De la même manière, vous pouvez spécifier le gestionnaire de paquets à l’aide de l’indicateur --package-manager. Cela est utile dans le cas exceptionnel où Snyk ne peut pas détecter automatiquement le gestionnaire de paquets.

$ snyk test --file=req.txt --package-manager=pip

Pour analyser tous les projets d’un dossier, vous pouvez utiliser l’indicateur --all-projects. Il exécute un processus de découverte automatique pour analyser le répertoire actuel et tous les fichiers de manifeste trouvés. Par défaut, Snyk analyse le répertoire actuel et trois niveaux supplémentaires de profondeur. Pour changer le niveau de profondeur, ajoutez simplement l’option --detection-depth.

$ snyk test --all-projects --detection-depth=4

Par défaut, Snyk n’analyse pas les dépendances de développement, car beaucoup les considèrent comme peu importantes par rapport aux vulnérabilités de production. Si vous souhaitez que Snyk inclue également vos dépendances de développement, utilisez l’indicateur --dev.

$ snyk test --dev

Un autre indicateur est utile à connaître pour la commande test, mais aussi d’autres commandes Snyk : --org. Il permet d’associer un test ou toute commande Snyk à une organisation spécifique. Les organisations sont des conteneurs dans lesquels vous pouvez regrouper des projets ; plusieurs utilisateurs peuvent leur être associés. Cet indicateur est particulièrement utile lorsque vous travaillez en équipe et créez des instantanés avec snyk monitor. Si vous ne spécifiez aucune organisation, les résultats sont associés à votre organisation par défaut.

$ snyk [cmd] --org=<org_id>

Si vous souhaitez analyser des référentiels publics à partir de la ligne de commande, c’est possible ! Il vous suffit de renseigner l’URL du référentiel public directement dans la commande. Cela ne fonctionne que sur les référentiels npm où package-lock.json est disponible. Essayez…

$ snyk test https://github.com/snyk/goof

Vous pouvez également analyser des paquets à distance dans npm en transmettant uniquement le nom du paquet, en analysant la dernière version ou en qualifiant entièrement le nom et la version du paquet.

$ snyk test lodash
$ snyk test ionic@1.6.5

Après l’exécution d’une commande Snyk test sur un projet, la sortie comporte trois sections.

• Problèmes pouvant être résolus par une mise à niveau : en mettant à jour la bibliothèque comme suggéré, vous supprimerez une ou plusieurs failles détectées dans votre projet.

• Problème pouvant être corrigé à l’aide d’un correctif : aucune mise à niveau disponible ne permet de corriger le problème. Néanmoins, Snyk a créé un correctif pour corriger la faille.

• Problème ne pouvant être corrigé lors d’une mise à niveau ou à l’aide d’un correctif :aucune mise à niveau n’est disponible pour la dépendance que vous avez importée. Il est possible qu’une faille se trouve dans l’une des dépendances transitives. S’il existe déjà une version plus récente de la dépendance transitive ayant corrigé la faille, elle s’affiche également. Dans certains écosystèmes, il est possible de remplacer manuellement les dépendances transitives ; ces informations sont donc précieuses.

Pour chaque faille affichée par la CLI dans l’une des trois sections susmentionnées s’affichent une description, le degré de gravité et un lien pour en savoir plus sur la faille détectée. 

Si vous préférez la sortie CLI au format JSON, utilisez l’indicateur --json. Vous pouvez utiliser la sortie JSON pour mettre en forme les résultats comme vous le souhaitez.

$ snyk test --json

L’enregistrement de votre sortie d’analyse dans un fichier JSON est encore plus simple. --json-file-output flag permet d’enregistrer le résultat dans le nom de fichier souhaité à des fins d’analyse ultérieure. En attendant, vous obtiendrez une sortie lisible, comme affichée précédemment dans votre console. C’est une solution idéale pour les pipelines CI lorsque, par exemple, vous souhaitez afficher les résultats d’une build spécifique dans un tableau de bord. Essayez :

$ snyk test --json-file-output=vuln.json

Il existe un outil de mappage Snyk JSON vers HTML pour mettre en forme les résultats dans un joli rapport HTML que vous pourrez présenter à votre responsable.

L’indicateur --severity-threshold permet de filtrer la sortie CLI par degré de gravité. Si les failles d’une gravité moyenne ou faible vous importent peu, vous pouvez les exclure de l’équation en procédant comme suit :

$ snyk [cmd] --severity-threshold=high

Snyk monitor

La commande snyk monitor prend un instantané de votre projet et envoie les résultats sur le site web de Snyk. Même si snyk monitor utilise snyk test en arrière-plan, il ne s’agit pas d’un remplacement ; Snyk monitor prend un instantané et surveille durablement cet instantané. Lorsque de nouvelles failles ou solutions sont découvertes, une alerte vous est envoyée via le canal de communication que vous avez choisi.

Dans un environnement CI, la commande snyk test est généralement exécutée avant toute chose afin de détecter d’éventuelles failles. S’il y en a, vous pouvez interrompre votre build, selon le cas d’utilisation. Par la suite, snyk monitor est généralement utilisée pour créer un instantané de cette version afin de la surveiller dans le temps. Le plus opportun est de le faire avant la phase de production. Une fois que le niveau de failles atteint vous convient, snyk monitor vous aidera à maintenir le cap durablement.

Lors de l’exécution de snyk monitor, vous devez renseigner suffisamment d’informations pour que votre instantané se retrouve à l’emplacement prévu. Si vous êtes membre de plusieurs organisations, pensez à préciser celle où votre instantané devra être envoyé à l’aide de l’indicateur --org. Si les noms de certains de vos projets se ressemblent, vous pouvez modifier le nom par défaut que Snyk leur attribue en saisissant un autre nom à l’aide de l’indicateur --project-name.

$ snyk monitor --file=package.json --project-name=myapp --org=myorg

Snyk ignore

Supposons que votre application contienne une faille pour laquelle il n’existe aucun correctif ni mise à jour, ou une vulnérabilité que vous considérez comme inexploitable actuellement dans votre application. Vous pouvez alors demander à Snyk d’ignorer la faille pendant un certain temps. Pour utiliser la commande ignore, exécutez d’abord snyk test et récupérez l’identifiant de la vulnérabilité dans la sortie CLI. Vous pouvez désormais ignorer cette faille à l’aide de la commande suivante :

$ snyk ignore --id=npm:tough-cookie:20160722 --expiry=2019-04-30 --reason='Not currently exploitable'

Les indicateurs --expiry et --reason sont facultatifs. Par défaut, la faille de sécurité est ignorée pendant 30 jours.

Remarque : la commande Snyk ignore créera un fichier .snyk contenant les informations sur le problème de sécurité ignoré.

Snyk Container

Snyk Container est la capacité CLI permettant d’analyser les images de conteneur, les images Docker par exemple. Auparavant, cette capacité pouvait être activée à l’aide de l’indicateur --docker de la CLI.

Vous pouvez analyser les images Docker à l’aide de Snyk de la même manière que pour votre application.

Lors du téléchargement d’images pour Docker Hub, vous pouvez analyser et surveiller cette image en procédant comme suit :

$ snyk container test <image>:<tag>
$ snyk container monitor <image>:<tag>

Lors de l’ajout d’un Dockerfile à l’une de ces commandes, Snyk vous donnera des conseils sur le correctif à appliquer à l’image de base que vous utilisez, entre autres. Si plusieurs images de base sont disponibles pour l’image que vous avez créée, nous pouvons vous indiquer ces alternatives.

Snyk Container ne prend pas seulement en charge les conteneurs Docker, mais également les images Distroless. Pour analyser ces images, procédez comme suit :

$ snyk container test gcr.io/distroless/base | head

De plus, les archives de conteneurs peuvent être analysées et surveillées régulièrement à l’aide des capacités de conteneur de Snyk. L’analyse fonctionne pour les archives de conteneurs Docker et les images Open Container Initiative (OCI).

$ snyk container test docker-archive:container.tar
$ snyk container test oci-archive:container.tar

Comme pour l’analyse de vos applications, les indicateurs --json et --json-file-output offrent une intégration fluide à vos propres systèmes.

En savoir plus sur Snyk CLI Container

L’infrastructure Snyk en tant que code (Snyk IaC)

Grâce aux capacités d’analyse de Snyk Infrastructure As Code, les développeurs peuvent détecter et corriger les erreurs de configuration susceptibles d’affecter la sécurité des applications. La commande snyk iac permet d’utiliser cette fonctionnalité dans Snyk CLI sur votre ordinateur local ou dans votre environnement CI. Vous recevrez alors des retours le plus tôt possible dans votre cycle de développement.  Snyk IaC est disponible avec une prise en charge des ressources Kubernetes, Helm Charts et Terraform AWS.

Pour analyser un fichier Kubernetes ou Terraform, vous pouvez, par exemple, procéder comme suit :

$ snyk iac test /path/to/Kubernetes.yaml
$ snyk iac test /path/to/terraform_file.tf

Tout comme pour snyk test, vous verrez s’afficher une description des problèmes détectés avec Snyk IaC, ainsi que leur niveau de gravité. Si vous avez besoin de cette sortie au format JSON pour l’intégrer à votre système, les indicateurs --json et --json-file-output sont également disponibles ici :

$ snyk iac test /path/to/Kubernetes.yaml --json

Snyk IaC permet aussi de détecter et de suivre les ressources non gérées et les dérives de configuration dans une infrastructure pour vous en alerter :

$ snyk iac describe <OPTIONS>

En savoir plus sur Snyk CLI IaC

Résolution des problèmes

Si vous avez des doutes quant à la commande à utiliser ou au fonctionnement d’un indicateur spécifique, vous pouvez toujours y ajouter --help ou appeler snyk help.

$ snyk auth --help
$ snyk container --help

Débogage

En cas de dysfonctionnement, vous pouvez demander à la CLI d’afficher le journal de débogage à l’aide de l’indicateur -d. Notre équipe en charge de l’assistance vous demandera probablement de procéder comme suit :

$ snyk [cmd] -d

Vous êtes à cours de tests sur un projet open source ?

L’analyse Snyk est gratuite et illimitée pour le développement open source. Néanmoins, il ne nous est pas toujours possible de reconnaître un projet open source. Si un message vous indiquant que vous êtes à cours de tests s’affiche dans la sortie CLI, vous pouvez suivre les étapes suivantes pour prouver que votre projet est bel et bien open source.

1. Exécutez snyk monitor.

2. Accédez à votre application dans le navigateur. (L’URL directe se trouve dans la sortie CLI.)

3. Dans le menu, cliquez sur les paramètres.

4. Entrez l’URL de votre référentiel open source dans le champ de l’URI Git distante.

Les résultats obtenus vous surprennent ?

Pour un résultat optimal, regénérez entièrement votre projet avant d’exécuter l’une des commandes CLI. Si la sortie d’une commande snyk test ou snyk monitor n’est pas celle attendue, veuillez lancer votre outil de build pour télécharger et installer toutes les dépendances.

Par exemple :

$ npm install
$ mvn install
$ dotnet restore
$ dep ensure

Suppression de votre clé API et de votre configuration

Si vous avez authentifié votre CLI à l’aide de snyk auth, vous pouvez supprimer votre jeton de la configuration à l’aide de la commande suivante :

$ snyk config unset api

Pour plus d’informations sur d’autres paramètres de configuration, appelez :

$ snyk help config

Vérifiez votre version

Utilisez toujours la dernière version de notre CLI. Nous publions de nouvelles versions de l’application plusieurs fois par semaine.

(Ré)installez la dernière version à l’aide de votre gestionnaire de paquets comme décrit dans la première section, ou recherchez la dernière version sur notre référentiel GitHub.

Pour savoir quelle version vous utilisez actuellement, exécutez :

$ snyk --version

Consultez les ressources

Les projets et écosystèmes ont des besoins qui leur sont propres. Pour trouver de l’aide relative à un cas d’utilisation précis, veuillez consulter les ressources CLI et la documentation de prise en charge des langages.