AgentBridge (Deutsch)

§1 Übersicht

Was ist AgentBridge?

Wenn ein IDE-Agent (z. B. GitHub Copilot, Cursor oder Claude Code) einen API-Aufruf durchführt, verbindet er sich direkt mit dem vorgeschalteten KI-Anbieter (OpenAI, Anthropic usw.). AgentBridge fängt diese Verbindung transparent auf TLS-Ebene ab — ohne dass Änderungen an der Agentenkonfiguration erforderlich sind — und leitet die Anfrage über OmniRoute um.

Damit können Sie:

Jeden Agenten zu jedem Anbieter umleiten: Copilot kommuniziert mit OpenAI? Leiten Sie ihn zu Anthropic Claude, Gemini oder einem der 352 Anbieter von OmniRoute um.
Modellzuordnungen anwenden: gemini-3-flash → claude-sonnet-4.7 transparent auf Handler-Ebene.
Den gesamten Agentendatenverkehr beobachten: Jede abgefangene Anfrage wird im Traffic Inspector veröffentlicht.
Die Ausfallsicherheit von OmniRoute nutzen: Kombinations-Routing, Leistungsschalter, Fallbacks und Kostenverfolgung funktionieren auch für den Datenverkehr von IDE-Agenten.

Positionierung im Marktvergleich

Funktion	9router	anti-api	llm-interceptor	OmniRoute AgentBridge
Antigravity	✓	✓	—	✓
GitHub Copilot	✓	✓	—	✓
Kiro (AWS)	✓	✓	—	✓
OpenAI Codex	—	✓	—	✓
Cursor IDE	✓	✓	—	✓
Zed Industries	—	✓	—	✓
Claude Code	—	—	✓	✓
Open Code	—	—	✓	✓
Trae	—	—	—	🔍 Wird untersucht
Dashboard-Benutzeroberfläche	✓	✗	✗	✓
Traffic Inspector	✗	✗	✓	✓
OmniRoute-Routing	✗	✗	✗	✓
Benutzeroberfläche für Modellzuordnungen	✗	✗	✗	✓
Umgehungsliste	✗	✗	✓	✓
Vorgeschaltetes CA-Zertifikat	✗	✗	✓	✓

§2 Architektur

2.1 Komponentenübersicht

IDE-Agent (VS Code / Cursor / usw.)
    │  HTTPS (Port 443)
    ▼
/etc/hosts — 127.0.0.1 api.githubcopilot.com   ← DNS-Umleitung
    │
    ▼
src/mitm/server.cjs  (Port 443, CJS-Kindprozess)
    │  löst das Ziel anhand der SNI des Host-Headers auf
    │  generiert ein SNI-spezifisches TLS-Zertifikat, signiert von der AgentBridge-CA
    ├── Treffer in der Umgehungsliste? → TCP-Durchleitung (keine Entschlüsselung)
    ├── Zieltreffer? → fetch → OmniRoute-Router (Port 20128)
    │       └── handler.intercept() — TypeScript
    │               ├── maskSecrets() auf Anfragetext/-headern
    │               ├── TrafficBuffer.push() — veröffentlicht im Traffic Inspector
    │               └── fetchRouter() → /v1/chat/completions
    └── Kein Treffer? → TCP-Durchleitung (keine Entschlüsselung)

2.2 MITM-Server (`src/mitm/server.cjs`)

Der zentrale MITM-Server wird als Node.js-CJS-Kindprozess ausgeführt (um eine Überarbeitung der bestehenden CJS-Codebasis zu vermeiden). Er:

lauscht auf Port 443 (erfordert entsprechende Berechtigungen oder authbind/setcap)
empfängt CONNECT-Tunnel vom Betriebssystem (über die DNS-Umleitung in /etc/hosts)
generiert SNI-spezifische TLS-Zertifikate, die von der AgentBridge-CA (DATA_DIR/mitm/ca.crt) signiert werden
ermittelt den Ziel-Agenten anhand des Host-Headers über die Registrierung targets/index.ts
leitet Anfragen über HTTP an die TypeScript-Handler-Schicht unter http://127.0.0.1:20128 weiter

TARGET_HOSTS wird aus DATA_DIR/mitm/targets.json geladen (beim Start von targets/index.ts geschrieben), wodurch dynamische Aktualisierungen ohne Neustart des CJS-Servers möglich sind.

Root-CA-Modell (#6684). Die oben beschriebene Verwendung eines pro SNI ausgestellten und von einer CA signierten Zertifikats ist das in #6684 hinzugefügte persistente Root-CA-Modell (src/mitm/cert/rootCa.ts + src/mitm/_internal/rootCaShim.cjs, wobei die bereits für TPROXY bewährte CA-/Leaf-Kryptografie aus src/mitm/tproxy/dynamicCert.ts wiederverwendet wird) — es ersetzt das ältere einzelne statische, selbstsignierte Leaf-Zertifikat (src/mitm/cert/generate.ts, weiterhin ausschließlich auf die Antigravity-Hosts beschränkt), auf das ein bloßes server.crt/server.key-Paar auf dem Datenträger hinweist. Migrationsverhalten: Bei einer Neuinstallation (ohne vorhandenes server.crt) wird das Root-CA-Modell automatisch verwendet; eine Installation, die dem alten statischen Leaf-Zertifikat bereits vertraut, verwendet dieses weiterhin, bis der Betreiber MITM_ROOT_CA_ENABLED=true setzt und die Bridge neu startet (src/mitm/cert/migration.ts ist die reine Entscheidungsfunktion — eine vertrauenswürdige MITM-CA, die ein Leaf-Zertifikat für jeden beliebigen Host signieren kann, ist wesentlich mächtiger als das alte Leaf-Zertifikat mit festen SANs, daher erfolgt die Umstellung bei einer bereits vertrauenden Installation niemals stillschweigend). Das CA-Zertifikat wird in denselben Vertrauensspeicherplatz omniroute-mitm.crt installiert, den zuvor das alte Leaf-Zertifikat verwendete (cert/install.ts::installCaCert) — eine Bereinigung wegen doppelten Vertrauens ist nicht erforderlich.

2.3 Handler-Basisklasse (`src/mitm/handlers/base.ts`)

Alle Agenten-Handler erweitern MitmHandlerBase:

export abstract class MitmHandlerBase {
  abstract readonly agentId: AgentId;

  abstract intercept(
    req: IncomingMessage,
    res: ServerResponse,
    body: Buffer,
    mappedModel: string
  ): Promise&lt;void&gt;;

  // Geschützte Hilfsmethoden: fetchRouter, pipeSSE, hookBufferStart, hookBufferUpdate
}

Jeder Handler ruft vor der Proxy-Weiterleitung hookBufferStart() und nach deren Abschluss hookBufferUpdate() auf. Dadurch werden InterceptedRequest-Einträge an globalTrafficBuffer übergeben (siehe Traffic Inspector §4).

2.4 Zielregistrierung (`src/mitm/targets/`)

Jeder Agent besitzt eine deklarative Zieldatei:

export const COPILOT_TARGET: MitmTarget = {
  id: "copilot",
  name: "GitHub Copilot",
  hosts: ["api.githubcopilot.com", "copilot-proxy.githubusercontent.com"],
  port: 443,
  endpointPatterns: ["/chat/completions", "/v1/chat/completions"],
  defaultModels: [{ id: "gpt-4o", name: "GPT-4o", alias: "gpt-4o" }],
  handler: () => import("../handlers/copilot"),
  riskNoticeKey: "providers.riskNotice.oauth",
};

Die Registrierung (targets/index.ts) exportiert ALL_TARGETS und erzeugt beim Start DATA_DIR/mitm/targets.json.

2.5 Durchleitung und Umgehungsliste (`src/mitm/passthrough.ts`)

Umgehungsliste (wird zuerst geprüft und hat Vorrang vor einem Zieltreffer):

Standardmuster: Banking-Hosts, .gov., OAuth-/SSO-Anbieter (Okta, Auth0) usw.
Benutzermuster: werden in der DB-Tabelle agent_bridge_bypass gespeichert
Umgangene Hosts erhalten einen transparenten TCP-Tunnel — TLS wird niemals entschlüsselt

Standardmäßige Durchleitung (kein Zieltreffer und nicht in der Umgehungsliste):

Erhält ebenfalls einen TCP-Tunnel — Verbindungen werden niemals unterbrochen
Verhindert, dass AgentBridge den allgemeinen HTTPS-Datenverkehr des Systems beeinträchtigt

Routing-Priorität:

Umgehungsliste → Zieltreffer → Durchleitung

2.6 Upstream-CA-Zertifikat (`src/mitm/upstreamTrust.ts`)

Für Unternehmensnetzwerke mit einer benutzerdefinierten CA:

AGENTBRIDGE_UPSTREAM_CA_CERT=/path/to/corporate-ca.pem

Wenn gesetzt, wird der globale Dispatcher von undici mit dem zusätzlichen CA-Zertifikat konfiguriert, sodass AgentBridge Upstream-Anbieter über unternehmenseigene Proxys zur TLS-Terminierung erreichen kann.

2.7 Maskierung geheimer Daten (`src/mitm/maskSecrets.ts`)

Der unabhängige Clean-Room-Scanner wird auf Anfragetexte und Anmeldeinformationsheader angewendet, bevor diese in den Traffic-Inspector-Puffer oder ein Protokoll gelangen. Er führt einen einzigen linearen Durchlauf aus:

Token mit dem Präfix sk- / ak- / pk- (im Stil von OpenAI/Anthropic)
RFC-6750-Anmeldeinformationen vom Typ Authorization: Bearer <token>, wobei das vollständige Token Vorrang hat
Allgemeine lange, undurchsichtige Token (≥40 Zeichen), einschließlich punktgetrennter und aufgefüllter Formen

sanitizeHeaders() wandelt beibehaltene Namen in Kleinbuchstaben um, verbindet Array-Werte deterministisch, verwirft die gemeinsame Sperrliste für Hop-by-Hop- und Framing-Header (einschließlich Proxy-Authentifizierung), schwärzt cookie und set-cookie vollständig und übergibt Anmeldeinformationswerte an den Scanner.

§3 Einrichtung

3.1 MITM-Server starten/stoppen

Verwenden Sie die AgentBridge-Serverkarte unter /dashboard/tools/agent-bridge:

Aktion	Beschreibung
Server starten	Startet `src/mitm/server.cjs` auf Port 443
Server stoppen	Beendet den untergeordneten Prozess ordnungsgemäß
Server neu starten	Stoppen + starten (übernimmt Änderungen an den Zielmodellen)
Zertifikat vertrauen	Installiert `DATA_DIR/mitm/ca.crt` im Vertrauensspeicher des Betriebssystems
Zertifikat herunterladen	Lädt `ca.crt` zur manuellen Installation herunter
Zertifikat neu erzeugen	Erstellt ein neues CA-Schlüsselpaar (alle vorhandenen agentenspezifischen Zertifikate werden ungültig)

3.2 Dem Zertifikat vertrauen

Dem AgentBridge-CA-Zertifikat muss vom Betriebssystem vertraut werden, bevor IDEs die MITM-Verbindung akzeptieren.

Linux (NSS — Chrome/Firefox):

certutil -A -d sql:$HOME/.pki/nssdb -n "OmniRoute AgentBridge" -t CT,, -i ~/.omniroute/mitm/ca.crt

macOS (Schlüsselbund):

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ~/.omniroute/mitm/ca.crt

Windows (certmgr):

certutil -addstore -f Root $env:USERPROFILE\.omniroute\mitm\ca.crt

Alternativ können Sie die Schaltfläche „Zertifikat vertrauen“ im Dashboard verwenden (führt den passenden Befehl für Ihr Betriebssystem aus und zeigt bei Bedarf eine sudo-Abfrage an).

Electron-basierte IDEs ignorieren den Vertrauensspeicher des Betriebssystems (`NODE_EXTRA_CA_CERTS`)

Einige IDEs — insbesondere Antigravity IDE und andere von Electron / VS Code abgeleitete Anwendungen — enthalten eine eigene Node.js-Laufzeit, die für ausgehende fetch-/HTTPS-Anfragen nicht den Vertrauensspeicher des Betriebssystems verwendet. Der CA auf Betriebssystem-/NSS-Ebene zu vertrauen, reicht für das native Backend der IDE aus (z. B. einen Go-Sprachserver, der das CA-Bundle des Betriebssystems verwendet), aber das Electron-Frontend wird weiterhin an TLS scheitern — dies zeigt sich dadurch, dass die Anwendung abgemeldet ist oder einen “Verbindungsfehler” anzeigt, obwohl das MITM-Protokoll zeigt, dass die Bootstrap-Aufrufe des Backends 200 zurückgeben. Zwei Schritte sind erforderlich, und beide sind wichtig:

Verweisen Sie die Laufzeit explizit auf die CA:

export NODE_EXTRA_CA_CERTS=/path/to/omniroute-agentbridge-ca.crt

Starten Sie die IDE aus dieser Shell. Beim Start über das Desktop-Symbol / Dock / Startmenü werden Shell-Exporte nicht übernommen, und ~/.config/environment.d/*.conf gilt erst nach einer neuen grafischen Anmeldung. Beenden Sie die IDE zuvor vollständig — aufgrund der Singleton-Sperre von Electron fokussiert ein zweiter Start lediglich den bestehenden Prozess, und die neue Umgebung wird ignoriert.

Der oben beschriebene Schritt für das Vertrauen auf Betriebssystemebene + NSS bleibt erforderlich (der von einigen Authentifizierungsabläufen verwendete Chromium-Netzwerk-Stack liest den benutzerspezifischen NSS-Speicher und besitzt eigene statische Pins für *.googleapis.com, die von einer lokal als vertrauenswürdig eingestuften CA überschrieben werden). NODE_EXTRA_CA_CERTS deckt zusätzlich den Node-fetch-Pfad ab.

3.3 DNS-Routing

Für jeden Agenten, dessen Datenverkehr Sie abfangen möchten, müssen dessen API-Hosts auf 127.0.0.1 aufgelöst werden. AgentBridge verwaltet die Einträge in /etc/hosts automatisch, wenn Sie im Einrichtungsassistenten DNS für einen Agenten aktivieren oder deaktivieren.

Beispieleinträge in /etc/hosts für GitHub Copilot:

127.0.0.1 api.githubcopilot.com
127.0.0.1 copilot-proxy.githubusercontent.com

3.4 Modellzuordnung

Verwenden Sie die Modellzuordnungstabelle in jeder Agentenkarte, um Zuordnungen von Quelle → Ziel zu definieren:

Quellmodell (nativ für den Agenten)	Zielmodell (OmniRoute)
`gpt-4o`	`claude-sonnet-4.7`
`*` (Platzhalter)	`claude-haiku-4.7`

Der Platzhalter * ordnet jedes unbekannte Modell dem angegebenen Zielmodell zu. Die Zuordnungen werden in der Tabelle agent_bridge_mappings gespeichert.

Tipp — ermitteln Sie die tatsächlichen Modell-IDs des Agenten. Eine IDE kann Modellnamen senden, die von ihren UI-Bezeichnungen abweichen und sich zwischen Hauptversionen ändern. Beispielsweise sendet Antigravity 2 gemini-3.1-pro-low, gemini-pro-agent und gemini-3.1-flash-lite über die Verbindung — nicht das in älteren Dokumentationen angegebene gemini-2.5-pro. Senden Sie eine Chatnachricht, ohne dass eine passende Zuordnung vorhanden ist: Das MITM protokolliert den exakten eingehenden Wert model: und leitet die Anfrage unverändert weiter. Ordnen Sie diesen exakten Wert zu; die nächste Anfrage wird dann abgefangen und an Ihr Ziel weitergeleitet.

3.5 Risikohinweis

AgentBridge fängt Anmeldedaten (OAuth-Token, API-Schlüssel) ab, die die IDE zur Authentifizierung bei vorgelagerten Anbietern verwendet. Diese werden vor der Protokollierung maskiert (siehe §2.7), sind jedoch für die MITM-Schicht von OmniRoute sichtbar. Bei der ersten Aktivierung jedes Agenten wird ein ausblendbarer modaler Risikohinweis angezeigt.

3.6 Wartung & Diagnose

Das Dashboard enthält eine Karte für Wartung & Diagnose (AgentBridgeMaintenanceCard in src/app/(dashboard)/dashboard/tools/agent-bridge/components/), die operative MITM-Routen zugänglich macht, für die zuvor keine Benutzeroberfläche vorhanden war. Ihr Untertitel lautet: „Testen Sie die Erfassungspipeline selbst, machen Sie verbliebene Systemzustände rückgängig und übertragen Sie Ihre Einrichtung zwischen Rechnern.“ Die Client-Hilfsfunktionen der Karte befinden sich in src/lib/inspector/agentBridgeMaintenanceApi.ts.

Schaltfläche	Route	Funktion
Diagnose	`GET /api/tools/agent-bridge/diagnose`	Führt den Selbsttest der Erfassungspipeline aus und zeigt einen Bericht für jede Prüfung an (✓/✗ + Hinweis zur Fehlerbehebung).
Repair	`POST /api/tools/agent-bridge/repair`	Macht verwaiste MITM-Systemzustände rückgängig (DNS-Spoofing-Einträge, Root-CA, System-Proxy), die nach einem Absturz oder SIGKILL zurückgeblieben sind. Idempotent — meldet „Nothing to repair“, wenn der Zustand sauber ist.
Remove CA	`DELETE /api/tools/agent-bridge/cert`	Hebt das Vertrauen in die MITM-Root-CA auf und entfernt sie aus dem Vertrauensspeicher des Betriebssystems (explizit, idempotent). Wird nur angezeigt, wenn die CA derzeit als vertrauenswürdig eingestuft ist; erfordert eine direkte Bestätigung mit „Remove CA?“.
Export config	`GET /api/tools/agent-bridge/config`	Lädt die portable Konfigurations-JSON herunter (siehe §3.7).
Import config	`POST /api/tools/agent-bridge/config`	Lädt eine zuvor exportierte Konfigurations-JSON hoch (siehe §3.7).

Diagnoseprüfungen (summarizeDiagnostics() in src/mitm/inspector/diagnostics.ts). Die Route führt für jede Prüfung den effektbehafteten Test aus und übergibt die booleschen Werte an die reine Zusammenfassungsfunktion; zurückgegeben werden ein einzelnes healthy-Urteil sowie ein Hinweis für jeden Fehler:

Prüfungsname	Was geprüft wird	Hinweis bei einem Fehler
`server-running`	Der MITM-Serverprozess ist aktiv	„Der MITM-Server wird nicht ausgeführt. Starten Sie ihn über die Registerkarte AgentBridge.“
`server-reachable`	Der MITM-Server akzeptiert Verbindungen an seinem Port (TCP-Test)	„Der MITM-Server akzeptiert an seinem Port keine Verbindungen. Prüfen Sie, ob der Port frei ist und ob Sie über die erforderlichen Berechtigungen zum Binden verfügen.“
`cert-exists`	Das MITM-Zertifikat wurde auf dem Datenträger generiert	„Es wurde noch kein MITM-Zertifikat generiert. Generieren Sie eines über die Registerkarte AgentBridge.“
`cert-trusted`	Die MITM-Root-CA befindet sich im Vertrauensspeicher des Betriebssystems	„Die MITM-Root-CA wird vom Vertrauensspeicher des Betriebssystems nicht als vertrauenswürdig eingestuft, daher schlägt die TLS-Interception fehl. Stufen Sie das Zertifikat über die Registerkarte AgentBridge als vertrauenswürdig ein.“
`dns-configured`	Zielhostnamen werden in `/etc/hosts` gespooft	„Zielhostnamen werden in /etc/hosts nicht gespooft, sodass der Datenverkehr den Proxy nie erreicht. Aktivieren Sie DNS für die Agents, deren Datenverkehr Sie erfassen möchten.“

Banner für verwaisten Zustand: Wenn die Seite einen nach einem Absturz zurückgebliebenen Zustand erkennt (DNS-Spoofing / CA / System-Proxy), zeigt die Karte ein gelbes Banner an — „Eine vorherige Sitzung hat einen Systemzustand zurückgelassen (DNS-Spoofing, CA oder System-Proxy). Führen Sie Repair aus, um ihn zu bereinigen.“ — und hebt die Schaltfläche Repair hervor. Repair ist das Gegenstück auf Anwendungsebene zum ProxyBridge-Flag --cleanup (es delegiert an repairMitm() in src/mitm/manager.ts).

Die MITM-Root-CA bleibt über Stopp/Start hinweg installiert, um wiederholte sudo- Eingabeaufforderungen zu vermeiden (dasselbe Verhalten wie bei mitmproxy/Charles). Daher ist das Entfernen eine explizite Remove CA-Aktion und erfolgt nicht automatisch beim Stoppen.

3.7 Import/Export portabler Konfigurationen

AgentBridge kann den vom Betreiber anpassbaren Zustand in ein versioniertes JSON-Objekt serialisieren, sodass eine Einrichtung auf mehreren Rechnern repliziert werden kann. Der Serializer ist src/lib/inspector/configPortability.ts (exportConfig() / importConfig()) und wird durch AgentBridgeConfigSchema validiert.

Der Export umfasst genau drei Bestandteile (integrierte Standardwerte werden absichtlich NICHT exportiert, damit sie beim Importieren weder dupliziert werden noch mit den importierten Werten in Konflikt geraten):

Feld	Quelle	Hinweise
`bypassPatterns`	benutzerdefinierte Umgehungsmuster (`agent_bridge_bypass`)	Standardmuster für Banken/Behörden/Okta sind ausgeschlossen
`customHosts`	benutzerdefinierte Hosts des Traffic Inspector (`inspector_custom_hosts`)	jeweils: `{ host, kind: "llm"\|"app"\|"custom", label? }`
`agentMappings`	agentspezifische Modellzuordnungen (`agent_bridge_mappings`)	`{ [agentId]: [{ source, target }] }` für jeden Agent mit vorhandenen Zuordnungen

// GET /api/tools/agent-bridge/config
{
  "version": 1,
  "bypassPatterns": ["*.internal.example.com"],
  "customHosts": [{ "host": "api.example.com", "kind": "llm", "label": null }],
  "agentMappings": {
    "copilot": [{ "source": "gpt-4o", "target": "claude-sonnet-4.7" }],
  },
}

Importverhalten (POST /api/tools/agent-bridge/config): Umgehungsmuster und agentspezifische Zuordnungen werden vollständig ersetzt; benutzerdefinierte Hosts werden idempotent hinzugefügt (INSERT OR IGNORE). Die Antwort gibt an, wie viele Elemente jedes Typs angewendet wurden:

{ "ok": true, "bypassPatterns": 1, "customHosts": 1, "agents": 1 }

Was NICHT in der Konfiguration enthalten ist: Serverbetriebsstatus, Zertifikatspfade, agentenspezifischer DNS-Status, Pfad zur Upstream-CA und TPROXY-Einstellungen – dabei handelt es sich um Host-/Laufzeitstatus, nicht um portable Einstellungen.

§4 Referenz pro Agent

#	Agent	Status	Abgefangene Hosts	Authentifizierungstyp
1	Antigravity	✅ Unterstützt	`daily-cloudcode-pa.googleapis.com`, `cloudcode-pa.googleapis.com`	Firebase OAuth
2	Kiro (AWS)	✅ Unterstützt	`prod.kiro.aws`, `dev.kiro.aws`	AWS SigV4
3	GitHub Copilot	✅ Unterstützt	`api.githubcopilot.com`, `copilot-proxy.githubusercontent.com`	GitHub OAuth
4	OpenAI Codex	✅ Unterstützt	`api.openai.com` (Codex-Pfade), `chatgpt.com`	OpenAI-Schlüssel
5	Cursor IDE	✅ Unterstützt	`api2.cursor.sh`, `api.cursor.sh`	Cursor OAuth
6	Zed Industries	✅ Unterstützt	`api.zed.dev`, `llm.zed.dev`	Zed OAuth
7	Claude Code	✅ Unterstützt	`api.anthropic.com` (Opt-in)	Anthropic-Schlüssel
8	Open Code	✅ Unterstützt	`openrouter.ai`, `api.openai.com` (zen-Pfade)	API-Schlüssel
9	Trae	🔍 In Untersuchung	Noch festzulegen — siehe §8	Noch festzulegen

Schritte des Einrichtungsassistenten (pro Agent)

Jede Agentenkarte verfügt über einen dreistufigen Einrichtungsassistenten:

Voraussetzungen prüfen — Läuft der Server? Ist das Zertifikat vertrauenswürdig? Ist die IDE installiert (automatisch erkannt)?
DNS aktivieren — Fügt Einträge zu /etc/hosts hinzu (erfordert sudo). Zeigt genau an, welche Zeilen hinzugefügt werden.
Modelle zuordnen — Optionale Tabelle für Modellzuordnungen. Platzhalter werden akzeptiert.

Agentenerkennung

Für die Agenten 1–8 versucht AgentBridge, die IDE-Installation automatisch zu erkennen:

export async function detectAgent(agentId: AgentId): Promise<DetectionResult>;
// Gibt zurück: { installed: boolean, version?: string, path?: string }

Die Erkennung verwendet betriebssystemspezifische Pfade und Binärdateiprüfungen (z. B. code --list-extensions | grep github.copilot für Copilot, ~/.config/antigravity/ für Antigravity).

§5 Sicherheit

Angewendete zwingende Regeln

Regel	Anwendung
#12 `sanitizeErrorMessage`	Alle Handler-Fehler werden vor der Antwort oder dem Puffereintrag bereinigt
#13 Umgebungsübergabe an Shell	Änderungen an `/etc/hosts` verwenden die Option `env` — keine String-Interpolation von Pfaden
#15 + #17 `isLocalOnlyPath()`	`/api/tools/agent-bridge/` ist LOCAL_ONLY + SPAWN_CAPABLE — Loopback wird vor der Authentifizierung erzwungen

Umgehungsliste für sensible Hosts

Die Umgehungsliste stellt sicher, dass Finanzinstitute, OAuth-/SSO-Anbieter und andere sensible Hosts niemals entschlüsselt werden. Ihr TLS-Datenverkehr wird als transparenter TCP-Tunnel weitergeleitet — OmniRoute sieht niemals den Klartext.

Die standardmäßigen Umgehungsmuster umfassen:

*.bank.*, *.gov.* (Finanzwesen/Behörden)
*.okta.com, *.auth0.com, *.microsoft.com (SSO/Identität)
*.apple.com, *.icloud.com (Apple-Systemdienste)

Vom Benutzer hinzugefügte Umgehungsmuster werden in der Tabelle agent_bridge_bypass gespeichert und haben Vorrang vor allen anderen Regeln.

Maskierung von Geheimnissen

maskSecrets() aus src/mitm/maskSecrets.ts wird angewendet:

Auf jeden Anfragekörper vor TrafficBuffer.push()
Auf jeden Header vor der Protokollierung oder Übertragung

Muster: Token mit dem Präfix sk-/ak-/pk-, Bearer-Token und generische Token mit mindestens 40 Zeichen.

Upstream-CA-Zertifikat

Wenn AGENTBRIDGE_UPSTREAM_CA_CERT gesetzt ist, wird die Datei beim Start gelesen. Wenn der Pfad vorhanden ist, die Datei jedoch nicht gelesen werden kann, protokolliert AgentBridge einen eindeutigen Fehler und verweigert den Start (dies verhindert unbemerkte TLS-Fehler in Unternehmensumgebungen).

Bekannte Einschränkungen

Port 443 erfordert erhöhte Berechtigungen: Unter Linux benötigt AgentBridge setcap 'cap_net_bind_service=+ep' für die Node-Binärdatei oder muss über authbind ausgeführt werden. Der Einrichtungsassistent zeigt betriebssystemspezifische Anweisungen an.
IDE-Neustart erforderlich: Nach der DNS-Umleitung muss die IDE neu gestartet werden, damit die neue Hostauflösung wirksam wird.
Fest codierte OAuth-Token: Einige Agenten (Kiro, Antigravity) speichern OAuth-Aktualisierungstoken lokal. Diese sind für AgentBridge transparent — es sieht das Bearer-Token in jeder Anfrage, das vor der Protokollierung maskiert wird.
Electron-Frontends benötigen NODE_EXTRA_CA_CERTS: IDEs, deren Frontend in einer gebündelten Node-/Electron-Laufzeitumgebung ausgeführt wird, ignorieren den Vertrauensspeicher des Betriebssystems bzw. von NSS und müssen aus einer Shell gestartet werden, in der NODE_EXTRA_CA_CERTS gesetzt ist (siehe §3.2). Symptom bei fehlender Konfiguration: Das IDE-Backend authentifiziert sich (MITM zeigt 200-Antworten), aber die Benutzeroberfläche bleibt abgemeldet.
Mehrere Installationen derselben IDE sind unabhängig: Eine Systeminstallation (z. B. /usr/share/antigravity/antigravity) und eine benutzerlokale „Full“-Installation (z. B. ~/AntigravityIDE_Full/antigravity-ide) sind separate Prozesse mit eigenen Laufzeitumgebungen — jede muss mit eingebundener CA neu gestartet werden. Ermitteln Sie vor dem Neustart anhand des Binärdateipfads, welche Installation ausgeführt wird.
Die Identität wird durch den System-Prompt des Agenten festgelegt, nicht durch das weitergeleitete Modell: Wenn Sie das Modell eines Agenten einem anderen Anbieter zuordnen, gibt die Antwort weiterhin die ursprüngliche Identität des Agenten an (z. B. antwortet Antigravity „Ich werde von Gemini unterstützt“), da die IDE dies in den System-Prompt einfügt. Überprüfen Sie das tatsächliche Backend in call_logs / proxy_logs (provider, model, target_format), anstatt das Modell nach seiner Identität zu fragen.

§6 Fehlerbehebung

Konflikt mit Port 443

Wenn bereits ein anderer Prozess auf Port 443 lauscht (Webserver, VPN usw.):

lsof -i :443          # Prozess ermitteln
sudo fuser -k 443/tcp  # Beenden erzwingen (mit Vorsicht verwenden)

Alternativ können Sie in den AgentBridge-Einstellungen einen nicht privilegierten Port konfigurieren und Weiterleitungsregeln mit iptables / pf einrichten.

Zertifikat wird nicht als vertrauenswürdig eingestuft

Wenn die IDE nach dem Start von AgentBridge TLS-Fehler anzeigt:

Überprüfen Sie, ob das Zertifikat installiert wurde: security find-certificate -c "OmniRoute AgentBridge" (macOS) oder certutil -L -d sql:$HOME/.pki/nssdb (Linux/NSS)
Einige Anwendungen verwenden einen eigenen Vertrauensspeicher (Firefox, Chrome unter Linux). Führen Sie „Trust Cert“ erneut aus und prüfen Sie den NSS-/Firefox-spezifischen Zertifikatsspeicher.
Starten Sie die IDE nach dem Festlegen der Vertrauenswürdigkeit neu — bereits laufende TLS-Sitzungen verwenden weiterhin den alten Vertrauensstatus.

IDE abgemeldet / „Verbindungsfehler“ trotz vertrauenswürdiger CA

Symptom: Nach der DNS-Umleitung und dem Festlegen der CA als vertrauenswürdig wird eine Electron-basierte IDE (z. B. Antigravity) abgemeldet geöffnet oder zeigt einen Authentifizierungs-/Verbindungsfehler an, obwohl das MITM-Protokoll zeigt, dass die Bootstrap-Aufrufe (loadCodeAssist, fetchAvailableModels, …) mit 200 beantwortet werden.

Ursache: Die in der IDE gebündelte Node-/Electron-Laufzeitumgebung ignoriert den Vertrauensspeicher des Betriebssystems. Das native Backend (ein Go-Sprachserver) vertraut der Betriebssystem-CA und authentifiziert sich, das Electron-Frontend jedoch nicht — daher geht die Benutzeroberfläche davon aus, offline zu sein.

Lösung (beide Schritte): Exportieren Sie NODE_EXTRA_CA_CERTS=<ca.crt> und starten Sie die IDE aus dieser Shell neu, nicht über das Desktop-Symbol. Beenden Sie die IDE zuvor vollständig — aufgrund der Singleton-Sperre von Electron fokussiert ein zweiter Start lediglich den bereits vorhandenen Prozess, und die neue Umgebung wird ignoriert. Siehe §3.2. Dies entspricht einem offenen Upstream-Bericht, bei dem ein eigenständiger Agent über ein MITM funktioniert, die IDE- Variante mit derselben Konfiguration jedoch fehlschlägt.

DNS-Änderungen nicht übernommen

Prüfen Sie, ob /etc/hosts aktualisiert wurde:

grep "omniroute\|127.0.0.1.*github\|127.0.0.1.*cursor" /etc/hosts

Leeren Sie den DNS-Cache:

# macOS
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
# Linux (systemd-resolved)
sudo systemctl restart systemd-resolved
# Windows
ipconfig /flushdns

IDE wird nicht erkannt

Die automatische Erkennung verwendet gängige Installationspfade. Wenn die Erkennung fehlschlägt, obwohl die IDE installiert ist:

Prüfen Sie, ob sich die IDE-Binärdatei an einem nicht standardmäßigen Speicherort befindet
Der Einrichtungsassistent funktioniert weiterhin — eine fehlgeschlagene Erkennung bedeutet lediglich, dass der Installationspfad nicht im Badge angezeigt wird

Handler-Fehler (Upstream-Abruf schlägt fehl)

Wenn AgentBridge Anfragen abfängt, aber alle Anfragen fehlschlagen:

Stellen Sie sicher, dass unter /dashboard/providers mindestens ein Anbieter verbunden ist
Prüfen Sie die OmniRoute-Serverprotokolle: APP_LOG_LEVEL=debug in .env
Stellen Sie sicher, dass OMNIROUTE_BASE_URL auf den korrekten Router-Endpunkt verweist (Standard: http://127.0.0.1:20128)

§7 API-Referenz

Alle Routen sind LOCAL_ONLY (nur Loopback, vor der Authentifizierung erzwungen) und SPAWN_CAPABLE. Siehe src/server/authz/routeGuard.ts.

Basispfad: /api/tools/agent-bridge/

Methode	Pfad	Beschreibung
GET	`/api/tools/agent-bridge/state`	Globaler Serverstatus + Erkennungs-/Statusinformationen pro Agent
GET	`/api/tools/agent-bridge/agents`	Registrierte Agents auflisten (ID, Name, Hosts, Verwendbarkeit, Status)
GET	`/api/tools/agent-bridge/agents/{id}`	Status eines Agents (Zielkonfiguration + Erkennung + gespeicherter Status)
PATCH	`/api/tools/agent-bridge/agents/{id}`	`setup_completed` für den Agent aktualisieren
GET	`/api/tools/agent-bridge/agents/{id}/detect`	Erkennungsprüfung für den Agent ausführen (`installed`, `version?`, `path?`)
POST	`/api/tools/agent-bridge/agents/{id}/dns`	DNS für den Agent aktivieren/deaktivieren (`{enabled: boolean}`)
GET	`/api/tools/agent-bridge/agents/{id}/mappings`	Modellzuordnungen für den Agent
PUT	`/api/tools/agent-bridge/agents/{id}/mappings`	Modellzuordnungen ersetzen
POST	`/api/tools/agent-bridge/server`	Server starten/stoppen/neu starten (`action: "start"\|"stop"\|"restart"\|"trust-cert"\|"regenerate-cert"`)
GET	`/api/tools/agent-bridge/cert`	Zertifikatsstatus (`exists`, `trusted`, `path`)
POST	`/api/tools/agent-bridge/cert`	MITM-Root-CA als vertrauenswürdig einstufen (installieren)
DELETE	`/api/tools/agent-bridge/cert`	Vertrauen in die MITM-Root-CA aufheben (entfernen) — idempotent (siehe §3.6)
POST	`/api/tools/agent-bridge/cert/regenerate`	Selbstsigniertes MITM-Zertifikat neu generieren
GET	`/api/tools/agent-bridge/cert/download`	PEM-Zertifikat zum Herunterladen streamen
GET	`/api/tools/agent-bridge/bypass`	Umgehungsmuster auflisten (`default` + `user`)
POST	`/api/tools/agent-bridge/bypass`	Benutzerdefinierte Umgehungsmuster vollständig ersetzen
DELETE	`/api/tools/agent-bridge/bypass?pattern=...`	Ein einzelnes benutzerdefiniertes Umgehungsmuster entfernen
GET	`/api/tools/agent-bridge/diagnose`	Selbsttest der Erfassungspipeline (siehe §3.6)
POST	`/api/tools/agent-bridge/repair`	Verwaisten MITM-Systemstatus rückgängig machen (siehe §3.6)
GET	`/api/tools/agent-bridge/config`	Portable Konfiguration als JSON exportieren (siehe §3.7)
POST	`/api/tools/agent-bridge/config`	Portable JSON-Konfiguration importieren (siehe §3.7)
GET	`/api/tools/agent-bridge/upstream-ca`	Pfad der konfigurierten Upstream-CA abrufen
POST	`/api/tools/agent-bridge/upstream-ca`	Pfad der Upstream-CA validieren + dauerhaft speichern
POST	`/api/tools/agent-bridge/upstream-ca/test`	Pfad einer Upstream-CA nur validieren (Testlauf) — wird nicht dauerhaft gespeichert
GET / POST / DELETE	`/api/tools/agent-bridge/tproxy`	Transparenter TPROXY-Entschlüsselungs-Erfassungsmodus — siehe `docs/security/MITM-TPROXY-DECRYPT.md` (git; nicht in `/docs` kompiliert)

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

§8 Roadmap

Trae-Untersuchung

Trae ist ein relativ neuer KI-Programmierassistent. Vor der Implementierung eines Handlers:

Die Binärdatei/Erweiterung in den VS Code- / JetBrains-Marktplätzen oder als eigenständige App identifizieren
Den Datenverkehr mit mitmproxy erfassen, um API-Hosts und Endpunktstrukturen zu ermitteln
Den Authentifizierungsmechanismus bestimmen
Auf Grundlage der Nutzungsbedingungen und der Auffindbarkeit der API eine Go-/No-Go-Entscheidung treffen

Bis zum Abschluss der Untersuchung zeigt die Trae-Karte im Dashboard ein „Wird untersucht“-Badge mit einem Link „Machbarkeit melden“. Der Handler-Stub unter src/mitm/handlers/trae.ts löst einen strukturierten Fehler Not yet implemented aus.

Backlog-Agenten (MITM erforderlich — keine Unterstützung für benutzerdefinierte Basis-URLs)

Die folgenden Tools unterstützen in ihren aktuellen Versionen keine benutzerdefinierten Basis-URLs, sodass MITM der einzige Weg zur Interzeption ist. Die Machbarkeitsbewertung steht noch aus:

Windsurf (Codeium/Cognition)
Amp (Sourcegraph)
Amazon Q / Kiro CLI (AWS Bedrock — unabhängig von Kiro IDE)
Cowork (Anthropic-Desktopanwendung)

Hinweis: GitHub Copilot CLI ≥v1.0.19 unterstützt COPILOT_PROVIDER_BASE_URL — für dieses Tool sollte anstelle von MITM die direkte Konfiguration verwendet werden.

OmniRoute-Quellcode (a58000c7685f)

HagiCode

HagiCode ist ein agentischer Coding-Arbeitsplatz mit strukturierten Workflows, Multi-Agent-Ausführung und Hero-Dungeon-Ansichten.

Mit einem intelligenteren, schnelleren und unterhaltsameren agentischen Workflow wird aus Ideen nutzbare Software.

HagiCode-Hauptoberfläche im hellen Design

SmartStrukturierte Workflows machen aus Absichten einen umsetzbaren Weg von der Idee bis zur Auslieferung.
EfficientMulti-Agent-Workflows führen Recherche, Umsetzung und Prüfung parallel aus.
FunHero Dungeon macht lange Coding-Sitzungen anschaulich und gemeinschaftlich.

HagiCode besuchen