Hinweis und Anforderungen für verantwortungsvollen Einsatz

Wichtig: Diese Anwendung führt aktives Man-in-the-Middle (MITM) Abfangen durch, einschließlich der Erstellung und Verwendung von TLS-Zertifikaten zur Entschlüsselung von HTTPS-Verkehr. Abhängig von Ihrer Rechtsordnung und Netzwerkumgebung kann das Abfangen von Verkehr ohne klare vorherige Zustimmung aller betroffenen Benutzer illegal sein und gegen Datenschutz-, Arbeitsplatzrichtlinien oder gesetzliche Vorschriften verstoßen.

Bevor Sie diese Software in einer anderen Umgebung als Ihrem eigenen lokalen Rechner verwenden:

1. Holen Sie ausdrückliche Zustimmung ein

Alle Benutzer eines Netzwerks, in dem dieser Proxy Verkehr abfangen könnte, müssen klar informiert werden, dass HTTP(S)-Abfangen und -Inspektion stattfinden werden. Die Zustimmung sollte ausdrücklich und idealerweise dokumentiert sein.

2. Nur in autorisierten Netzwerken verwenden

Führen Sie diese Software nicht in Netzwerken aus, die Sie weder besitzen noch verwalten oder für die Sie keine ausdrückliche Berechtigung zum Testen oder Überwachen haben.

3. Datenschutz- und Datenschutzgesetze respektieren

In vielen Regionen gelten strenge Gesetze zum Abfangen, Protokollieren und Speichern von Benutzerdaten (z. B. DSGVO, CCPA, Abhörgesetze). Sie sind verantwortlich dafür, dass Ihre Nutzung allen geltenden Vorschriften entspricht.

4. Sichern Sie den generierten CA-Schlüssel

Der generierte private CA-Schlüssel (normalerweise ca-key.pem) erlaubt es dem Inhaber, jede Domäne zu imitieren, für Benutzer, die dem entsprechenden Zertifikat vertrauen.

• Bewahren Sie ihn sicher auf.
• Geben Sie ihn niemals weiter.
• Rotieren/löschen Sie ihn, wenn er kompromittiert wurde.

5. Nur für Tests und Debugging verwenden

Dieser Proxy ist für Entwicklung, Debugging, kontrollierte Tests oder Bildungszwecke konzipiert – nicht für verdeckte Überwachung oder unbefugte Überwachung.

Durch die Nutzung dieser Software erkennen Sie an und übernehmen die volle Verantwortung dafür, dass Ihre Nutzung rechtmäßig, ethisch und allen betroffenen Benutzern ordnungsgemäß mitgeteilt wird.

Funktionen

• HTTP- und HTTPS-Proxying über Standard-Proxy-Semantik
• MITM-Abfangen für HTTPS mit pro-Host-Zertifikaten
• HTTP/1.1- und HTTP/2-Downstream-Verarbeitung mit ALPN-Aushandlung
• WebSocket-Tunneling: ws:// und wss://
• Flexibler Festplatten-Cache für GET-Antworten
  • Ein-/Ausschluss nach Domäne und nach Dateierweiterung
  • TTL-basierter Ablauf
  • Cache-Treffer-Indikatoren in Antworten (Via und ein benutzerdefinierter x--uid-Header)
• Live-Konfigurations-Neuladen: optionales Pollen von config.json und heißes Anwenden von Änderungen
• Lokale Admin-API/Dashboard mit Bearer-Token-Authentifizierung, Unterstützung für Nur-Lese-Token, Admin-Benutzerrollen-Datensätze, Health-/Version-/Audit-Endpunkte, Live-Traffic-SSE und CA-Metadaten/Download
• Laufzeit-Blocking-Richtlinie für Ports, Domänen und IP/CIDR-Bereiche
• Optionaler Bedrohungsscanner mit heuristischen und KI-gestützten Bewertungen, Schwärzung, Bewertungs-Caching, Quarantäne-Metadaten und Dashboard-Endpunkten
• Ausführliche und pro-Anfrage-Protokollierungssteuerung
• Sinnvolle Standardeinstellungen mit optionaler JSON-Konfiguration

Installation

Voraussetzungen:

• Go 1.25 oder neuer

Klonen und bauen: ```bash git clone https://github.com/Welfordian/mitm-proxy.git cd mitm-proxy go build ./

Beim ersten Start wird eine lokale CA erstellt und in ca-cert.pem und ca-key.pem gespeichert.

2. Konfigurieren Sie Ihren Browser oder curl, um den Proxy unter http://localhost:8080 zu verwenden.

3. Vertrauen Sie dem generierten CA-Zertifikat (ca-cert.pem) in Ihrem Betriebssystem/Browser, um HTTPS-Abfangen zu ermöglichen. Siehe Vertrauen in die lokale CA.

4. Besuchen Sie eine HTTPS-Website über den Proxy und beobachten Sie die Logs. Verwenden Sie den ausführlichen Modus für mehr Details: ```bash ./mitm-proxy --verbose

Anmerkungen:

• Falls ca_cert_path/ca_key_path nicht angegeben werden, schreibt der Proxy ein generiertes CA-Zertifikat nach ca-cert.pem / ca-key.pem.
• excluded_domains unterstützt Platzhalter (siehe IsDomainExcluded in internal/config).
• admin_addr standardmäßig auf localhost. Wenn admin_token leer ist, wird ein pro-Lauf gültiger Token generiert und beim Start ausgegeben.
• admin_read_token kann für schreibgeschützte Dashboard-/API-Clients gesetzt werden.
• traffic_capture.store_bodies ist standardmäßig deaktiviert; wenn aktiviert, sind Body-Beispiele standardmäßig größenbegrenzt und geschwärzt.
• traffic_capture.store_headers und traffic_capture.store_cookies steuern, ob erfasste Metadaten persistent gespeichert werden. redacted_headers schwärzt gesamte Header-Werte, während redacted_cookies vor der Speicherung passende einzelne Cookie- und Set-Cookie-Namen schwärzt.
• proxy_auth aktiviert die Basic-Client-Proxy-Authentifizierung, die auf SQLite-verwalteten Benutzern und geordneten ACL-Regeln basiert.
• blocked_domains unterstützt exakte Namen und Platzhaltermuster wie *.example.com; blocked_ips unterstützt einzelne IPs und CIDR-Bereiche.
• cache.include_domains und cache.exclude_domains schließen sich gegenseitig aus, ebenso wie include_extensions und exclude_extensions.
• Der Watcher überwacht nur die mit --config übergebene Datei oder die Standarddatei ./config.json und wendet Änderungen heiß über Proxy.SetConfig an.

Admin-Dashboard

Der Admin-Server stellt das Dashboard standardmäßig unter http://127.0.0.1:9090/admin/ bereit. API-Routen erfordern Authorization: Bearer <token>; für die lokale Browsernutzung speichert /admin/?token=<token> den Token im lokalen Speicher des Browsers.

Die anfängliche Dashboard-/API-Abdeckung umfasst:

• GET /api/health und GET /api/version
• GET /api/audit
• GET /api/traffic, GET /api/traffic/stats, GET /api/traffic/{id}, GET /api/traffic/stream, DELETE /api/traffic und POST /api/traffic/{id}/replay
• GET /api/traffic/export?format=har für den HAR-Export
• GET/POST/PUT/DELETE /api/repeater/cases und POST /api/repeater/cases/{id}/send für gespeicherte bearbeitbare Wiedergabefälle
• GET/POST/PUT/DELETE /api/scopes plus Scope-Zuweisungsendpunkte für Traffic und Repeater-Fälle
• GET/POST/DELETE /api/pentest/maps plus Endpunkt-Klonaktionen für passive Zielkarten
• GET/POST/PUT/DELETE /api/proxy-auth/users und /api/proxy-acl/rules plus POST /api/proxy-acl/test für die Proxy-Client-Zugriffssteuerung
• POST /api/ai/traffic/{id}/explain, POST /api/ai/traffic/{id}/suggest-tests, POST /api/ai/repeater/cases/{id}/suggest-tests, POST /api/ai/repeater/cases/{id}/compare-runs und GET/POST/DELETE /api/ai/notes für AI-Research-Copilot-Notizen
• GET /api/certificates/ca, GET /api/certificates/ca/download, POST /api/certificates/ca/rotate, POST /api/certificates/ca/import und GET /api/certificates/leaf
• GET/POST/DELETE Blockregeln für Ports, Domains und IPs
• GET /api/deployments/current, POST /api/deployments/current/reload, GET /api/logs, GET /api/cache mit zwischengespeicherten Einträgen und Treffer-/Fehltrefferzahlen, POST /api/cache/purge und GET/PUT /api/settings
• GET /api/threats/events, GET /api/threats/stream, GET /api/threats/config, POST /api/threats/test und Threat-Override-Endpunkte
• GET /metrics für Prometheus-kompatible Prozess-/Admin-/Threat-Zähler

Das Dashboard enthält eine Bestätigung zur verantwortungsvollen Nutzung beim ersten Start. Der private CA-Schlüssel wird niemals über die Admin-API offengelegt. Der Dashboard-Zustand wird standardmäßig in SQLite unter dashboard.db gespeichert. Über das Dashboard geänderte Einstellungen werden sofort angewendet und in die konfigurierte JSON-Datei zurückgeschrieben, bzw. in config.json, wenn der Proxy mit den Standardeinstellungen gestartet wurde.

Das Admin-Frontend ist eine Vite/React-App in internal/admin/ui. Ihr Produktionsbuild wird nach internal/admin/ui/dist ausgegeben und in das Go-Binary eingebettet. So aktualisieren Sie die Dashboard-Assets:```bash cd internal/admin/ui npm install npm run build

Only http:// and https:// upstream proxy URLs are supported in v1. If Basic auth is needed, set username and provide the password through the named environment variable; credentials embedded in the URL are rejected and are never shown in dashboard settings. If the upstream proxy is enabled but unavailable, affected requests fail visibly instead of silently falling back to direct connections.

Proxy Access Control

The dashboard's Access Control view manages client proxy users and ordered allow/deny ACL rules. Proxy users are stored in SQLite with bcrypt password hashes; plaintext passwords are accepted only when creating or resetting a user and are never returned by the API.

Enable Basic proxy authentication through proxy_auth in config.json or the Settings view. When enabled, clients must send Proxy-Authorization: Basic ... unless loopback clients are exempt. ACL rules are evaluated by priority and can match username, source IP/CIDR, host or wildcard host, port or port range, method, and research scope. Empty matcher lists mean "any".

Proxy-Authorization is stripped before forwarding, upstream chaining, traffic capture, cache lookup, threat scanning, and Repeater cloning. Captured traffic includes proxy_user attribution when available, and the Traffic search box can match proxy usernames.

Research Repeater

The dashboard's Repeater view lets security researchers clone captured HTTP traffic into saved editable cases. A case stores the method, URL, headers, body sample, timeout, and optional source traffic flow ID. Each send stores a run with status, duration, response headers, a capped response body sample, and any upstream error.

Captured request bodies are only prefilled when traffic_capture.store_bodies was enabled at capture time. If body redaction was enabled, the repeater receives the redacted sample; uncaptured bodies remain empty and can be edited manually.

The legacy POST /api/traffic/{id}/replay endpoint remains available for one-shot replay, while the repeater is intended for repeatable request mutation and response comparison.

Pentest Toolkit

The dashboard's Pentest Toolkit view builds passive target maps from captured traffic. Rebuilding a map analyzes only stored traffic for the selected scope, groups endpoints by normalized path, extracts query/body/cookie/header parameters, records reflected and interesting parameters, and adds passive hints such as missing security headers, cookie attribute gaps, permissive CORS, and verbose errors.

Pentest maps are persisted in SQLite and can be deleted independently. The toolkit never sends requests, crawls, fuzzes, or mutates targets; endpoint evidence can be cloned into Repeater for manual testing.

Research Scopes

The dashboard's Scopes view lets researchers define named target boundaries with host, URL substring, and optional method patterns. Enabled scopes are matched automatically when traffic is captured; matching flows, cloned Repeater cases, and threat scanner events receive a single scope_id.

The global scope selector filters Traffic, Repeater, and Threat Scanner views across all traffic, a selected enabled scope, or out-of-scope items. Deleting a scope clears related scope_id values without deleting captured traffic, Repeater cases, runs, or threat data.

Scope filters are available on GET /api/traffic, GET /api/repeater/cases, and GET /api/threats/events with scope_id=<id> or scope_id=__out_of_scope__. Add include_out_of_scope=true to include unscoped rows beside a selected scope.

AI Research Copilot

The dashboard's AI Copilot view stores AI-generated research notes linked to Traffic, Repeater cases, runs, scopes, or threat events. Traffic detail can ask the copilot to explain a request or suggest next manual tests; Repeater can suggest tests for a saved case or compare the latest two runs.

The copilot is advisory only. It never sends traffic, edits Repeater cases, changes scopes, changes settings, or purges data. Out-of-scope traffic can be explained, but active testing suggestions are intentionally withheld.

Enable it through ai_copilot in config.json or the Settings view:```json { "ai_copilot": { "enabled": true, "provider": "openai", "model": "gpt-5.4-nano", "timeout_ms": 10000, "max_body_bytes": 32768, "redact_before_ai": true, "openai_api_key_env": "OPENAI_API_KEY" } }

Auf macOS/Linux:```bash export OPENAI_API_KEY="sk-..."

3. Starten Sie den Proxy:```bash go run . --config ./config.json

WebSocket-Hinweise:

• ws:// wird vom HTTP-Handler via Verbindungs-Hijacking behandelt.
• wss:// wird auf dem HTTP/1.1 MITM-Pfad erkannt und nach dem initialen Handshake Ende‑zu‑Ende getunnelt.

Caching

Der Cache ist dateibasiert und berücksichtigt nur HTTP-GET-Anfragen, wenn er aktiviert ist. Die Auswahl wird gesteuert durch:

• cache.include_domains / cache.exclude_domains (Host-Zuordnung)
• cache.include_extensions / cache.exclude_extensions (URL-Pfaderweiterung, Groß-/Kleinschreibung nicht beachtet)
• cache.ttl (Sekunden)

Bei einem Cache-Treffer enthalten die Antworten:

• Via: <proxy_name>
• x--uid: eine stabile Kennung, die aus dem Cache-Datei-Hash abgeleitet wird

Das Cache-Verzeichnis wird beim Start und bei Konfigurationsänderungen sichergestellt. Wenn kein Verzeichnis festgelegt ist, wird standardmäßig ./cache verwendet.

Build und Run ```bash

go build ./ ./mitm-proxy --config ./config.json