Automatiser les vérifications de sécurité des packages npm avec npq

npq audite un package npm avant son installation, tandis que npm audit ne signale les vulnérabilités qu’une fois le code déjà écrit dans node_modules. C’est précisément là tout l’intérêt : au moment où quelqu’un audite l’arbre de dépendances, un script postinstall malveillant s’est déjà exécuté sur votre machine. npq déplace la vérification en amont — il inspecte les métadonnées du package, son ancienneté, ses scripts et les CVE connus au moment de la demande d’installation, puis vous demande si vous souhaitez continuer.

Ce guide intègre npq dans votre terminal et dans un hook pre-commit, afin que l’audit s’exécute là où vous récupérez les dépendances — et non uniquement lorsque vous pensez à le lancer manuellement.

npm install -g npq

Le manque que npq comble

npq est un auditeur de sécurité pré-installation qui exécute un ensemble de vérifications — appelées « marshalls » — sur les métadonnées d’un package avant que npm ne récupère ni n’exécute le moindre code. C’est l’inverse de npm audit, qui lit votre arbre de dépendances installées et signale les CVE après coup. La campagne Shai-Hulud de 2025 a exploité des scripts de cycle de vie s’exécutant lors de l’installation, ce qui correspond exactement à la fenêtre que npm audit ne peut pas couvrir, mais que npq peut. L’outil est open source sur lirantal/npq et développé par Liran Tal.

Installer npq et effectuer un audit ponctuel

Installez npq globalement, puis appelez npq install à la place de npm install pour tout package que vous souhaitez vérifier au préalable.

npm install -g npq
npq install express

Le package npq sur npm installe deux binaires : npq et npq-hero. Le premier exécute un audit explicite ; le second est un wrapper npm de substitution présenté dans la section suivante. Lorsque vous exécutez npq install express, npq récupère les métadonnées, exécute ses marshalls, affiche les résultats et — si quelque chose est signalé — vous invite à confirmer avant de déléguer à npm.

Un package signalé produit une sortie de ce type :

warning Package has install scripts (preinstall, postinstall)
warning Package is older than 22 days? no — published 1 day ago
? Would you like to continue installing package(s)? (Y/n)

L’invite constitue le point de contrôle. Rien ne s’installe tant que vous n’avez pas répondu, ou que le minuteur d’auto-continuation de 15 secondes (uniquement en cas d’avertissements) n’a pas expiré.

Créer un alias npm vers npq-hero et le rendre persistant

Pour auditer automatiquement chaque installation, créez un alias de npm vers npq-hero et enregistrez-le dans la configuration de votre shell. npq-hero est le wrapper conçu à cet effet — il transmet toutes les sous-commandes npm (run, ci, publish, et les autres) sans modification, en interceptant uniquement les installations pour exécuter l’audit en premier.

echo "alias npm='npq-hero'" >> ~/.zshrc   # ou ~/.bashrc pour bash
source ~/.zshrc

Une fois l’alias en place, npm install fastify passe par les marshalls de npq avant que npm ne récupère le moindre tarball. Créez l’alias de npm vers npq-hero plutôt que vers npq directement — npq est le binaire d’audit, tandis que npq-hero est le wrapper complet compatible npm documenté dans le README de npq. Créer un alias vers le binaire npq brut casse les sous-commandes que npq n’implémente pas lui-même.

Que vérifie réellement npq ?

npq exécute un ensemble de vérifications de sécurité, appelées « marshalls », documentées dans le README de npq. Elles se répartissent en quatre catégories pratiques :

Ce regroupement correspond à la façon dont une attaque se manifeste concrètement : un typosquat avec un script postinstall et zéro téléchargement déclenche simultanément plusieurs marshalls. Chaque vérification est un signal à peser, non un verdict binaire — npq expose les données et vous laisse la décision.

Désactiver l’auto-continuation pour une revue explicite

Par défaut, l’invite interactive de npq attend 15 secondes puis poursuit automatiquement l’installation lorsque seuls des avertissements sont présents. Définissez NPQ_DISABLE_AUTO_CONTINUE=true ou passez --disable-auto-continue pour supprimer le compte à rebours et forcer une réponse explicite (y/N) avant que npq ne délègue à npm. Le flag et la variable d’environnement sont tous deux documentés dans le README de npq.

# Les deux formes fonctionnent
NPQ_DISABLE_AUTO_CONTINUE=true npq install
npq install --disable-auto-continue

Cela fait de npq une étape de revue délibérée — utile dans votre terminal et dans un hook de commit git, où quelqu’un est présent pour répondre à l’invite. Il ne s’agit pas d’un mode d’échec non interactif documenté : l’invite attend toujours une réponse, et npq ne propose pas de flag qui convertisse automatiquement chaque package signalé en sortie non nulle.

Router pnpm via npq

npq délègue au gestionnaire de packages indiqué dans NPQ_PKG_MGR, de sorte que la même couche d’audit couvre également pnpm. Définissez la variable par commande pour les usages ponctuels, ou intégrez-la dans un alias shell pour une utilisation quotidienne.

# Audits ponctuels via pnpm
NPQ_PKG_MGR=pnpm npq install fastify

# Faire passer pnpm systématiquement par npq
alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"
echo 'alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"' >> ~/.zshrc

La variable NPQ_PKG_MGR, référencée dans le README de npq, indique à npq-hero quel gestionnaire de packages invoquer une fois l’audit réussi. La forme avec alias vous offre la même garantie pour pnpm que l’alias npm vous offre pour npm : aucune installation ne se poursuit tant que les marshalls n’ont pas été exécutés.

Ajouter un hook pre-commit husky

Interceptez les dépendances risquées avant qu’elles ne soient commitées en exécutant npq depuis un hook pre-commit husky. Cela audite les dépendances déclarées dans package.json à chaque commit, ce qui est particulièrement utile pour les commits qui modifient les manifestes de dépendances.

Installez husky et initialisez-le (syntaxe husky v9) :

npm install --save-dev husky
npx husky init

Puis écrivez le hook dans .husky/pre-commit :

# .husky/pre-commit
if git diff --cached --name-only | grep -qE 'package(-lock)?\.json'; then
  npx npq
fi

La vérification git diff --cached limite l’audit aux commits qui modifient effectivement package.json ou package-lock.json, afin que les commits sans rapport ne supportent pas le coût de l’audit. La commande npx npq seule (sans sous-commande install) audite les dépendances déclarées dans package.json et se termine avec un code de sortie non nul en cas de problème. Husky bloquant les commits lorsqu’un hook se termine avec un code non nul, cela fait du hook une barrière stricte en pre-commit. La commande npx husky init et le format de script brut .husky/pre-commit correspondent à la convention husky v9 ; la v8 utilisait une syntaxe husky add différente, vérifiez donc votre version installée avant de copier des extraits plus anciens.

Limites honnêtes : heuristiques, non preuves

Les marshalls de npq sont des signaux heuristiques, non des preuves de malveillance. Un package publié la veille avec zéro téléchargement est suspect selon les vérifications d’ancienneté et de popularité de npq — mais tout package légitime commence exactement dans cet état. npq réduit le bruit à un ensemble de signaux pondérés et vous laisse la décision ; il ne peut pas, et ne prétend pas, classifier les intentions. Traitez une installation signalée comme une invitation à examiner le package, non comme une menace confirmée.

npq ne remplace pas non plus npm audit ni Socket — il les complète. Ces trois outils couvrent des fenêtres différentes :

npq intercepte les signaux pré-installation ; npm audit détecte les CVE dans les packages déjà présents sur le disque ; Socket ajoute une surveillance comportementale continue de votre graphe de dépendances après le merge. Associer la barrière d’installation de npq à --ignore-scripts par défaut (et à des outils comme LavaMoat allow-scripts pour les dépendances qui ont réellement besoin de scripts de cycle de vie) couvre la majeure partie de la surface d’attaque au moment de l’installation.

Conclusion

Créer un alias de npm vers npq-hero et bloquer les commits avec un hook husky place le même audit pré-installation devant chaque point où vous récupérez des dépendances — terminal local et commit. Commencez par l’installation globale et l’alias shell, puis configurez le hook husky la prochaine fois que vous modifiez vos manifestes de dépendances. Les marshalls sont des heuristiques, alors lisez ce qu’ils signalent — mais lire un avertissement vaut mieux que découvrir une charge utile postinstall après qu’elle s’est déjà exécutée.

FAQ

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.