HTTP Breakout Proxy

Ein leichter HTTP/HTTPS-Intercepting-Proxy und Traffic-Analyse-Tool, geschrieben in Go, mit einer webbasierten Benutzeroberfläche zur Echtzeit-Inspektion, Filterung, Farbmarkierung und Annotation des abgefangenen Datenverkehrs.

Überblick

HTTP Breakout Proxy fungiert sowohl als HTTP- und HTTPS-MITM-Proxy als auch als Live-Visualisierungswerkzeug.
Er erfasst Anfragen und Antworten zwischen zwei Softwarekomponenten und ermöglicht Entwicklern Folgendes:

• Untersuchen von Headern, Körpern und Zeitdetails für jede Anfrage und Antwort.
• Organisieren, Filtern und Persistieren der erfassten Daten.
• Hervorheben von Anfragen basierend auf benutzerdefinierten Farbschemata (Color Rules).
• Dynamisches Anhalten oder Fortsetzen der Aufnahme.
• Anzeige der Anfragezeit als Gantt-Diagramm zur Visualisierung der Leistungsphasen.

Der Proxy enthält eine voll funktionsfähige Benutzeroberfläche, die von jedem modernen Webbrowser aus zugänglich ist, und ermöglicht so sofortige Echtzeitanalysen ohne externe Werkzeuge.

Funktionen

🔍 Erfassung und Inspektion

• Abfangen von sowohl HTTP- als auch HTTPS-Datenverkehr (mit MITM-CA-Unterstützung).
• Anzeige aller Metadaten, Header und Körper von Anfragen und Antworten.
• Unterstützt Kürzung bei sehr großen Körpern.

💾 Persistierung

• Erfassungen und Farbschemata werden in captures.json (oder einer angegebenen Datei) gespeichert.
• Lädt den Zustand beim Start automatisch neu und speichert regelmäßig auf die Festplatte.
• Standard-Farbschemata werden beim ersten Start generiert, falls keine vorhanden sind.

🖥️ Web-Benutzeroberfläche

• Responsive eingebettete Webschnittstelle (vom Proxy selbst bereitgestellt).
• Anzeige der Erfassungen in einer scrollbaren Liste mit farbcodierten Indikatoren.
• Detailbereich zeigt:
  • Header und Körper von Anfrage und Antwort
  • Zeitaufschlüsselungen
  • Bearbeitbare Notizen
  • Gantt-ähnliches Leistungsdiagramm für Verbindungsphasen

🎨 Farbschemata

• Definieren Sie bedingte Farbhervorhebungen für Erfassungen mit einer flexiblen Filtersyntax:
  • Beispiel: status:4 status:5 → hebt HTTP-Fehler hervor
  • Beispiel: url:/api/ → hebt API-Anfragen hervor
  • Beispiel: /\.css$/ → Regex-Übereinstimmung in der URL
• Jedes Schema umfasst:
  • Name, Farbe, Übereinstimmungsausdruck, Priorität und Notiz
• Die höchste Priorität gewinnt.
• Interaktiv über eine modale Oberfläche mit Live-Vorschauen verwaltet.
• Werden über Sitzungen hinweg persistiert.

⏸️ Aufnahmesteuerung

• Die Pause/Resume-Taste ermöglicht es, das Sammeln neuer Erfassungen zu stoppen, ohne den Proxy anzuhalten.
• Nützlich, wenn man sich auf einen festen Datensatz konzentrieren oder ein bestimmtes Verhalten isolieren möchte.

📈 Leistungsvisualisierung

• Jede Erfassung enthält detaillierte Verbindungszeiten:
  • DNS-Auflösung
  • TCP-Verbindungsaufbau
  • TLS-Handshake
  • Serververarbeitung
  • Antwortlesen
• Angezeigt als Gantt-Diagramm im Detailbereich.
• Die Skala rundet automatisch auf die nächste Sekunde für die Lesbarkeit.

🧭 Filtern und Suchen

• Echtzeit-Filterfeld mit Unterstützung für:
  • Feldbasierte Filter (method:GET, status:404, header:Content-Type=application/json)
  • Regex-Ausdrücke (/login/)
  • Kombinierte Begriffe mit UND/ODER-Semantik
• Groß-/Kleinschreibung nicht beachtend und teilweise Übereinstimmung unterstützt.
• Der Filter wird sowohl auf die Erfassungsliste als auch auf die Farbhervorhebung angewendet.
• Suchverlauf wird lokal im Browser gespeichert.

🧹 Verwaltung

• Einzelne Erfassungen löschen oder alle Erfassungen über die Benutzeroberfläche löschen.
• Regeln und Notizen werden zusammen mit den Erfassungen persistiert.

🧩 Exportfunktionen

• Eine Erfassung kopieren als:
  • curl-Befehl (für das Terminal formatiert)
  • python requests-Codeausschnitt (saubere JSON-Darstellung)
• Antwortkörper direkt über die Benutzeroberfläche herunterladen.

Befehlszeilenverwendung

httpbreakout -l 127.0.0.1:8080

Schnellstart

Erstellen (aus dem Quellcode)

git clone https://github.com/jbsouthe/http-breakout-proxy.git
cd http-breakout-proxy
go build -o http-breakout-proxy

Dies erzeugt eine einzelne ausführbare Datei, die den kompilierten Proxy und die eingebetteten UI-Assets enthält.

Ausführen (Standard)

# mit Standardeinstellungen ausführen (Proxy + UI)
./http-breakout-proxy

Standardmäßig bindet die Binärdatei an 127.0.0.1:8080 für den Proxy (und optional die UI – siehe CLI-Flags). Öffnen Sie die UI in einem Browser, um Erfassungen zu inspizieren.

Beispiel: Proxy mit curl ausführen

# eine HTTPS-Anfrage über den Proxy senden (Proxy hört auf 127.0.0.1:8080)
curl -x http://127.0.0.1:8080 https://example.com

Der abgefangene Datenverkehr erscheint in der Web-UI.

Befehlszeilenargumente

Verwenden Sie ./http-breakout-proxy -h, um verfügbare Flags und Nutzungsbeschreibungen aufzulisten.

Web-UI-Überblick

Die Benutzeroberfläche ist für Untersuchungs-Workflows optimiert.

• Obere Symbolleiste: globales Filtereingabefeld (unterstützt Regex und Schlüsselwortpräfixe), Pause/Resume-Aufnahme, Löschen und Filter-Hilfe (öffnet in einem neuen Tab).
• Linkes Panel: chronologische Erfassungsliste (neueste zuerst). Jeder Eintrag zeigt den Erfassungsnamen; standardmäßig ist dies METHODE URL [STATUS], aber ein benutzerdefinierter Name kann zugewiesen werden.
• Rechtes Panel: Details zur ausgewählten Erfassung:
  • Übersicht: Metadaten, Header und Körper (wo anwendbar als formatiertes JSON).
  • Anfrage / Antwort-Tabs: roh formatierte Körper.
  • Raw-Tab: vollständiges Erfassungs-JSON.
• Zeilenaktionen: Kopieren als curl, Kopieren als Python requests, Antwortkörper herunterladen, umbenennen, löschen.

Filtersprache (Kurzreferenz)

• Einfaches Token: Übereinstimmung überall (Methode, URL, Status, Host, Header, Körper).
• Präfixe: method:, status:, host:, url:, body:, req.body:, resp.body:, header:, req.header:, resp.header:.
• Regex-Syntax: /muster/flags (z.B. /bearer\\s+\\S+/i).
• Header-Spezifikation: header:name=value wobei name oder value Regex sein können.

Beispiele:

• method:POST status:2 host:api.example.com
• /token\\s*[:=]\\s*\\S+/i
• req.header:authorization=/bearer/i
• body:/\\"success\\"\\s*:\\s*true/i

HTTPS-Abfangen (MITM)

Wenn der Man-In-The-Middle-Modus aktiviert ist:

1. Der Proxy erzeugt ein RSA-CA-Schlüsselpaar und ein Wurzelzertifikat und speichert sie in -ca (Standard ./ca).
2. Um HTTPS-Datenverkehr zu inspizieren, müssen Sie das generierte CA-Zertifikat (ca.pem oder ähnlich) dem Vertrauensspeicher des Clients (oder Systems) hinzufügen, der die Anfragen stellt. Auf vielen Plattformen sind dafür Administratorrechte erforderlich.
3. Der Proxy führt TLS-Abfangen durch, indem er für jeden vom Client angefragten Hostnamen Blattzertifikate ausstellt, die von der lokalen CA signiert sind.

Sicherheitshinweis: Installieren Sie die CA nur in kontrollierten Umgebungen. Vertrauen Sie dieser CA nicht in Systemen, in denen Sie sensible, nicht zusammenhängende Datenverkehr lesen.

Persistierung

Wenn Persistenz aktiviert ist (über -f oder einen konfigurierten Pfad):

• Erfassungen werden regelmäßig auf die Festplatte geschrieben (z.B. captures.json).
• Beim Start versucht die Anwendung, frühere Erfassungen aus der Persistenzdatei in den speicherinternen Puffer zu laden (unter Beibehaltung der Reihenfolge).
• Umbenennungen und Löschungen werden bei Speichervorgängen mit dem persistenten Speicher synchronisiert; erwägen Sie einen sofortigen Flush für kritische Operationen.

Speicherformat

Erfasste Elemente werden als JSON serialisiert und enthalten die folgenden Felder (nicht abschließend):

• id – eindeutiger Sequenzbezeichner
• time – Zeitstempel (ISO 8601)
• method, url
• request_headers, response_headers
• request_body, response_body – bei Bedarf auf -max-body gekürzt
• response_status, duration_ms
• name – optionales Benutzerlabel
• notes, deleted – Steuermetadaten für SSE-Ereignisse und UI-Zustand

Export- und Wiedergabehilfen

• Kopieren als cURL: erstellt einen shellsicheren curl-Befehl inklusive Header und Körper (lässt Hop-by-Hop-Header weg).
• Kopieren als Python: erzeugt einen kleinen requests-Schnipsel mit url, headers und optionalem data.
• Herunterladen: speichert den Antwortkörper in einer Datei; die Erweiterung wird nach Möglichkeit aus Content-Type abgeleitet.

Design-Überlegungen:

• Hop-by-Hop-Header (z.B. Host, Content-Length, Connection) werden aus generierten Wiedergabebefehlen weggelassen.
• Binäre Antwortkörper (Bilder, PDFs) können mit Binär-Blobs heruntergeladen werden. Wenn Antworten Base64-codiert gespeichert sind, dekodiert der Client vor dem Herunterladen.

API: REST-Endpunkte (für Automatisierung)

• GET /api/captures – Erfassungen auflisten (JSON-Array).
• DELETE /api/captures – alle Erfassungen löschen.
• GET /api/captures/{id} – eine einzelne Erfassung abrufen.
• DELETE /api/captures/{id} – bestimmte Erfassung löschen.
• PATCH /api/captures/{id} – Erfassungsmetadaten aktualisieren; Körperbeispiel: { "name": "Mein Label" }.
• GET /api/pause – gibt { "paused": true|false } zurück.
• POST /api/pause – Pausenstatus setzen; Körperbeispiel: { "paused": true }.
• GET /events – Server-Sent-Events (SSE)-Stream für Live-Erfassungsbenachrichtigungen und Steuerungsereignisse.

Implementierungshinweise (für Entwickler)

• Einbetten der UI: Verwenden Sie //go:embed ui/* und fs.Sub, um statische Dateien bereitzustellen. Dies erzeugt ein einzelnes auslieferbares Artefakt.
• Dekomprimierung: Der Erfassungscode prüft Content-Encoding und versucht, gzip- und deflate-Körper vor der Anzeige zu dekomprimieren. Die ursprünglichen Bytes werden zur Proxy-Transparenz beibehalten.
• Nebenläufigkeit: Der Erfassungsspeicher verwendet internes Locking, um threadsichere Anhänge-/List-/Get-/Update-Operationen zu gewährleisten. Wo möglich, werden atomare boolesche Werte für Umschaltflags (z.B. Pause/Resume) verwendet.
• SSE: Ein leichtgewichtiger Broker sendet Erfassungshinzufügungen, -löschungen, -umbenennungen und Steuerungsereignisse an verbundene UI-Clients.
• Pufferung: Erfassungskörper werden mit io.LimitReader gelesen, um Kürzungen zu erkennen und die Speichernutzung zu schützen.

Paketierung & Verteilung

Empfohlenes Vertriebsmodell:

1. Statische, optimierte Binärdateien für Zielplattformen erstellen (CGO_ENABLED=0, -trimpath, -ldflags "-s -w").
2. Archive erstellen (.tar.gz für Unix, .zip für Windows) und README.md sowie LICENSE beifügen.
3. SHA-256-Prüfsummen bereitstellen und Artefakte an GitHub-Releases anhängen.
4. Optional goreleaser verwenden, um plattformübergreifende Builds und Release-Artefakte zu automatisieren.

Beispiel-Build-Befehle:

# Linux x86_64
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dist/http-breakout-proxy-linux-amd64 .

# macOS (arm64)
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dist/http-breakout-proxy-darwin-arm64 .

Ausführen als Dienst

systemd-Unit (Linux-Beispiel)

[Unit]
Description=HTTP Breakout Proxy
After=network.target

[Service]
ExecStart=/opt/http-breakout-proxy/http-breakout-proxy -l 0.0.0.0:8080
Restart=on-failure
User=proxy
Group=proxy

[Install]
WantedBy=multi-user.target

launchd (macOS-Benutzeragent)

Erstellen Sie ein plist in ~/Library/LaunchAgents und laden Sie es mit launchctl.

Fehlerbehebung

• Erfasster Körper erscheint als binäres Kauderwelsch
  Der Körper ist komprimiert (z.B. gzip). Stellen Sie sicher, dass Sie einen Build ausführen, der automatische Dekomprimierung beinhaltet; die UI zeigt dekomprimiertes JSON/Text an, wenn verfügbar.

• HTTPS-Datenverkehr wird nicht angezeigt / Verbindungsfehler
  Der Client vertraut der generierten CA nicht. Installieren Sie ca/ca.pem im Client-/System-Vertrauensspeicher und markieren Sie es als vertrauenswürdig für TLS-Abfangen.

• UI zeigt veraltete Auswahl nach dem Löschen von Erfassungen
  Aktualisieren Sie auf einen Client, der selectedId bei cleared-SSE-Ereignissen löscht, oder rufen Sie den Endpunkt GET /api/captures auf, um den Zustand zu aktualisieren.

• 405 bei DELETE /api/captures
  Stellen Sie sicher, dass der Server-Handler DELETE für /api/captures akzeptiert und Sie keinen abschließenden Schrägstrich-Konflikt haben.

Sicherheit & Datenschutz

Dieses Werkzeug führt TLS-Abfangen durch, wenn MITM aktiviert ist. Verwenden Sie es nur in kontrollierten Umgebungen, in denen Sie ausdrücklich zur Datenverkehrsinspektion berechtigt sind. Die generierte CA ist mächtig: Behandeln Sie ihren privaten Schlüssel mit derselben Vertraulichkeit wie jeden anderen Root-CA-Privatschlüssel. Installieren Sie die CA nicht in gemeinsam genutzten oder Produktions-Vertrauensspeichern.

Mitwirken

Beiträge sind willkommen. Bitte eröffnen Sie Issues für Fehler oder Funktionsanfragen. Für Codebeiträge:

1. Forken Sie das Repository.
2. Erstellen Sie einen Feature-Branch.
3. Führen Sie, wo anwendbar, Unit-Tests und Linter aus.
4. Reichen Sie einen Pull-Request mit einer Beschreibung der Änderung, der Begründung und eventuellen Rückwärtskompatibilitätsbedenken ein.

Lizenz

Dieses Projekt wird unter der MIT-Lizenz vertrieben. Siehe LICENSE für Details.

Namensnennung & Kontakt

Autor: John Southerland (GitHub: jbsouthe)
Projekt: http-breakout-proxy – vorgesehen zum Debuggen, Entwickeln und Lernen über HTTP-Verhalten.