PacketPirate

Un proxy MITM headless, scriptabile, basato su riga di comando, progettato per l'intercettazione, l'analisi e la modifica del traffico di rete su sistemi Windows. Funziona in modo simile ai proxy GUI standard del settore, ma è ottimizzato per ambienti di automazione, operazione headless e integrazione con i flussi di lavoro di sviluppo.

Nota: Questo è uno strumento standalone, senza dipendenze, implementato in Node.js.

Panoramica

• PacketPirate è uno strumento di intercettazione del traffico a livello di sistema. Sfruttando le impostazioni del proxy HTTP di Windows, può catturare il traffico di qualsiasi applicazione in esecuzione sul tuo computer—inclusi browser web (Chrome, Edge), strumenti CLI (curl, git) e applicazioni desktop (Spotify, VS Code, Discord).

• Intercettazione Globale di Sistema: cattura il traffico HTTP/HTTPS da qualsiasi processo che rispetti il proxy di sistema.

• Process-Aware: identifica esattamente quale applicazione sta generando traffico.

• Motore di Regole Dinamico: configurabile tramite JSON per eseguire azioni specifiche sul traffico corrispondente (es. estrazione di token, registrazione delle richieste).

• Registrazione Completa del Traffico: in grado di scaricare interi corpi di richieste e risposte (HTML, JSON, Binario) per l'analisi.

• Architettura Headless: funziona interamente da CLI, adatta a servizi in background e pipeline di test automatizzati.

• Gestione Personalizzata dei Certificati: include utility per generare e considerare attendibili CA root autofirmate per la decrittazione HTTPS.

Installazione

Prerequisiti

• Node.js (v14 o superiore)
• Windows 10/11 (richiesto per le funzionalità di automazione del proxy di sistema)
• PowerShell (per gli script di gestione dei certificati)

Preparazione

Clona il repository e inizializza l'ambiente:

# 1. Generate local SSL certificates
npm run setup

# 2. Trust the generated Root CA
npm run trust
# Note: Requires administrative approval to add the certificate to the Trusted Root Store.

Utilizzo

Avvia il server proxy:

npm start

Questo avvia l'interfaccia CLI standard.

Funzionamento da CLI

Il menu interattivo fornisce i seguenti controlli:

1. Scansione Processi: elenca i processi attivi con connessioni di rete stabilite. Consente di filtrare il traffico verso un PID specifico (es. monitorare esclusivamente code.exe).
2. Attiva/Disattiva Filtri: abilita/disabilita specifici sottosistemi di monitoraggio:
   • Scansione URL API: registra gli endpoint API richiesti.
   • Dump Header: restituisce le intestazioni complete delle richieste sulla console.
   • Caccia ai Token: rilevamento euristico dei token Bearer nelle intestazioni Authorization.
   • Dump Completo del Traffico: cattura tutto il traffico (intestazioni + corpi completi) in file di log jsonl strutturati.
3. Avvia Proxy: vincola il server alla prima porta disponibile (predefinita 8080) e configura il proxy di sistema di Windows.
4. Genera Regole: helper per creare rapidamente nuovi pattern di intercettazione.

Configurazione

La logica di intercettazione è definita in config/rules.json. Questo file consente una configurazione persistente della gestione del traffico.

Schema:

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

Esempio:

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

Dettagli Tecnici

Architettura

Il tool utilizza un'architettura a doppio server:

1. Server Proxy: gestisce la richiesta di tunneling CONNECT iniziale ed esegue il filtraggio dell'host.
2. Server MITM: decritta il traffico HTTPS utilizzando la CA generata dinamicamente, ispeziona il payload tramite il motore di regole e inoltra la richiesta a monte.

Gestione della rete

• Gestione delle porte: rileva automaticamente gli errori EADDRINUSE e incrementa il numero di porta finché non viene trovata una porta libera.
• Proxy di sistema: utilizza la manipolazione diretta del registro tramite PowerShell per applicare le impostazioni del proxy a livello di sistema.
• Pulizia: implementa i gestori SIGINT/SIGTERM per garantire che le impostazioni del proxy vengano ripristinate all'uscita, prevenendo problemi di connettività di rete.

Ciclo di vita dei certificati e sicurezza

Il tool si basa su un modello a doppio certificato per l'intercettazione HTTPS:

1. Generazione della CA Root: npm run setup crea una CA Root autofirmata (PacketPirateRoot).
   • Logica: usa New-SelfSignedCertificate di PowerShell per generare una coppia di chiavi valida per 5 anni.
   • Esportazione: la chiave viene esportata in src/certs/server.pfx (formato PKCS#12) con la password "headless".
2. Stabilimento della fiducia: npm run trust inietta questa CA Root nell'archivio CurrentUser\Root di Windows.
   • Ambito di sicurezza: scegliendo CurrentUser anziché LocalMachine, limitiamo il raggio di trust al tuo profilo utente specifico, riducendo il rischio a livello di sistema.
   • Accettazione da parte dei browser: Chrome, Edge e IE ereditano questo archivio di trust. Firefox richiede un'opzione separata (security.enterprise_roots.enabled) per rispettare l'archivio di trust di Windows.
3. Rimozione: npm run untrust fornisce una rimozione pulita.

🎓 Educativo: Come l'abbiamo costruito

Questo progetto è un esempio pratico di programmazione di sistema usando Node.js. Va oltre i tipici server web per interagire con il sistema operativo e lo stack di rete a un livello più basso.

Architettura

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

Concetti chiave

1. Il pattern del "Doppio Server"

Il modulo http standard di Node.js non può gestire facilmente il metodo CONNECT (usato per i tunnel HTTPS) e il traffico HTTPS normale sulla stessa istanza del server.

• Server A (Net/HTTP): ascolta sulla porta 8080. Gestisce la richiesta CONNECT iniziale. Agisce come un semplice tubo TCP.
• Server B (HTTPS): esiste solo in memoria (o su una porta casuale). Contiene la chiave privata.
• Il Trucco: quando il Server A riceve una connessione, "emette" il socket al Server B. Il Server B pensa di aver appena ricevuto una nuova connessione e avvia l'handshake SSL. Questo ci permette di decrittare il traffico senza soluzione di continuità.

2. Attribuzione dei processi (il trucco netstat)

Come facciamo a sapere quale app sta inviando traffico? I pacchetti TCP stessi non hanno un'etichetta "Process ID".

• Porte effimere: ogni connessione in uscita usa una porta casuale con un numero alto (es. 54321).
• Correlazione: richiamiamo netstat -ano per scoprire quale PID possiede la porta 54321.
• Ottimizzazione: farlo per ogni pacchetto è lento, quindi memorizziamo nella cache i risultati o controlliamo solo quando necessario.

3. Diramazione degli Stream

Usiamo gli Stream di Node.js per gestire i dati in modo efficiente. Invece di aspettare che l'intera risposta da 10MB venga scaricata prima di mostrarla, "forkiamo" lo stream:

• Pipe 1: va al Client (così l'app continua a funzionare).
• Pipe 2: va al nostro Logger (così possiamo salvarlo su disco). Questo viene fatto usando gli stream PassThrough, consentendo il monitoraggio in tempo reale con una latenza aggiuntiva minima.

Licenza

GNU GPL v3.0