Traffic Inspector (Deutsch)

§1 Überblick

Was Traffic Inspector einzigartig macht

Funktion	mitmweb	Charles	Fiddler	OmniRoute Traffic Inspector
Webbasiert	✓	✗	✗	✓
Open Source	✓	✗	teilweise	✓
Agenten-fähig (erkennt, ob die Anfrage von Antigravity/Copilot/etc. stammt)	✗	✗	✗	✓
LLM-fähig (analysiert OpenAI-/Anthropic-/Gemini-Struktur, Tokens und Modell)	✗	✗	✗	✓
Modellzuordnung sichtbar (gemini-3-flash → claude-sonnet-4.7)	✗	✗	✗	✓
Getrennte Proxy-/Upstream-Latenz	teilweise	✗	✗	✓
In OmniRoute integriert: Routing, Fallback und Kosten	✗	✗	✗	✓
Systemweites Proxy-Debugging (jede App auf dem Rechner)	✓	✓	✓	✓
Benutzerdefinierte Host-Erfassung (DNS-Umleitung pro Host)	✓	✓	✓	✓
HTTP_PROXY-Umgebungsmodus	✓	✓	✓	✓
Konversationsansicht (mehrere Dialogrunden, tool_use/tool_result)	✗	✗	✗	✓
SSE-Stream-Zusammenführung (Rekonstruktion aus Delta-Ereignissen)	✗	✗	✗	✓
Sitzungsaufzeichnung (benannt, als .har/.jsonl exportierbar)	✗	✓	✓	✓

Architektur in einem Absatz

Der TrafficBuffer (src/mitm/inspector/buffer.ts) ist ein gemeinsam genutzter In-Memory-Ringpuffer (standardmäßig 1000 Einträge, konfigurierbar über INSPECTOR_BUFFER_SIZE). Alle Erfassungsquellen schreiben über push() in ihn. Der Puffer klassifiziert jeden Eintrag mithilfe von kindDetector.ts (bestimmt, ob es sich um eine LLM-Anfrage handelt), berechnet einen contextKey (SHA-256-Fingerabdruck des System-Prompts) und überträgt ihn über globalTrafficBuffer.subscribe() an alle WebSocket-Abonnenten. Das Dashboard stellt über GET /api/tools/traffic-inspector/ws eine Verbindung her und empfängt beim Verbindungsaufbau einen Snapshot, gefolgt von new-/update-/clear-Ereignissen.

---

§2 Erfassungsmodi

Traffic Inspector unterstützt 5 gleichzeitige Erfassungsquellen. Jede kann unabhängig ein- und ausgeschaltet werden. Das Feld source jeder InterceptedRequest (src/mitm/inspector/types.ts) enthält einen der Werte "agent-bridge", "custom-host", "http-proxy", "system-proxy" oder "tproxy".

Modus 1 — AgentBridge (standardmäßig immer aktiviert)

Quelle: AgentBridge-Handler (src/mitm/handlers/base.ts) Mechanismus: Jeder Aufruf von intercept() in MitmHandlerBase ruft vor der Weiterleitung hookBufferStart() und nach Abschluss hookBufferUpdate() auf. Keine zusätzliche Konfiguration — funktioniert, sobald AgentBridge ausgeführt wird. Reichweite: Die 9 in AgentBridge konfigurierten IDE-Agenten Hinweis: Feld source in InterceptedRequest = "agent-bridge"

Modus 2 — Benutzerdefinierte Hosts (DNS-Umleitung)

Quelle: Benutzerdefinierte Hostliste (Tabelle inspector_custom_hosts) Mechanismus: Beim Hinzufügen eines Hosts über die Benutzeroberfläche wird 127.0.0.1 <host> zu /etc/hosts hinzugefügt (erfordert sudo). Der vorhandene AgentBridge-MITM-Server (Port 443) erzeugt dynamisch ein SNI-Zertifikat für den neuen Host. Reichweite: Jede Anwendung, die den hinzugefügten Host verwendet — keine Änderung der Anwendungskonfiguration erforderlich Hinweis: source = "custom-host"

Beispiele für Anwendungsfälle:

• api.openai.com aus Python-Skripten überwachen
• my-internal-llm.company.com debuggen
• Datenverkehr von Mobilgeräten im selben Netzwerk erfassen (mittels ARP-Spoofing — fortgeschritten)

Modus 3 — HTTP_PROXY-Listener (Port 8080)

Quelle: Anwendungen, die die Umgebungsvariablen HTTP_PROXY/HTTPS_PROXY verwenden Mechanismus: Sekundärer Listener auf Port 8080 (src/mitm/inspector/httpProxyServer.ts), der als standardmäßiger expliziter HTTP/HTTPS-Proxy fungiert. Akzeptiert CONNECT-Tunnel (HTTPS) und direkte HTTP-Anfragen. Reichweite: Jede Anwendung, die die Umgebungsvariable HTTP_PROXY berücksichtigt — keine DNS-Änderung, kein sudo Hinweis: source = "http-proxy"

# Schnelle Erfassung für einen einzelnen Befehl:
HTTPS_PROXY=http://127.0.0.1:8080 curl https://api.openai.com/v1/models

# Dauerhafte Erfassung in einer Shell-Sitzung:
export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080

TLS-Einschränkung: HTTPS-CONNECT-Tunnel werden standardmäßig nur als Metadaten erfasst (Host, Port, Timing) — der TLS-Inhalt wird nicht entschlüsselt. Aktivieren Sie den Schalter „HTTPS im Proxy-Modus entschlüsseln“ (Opt-in; das AgentBridge-Zertifikat muss als vertrauenswürdig eingestuft sein), um den vollständigen Inhalt zu untersuchen.

Portkonflikt: Wenn Port 8080 bereits verwendet wird, gibt AgentBridge den Statuscode 409 mit einem strukturierten Fehler zurück. Ändern Sie den Port über die Umgebungsvariable INSPECTOR_HTTP_PROXY_PORT.

Modus 4 — Systemweiter Proxy (fortgeschritten, Opt-in)

Quelle: Proxy-Einstellungen des Betriebssystems (gelten für alle Anwendungen auf dem Rechner) Mechanismus: Verwendet Betriebssystem-APIs, um den gesamten HTTP/HTTPS-Datenverkehr durch den HTTP_PROXY-Listener umzuleiten:

• macOS: networksetup -setwebproxy / -setsecurewebproxy
• Linux: gsettings set org.gnome.system.proxy + /etc/environment
• Windows: netsh winhttp set proxy 127.0.0.1:8080 Reichweite: Jede Anwendung auf dem Rechner, die die systemweiten Proxy-Einstellungen berücksichtigt Hinweis: source = "system-proxy"

Sicherheitsmechanismen:

• Timer zur automatischen Deaktivierung (standardmäßig 30 Minuten, konfigurierbar über INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES)
• Der vorherige Zustand des System-Proxys wird in der Datenbank gespeichert und beim Zurücksetzen wiederhergestellt
• Das Dashboard zeigt die Aufforderung „System-Proxy wird zurückgesetzt“ an, wenn der Benutzer bei aktivem Proxy die Seite verlässt
• Die Benutzeroberfläche zeigt das Badge ⚠ Fortgeschritten und ein ausdrückliches Bestätigungs-Kontrollkästchen an

Modus 5 — Transparente TPROXY-Entschlüsselung (Linux, root, Opt-in)

Quelle: Kernel-TPROXY + richtlinienbasiertes Routing (src/mitm/tproxy/) Mechanismus: Markiert neue lokale ausgehende TCP-Verbindungen zu einem Zielport (standardmäßig 443) in mangle OUTPUT; eine ip rule leitet die markierten Pakete an die lokale Zustellung um, und das TPROXY-Ziel von mangle PREROUTING übergibt sie an einen transparenten (IP_TRANSPARENT) Listener (standardmäßig Port 8443). Der Listener terminiert TLS mit einem Leaf-Zertifikat, das von einer dynamischen CA bei Bedarf für jeden SNI-Hostnamen ausgestellt wird, erfasst den entschlüsselten Austausch und leitet die Anfrage erneut verschlüsselt an das ursprüngliche Ziel weiter. Reichweite: Beliebige Zielhosts auf dem Zielport — kein Spoofing von /etc/hosts, keine HTTP_PROXY-Umgebungsvariable und keine Änderung des systemweiten Proxys. Der abgefangene Prozess benötigt keine Konfigurationsänderung, muss jedoch der dynamischen CA vertrauen. Hinweis: source = "tproxy"

Anforderungen: Nur Linux (IP_TRANSPARENT ist Linux-spezifisch), die Fähigkeit CAP_NET_ADMIN (root) und ein natives N-API-Addon, das mit einer C-Toolchain gebaut werden muss (npm run build:native:tproxy). Wenn diese Voraussetzungen nicht erfüllt sind, ist der Schalter im Dashboard deaktiviert und zeigt den Tooltip „Die TPROXY-Entschlüsselung erfordert Linux + root + das native Addon“ an. Die Firewall-Regeln werden transaktional angewendet bzw. zurückgesetzt (ein Absturz hinterlässt niemals eine mangle-Regel) und beim Neustart entfernt. Ein SO_MARK-basierter Schleifenschutz verhindert, dass die eigene erneut verschlüsselte Weiterleitung des Proxys erneut abgefangen wird.

Dies ist ein umfangreiches Subsystem mit einem eigenen Betriebshandbuch — siehe docs/security/MITM-TPROXY-DECRYPT.md (git; nicht in /docs kompiliert) für das vollständige Firewall-Rezept, die dynamische CA pro SNI samt Trust-Store-Installationsprogramm, die ausschließlich lokale Route, Details zum Schleifenschutz und das Konfigurationsschema. Der Schalter wird über GET / POST / DELETE /api/tools/agent-bridge/tproxy gesteuert (Hinweis: Die Route befindet sich unter dem AgentBridge-Präfix, nicht unter dem Traffic-Inspector-Präfix).

Vergleich der Erfassungsmodi

Modus	Einrichtung	Sudo?	Reichweite	Hinweise
1. AgentBridge	Automatisch	Einmalig (Zertifikat+hosts)	9 IDE-Agenten	Standardmäßig aktiviert
2. Custom Hosts	Eingabe pro Host	Ja (hosts-Datei)	Jede App, die diesen Host verwendet	In der DB gespeichert
3. HTTP_PROXY	export HTTPS_PROXY=...	Nein	Apps, die Umgebungsvariablen beachten	Port 8080, standardmäßig keine TLS-Entschlüsselung
4. Systemweit	Umschalten + bestätigen	Ja	Alle Apps auf dem Rechner	Automatische Deaktivierung nach 30 Minuten
5. TPROXY decrypt	Umschalten (Linux + natives Add-on)	Ja (root + CA-Installation)	Jeder Host am Zielport	Entschlüsselt beliebige Hosts; standardmäßig deaktiviert – siehe docs/security/MITM-TPROXY-DECRYPT.md (git; nicht in /docs kompiliert)

---

§3 Benutzeroberfläche

3.1 Layout

┌─ Traffic Inspector ─────────────────────────────────────────────────────┐
│ ┌─ Symbolleiste für Erfassungsquellen ─────────────────────────────┐   │
│ │ [✓ AgentBridge]  [✓ Eigene Hosts (3)]  [○ HTTP_PROXY]  [○ System]│   │
│ └─────────────────────────────────────────────────────────────────────┘  │
│ ┌─ Filter-/Steuerleiste ───────────────────────────────────────────┐   │
│ │ Profil: (●) Nur LLM  (○) Benutzerdef.  (○) Alle                  │   │
│ │ [⎉ Pause] [🗑 Leeren] [⬇ .har] [● REC Sitzung]  ● live 482/1k  │   │
│ └─────────────────────────────────────────────────────────────────────┘  │
├══◀▶══════════════════════════════╬══════════════════════════════════════╤╡
│ ANFRAGELISTE (Größe änderbar)    ║ DETAILBEREICH                        ▲ │
│ ────────────────────────────── │ ║ [Konversation][Header][Anfrage]      │ │
│ ▎ 14:32 POST 200 12k AG openai ║ [Antwort][Timing][LLM][Statistik]    │ │
│ ▎ 14:31 POST 200 8k  CP openai ║                                     ▼ │
│ ▎ 14:31 POST 503 ⚠   KR ...   ║                                       │
│ ▎ 14:30 GET  200 3k  🌐 eigener ║                                      │
└══════════════════════════════════╝══════════════════════════════════════╝

3.2 Anfrageliste (linker Bereich)

• Virtualisiert (useVirtualList + ResizeObserver): verarbeitet 1000 Elemente ohne Einfrieren
• Automatisches Scrollen mit Umschalter zum Pausieren während der Untersuchung
• Farbcodierter Status: Grün (2xx), Gelb (3xx), Rot (4xx/5xx), Grau (laufend)
• Agenten-Emoji: 🔵 Antigravity, 🟢 Copilot, 🟠 Kiro, 🟣 Codex, 🔷 Cursor, 🟤 Zed, 🟡 Claude Code, ⚫ Open Code, 🌐 eigener Host
• Kontextfarbleiste: 1 px breiter linker Rahmen, eingefärbt anhand von contextKey (SHA-256 des System-Prompts) — gruppiert zusammengehörige Konversationen visuell
• Verzögert geladener Body: Nur der Body der ausgewählten Anfrage wird in den Detailregisterkarten materialisiert (vermeidet das Rendern von 1000 × 1 MB großen Bodys)

3.3 Detailbereich — 7 Registerkarten

Registerkarte	Inhalt	Hinweise
Konversation	Mehrstufige Chatblasen (system/user/assistant + tool_use/tool_result)	Aus beliebigen Anbieterformaten normalisiert; wird nur bei detectedKind === "llm" angezeigt
Header	Tabellen mit Anfrage- und Antwort-Headern	Vertrauliche Header (Authorization, Cookie, api-key) sind standardmäßig maskiert; Umschalter „Geheimnisse anzeigen“
Anfrage	Roher Body, JSON-Baumansicht, Badge für das Modellfeld	Formatiertes JSON oder Rohtext
Antwort	Roher Body oder SSE-Ereignisliste; Umschalter „Roh ↔ Zusammengeführt“	Der SSE-Merger rekonstruiert die endgültige Nachricht aus Delta-Ereignissen
Timing	Wasserfalldiagramm: Proxy-Overhead gegenüber Upstream-Latenz	Gesamtzeit, TTFB und Größe
LLM-Details	Anbieter, Modell, Nachrichtenanzahl, Ein-/Ausgabe-Tokens, Kostenschätzung, zugeordnetes Ziel	Wird nur für LLM-Anfragen angezeigt
Statistik	Recharts: Latenzzeitachse, Token-Balkendiagramm, Streudiagramm der Tool-Aufrufe	Wird nur angezeigt, wenn eine aufgezeichnete Sitzung geladen ist

3.4 Steuerelemente der Symbolleiste

Steuerelement	Aktion
⎉ Pause	Stoppt das Rendern neuer Anfragen; das Badge „X neu“ zählt weiter hoch
🗑 Leeren	Leert die Liste der Benutzeroberfläche (der Serverpuffer bleibt unverändert)
⬇ .har exportieren	Lädt die aktuell gefilterte Liste als HAR-Datei herunter
● Sitzung aufzeichnen	Startet eine benannte Aufzeichnungssitzung
Profilauswahl	Nur LLM / Eigene Hosts / Alle
Hostfilter	Teilzeichenfolgenübereinstimmung im Feld host
Agentenfilter	Dropdown-Menü: Alle / nach Agent
Statusfilter	Alle / 2xx / 3xx / 4xx / 5xx / Fehler
Quellenfilter	Alle / agent-bridge / custom-host / http-proxy / system-proxy / tproxy
Live-Filter	Zeigt nur laufende (offene) Anfragen an — Umschalter liveOnly (siehe §4.6)

3.5 Größenveränderbare Bereiche

• Liste und Detailbereich sind durch einen Ziehgriff getrennt
• Listenbreite: mindestens 280 px, maximal 720 px, gespeichert in localStorage (inspector.listWidth)
• Auf eine 48 px breite Leiste reduzierbar (nur Symbole); durch Klicken auf eine Zeile in der Leiste wird sie erweitert

---

§4 LLM-spezifische Funktionen

4.1 Typ-Erkennung (src/mitm/inspector/kindDetector.ts)

Klassifiziert jede Anfrage anhand von 4 Signalen als "llm", "app" oder "unknown":

1. Host-Registry — ca. 18 bekannte Hostnamen von LLM-APIs (OpenAI, Anthropic, Gemini, Groq, Mistral, Together, Fireworks, Cohere, Perplexity, Hugging Face, OpenRouter, xAI, Moonshot usw.)
2. Pfadmuster — /v1/chat/completions, /v1/messages, /generateContent, /v1/responses usw.
3. Body-Struktur — erkennt die Felder messages[] (OpenAI/Claude), contents[] (Gemini), prompt und input
4. User-Agent-Hinweise — codex, claude, gemini, antigravity, kiro, copilot, cursor in der UA-Zeichenfolge

Benutzerdefinierte Hosts, die über Modus 2 hinzugefügt werden, übernehmen ihren kind aus der Formulareingabe (standardmäßig "custom").

4.2 SSE-Zusammenführung (src/mitm/inspector/sseMerger.ts)

Unabhängige Clean-Room-Implementierung. Das Parsen von Ereignissen folgt dem WHATWG-Algorithmus für Server-Sent Events, während die Rekonstruktion den öffentlichen Streaming-Schemata von OpenAI, Anthropic und Gemini folgt.

Rekonstruiert die endgültige Assistentennachricht aus unverarbeiteten SSE-Delta-Ereignissen:

• Anthropic: akkumuliert content_block_delta nach Index; verarbeitet text_delta, input_json_delta (Tool-Aufrufe) und thinking_delta
• OpenAI: akkumuliert Auswahlmöglichkeiten/Tool-Aufrufe von Chat Completions sowie Ausgabeelemente der Responses API nach Index
• Gemini: akkumuliert candidates[i].content.parts
• Unbekannt: gibt unverarbeitete Ereignisse unverändert zurück

Der Tab „Antwort“ zeigt einen Umschalter: „Unverarbeitete Ereignisse ↔ Zusammengeführt“.

4.3 Konversationsnormalisierung (src/mitm/inspector/conversationNormalizer.ts)

Unabhängige Clean-Room-Implementierung. Die Normalisierung wird durch lokale Black-Box- Verträge und die öffentlichen Nachrichtenschemata von OpenAI, Anthropic und Gemini definiert; es wird kein Quellcode einer vorgelagerten Implementierung verwendet.

Konvertiert die Nachrichtenformate von OpenAI, Anthropic und Gemini vor dem Rendern in eine einheitliche NormalizedConversation:

interface NormalizedConversation {
  request: NormalizedTurn[]; // Nachrichten / Inhalte / Prompt aus dem Anfrage-Body
  response: NormalizedTurn[]; // Assistentenantwort (über sseMerger zusammengeführt)
  contextKey: string | null; // SHA-256-Fingerabdruck des System-Prompts
}

Blocktypen: text, tool_use, tool_result. Der Tab „Konversation“ verwendet unabhängig vom Anbieter diese Struktur.

4.4 Einfärbung des Kontextschlüssels (src/mitm/inspector/contextKey.ts)

• Berechnet SHA-256 für den System-Prompt (erste Nachricht mit role:system, das Feld system oder Geminis systemInstruction)
• Gibt ein 12 Zeichen langes Hex-Präfix zurück ("a3f9c2...")
• Das Frontend ordnet den Schlüssel einer deterministischen HSL-Farbe für die linke Rahmenleiste zu
• Filter „gleicher Kontext“: Ein Klick auf den Chip ctx #a3f fügt einen Filter hinzu, sodass nur Anfragen mit demselben Fingerabdruck angezeigt werden

Dadurch lassen sich verschiedene „Personas“ oder Aufgaben, die in derselben Agentensitzung ausgeführt werden, visuell leicht unterscheiden.

4.5 Extraktion von LLM-Metadaten

Für LLM-Anfragen extrahiert der Tab „LLM-Details“:

interface LlmMetadata {
  provider: string | null; // "openai" | "anthropic" | "gemini" | ...
  apiKind: string | null; // "chat.completions" | "messages" | "embeddings" | ...
  model: string | null; // aus dem Anfrage-Body oder der Antwort
  messages: number; // Anzahl der Gesprächsbeiträge
  tokensIn: number | null; // usage.prompt_tokens / usage.input_tokens
  tokensOut: number | null; // usage.completion_tokens / usage.output_tokens
  streamed: boolean; // true bei einer SSE-Antwort
  mappedTo: string | null; // x-omniroute-mapped-Header
  costEstimateUsd: number | null; // geschätzte Kosten auf Grundlage der OmniRoute-Preise
}

4.6 Live-Filter für laufende Anfragen

Das Anfragefeld status hat den Typ number | "in-flight" | "error" — ein Eintrag wird beim Start der Anfrage sofort als "in-flight" hinzugefügt und direkt aktualisiert, sobald die Antwort (oder ein Fehler) eintrifft. Der Umschalter „Live“ in der Werkzeugleiste (liveOnly, i18n-Schlüssel trafficInspector.liveOnly) beschränkt die Liste auf Einträge, deren status === "in-flight" ist, sodass offene Verbindungen in Echtzeit beobachtet werden können.

Der Filter ist ein reines clientseitiges Prädikat in src/lib/inspector/matchesTrafficFilter.ts:

if (f.liveOnly && req.status !== "in-flight") return false;

Der Zustand des Umschalters befindet sich in useTrafficFilters (den Hooks des Inspector-Dashboards) und wird mit den anderen Filtern kombiniert (Profil, Host, Agent, Quelle, Status, Kontext).

4.7 Prozesszuordnung (Linux)

Unter Linux kann jede abgefangene Anfrage dem ursprünglichen lokalen Prozess zugeordnet werden. InterceptedRequest werden zwei optionale Felder hinzugefügt:

pid?: number;          // ID des ursprünglichen Prozesses (nur Linux)
processName?: string;  // Name des ursprünglichen Prozesses (nur Linux)

src/mitm/inspector/processAttribution.ts ordnet den ephemeren Client-Port der Verbindung einer PID und einem Namen zu, indem:

1. /proc/net/tcp und /proc/net/tcp6 gelesen werden, um den Socket-Inode für den Port zu finden (parseProcNetTcpForInode, ein reiner, mit Fixtures testbarer Parser).
2. /proc/<pid>/fd/ nach einem symbolischen Link auf socket:[<inode>] durchsucht wird.
3. Der Prozessname aus /proc/<pid>/comm gelesen wird.

Ein TTL-Cache von 1 Sekunde begrenzt die Kosten des procfs-Scans unter Last. Die Zuordnung erfolgt nach dem Best-Effort-Prinzip — jeder Fehler wird zu null aufgelöst und blockiert niemals die Erfassung. Unter macOS/Windows gibt die Funktion null zurück (Stub; Unterstützung für lsof/GetExtendedTcpTable ist als Folgearbeit vorgesehen).

---

§5 Sitzungen

5.1 Aufzeichnen einer Sitzung

1. Klicken Sie in der Symbolleiste auf „● Sitzung aufzeichnen“ → geben Sie einen Namen ein (optional)
2. Die Live-Anzeige wird normal fortgesetzt; ein rot pulsierender Indikator zeigt ◉ AUFZ · <Name> · 00:42 · 23 Anfr.
3. Klicken Sie auf „⏹ Beenden“ → der Sitzungssnapshot wird in inspector_sessions + inspector_session_requests gespeichert

5.2 Anzeigen einer aufgezeichneten Sitzung

Das Dropdown-Menü Sitzungen in der Symbolleiste listet gespeicherte Sitzungen auf. Wenn Sie eine auswählen:

• Wird der Snapshot der Sitzung geladen (eingefrorener Zustand)
• Ein Banner zeigt: Aufgezeichnete Sitzung „<Name>“ wird angezeigt — [Zurück zur Live-Ansicht]
• Die Registerkarte „Statistiken“ mit Recharts-Aggregationen wird verfügbar

5.3 Exportformate

Jede Sitzung kann wie folgt exportiert werden:

Format	Verwendung
HAR (HTTP Archive 1.2)	Kompatibel mit Chrome DevTools, Charles und Fiddler — für die Offline-Analyse importieren
JSONL	Ein InterceptedRequest pro Zeile — kompatibel mit dem Format von llm-interceptor

Der Export erfolgt über GET /api/tools/traffic-inspector/sessions/{id}/export.har oder die Schaltfläche ⬇ im Dropdown-Menü „Sitzungen“.

---

§6 Sicherheit

Traffic Inspector zeigt den gesamten abgefangenen HTTPS-Datenverkehr an, einschließlich Autorisierungsheadern und Anfrageinhalten. Die folgenden Schutzmaßnahmen sind implementiert:

Schutzmaßnahme	Details
LOCAL_ONLY	Alle Routen und der WebSocket-Endpunkt sind ausschließlich über die Loopback-Schnittstelle erreichbar (durchgesetzt in routeGuard.ts vor der Authentifizierung)
Maskierung von Geheimnissen	Der lineare Scanner maskSecret() schwärzt RFC-6750-Bearer-Anmeldedaten, anbieterspezifische Schlüssel und lange undurchsichtige Token vor TrafficBuffer.push()
Begrenzung der Inhaltsgröße	Inhalte > INSPECTOR_MAX_BODY_KB (Standardwert: 1024 KB) werden gekürzt und mit dem Hinweis "(aus Leistungsgründen gekürzt)" versehen
Header-Bereinigung	Namen werden in Kleinbuchstaben umgewandelt; Framing-, Hop-by-Hop- und Proxy-Authentifizierungsheader werden entfernt; Cookies werden vollständig geschwärzt; Werte mit Anmeldedaten werden an maskSecret() delegiert
CSP	Strenge Content Security Policy auf den Traffic-Inspector-Seiten, um XSS durch eingeschleuste Antwortinhalte zu verhindern
Standardmäßig keine Persistenz	Der TrafficBuffer befindet sich im Arbeitsspeicher und geht bei einem Serverneustart verloren. Sitzungen werden nur dann dauerhaft gespeichert, wenn sie explizit aufgezeichnet werden

Angewendete verbindliche Regeln

Regel	Anwendung
#12 sanitizeErrorMessage	Alle HTTP-Fehlerantworten der Traffic-Inspector-Routen werden bereinigt
#15 + #17 isLocalOnlyPath()	/api/tools/traffic-inspector/ ist LOCAL_ONLY + SPAWN_CAPABLE (System-Proxy-Befehle)

Bekannte Einschränkungen

• Der systemweite Proxy-Modus wirkt sich auf alle Anwendungen auf dem Rechner aus, einschließlich VPN-Clients und SSO. Verwenden Sie ihn immer mit dem Timer zur automatischen Deaktivierung. Verwenden Sie ihn nicht auf gemeinsam genutzten Rechnern.
• CONNECT-Tunnel-HTTPS: Modus 3 (HTTP_PROXY) erfasst für HTTPS-Ziele nur Tunnelmetadaten, sofern die TLS-Interception nicht aktiviert ist. Dies ist beabsichtigt — eine transparente Erfassung, ohne dass das AgentBridge-Zertifikat als vertrauenswürdig eingestuft ist, würde die TLS-Verifizierung für diese Anwendungen fehlschlagen lassen.
• Fest codierte Zeichenfolgen in einigen Komponenten: Einige UI-Komponenten (F7/F8) enthalten eine geringe Anzahl fest codierter Zeichenfolgen, die noch nicht durch i18n-Schlüssel abgedeckt sind. Diese sind im i18n-Lückenbericht als bekannte Einschränkung dokumentiert; sie werden in einem nachfolgenden Durchlauf migriert. Bei den betroffenen Zeichenfolgen handelt es sich um dekorative UI-Beschriftungen, die für die funktionale Nutzung keine Übersetzung erfordern.

---

§7 Fehlerbehebung

WebSocket-Verbindung getrennt

Wenn die Live-Anzeige „Getrennt“ anzeigt:

1. Prüfen Sie, ob der Server noch ausgeführt wird: GET /api/tools/traffic-inspector/capture-modes
2. Laden Sie die Seite neu — das WebSocket stellt die Verbindung wieder her und empfängt einen neuen Snapshot
3. Wenn der Server neu gestartet wurde, wurde der In-Memory-Puffer geleert — alte Einträge sind verloren, sofern keine Sitzung aufgezeichnet wurde

Portkonflikt bei 8080

Wenn der HTTP_PROXY-Modus nicht gestartet werden kann:

lsof -i :8080    # Prozess ermitteln

Ändern Sie den Port:

.env

INSPECTOR_HTTP_PROXY_PORT=8888

System-Proxy wurde nicht zurückgesetzt

Wenn OmniRoute abstürzt, während der systemweite Proxy-Modus aktiv ist:

macOS:

networksetup -setwebproxystate Wi-Fi off
networksetup -setsecurewebproxystate Wi-Fi off

Linux (GNOME):

gsettings set org.gnome.system.proxy mode 'none'

Windows:

netsh winhttp reset proxy

Das Dashboard bietet beim nächsten Laden außerdem „System-Proxy zurücksetzen“ an, wenn es erkennt, dass der Proxy laut Datenbankstatus aktiv war.

Puffer voll

Wenn der Puffer INSPECTOR_BUFFER_SIZE erreicht (Standardwert: 1000), verdrängen neue Einträge die ältesten. Wenn wichtige Anfragen verloren gehen:

• Erhöhen Sie INSPECTOR_BUFFER_SIZE (z. B. auf 5000) — dies erhöht den Speicherverbrauch zugunsten einer längeren Aufbewahrung
• Zeichnen Sie eine Sitzung auf, um den relevanten Zeitraum dauerhaft in der Datenbank zu speichern

---

§8 API-Referenz

Alle Routen sind LOCAL_ONLY (nur Loopback) und SPAWN_CAPABLE (System-Proxy-Befehle). Siehe src/server/authz/routeGuard.ts.

Basispfad: /api/tools/traffic-inspector/

Anfrageverwaltung

Methode	Pfad	Beschreibung
GET	/requests	Anfragen auflisten (filterbar: ?profile=llm&host=&agent=&status=&source=&sessionId=)
GET	/requests/{id}	Details einer einzelnen Anfrage
DELETE	/requests	In-Memory-Puffer leeren
POST	/requests/{id}/replay	Dieselbe Anfrage erneut über den OmniRoute-Router ausführen
PUT	/requests/{id}/annotation	Notiz zu einer Anfrage speichern oder aktualisieren

WebSocket

Methode	Pfad	Beschreibung
GET	/ws	Live-WebSocket-Stream. Sendet beim Verbindungsaufbau snapshot, danach new-/update-/clear-Ereignisse

Export

Methode	Pfad	Beschreibung
GET	/export.har	Aktuelle gefilterte Liste als HAR 1.2 exportieren

Benutzerdefinierte Hosts

Methode	Pfad	Beschreibung
GET	/hosts	Benutzerdefinierte Hosts auflisten
POST	/hosts	Host hinzufügen (bearbeitet automatisch /etc/hosts)
DELETE	/hosts/{host}	Host entfernen
PATCH	/hosts/{host}	enabled umschalten

Erfassungsmodi

Methode	Pfad	Beschreibung
GET	/capture-modes	Status der AgentBridge-, benutzerdefinierten Host-, HTTP_PROXY- und System-Proxy-Modi sowie des Schalters tls-intercept
POST	/capture-modes/http-proxy	HTTP_PROXY-Listener starten/stoppen ({action: "start"|"stop"})
POST	/capture-modes/system-proxy	Systemweiten Proxy anwenden/zurücksetzen ({action: "apply"|"revert"})
POST	/capture-modes/tls-intercept	Entschlüsselung von HTTPS-Nachrichtenkörpern im Proxy-Modus umschalten ({enabled: boolean})

TPROXY-Entschlüsselung (Erfassungsmodus 5) wird über eine separate Route unter dem AgentBridge-Präfix gesteuert — GET / POST / DELETE /api/tools/agent-bridge/tproxy — und nicht unter /api/tools/traffic-inspector/. Siehe docs/security/MITM-TPROXY-DECRYPT.md (git; nicht in /docs kompiliert).

Sitzungen

Methode	Pfad	Beschreibung
POST	/sessions	Aufzeichnung starten ({name?: string})
PATCH	/sessions/{id}	Stoppen oder umbenennen ({action: "stop"|"rename", name?: string})
GET	/sessions	Alle gespeicherten Sitzungen auflisten
GET	/sessions/{id}	Sitzungs-Snapshot (alle Anfragen)
DELETE	/sessions/{id}	Sitzung löschen
GET	/sessions/{id}/export.har	Sitzung als HAR 1.2 exportieren

Interne Aufnahme (D4-Fallback)

Methode	Pfad	Beschreibung
POST	/internal/ingest	Akzeptiert abgefangene Anfragen aus dem Passthrough-Pfad von server.cjs; erfordert den Header INSPECTOR_INTERNAL_INGEST_TOKEN

Vollständige OpenAPI-Schemas: docs/openapi.yaml → Tag Traffic Inspector.

---

OmniRoute-Quellcode (a58000c7685f)