Automatisierung von npm-Paketsicherheitsprüfungen mit npq

npq prüft ein npm-Paket vor der Installation, während npm audit Schwachstellen erst meldet, nachdem der Code bereits in node_modules geschrieben wurde. Genau darin liegt der entscheidende Unterschied: Wenn jemand den Abhängigkeitsbaum prüft, hat ein bösartiges postinstall-Skript möglicherweise bereits auf dem Rechner ausgeführt. npq verlagert die Prüfung nach vorne — es untersucht Paket-Metadaten, Alter, Skripte und bekannte CVEs zum Zeitpunkt der Installationsanfrage und fragt anschließend, ob der Vorgang fortgesetzt werden soll.

Diese Anleitung bindet npq in Ihr Terminal und einen Pre-Commit-Hook ein, sodass die Prüfung genau dort stattfindet, wo Sie Abhängigkeiten beziehen — nicht erst, wenn Sie sich daran erinnern, sie manuell auszuführen.

npm install -g npq

Die Lücke, die npq schließt

npq ist ein Sicherheitsprüfer für die Pre-Install-Phase, der eine Reihe von Prüfungen — sogenannte „Marshalls” — gegen die Metadaten eines Pakets ausführt, bevor npm dessen Code abruft oder ausführt. Dies ist das Gegenteil von npm audit, das den installierten Abhängigkeitsbaum liest und CVEs im Nachhinein meldet. Die Shai-Hulud-Kampagne von 2025 nutzte Lifecycle-Skripte als Angriffsmittel, die während der Installation ausgeführt werden — genau das Zeitfenster, das npm audit nicht abdecken kann, npq jedoch schon. Das Tool ist als Open Source unter lirantal/npq verfügbar und wurde von Liran Tal entwickelt.

npq installieren und eine einmalige Prüfung durchführen

Installieren Sie npq global und verwenden Sie anschließend npq install anstelle von npm install für jedes Paket, das Sie vorab prüfen möchten.

npm install -g npq
npq install express

Das npq-Paket auf npm installiert zwei Binärdateien: npq und npq-hero. Die erste führt eine explizite Prüfung durch; die zweite ist ein npm-Wrapper, der im nächsten Abschnitt behandelt wird. Wenn Sie npq install express ausführen, ruft npq Metadaten ab, führt seine Marshalls aus, gibt etwaige Befunde aus und fordert Sie — falls etwas markiert wurde — zur Bestätigung auf, bevor es an npm delegiert.

Ein markiertes Paket erzeugt eine Ausgabe in etwa dieser Form:

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)

Die Eingabeaufforderung ist der Kontrollpunkt. Es wird nichts installiert, bis Sie antworten oder der 15-Sekunden-Timer für die automatische Fortsetzung bei reinen Warnungen abläuft.

npm auf npq-hero aliasieren und dauerhaft speichern

Um jede Installation automatisch zu prüfen, setzen Sie einen Alias von npm auf npq-hero und tragen Sie diesen in Ihre Shell-Konfiguration ein. npq-hero ist der dafür vorgesehene Wrapper — er leitet jeden npm-Unterbefehl (run, ci, publish und weitere) unverändert weiter und fängt nur Installationen ab, um zunächst die Prüfung durchzuführen.

echo "alias npm='npq-hero'" >> ~/.zshrc   # oder ~/.bashrc für bash
source ~/.zshrc

Mit dem gesetzten Alias wird npm install fastify durch die Marshalls von npq geleitet, bevor npm das Tarball überhaupt abruft. Setzen Sie den Alias von npm auf npq-hero und nicht direkt auf npq — npq ist die Prüf-Binärdatei, während npq-hero der vollständige, npm-kompatible Passthrough-Wrapper ist, der in der npq-README dokumentiert ist. Ein Alias auf die rohe npq-Binärdatei bricht Unterbefehle, die npq selbst nicht implementiert.

Was prüft npq konkret?

npq führt eine Reihe von Sicherheitsprüfungen durch, die als „Marshalls” bezeichnet werden und in der npq-README dokumentiert sind. Sie lassen sich in vier praktische Kategorien einteilen:

Diese Gruppierung spiegelt wider, wie ein Angriff tatsächlich in Erscheinung tritt: Ein Typosquat mit einem postinstall-Skript und null Downloads löst gleichzeitig mehrere Marshalls aus. Jede Prüfung ist ein Signal, das Sie abwägen, kein binäres Urteil — npq stellt die Daten bereit und überlässt Ihnen die Entscheidung.

Automatische Fortsetzung für explizite Überprüfung deaktivieren

Standardmäßig wartet npqs interaktive Eingabeaufforderung 15 Sekunden und setzt die Installation automatisch fort, wenn nur Warnungen vorliegen. Setzen Sie NPQ_DISABLE_AUTO_CONTINUE=true oder übergeben Sie --disable-auto-continue, um den Countdown zu entfernen und eine explizite (y/N)-Antwort zu erzwingen, bevor npq an npm übergibt. Sowohl das Flag als auch die Umgebungsvariable sind in der npq-README dokumentiert.

# Beide Varianten funktionieren
NPQ_DISABLE_AUTO_CONTINUE=true npq install
npq install --disable-auto-continue

Dadurch wird npq zu einem bewussten Überprüfungsschritt — nützlich im Terminal und innerhalb eines Git-Commit-Hooks, wo jemand anwesend ist, um die Eingabeaufforderung zu beantworten. Es handelt sich nicht um einen dokumentierten nicht-interaktiven Fehlermodus: Die Eingabeaufforderung erwartet weiterhin eine Antwort, und npq bietet kein Flag, das jedes markierte Paket automatisch mit einem Nicht-Null-Exit-Code abbricht.

pnpm über npq leiten

npq delegiert an den in NPQ_PKG_MGR angegebenen Paketmanager, sodass dieselbe Prüfschicht auch pnpm abdeckt. Setzen Sie die Variable pro Befehl für einmalige Prüfungen oder integrieren Sie sie in einen Shell-Alias für den täglichen Gebrauch.

# Einmalige Prüfungen über pnpm
NPQ_PKG_MGR=pnpm npq install fastify

# pnpm immer über npq leiten
alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"
echo 'alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"' >> ~/.zshrc

Die Variable NPQ_PKG_MGR, die in der npq-README aufgeführt ist, teilt npq-hero mit, welchen Paketmanager es nach bestandener Prüfung aufrufen soll. Der Alias-Ansatz bietet für pnpm dieselbe Garantie wie der npm-Alias für npm: Keine Installation wird durchgeführt, bevor die Marshalls ausgeführt wurden.

Einen Husky-Pre-Commit-Hook hinzufügen

Fangen Sie riskante Abhängigkeiten ab, bevor sie committet werden, indem Sie npq über einen husky-Pre-Commit-Hook ausführen. Dadurch werden die in package.json deklarierten Abhängigkeiten bei jedem Commit geprüft — besonders wertvoll bei Commits, die Abhängigkeits-Manifeste berühren.

Installieren Sie husky und initialisieren Sie es (husky v9-Syntax):

npm install --save-dev husky
npx husky init

Schreiben Sie dann den Hook in .husky/pre-commit:

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

Die git diff --cached-Prüfung begrenzt die Prüfung auf Commits, die tatsächlich package.json oder package-lock.json ändern, sodass nicht zusammenhängende Commits keinen Prüfaufwand verursachen. Das bloße npx npq (ohne den Unterbefehl install) prüft die in package.json deklarierten Abhängigkeiten und beendet sich mit einem Nicht-Null-Exit-Code, wenn Probleme gefunden werden. Da Husky Commits blockiert, wenn ein Hook mit einem Nicht-Null-Exit-Code endet, macht dies den Hook zu einem harten Pre-Commit-Gate. Der Befehl npx husky init und das einfache Skriptformat für .husky/pre-commit entsprechen der v9-Husky-Konvention; v8 verwendete eine andere husky add-Syntax — überprüfen Sie daher Ihre installierte Version, bevor Sie ältere Snippets übernehmen.

Ehrliche Einschränkungen: Heuristiken, kein Beweis

Die Marshalls von npq sind heuristische Signale, kein Beweis für Schadsoftware. Ein gestern veröffentlichtes Paket mit null Downloads ist nach npqs Alters- und Popularitätsprüfungen verdächtig — aber jedes legitime neue Paket beginnt genau in diesem Zustand. npq reduziert das Rauschen auf eine Reihe gewichteter Signale und überlässt Ihnen die Entscheidung; es kann keine Absicht klassifizieren und erhebt auch keinen solchen Anspruch. Betrachten Sie eine markierte Installation als Anlass, das Paket zu lesen — nicht als bestätigte Bedrohung.

npq ersetzt auch nicht npm audit oder Socket — es ergänzt sie. Die drei Tools decken unterschiedliche Zeitfenster ab:

npq erfasst Pre-Install-Signale; npm audit erfasst CVEs in bereits auf dem Datenträger befindlichen Paketen; Socket ergänzt dies durch kontinuierliches Verhaltensmonitoring Ihres Abhängigkeitsgraphen nach dem Merge. Die Kombination von npqs Install-Zeit-Gate mit --ignore-scripts als Standard (sowie Tools wie LavaMoat allow-scripts für Abhängigkeiten, die Lifecycle-Skripte tatsächlich benötigen) schließt den Großteil der Angriffsfläche zur Installationszeit.

Fazit

Das Aliasieren von npm auf npq-hero und das Absichern von Commits mit einem Husky-Hook stellt dieselbe Pre-Install-Prüfung an jedem Ort bereit, an dem Sie Abhängigkeiten beziehen — im lokalen Terminal und beim Commit. Beginnen Sie mit der globalen Installation und dem Shell-Alias und richten Sie dann den Husky-Hook ein, wenn Sie das nächste Mal Ihre Abhängigkeits-Manifeste anpassen. Die Marshalls sind Heuristiken — lesen Sie daher, was sie markieren. Aber eine Warnung zu lesen ist besser, als eine postinstall-Payload zu entdecken, nachdem sie bereits ausgeführt wurde.

Häufig gestellte Fragen

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.