PacketPirate

Ein headless, skriptbarer, kommandozeilenbasierter MITM-Proxy, der für Netzwerkverkehr-Abfangen, -Analyse und -Modifikation auf Windows-Systemen entwickelt wurde. Er funktioniert ähnlich wie branchenübliche GUI-Proxys, ist jedoch für Automatisierungsumgebungen, Headless-Betrieb und die Integration in Entwicklungs-Workflows optimiert.

Hinweis: Dies ist ein eigenständiges, ablauffähiges Werkzeug ohne Abhängigkeiten, implementiert in Node.js.

Überblick

• PacketPirate ist ein systemweites Netzwerk-Interception-Tool. Durch die Nutzung der Windows-HTTP-Proxy-Einstellungen kann es Datenverkehr von jeder Anwendung auf Ihrem Rechner erfassen – einschließlich Webbrowsern (Chrome, Edge), CLI-Tools (curl, git) und Desktop-Anwendungen (Spotify, VS Code, Discord).

• Global System Interception: Erfasst HTTP/HTTPS-Datenverkehr von jedem Prozess, der den System-Proxy respektiert.

• Process-Aware: Identifiziert genau, welche Anwendung Datenverkehr erzeugt.

• Dynamic Rule Engine: Über JSON konfigurierbar, um spezifische Aktionen auf passenden Datenverkehr auszuführen (z. B. Token-Extraktion, Anfrage-Logging).

• Full Traffic Logging: Kann vollständige Anfrage- und Antwort-Bodys (HTML, JSON, Binär) zur Analyse speichern.

• Headless Architecture: Läuft vollständig über die CLI, geeignet für Hintergrunddienste und automatisierte Testpipelines.

• Custom Certificate Management: Enthält Hilfsprogramme zum Erzeugen und Vertrauen selbstsignierter Root-CAs für die HTTPS-Entschlüsselung.

Installation

Voraussetzungen

• Node.js (v14 oder höher)
• Windows 10/11 (erforderlich für System-Proxy-Automatisierungsfunktionen)
• PowerShell (für Zertifikatverwaltungsskripte)

Einrichtung

Repository klonen und die Umgebung initialisieren:

# 1. Lokale SSL-Zertifikate erzeugen
npm run setup

# 2. Der erzeugten Root-CA vertrauen
npm run trust
# Hinweis: Erfordert administrative Freigabe, um das Zertifikat zum Store der vertrauenswürdigen Stammzertifikate hinzuzufügen.

Verwendung

Proxy-Server starten:

npm start

Dies startet die Standard-CLI-Oberfläche.

CLI-Bedienung

Das interaktive Menü bietet die folgenden Steuerungsmöglichkeiten:

1. Scan Processes: Listet aktive Prozesse mit etablierten Netzwerkverbindungen auf. Ermöglicht das Filtern von Datenverkehr auf eine bestimmte PID (z. B. ausschließliches Überwachen von code.exe).
2. Toggle Filters: Aktiviert/deaktiviert spezifische Überwachungssubsysteme:
   • API URL Scan: Protokolliert angefragte API-Endpunkte.
   • Header Dump: Gibt vollständige Anfrage-Header in der Konsole aus.
   • Token Hunt: Heuristische Erkennung von Bearer-Tokens in Authorization-Headern.
   • Full Traffic Dump: Erfasst allen Datenverkehr (Header + vollständige Bodys) in strukturierten jsonl-Logdateien.
3. Start Proxy: Bindet den Server an den ersten verfügbaren Port (Standard 8080) und konfiguriert den Windows-System-Proxy.
4. Generate Rules: Hilfsfunktion zum schnellen Erstellen neuer Interceptions-Muster.

Konfiguration

Die Interceptions-Logik wird in config/rules.json definiert. Diese Datei ermöglicht eine dauerhafte Konfiguration der Datenverkehrsbehandlung.

Schema:

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

Beispiel:

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

Technische Details

Architektur

Das Tool verwendet eine Zwei-Server-Architektur:

1. Proxy-Server: Behandelt die anfängliche CONNECT-Tunnelanfrage und führt Host-Filterung durch.
2. MITM-Server: Entschlüsselt HTTPS-Datenverkehr mithilfe der dynamisch erzeugten CA, prüft die Nutzlast gegen die Rule-Engine und leitet die Anfrage stromaufwärts weiter.

Netzwerkverarbeitung

• Port-Verwaltung: Erkennt EADDRINUSE-Fehler automatisch und erhöht die Portnummer, bis ein freier Port gefunden wird.
• System-Proxy: Verwendet direkte Registrierungsmanipulation über PowerShell, um Proxy-Einstellungen systemweit durchzusetzen.
• Bereinigung: Implementiert SIGINT/SIGTERM-Handler, um sicherzustellen, dass die Proxy-Einstellungen beim Beenden zurückgesetzt werden und Netzwerkverbindungsprobleme vermieden werden.

Zertifikatslebenszyklus und Sicherheit

Das Tool basiert auf einem Zwei-Zertifikatsmodell für die HTTPS-Interception:

1. Root-CA-Erzeugung: npm run setup erstellt eine selbstsignierte Root-CA (PacketPirateRoot).
   • Logik: Verwendet PowerShells New-SelfSignedCertificate, um ein Schlüsselpaar zu erzeugen, das 5 Jahre gültig ist.
   • Export: Der Schlüssel wird nach src/certs/server.pfx (PKCS#12-Format) mit dem Passwort „headless“ exportiert.
2. Vertrauensaufbau: npm run trust fügt diese Root-CA in den Windows-Store CurrentUser\Root ein.
   • Sicherheitsumfang: Durch die Ausrichtung auf CurrentUser statt auf LocalMachine begrenzen wir den Vertrauensradius auf Ihr spezifisches Benutzerprofil und reduzieren so das systemweite Risiko.
   • Browser-Akzeptanz: Chrome, Edge und IE übernehmen diesen Vertrauensspeicher. Firefox benötigt eine separate Einstellung (security.enterprise_roots.enabled), um den Windows-Vertrauensspeicher zu respektieren.
3. Entfernung: npm run untrust bietet eine saubere Deinstallation.

🎓 Lehrreich: Wie wir es gebaut haben

Dieses Projekt ist ein praktisches Beispiel für Systemprogrammierung mit Node.js. Es geht über typische Webserver hinaus und interagiert auf niedrigerer Ebene mit dem Betriebssystem und dem Netzwerk-Stack.

Architektur

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

Kernkonzepte

1. Das „Dual-Server“-Muster

Das standardmäßige http-Modul von Node.js kann die CONNECT-Methode (für HTTPS-Tunnel) und normalen HTTPS-Datenverkehr nicht einfach auf derselben Serverinstanz verarbeiten.

• Server A (Net/HTTP): Lauscht auf Port 8080. Er behandelt die anfängliche CONNECT-Anfrage. Er fungiert als simpler TCP-Pipe.
• Server B (HTTPS): Er existiert nur im Speicher (oder auf einem zufälligen Port). Er hält den privaten Schlüssel.
• Der Trick: Wenn Server A eine Verbindung erhält, „emittiert“ er den Socket an Server B. Server B denkt, er habe gerade eine neue Verbindung erhalten, und startet den SSL-Handshake. Dies ermöglicht eine nahtlose Entschlüsselung des Datenverkehrs.

2. Prozesszuordnung (Der netstat-Hack)

Woher wissen wir, welche App Datenverkehr sendet? Die TCP-Pakete selbst haben kein „Prozess-ID“-Etikett.

• Ephemere Ports: Jede ausgehende Verbindung verwendet einen zufälligen hochnummerierten Port (z. B. 54321).
• Korrelation: Wir rufen netstat -ano auf, um herauszufinden, welche PID Port 54321 besitzt.
• Optimierung: Dies für jedes Paket zu tun, ist langsam, daher cachen wir die Ergebnisse oder prüfen nur bei Bedarf.

3. Stream-Forking

Wir verwenden Node.js-Streams, um Daten effizient zu verarbeiten. Anstatt zu warten, bis die vollständige 10-MB-Antwort heruntergeladen ist, bevor wir sie anzeigen, „forken“ wir den Stream:

• Pipe 1: Geht an den Client (damit die App weiter funktioniert).
• Pipe 2: Geht an unseren Logger (damit wir sie auf der Festplatte speichern können). Dies geschieht mithilfe von PassThrough-Streams und ermöglicht Echtzeit-Überwachung mit minimaler zusätzlicher Latenz.

Lizenz

GNU GPL v3.0