PackageInferno

PackageInferno-Logo

Blitzschnell einfacher, Docker-zentrierter npm-Lieferkettenscanner. Eine Compose-Datei führt Folgendes aus:

Enumerator → erstellt die Warteschlange der Pakete
Fetcher → lädt Tarballs herunter (und optional zu S3 hoch)
Analyzer → statische Analyse + optional YARA
Postgres → lokale DB für Ergebnisse
Streamlit Dashboard → Ergebnisse visualisieren auf http://localhost:8501

Dies ist die Container-Only-Edition. Das Projekt kann mithilfe von EC2, SQS und RDS skalierbar aufgebaut werden. Der größte Teil davon ist im Toolset dafür vorbereitet.

Was Sie erhalten

Ende-zu-Ende-Pipeline in Docker (keine Installationen auf dem Host außer Docker)
Konfigurierbare Regeln über scan.yml (Allowlists, Schwellenwerte, YARA)
Lokales Postgres-Schema + Scanverlauf (scan_runs) einsatzbereit
Optionale S3-Uploads für Tarballs und Ergebnisse (Anmeldeinformationen über ~/.aws)
Streamlit-Dashboard: Suche, Drill-down und Analysen

Inhalt

docker-compose.yml – Dienste: db, enumerator, fetcher, analyzer, dashboard, init-db
enumerator/ – Node-Worker, der die NDJSON-Warteschlange erstellt
fetcher/ – Node-Worker, der Tarballs herunterlädt (+ Upload zu S3, falls aktiviert)
analyzer/ – Python-Statik-Analyzer (+ optionales YARA inline)
dashboard/ – Streamlit-App (Port 8501)
infra/migrations.sql – Kern-DB-Schema (packages, versions, findings, scores, indexes)
infra/20251106_scan_runs.sql – Scanverlaufstabelle
scan.yml – Analysekonfiguration (Regeln, Bewertung, Allowlists, YARA)
scripts/run_pipeline.sh – enumerate → fetch → analyze ausführen
scripts/init_db.sh – DB-Schema booten
scripts/test_setup.sh – automatische Setup-Validierung
SCANNING_GUIDE.md – detaillierte Scanstrategien und Beispiele

Schnellstart (lokal)

Voraussetzungen: Docker Desktop (oder Engine) mit Compose v2.

Einzeilige Installation

curl -fsSL https://raw.githubusercontent.com/MHaggis/Package-Inferno/main/install.sh | bash

Dies klont das Repository in ~/package-inferno und gibt Ihnen Anweisungen für den Start.

Option A: Vorgefertigte Images verwenden (am schnellsten)

Vorgefertigte Container aus der GitHub Container Registry ziehen und ausführen:

# Repository klonen (für Konfigurationsdateien und Skripte)
git clone https://github.com/MHaggis/Package-Inferno.git
cd Package-Inferno

# Mit vorgefertigten Images ausführen
docker compose -f docker-compose.ghcr.yml up -d db
./scripts/init_db.sh
SEEDS="lodash,express" docker compose -f docker-compose.ghcr.yml run --rm enumerator
docker compose -f docker-compose.ghcr.yml run --rm fetcher
docker compose -f docker-compose.ghcr.yml run --rm analyzer

Verfügbare Images:

ghcr.io/mhaggis/package-inferno/enumerator:main
ghcr.io/mhaggis/package-inferno/fetcher:main
ghcr.io/mhaggis/package-inferno/analyzer:main

Option B: Aus dem Quellcode erstellen

Automatisierte Setup-Validierung

Führen Sie das Testskript aus, um Ihre Installation zu validieren:

./scripts/test_setup.sh

Dies wird:

✓ Docker und Docker Compose prüfen
✓ Datenbank starten und initialisieren
✓ Testscan durchführen (2 Pakete)
✓ Überprüfen, ob Ergebnisse korrekt gespeichert sind

Manuelles Setup

Postgres starten und Schema initialisieren:

docker compose up -d db
./scripts/init_db.sh

Pipeline ausführen:

./scripts/run_pipeline.sh

Dashboard starten:

docker compose up -d dashboard
# öffnen Sie http://localhost:8501

Ergebnisse landen unter ./out/findings/*.findings.json und in der Tabelle findings, wenn die DB aktiviert ist.

Scanmodi

PackageInferno unterstützt mehrere Scanstrategien, abhängig von Ihren Zielen:

Modus	Anwendungsfall	Geschwindigkeit	Abdeckung	Befehl
Spezifische Seeds	Bekannte Pakete testen/untersuchen	Am schnellsten	Gezielt	`SEEDS="pkg1,pkg2"`
Kleine Stichprobe	Setup validieren, Beispielscan	Schnell	10-100 Pakete	`MAX_CHUNKS=2 CHUNK_LIMIT=10`
Vollständiges Registry	Umfassende Lieferkettenprüfung	Stunden-Tage	2M+ Pakete	`MAX_CHUNKS=0 CHUNK_LIMIT=100`
Änderungs-Feed	Neue Veröffentlichungen überwachen (automatisch enthalten)	Echtzeit	Aktuelle Updates	Eingebaut

1. Bestimmte Pakete scannen (für Tests empfohlen)

Zielen Sie auf bestimmte Pakete ab, die Sie analysieren möchten:

# Einzelner Befehl mit Seeds
export SEEDS="lodash,express,axios"
./scripts/run_pipeline.sh

# Oder aus einer Datei
echo -e "react\nvue\nangular" > packages.txt
export SEEDS_FILE=packages.txt
./scripts/run_pipeline.sh

Wie ich anfangs getestet habe: Verwendet SEEDS="is-odd,is-even" zur schnellen Validierung.

2. Aus dem npm-Registry scannen (_all_docs)

Pakete seitenweise aus dem npm-Registry scannen:

# Vorherige Läufe bereinigen
rm -rf downloads/* out/*

# 2 Seiten mit je 10 Paketen scannen (20 Pakete)
export MAX_CHUNKS=2        # Anzahl der Seiten
export CHUNK_LIMIT=10      # Pakete pro Seite
unset SEEDS                # Wichtig: Seeds-Modus deaktivieren

# Einzelne Schritte für bessere Übersicht ausführen
docker compose run --rm enumerator  # Entdeckt und reiht ein
docker compose run --rm fetcher     # Lädt Tarballs herunter
docker compose run --rm analyzer    # Scannt nach Bedrohungen

Beispielausgabe:

config: chunkLimit=10, maxChunks=2
checking recent changes feed...
changes feed: enqueued 2 new versions
enumerating via _all_docs (fresh scan)
page 1/2 count: 10
page 2/2 count: 10
done, enqueued 22 (22 new versions)

3. Kontinuierliche Überwachung (unbegrenzter Scan)

Das gesamte npm-Registry scannen:

export MAX_CHUNKS=0        # 0 = unbegrenzt
export CHUNK_LIMIT=100     # Größere Stapel für Effizienz
./scripts/run_pipeline.sh

Warnung: Dies wird Stunden/Tage laufen und Hunderttausende von Paketen scannen. Überwachen Sie den Festplattenspeicher und die Datenbankgröße.

4. Unterbrochene Scans fortsetzen

Der Enumerator speichert den Zustand in ./out/enumerator_state.json mit Cursorposition:

{
  "last_seq": "0",
  "last_startkey": "package-name",
  "last_run": "2025-11-23T19:24:49.123Z",
  "last_processed": 22,
  "last_new": 22
}

Führen Sie einfach die Pipeline erneut aus, und sie wird ab dem letzten Cursor fortgesetzt:

./scripts/run_pipeline.sh  # Wird automatisch fortgesetzt

Um einen neuen Scan zu erzwingen:

rm -f out/enumerator_state.json
./scripts/run_pipeline.sh

Beispiel-Scannergebnisse

Von einem 2-seitigen Scan von 22 Paketen zeigt PackageInferno Folgendes:

-- Top suspicious packages by score
SELECT p.name, s.score, s.label, COUNT(f.id) as findings 
FROM packages p 
JOIN versions v ON p.id = v.package_id 
JOIN scores s ON v.id = s.version_id 
LEFT JOIN findings f ON v.id = f.version_id 
GROUP BY p.name, s.score, s.label 
ORDER BY s.score DESC;

-- Results:
   name                | score | label      | findings
-----------------------+-------+------------+----------
 rendition             | 606   | malicious  | 153
 vs-deploy             | 454   | malicious  | 119
 --123hoodmane-pyodide | 213   | malicious  | 46

Was machte rendition so verdächtig?

57 × url_outside_allowlist – Nicht in der Allowlist enthaltene Domains
46 × suspicious_pattern – Shell/eval-Muster
12 × advanced_obfuscation – Hex-Kodierung, XOR, String-Arrays
6 × big_base64_blob – Große kodierte Payloads
18 × url_in_code – Eingebettete URLs

Das Bewertungssystem (konfiguriert in scan.yml) aggregiert diese Ergebnisse, um einen Risikoscore und ein Label (clean, suspicious oder malicious) zu erzeugen.

Package-Inferno

Beliebteste