Support technique
Documentation
Connexion
Nous contacter
Accédez directement au résumé généré par l'IA de cet article de blog 
Vous avez installé un paquet via npm, le résultat de l'audit npm semblait correct, et vous êtes passé à autre chose.
Six mois plus tard. Vous récupérez les dernières modifications, un message s'affiche dans l'environnement d'intégration continue (CI), et vous avez désormais besoin d'une réponse claire concernant une dépendance : est-ce que tslib est-il réellement un problème dans cette branche ? Parcourir tout le rapport d'audit pour trouver cette seule réponse est une perte de temps.
La version moderne de npm permet d'y répondre plus directement. Vous pouvez interroger l'arborescence des dépendances à l'aide d'un sélecteur de vulnérabilités, filtrer les données d'audit structurées avec jq, ou vous rabattre sur de simples outils en ligne de commande lorsque vous n'avez besoin que d'un aperçu rapide. Vous pouvez alors déterminer précisément pourquoi ce paquet a été installé.
Voici quatre méthodes pour vérifier un paquet npm, classées par ordre de priorité.
Remarque : les commandes ci-dessous ont été testées avec npm 10.9.7 et npm 12.0.1. Les sélecteurs et les formats de sortie varient d'une version majeure à l'autre de npm ; veillez donc à exécuter npm -v avant d'intégrer quoi que ce soit de tout cela dans un script.
1. Interroger directement le paquet avec npm query
npm query parcourt l'arborescence de vos dépendances installées à l'aide de sélecteurs de dépendances de type CSS. Deux d'entre eux sont utilisés ici : #tslib correspond aux paquets nommés tslib, et :vuln limite les résultats aux instances pour lesquelles un avis de sécurité est connu.
npm query '#tslib:vuln'
Un tableau vide signifie que npm n'a trouvé aucune instance de ce paquet correspondant à un avis connu dans l'arborescence et les données du registre qu'il a interrogées. Un tableau non vide signifie qu'il en a trouvé, et chaque entrée contient des métadonnées détaillées sur le paquet et l'arborescence des dépendances, ainsi qu'un champ « emplacement » indiquant où se trouve cette copie dans le répertoire node_modules.
Ce flux de métadonnées contient beaucoup de données JSON pour une seule question. Réduisez-le à l'aide de jq:
npm query '#tslib:vuln' | jq '.[] | {location, version, advisories: [.queryContext.advisories[] | {severity, title}]}'
La :vuln associe chaque avis correspondant au nœud situé sous queryContext.advisories, ce qui vous permet d’obtenir la gravité, le titre, le score CVSS, le CWE et la plage de versions vulnérables sans avoir à exécuter une deuxième commande – et vous obtenez toutes ces informations, pas seulement la première.
Vous pouvez filtrer par niveau de gravité dans le sélecteur, ce qui s'avère utile lorsque l'arborescence contient trop d'éléments :
npm query ':vuln([severity=high])'
Une petite précision : le filtrage par niveau de gravité ne retient que les éléments correspondant exactement à ce niveau, et aucun autre niveau supérieur ou inférieur. [severity=high] ne vous affichera pas les résultats critiques. Transmettez-les sous forme de liste si vous souhaitez obtenir les deux :
npm query ':vuln([severity=critical],[severity=high])'
Les sélecteurs permettent de composer, ce qui vous permet de limiter la vérification à votre arborescence de production au lieu d'avoir recours à un indicateur :
npm query '.prod#tslib:vuln' # ce paquet, arborescence de production uniquement npm query '.prod:vuln' # tout ce qui est vulnérable dans l'arborescence de production
Deux autres points à connaître avant de vous fier à cette fonctionnalité dans le cadre de l'automatisation. :vuln et :outdated interrogent tous deux le registre ; aucun des deux ne fonctionne donc hors ligne. Et le #name@version que l’on trouve encore dans l’ancienne documentation n’est plus pris en charge : npm 12 rejette #[email protected] en renvoyant une erreur EQUERYNODEPTYPE . Utilisez plutôt le pseudo-sélecteur semver :
npm query '#tslib:semver(2.4.0)'
La :vuln a fait son apparition dans la version 10.5.0 de npm. Si vous n’êtes pas sûr de la version que vous utilisez, vérifiez-la plutôt que de faire des suppositions :
npm query « :vuln » >/dev/null 2>&1 && echo "pris en charge" || echo "mettre à jour npm"
Pour les versions plus anciennes, passez directement à la section méthode jq .
2. Filtrer npm audit JSON avec jq
npm audit remonte à la version 6 de npm, tandis que :vuln nécessite npm 10.5.0 ou une version ultérieure. Le format JSON d'audit constitue donc le choix le plus sûr pour un dépôt partagé où les contributeurs peuvent utiliser des versions plus anciennes de npm.
npm audit --json | jq '.vulnerabilities["tslib"]'
Le –json renvoie des données d’audit lisibles par machine au lieu d’un tableau formaté. Sur npm 7 et versions ultérieures, ce rapport contient une « vulnerabilities » dont les clés correspondent aux noms de paquets ; le filtre ci-dessus extrait donc l’entrée relative à tslib . Récupérez les champs qui déterminent réellement une décision :
npm audit --json | jq '.vulnerabilities["tslib"] | {severity, range, fixAvailable}'
Read the top-level range as the aggregate vulnerable range for that entry. Do not reach into .via[0].range to get it. The via array mixes advisory objects with bare package-name strings for vulnerabilities inherited through a parent, and even when via[0] happens to be an object it often carries a narrower range than the entry as a whole – on a test tree, express reported <4.20.0 from via[0] against an aggregate range of <=4.21.2 || 5.0.0-alpha.1 – 5.0.0. Silently wrong is worse than empty.
Si vous souhaitez distinguer les avis directs des avis hérités, demandez via de manière explicite et lisez-le vous-même :
npm audit --json | jq '.vulnerabilities["tslib"] | {severity, range, via, fixAvailable}'
Utilisez la syntaxe des crochets plutôt que .vulnerabilities.tslib. Cela ne coûte que deux caractères et c’est la seule forme qui fonctionne avec un nom de package dans un périmètre, là où la notation par points ne fonctionne pas avec le @ et le /:
npm audit --json | jq '.vulnerabilities["@babel/traverse"]'
Pour voir tous les éléments signalés avant de passer en revue chaque paquet un par un :
npm audit --json | jq -r '.vulnerabilities | keys[]'
null Cela ne signifie pas qu’il n’y a pas de vulnérabilité
Si le filtre renvoie null, cela signifie simplement que le rapport ne contient aucune entrée sous cette clé. Quatre situations différentes peuvent entraîner ce même résultat null:
- La version installée ne fait l'objet d'aucun avis dans les données interrogées par npm.
- Ce paquet ne fait pas partie de l'arborescence auditée.
- Le paquet a été exclu de l'audit, par exemple via –omit=dev.
- Le nom du paquet a été saisi de manière incorrecte.
Faites en sorte que le résultat soit explicite, plutôt que de laisser place à l'interprétation :
npm audit --json | jq '.vulnerabilities["tslib"] // "aucune entrée dans le rapport d'audit"'
Vérifiez ensuite que le paquet est bien installé, en suivant la procédure décrite à la section 4.
Si vous conditionnez une compilation à cela
Le code de sortie risque de vous induire en erreur. npm audit renvoie le code 1 dès qu’il détecte une vulnérabilité correspondant au niveau d’audit configuré ou supérieur, où que ce soit dans l’arborescence – cela ne dit rien sur le paquet dont vous parlez. Augmenter le seuil avec –audit-level=high modifie le moment où la commande échoue ; cela ne supprime pas les résultats de gravité inférieure du rapport, qui reste identique dans les deux cas.
npm query fonctionne mieux ici : il renvoie un code de sortie 0, qu'il trouve quelque chose ou non, ce qui vous permet de filtrer directement le jeu de résultats.
si [ "$(npm query '#tslib:vuln' | jq length)" -gt 0 ]; puis echo « présence d'une version vulnérable de tslib » fi
Si vous ne vous intéressez qu'aux éléments qui sont déployés en production, exécutez npm audit –omit=dev pour le chemin d'audit, ou utilisez le .prod présenté dans la section 1 pour le chemin de requête. Une anomalie critique dans une dépendance réservée à la compilation ne relève pas du même contexte que celle détectée dans votre arborescence d'exécution.
3. Effectuer une recherche rapide dans des résultats lisibles par l'utilisateur avec grep
Si vous souhaitez simplement obtenir un aperçu rapide sans vous soucier du format JSON, redirigez la sortie standard vers grep.
npm audit | grep -A 5 -i "tslib"
Le | l'opérateur remet npm auditvers grep, qui l’analyse ligne par ligne. -A 5 affiche cinq lignes de contexte après chaque correspondance, ce qui permet de récupérer les détails de l’avis qui l’entourent. -i rend la recherche insensible à la casse.
C'est un point délicat, et il convient d'expliquer précisément pourquoi. Les sauts de ligne, les modifications de mise en page entre les versions de npm et les blocs d'avis plus longs que votre fenêtre de contexte peuvent tous masquer la partie dont vous aviez besoin. Pire encore, une absence de correspondance silencieuse est ambiguë exactement de la même manière que « null » : cela peut signifier que le résultat est correct, ou bien que votre motif a omis une ligne renvoyée à la ligne.
Ça peut faire l'affaire pour une évaluation rapide. Ne l'utilisez jamais comme preuve qu'un paquet ne présente aucune vulnérabilité connue.
4. Vérifier quelles versions sont réellement installées
Un rapport d'audit décrit l'arborescence des dépendances que npm résout à partir de votre fichier de verrouillage. Par défaut npm audit nécessite un fichier fichier package-lock.json ou un fichier shrinkwrap, transmet les noms et versions des paquets résolus au registre, puis les compare aux avis de sécurité connus. Il s'exécute même avec l'option –package-lock-only et sans répertoire node_modules .
npm ls inspecte l'arborescence installée sous node_modules: npm ls tslib
Le filtre de position utilisé ici va plus loin que ce à quoi on pourrait s'attendre. npm parcourt l'arborescence dans son intégralité et affiche le chemin d'accès de chaque instance correspondante, y compris les copies imbriquées ; ainsi, un paquet situé à quatre niveaux de profondeur apparaît tout de même. En ajoutant –all ne modifie pas ce résultat lorsque vous filtrez par nom (vérifié sur npm 10 et npm 12) ; –all est l'option à utiliser pour une commande npm lsnon filtré, alors que l'affichage par défaut s'arrête aux dépendances directes.
Attendez-vous à des doublons. Un même projet peut facilement contenir trois exemplaires d'un même paquet, dans des versions différentes, et seules certaines d'entre elles se situent dans la plage de versions vulnérables.
N'écrivez pas de scripts qui vont à l'encontre de npm ls Code de sortie
npm ls tslib renvoie 0 lorsqu’il trouve une correspondance et 1 dans le cas contraire, ce qui ressemble à une simple vérification de présence. Ce n’est pas tout à fait le cas. Si le paquet correspondant est lui-même signalé comme invalide, superflu ou manquant, npm génère ELSPROBLEMS et se termine avec le code de sortie 1 tout en affichant le paquet qu’il a trouvé. Une dépendance installée mais non conforme s’affiche comme « non installée » :
`– [email protected] invalide : « 0.0.8 » provenant du projet racine
Code d'erreur npm ELSPROBLEMS
Les problèmes sans rapport, situés ailleurs dans l'arborescence, n'ont pas faussé le code de sortie filtré lors des tests ; ce cas est donc plus restreint qu'il n'y paraît – mais c'est exactement celui que vous risquez de rencontrer lorsque vous recherchez une incompatibilité de versions. Pour les scripts, comptez les correspondances avec npm query , qui renvoie 0 quel que soit l’état de l’arborescence et détecte également les copies imbriquées :
[ "$(npm query '#tslib' | jq length)" -gt 0 ] && echo "installé" || echo "non installé"
Accéder à npm ls –json pour .dependencies["tslib"] est une alternative tentante, mais qui peut s’avérer être un piège : les paquets transitifs sont imbriqués sous leurs parents ; ainsi, une recherche au niveau supérieur indique qu’un paquet est absent alors qu’il se trouve deux niveaux plus bas.
Encore une chose : le fichier de verrouillage et node_modules s'écartent constamment l'un de l'autre. Après avoir récupéré les modifications, exécutez npm ci avant de considérer l'arborescence locale comme faisant autorité.
Bonus : découvrez pourquoi ce paquet est installé
Lorsque le paquet signalé ne figure pas dans votre propre fichier package.json, c’est qu’un autre élément l’y a ajouté. Exécutez cette commande depuis la racine du projet :
npm explain tslib
npm explain affiche la chaîne de dépendances pour chaque installation correspondante, de sorte que chaque copie dispose de sa propre traçabilité jusqu'au projet racine. Lorsque plusieurs copies existent et que vous ne vous intéressez qu'à l'une d'entre elles, indiquez son chemin d'accès :
npm explain node_modules/some-package/node_modules/tslib
Cela affiche la chaîne pour cette instance spécifique, y compris dans les cas où deux parents différents dépendent tous deux du même paquet intermédiaire.
S'il s'agit d'une dépendance directe → mettez-la à jour vous-même. Si elle est « pinée » par un composant parent → mettez à jour ce composant parent, ou ajoutez un entrée de dans le fichier package.json (npm 8.3+) à titre de solution provisoire. Une « override » impose une version pour laquelle le paquet parent n’a jamais été testé ; considérez donc cela comme une modification qui nécessite une suite de tests, et non comme une simple correction d’une ligne.
Qu'est-ce que npm audit ne peut pas vous dire
Considérez tout cela comme un triage de base plutôt que comme un programme de sécurité des applications. Aucune de ces commandes ne permettra de :
- Déterminez si votre application peut accéder au chemin d'exécution du code vulnérable.
- Vérifiez la logique de votre propre code source.
- Analyser de manière approfondie les binaires natifs inclus dans un paquet.
- Détecter un paquet malveillant ou délibérément dissimulé avant que quelqu'un ne le signale.
Le premier point est le plus important : le nombre de résultats d'audit ne correspond pas au nombre de vulnérabilités exploitables dans votre application. Chaque résultat dépend de l'arborescence npm résolue, du registre que vous avez configuré et des données d'alerte disponibles au moment où vous avez exécuté la commande. Si vous relancez le même audit la semaine prochaine, vous obtiendrez peut-être un résultat différent sans que votre code ait été modifié.
Conclusion
En bref, voici la marche à suivre pour l'essayer :
npm query '#tslib:vuln' # vérification native npm la plus propre npm audit --json | jq '.vulnerabilities["tslib"]' # portable, compatible avec les scripts npm ls tslib # ce qui est réellement installé npm explain tslib # pourquoi est-il installé ? Une vérification ponctuelle en terminal n'est qu'un instantané, et l'intérêt de l'analyse des dépendances réside dans sa répétition. Les outils de surveillance continue – Dependabot, un scanner open source comme OSV-Scanner, ou une plateforme commerciale d’analyse de la composition logicielle – mettront en évidence les avis de sécurité récemment publiés concernant du code que vous n’avez pas modifié, maintiendront les résultats visibles dans tous les dépôts et automatiseront une partie du travail de mise à jour. Ce qu’ils ne feront pas, c’est dépasser les limites mentionnées ci-dessus : ils s’appuient encore principalement sur des informations relatives aux vulnérabilités connues, et un paquet malveillant non signalé leur échappe également.
Pour combler cette lacune spécifique, il faut effectuer la vérification avant même la publication de l’avis de sécurité. C’est précisément l’approche adoptée par TuxCare SecureChain for OSS : ce service fournit vos dépendances npm à partir d’un registre soigneusement sélectionné, dans lequel les paquets sont recompilés à partir du code source et contrôlés avant même d’être intégrés à votre node_modules.
Les commandes du terminal restent toutefois utiles. Lorsque vous avez besoin d'une réponse immédiate concernant un paquet dans un projet, elles sont plus rapides que d'ouvrir un tableau de bord.
