PacketPirate

Un proxy MITM en ligne de commande, scriptable et sans interface graphique, conçu pour l'interception, l'analyse et la modification du trafic réseau sur les systèmes Windows. Il fonctionne de manière similaire aux proxys graphiques standards de l'industrie, mais il est optimisé pour les environnements d'automatisation, le fonctionnement sans interface graphique et l'intégration aux flux de développement.

Remarque : Il s'agit d'un outil autonome, sans dépendances, implémenté en Node.js.

Aperçu

• PacketPirate est un outil d'interception réseau à l'échelle du système. En exploitant les paramètres de proxy HTTP de Windows, il peut capturer le trafic de toute application exécutée sur votre machine—y compris les navigateurs web (Chrome, Edge), les outils CLI (curl, git) et les applications de bureau (Spotify, VS Code, Discord).

• Interception globale du système : Capture le trafic HTTP/HTTPS de tout processus respectant le proxy système.

• Conscience des processus : Identifie exactement quelle application génère le trafic.

• Moteur de règles dynamique : Configurable via JSON pour exécuter des actions spécifiques sur le trafic correspondant (par exemple, extraction de jetons, journalisation des requêtes).

• Journalisation complète du trafic : Capable de vider les corps de requêtes et de réponses complets (HTML, JSON, binaire) pour analyse.

• Architecture sans interface graphique : Fonctionne entièrement en CLI, adapté aux services d'arrière-plan et aux pipelines de test automatisés.

• Gestion personnalisée des certificats : Inclut des utilitaires pour générer et approuver des autorités de certification (CA) racines auto-signées pour le déchiffrement HTTPS.

Installation

Prérequis

• Node.js (v14 ou supérieur)
• Windows 10/11 (requis pour les fonctionnalités d'automatisation du proxy système)
• PowerShell (pour les scripts de gestion des certificats)

Mise en place

Clonez le dépôt et initialisez l'environnement :

# 1. Générer les certificats SSL locaux
npm run setup

# 2. Approuver l'autorité de certification racine générée
npm run trust
# Remarque : Nécessite une approbation administrative pour ajouter le certificat au magasin des autorités de certification racines de confiance.

Utilisation

Démarrez le serveur proxy :

npm start

Ceci lance l'interface CLI standard.

Fonctionnement en CLI

Le menu interactif fournit les commandes suivantes :

1. Scan Processes (Analyser les processus) : Liste les processus actifs avec des connexions réseau établies. Permet de filtrer le trafic vers un PID spécifique (par exemple, surveiller exclusivement code.exe).
2. Toggle Filters (Activer/désactiver les filtres) : Active ou désactive les sous-systèmes de surveillance spécifiques :
   • API URL Scan : Journalise les points de terminaison d'API demandés.
   • Header Dump : Affiche les en-têtes de requête complets dans la console.
   • Token Hunt : Détection heuristique des jetons Bearer dans les en-têtes Authorization.
   • Full Traffic Dump : Capture tout le trafic (en-têtes + corps complets) dans des fichiers journaux jsonl structurés.
3. Start Proxy (Démarrer le proxy) : Lie le serveur au premier port disponible (par défaut 8080) et configure le proxy système Windows.
4. Generate Rules (Générer des règles) : Aide à créer rapidement de nouveaux modèles d'interception.

Configuration

La logique d'interception est définie dans config/rules.json. Ce fichier permet une configuration persistante du traitement du trafic.

Schéma :

{
  "rules": [
    {
      "name": "Description of rule",
      "host": "hostname.match",
      "urlPattern": "regex_pattern",
      "action": "log | save_token",
      "outputFile": "path/to/output.txt",
      "tokenFilter": "regex_filter"
    }
  ]
}

Exemple :

{
    "rules": [
        {
            "name": "Test API",
            "host": "jsonplaceholder.typicode.com",
            "action": "save_token",
            "outputFile": "test_tokens.txt"
        }
    ]
}

Détails techniques

Architecture

L'outil utilise une architecture à double serveur :

1. Serveur proxy : Gère la requête initiale de tunnellisation CONNECT et effectue le filtrage des hôtes.
2. Serveur MITM : Déchiffre le trafic HTTPS à l'aide de l'autorité de certification générée dynamiquement, inspecte la charge utile par rapport au moteur de règles et transmet la requête en amont.

Gestion du réseau

• Gestion des ports : Détecte automatiquement les erreurs EADDRINUSE et incrémente le numéro de port jusqu'à ce qu'un port libre soit trouvé.
• Proxy système : Utilise la manipulation directe du registre via PowerShell pour appliquer les paramètres de proxy à l'échelle du système.
• Nettoyage : Implémente des gestionnaires SIGINT/SIGTERM pour garantir que les paramètres de proxy sont rétablis à la sortie, évitant ainsi les problèmes de connectivité réseau.

Cycle de vie des certificats et sécurité

L'outil repose sur un modèle à double certificat pour l'interception HTTPS :

1. Génération de l'autorité de certification racine : npm run setup crée une autorité de certification racine auto-signée (PacketPirateRoot).
   • Logique : Utilise New-SelfSignedCertificate de PowerShell pour générer une paire de clés valide 5 ans.
   • Exportation : La clé est exportée vers src/certs/server.pfx (format PKCS#12) avec le mot de passe « headless ».
2. Établissement de la confiance : npm run trust injecte cette autorité de certification racine dans le magasin Windows CurrentUser\Root.
   • Portée de sécurité : En ciblant CurrentUser plutôt que LocalMachine, nous limitons le périmètre de confiance à votre profil utilisateur spécifique, réduisant ainsi le risque à l'échelle du système.
   • Acceptation par les navigateurs : Chrome, Edge et IE héritent de ce magasin de confiance. Firefox nécessite une option distincte (security.enterprise_roots.enabled) pour respecter le magasin de confiance Windows.
3. Suppression : npm run untrust permet un nettoyage propre.

🎓 Pédagogique : Comment nous l'avons construit

Ce projet est un exemple pratique de programmation système utilisant Node.js. Il va au-delà des serveurs web classiques pour interagir avec le système d'exploitation et la pile réseau à un niveau inférieur.

Architecture

participant App as Application (VS Code)
participant OS as Windows OS
participant Proxy as Proxy Server
participant MITM as MITM Server
participant Web as Internet

Note over App,Proxy: 1. Plain HTTP Tunneling
App->>Proxy: CONNECT google.com:443
Proxy-->>App: 200 Connection Established

Note over Proxy,MITM: 2. The "Hand-Off" Trick
Proxy->>MITM: Pipe socket data (raw encrypted bytes)

Note over App,MITM: 3. TLS Handshake and Decryption
MITM-->>App: ServerHello (signed by local root CA)
App->>MITM: Encrypted request (GET /)

Note over MITM: 4. Interception Logic
MITM->>MITM: Decrypt → Inspect headers → Log

Note over MITM,Web: 5. Upstream Forwarding
MITM->>Web: New HTTPS request (GET /)
Web-->>MITM: Response
MITM-->>App: Response

Concepts clés

1. Le modèle « Double serveur »

Le module http standard de Node.js ne peut pas gérer facilement la méthode CONNECT (utilisée pour les tunnels HTTPS) et le trafic HTTPS normal sur la même instance de serveur.

• Serveur A (Net/HTTP) : Écoute sur le port 8080. Il gère la requête initiale CONNECT. Il agit comme un tube TCP passif.
• Serveur B (HTTPS) : Il n'existe qu'en mémoire (ou sur un port aléatoire). Il détient la clé privée.
• L'astuce : Lorsque le serveur A reçoit une connexion, il « émet » la socket vers le serveur B. Le serveur B pense qu'il vient de recevoir une nouvelle connexion et démarre la poignée de main SSL. Cela nous permet de déchiffrer le trafic de manière transparente.

2. Attribution des processus (l'astuce netstat)

Comment savons-nous quelle application envoie le trafic ? Les paquets TCP eux-mêmes n'ont pas d'étiquette « ID de processus ».

• Ports éphémères : Chaque connexion sortante utilise un port aléatoire élevé (par exemple, 54321).
• Corrélation : Nous faisons appel à netstat -ano pour trouver quel PID possède le port 54321.
• Optimisation : Faire cela pour chaque paquet est lent, donc nous mettons les résultats en cache ou ne vérifions que lorsque c'est nécessaire.

3. Bifurcation de flux

Nous utilisons les flux (Streams) de Node.js pour gérer les données efficacement. Au lieu d'attendre le téléchargement complet de la réponse de 10 Mo avant de l'afficher, nous « bifurquons » le flux :

• Tuyau 1 : Va vers le client (pour que l'application continue de fonctionner).
• Tuyau 2 : Va vers notre journaliseur (pour que nous puissions l'enregistrer sur le disque). Ceci est réalisé à l'aide de flux PassThrough, permettant une surveillance en temps réel avec une latence ajoutée minimale.

Licence

GNU GPL v3.0