PackageInferno

Logo PackageInferno

Analyseur de chaîne d'approvisionnement npm, ultra-simple et conçu pour Docker. Un seul fichier compose exécute :

Enumerateur → construit la file d'attente des paquets
Téléchargeur → télécharge les archives (et éventuellement les envoie vers S3)
Analyseur → analyse statique + YARA optionnel
Postgres → base de données locale pour les résultats
Tableau de bord Streamlit → visualise les résultats sur http://localhost:8501

Il s'agit de l'édition conteneur uniquement. Le projet peut être construit pour passer à l'échelle avec EC2, SQS et RDS. La plupart des éléments sont déjà configurés dans l'ensemble d'outils.

Ce que vous obtenez

Pipeline de bout en bout dans Docker (aucune installation sur l'hôte en dehors de Docker)
Règles configurables via scan.yml (listes blanches, seuils, YARA)
Schéma Postgres local + historique d'analyse (scan_runs) prêt à l'emploi
Envoi optionnel vers S3 pour les archives et les résultats (identifiants via ~/.aws)
Tableau de bord Streamlit : recherche, exploration détaillée et analyses

Contenu

docker-compose.yml – services : db, enumerateur, téléchargeur, analyseur, tableau de bord, init-db
enumerator/ – Worker Node qui construit la file d'attente NDJSON
fetcher/ – Worker Node qui télécharge les archives (+ envoi vers S3 si activé)
analyzer/ – Analyseur Python statique (+ YARA intégré en option)
dashboard/ – Application Streamlit (port 8501)
infra/migrations.sql – schéma de base de données principal (paquets, versions, résultats, scores, index)
infra/20251106_scan_runs.sql – table d'historique des analyses
scan.yml – configuration d'analyse (règles, notation, listes blanches, YARA)
scripts/run_pipeline.sh – exécute l'enumeration → téléchargement → analyse
scripts/init_db.sh – amorçage du schéma de la base de données
scripts/test_setup.sh – validation automatisée de l'installation
SCANNING_GUIDE.md – stratégies d'analyse détaillées et exemples

Démarrage rapide (local)

Prérequis : Docker Desktop (ou moteur) avec Compose v2.

Installation en une ligne

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

Clone le dépôt dans ~/package-inferno et vous donne les instructions pour commencer.

Option A : Utiliser les images pré-construites (le plus rapide)

Tirez et exécutez les conteneurs pré-construits depuis le registre des conteneurs GitHub :

# Clonez le dépôt (pour les fichiers de configuration et les scripts)
git clone https://github.com/MHaggis/Package-Inferno.git
cd Package-Inferno

# Exécutez avec les images pré-construites
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

Images disponibles :

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

Option B : Construire à partir des sources

Validation automatisée de l'installation

Exécutez le script de test pour valider votre installation :

./scripts/test_setup.sh

Cela va :

✓ Vérifier Docker et Docker Compose
✓ Démarrer et initialiser la base de données
✓ Effectuer une analyse test (2 paquets)
✓ Vérifier que les résultats sont correctement stockés

Installation manuelle

Démarrez Postgres et initialisez le schéma :

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

Exécutez le pipeline :

./scripts/run_pipeline.sh

Lancez le tableau de bord :

docker compose up -d dashboard
# ouvrez http://localhost:8501

Les résultats se trouvent dans ./out/findings/*.findings.json et dans la table findings lorsque la base de données est activée.

Modes d'analyse

PackageInferno prend en charge plusieurs stratégies d'analyse selon vos objectifs :

Mode	Cas d'utilisation	Vitesse	Couverture	Commande
Graines spécifiques	Tester/analyser des paquets connus	La plus rapide	Ciblée	`SEEDS="pkg1,pkg2"`
Petit lot	Valider l'installation, analyse échantillon	Rapide	10-100 paquets	`MAX_CHUNKS=2 CHUNK_LIMIT=10`
Registre complet	Audit complet de la chaîne d'approvisionnement	Heures-Jours	2M+ paquets	`MAX_CHUNKS=0 CHUNK_LIMIT=100`
Flux de modifications	Surveiller les nouvelles versions (inclus automatiquement)	Temps réel	Mises à jour récentes	Intégré

1. Analyser des paquets spécifiques (recommandé pour les tests)

Ciblez des paquets spécifiques que vous souhaitez analyser :

# Commande unique avec des graines
export SEEDS="lodash,express,axios"
./scripts/run_pipeline.sh

# Ou depuis un fichier
echo -e "react\nvue\nangular" > packages.txt
export SEEDS_FILE=packages.txt
./scripts/run_pipeline.sh

Comment j'ai testé initialement : J'ai utilisé SEEDS="is-odd,is-even" pour une validation rapide.

2. Analyser depuis le registre npm (_all_docs)

Analysez des paquets paginés depuis le registre npm :

# Nettoyez les exécutions précédentes
rm -rf downloads/* out/*

# Analysez 2 pages de 10 paquets chacune (20 paquets)
export MAX_CHUNKS=2        # Nombre de pages
export CHUNK_LIMIT=10      # Paquets par page
unset SEEDS                # Important : désactiver le mode graines

# Exécutez les étapes individuellement pour une meilleure visibilité
docker compose run --rm enumerator  # Découvre et met en file d'attente
docker compose run --rm fetcher     # Télécharge les archives
docker compose run --rm analyzer    # Analyse les menaces

Exemple de sortie :

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. Surveillance continue (analyse illimitée)

Analysez l'ensemble du registre npm :

export MAX_CHUNKS=0        # 0 = illimité
export CHUNK_LIMIT=100     # Lots plus grands pour l'efficacité
./scripts/run_pipeline.sh

Attention : Cela va s'exécuter pendant des heures/jours et analyser des centaines de milliers de paquets. Surveillez l'espace disque et la taille de la base de données.

4. Reprendre des analyses interrompues

L'enumerateur sauvegarde l'état dans ./out/enumerator_state.json avec la position du curseur :

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

Réexécutez simplement le pipeline et il reprendra à partir du dernier curseur :

./scripts/run_pipeline.sh  # Reprend automatiquement

Pour forcer une nouvelle analyse :

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

Exemple de résultats d'analyse

D'après une analyse de 2 pages de 22 paquets, voici ce que PackageInferno a détecté :

-- Paquets les plus suspects par 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;

-- Résultats :
   name                | score | label      | findings
-----------------------+-------+------------+----------
 rendition             | 606   | malveillant | 153
 vs-deploy             | 454   | malveillant | 119
 --123hoodmane-pyodide | 213   | malveillant | 46

Package-Inferno

Populaires