Anmeldedaten-Proxy – Technik
So funktioniert der Proxy.
Wogegen er schützt. Wogegen nicht.
Diese Seite richtet sich an Sicherheitsprüfer, Penetrationstester und Ingenieure, die das Bedrohungsmodell des Proxys bewerten. Sie beschreibt, was der Proxy auf Protokollebene tut, wo Anmeldedaten im Speicher vorhanden sind und welche Angriffsflächen verbleiben.
Architektur
Der Proxy ist ein HTTPS MITM-Proxy, der auf CONNECT basiert. Ein KI-Agent setzt HTTPS_PROXY so, dass er darauf zeigt. Wenn der Agent eine HTTPS-Anfrage stellt, fängt der Proxy die TLS-Verbindung ab, prüft Anforderungsheader auf Anmeldedaten-Referenzen, löst diese im Clavitor Tresor auf und leitet die Anfrage mit eingefügten Anmeldedaten an die Upstream-API weiter.
Der Proxy lauscht standardmäßig auf 127.0.0.1:1983 – das Sidecar-Muster, bei dem sich Proxy und Agent einen Host teilen. Für gemeinsam genutzte Bereitstellungen (ein Proxy für mehrere Agenten in einem privaten Netzwerk, Container-Sidecar für mehrere Workloads, dedizierter Proxy-Host) ist die Schnittstelle über CLAVITOR_PROXY_LISTEN konfigurierbar.
Der Proxy ist eine eigenständige Go-Binärdatei. Kein CGO. Die gesamte Clavitor-Protokollkryptografie läuft über eine kanonische Rust-Implementierung, die zu WebAssembly kompiliert und beim Start über wazero geladen wird.
TLS-Handling
Der Proxy generiert beim ersten Start eine selbstsignierte ECDSA P-256 Root-CA, die im Verzeichnis der Binärdatei mit Modus 0600 gespeichert wird. Für jeden Upstream-Host wird bei Bedarf ein Blattzertifikat erstellt, das von dieser CA signiert und im Speicher mit begrenzter Verdrängung (1.000 Hosts) zwischengespeichert wird. Blattzertifikate sind 24 Stunden gültig und werden zur Vermeidung von Ablauf während der Sitzung transparent nach 23 Stunden neu generiert.
Der Agent muss dem CA-Zertifikat des Proxys vertrauen. Exportieren Sie es mit clavitor-proxy ca.
Upstream-Verbindungen verwenden mindestens TLS 1.3 mit ALPN-Aushandlung für HTTP/2 und HTTP/1.1. Der Systemzertifikatspool wird für die Upstream-Verifizierung verwendet. Kein Certificate Pinning – der Proxy vertraut dem, was das Betriebssystem vertraut.
Anmeldedaten werden niemals zwischengespeichert, niemals auf die Festplatte geschrieben und niemals länger als eine HTTP-Anfrage aufbewahrt.
| Phase | Wo die Anmeldedaten vorhanden sind | Dauer |
|---|---|---|
| Im Ruhezustand im Tresor | AES-GCM-Chiffretext in der Tresordatenbank | Bis zur Löschung |
| Im Transit zum Proxy | TLS-verschlüsselte JSON-Antwort von der Tresor-API | Ein HTTP-Roundtrip |
| Im Proxy entschlüsselt | Prozessspeicher (Go-String im Heap) | Eine HTTP-Anfrage |
| In die Upstream-Anfrage eingefügt | TLS-verschlüsselte Bytes auf dem Draht zum Upstream | Eine HTTP-Anfrage |
Der Proxy hält den Schlüssel zur Entschlüsselung der Anmeldedaten des Agenten (16 Bytes) während seiner gesamten Laufzeit im Speicher. Er wird beim Start aus der verschlüsselten Sidecar-Konfiguration (CLV1-Format) geladen und bei ordnungsgemäßer Beendigung gelöscht. Der Schlüssel verlässt niemals den Prozess.
Die Sidecar-Konfiguration ist mit AES-128-GCM und HMAC-SHA256 verschlüsselt, wobei deterministische Schlüssel verwendet werden, die von einem statischen Seed abgeleitet sind. Dies ist eine Verschleierung, keine Vertraulichkeit – die Sicherheitsgrenze sind Dateiberechtigungen (0600) und der Besitz der Datei. Das CLV1-Format wird zwischen dem Proxy, der CLI und der Browsererweiterung gemeinsam genutzt.
Auflösungsmodi
Modus 1 – expliziter Sitzhalter
Der Agent fügt eine clavitor://Entry/field-Referenz in einen Anforderungsheader ein. Der Proxy durchsucht den Tresor nach dem Eintrag anhand des Namens, ruft ihn ab, entschlüsselt das benannte Feld und ersetzt den Sitzhalter durch den tatsächlichen Wert.
Wenn die Suche null oder mehr als ein Ergebnis liefert, gibt der Proxy 502 mit einem stabilen Fehlercode zurück. Der Sitzhalter wird niemals entfernt und unverändert weitergeleitet.
Modus 2 – URL-Abgleich
Wenn kein Sitzhalter vorhanden ist, fragt der Proxy den Tresor nach Einträgen ab, deren URL-Feld mit dem Upstream-Host übereinstimmt. Wenn genau eine Übereinstimmung mit einer erkannten Feldform existiert, fügt der Proxy Anmeldedaten automatisch ein.
Null Übereinstimmungen → Passthrough (keine Erwartung von Anmeldedaten). Mehrere Übereinstimmungen → 502 mit Disambiguierungsanleitung. Unbekannte Feldform → 502.
Der Entscheidungsbaum ist deterministisch: Sitzhalter vorhanden → auflösen oder fehlschlagen. Kein Sitzhalter → URL-Abgleich oder Passthrough. Es gibt keinen stillen Fallback-Pfad, bei dem eine fehlgeschlagene Auflösung dazu führt, dass eine Anfrage ohne Anmeldedaten an Upstream geht.
Standardmäßig sieht der Tresor bei jeder Anfrage die eigene Agenten-ID des Proxys. Ratenbegrenzungen, Bereichsprüfungen und Audit-Einträge werden dem Proxy zugeordnet.
Wenn mehrere Agenten eine Proxy-Instanz gemeinsam nutzen, kann der Sitzhalter eine Agenten-ID enthalten: clavitor://agentid@Entry/field. Der Proxy sendet diese Agenten-ID an den Tresor, der die Bereiche und Ratenbegrenzungen dieses Agenten anwendet und den Zugriff dagegen protokolliert. Die Agenten-ID ist der 32-stellige Hex-Wert, der auf der Agenten-Detailseite in der Tresor-Benutzeroberfläche angezeigt wird.
# Without agent ID — attributed to the proxy Authorization: Bearer clavitor://OpenAI/key # With agent ID — attributed to agent 0102030405060708090a0b0c0d0e0f10 Authorization: Bearer clavitor://0102030405060708090a0b0c0d0e0f10@OpenAI/key
| Bereitstellung | Identitätsmodell | Isolierung |
|---|---|---|
| Ein Proxy pro Agent | Proxy-ID = Agenten-ID (Standard) | Vollständig – separate Binärdatei, Konfiguration, Bereich, Ratenbegrenzungen |
| Gemeinsamer Proxy, keine Agenten-ID in der URL | Alle Agenten teilen sich die ID des Proxys | Gemeinsamer Bereich und gemeinsame Ratenbegrenzungen |
Gemeinsamer Proxy + agentid@ in der URL | Pro Agent identifiziert | Pro Agent Bereich, Ratenbegrenzungen und Audit |
Die Agenten-ID in der URL ist kein Authentifizierungsmechanismus – das CVT-Token des Proxys authentifiziert die Verbindung. Die Agenten-ID bestimmt die Zuordnung: wessen Bereiche gelten, wessen Ratenbegrenzungen zählen, wessen Audit-Log den Zugriff aufzeichnet. Der Tresor lehnt unbekannte Agenten-IDs mit einem deutlichen Fehler ab.
Netzwerksicherheit
SSRF-Schutz
Standardmäßig blockiert der Proxy Upstream-Verbindungen zu privaten Netzwerken (RFC 1918), Cloud-Instanz-Metadaten (169.254.169.254), Loopback, Link-Local und Carrier-Grade NAT-Bereichen. DNS wird zuerst aufgelöst; alle zurückgegebenen IPs werden validiert, bevor die TCP-Verbindung hergestellt wird, wodurch das DNS-Rebinding-TOCTOU-Fenster geschlossen wird.
Überschreiben mit CLAVITOR_PROXY_ALLOW_PRIVATE=true für Agenten, die legitimerweise private APIs erreichen.
Ziel-Pinning
Das CONNECT-Ziel wird beim Aufbau des Tunnels erfasst und für die gesamte Lebensdauer des Tunnels verwendet. Nachfolgende Anfragen innerhalb des Tunnels können nicht durch Manipulation des Host-Headers auf einen anderen Host umgeleitet werden. Ein Unterschied führt zu 502.
Dies verhindert, dass ein Agent einen Tunnel zu api.openai.com aufbaut und dann Anfragen an internal-service.corp sendet.
Header-Handling
Hop-by-hop-Header werden gemäß RFC 7230 §6.1 aus Anfragen und Antworten entfernt: Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailers, Transfer-Encoding, Upgrade.
Set-Cookie wird aus Upstream-Antworten entfernt, um zu verhindern, dass Upstreams Cookies im HTTP-Client des Agenten setzen.
Anfrage- und Antwortkörper werden ohne Pufferung gestreamt. Anforderungskörper sind standardmäßig auf 64 MB begrenzt (CLAVITOR_PROXY_MAX_BODY_MB). Antwortkörper werden ohne harte Begrenzung gestreamt; eine Protokollwarnung wird ausgegeben, wenn Content-Length 100 MB überschreitet.
Im URL-Abgleichmodus ordnet der Proxy Tresor-Feldbezeichnungen HTTP-Headern zu:
| Feldbezeichnung | Eingefügter Header |
|---|---|
key, apikey, api_key, token, secret, bearer, access_token | Authorization: Bearer <value> |
x-api-key, api-key | X-API-Key: <value> |
username + password (gepaart) | Authorization: Basic base64(user:pass) |
| Alles andere | Abgelehnt – ERR-PROXY-052 |
Im Sitzhaltermodus steuert der Agent, welches Feld aufgelöst und wohin es gesendet wird. Die obige Zuordnung gilt nur für den URL-Abgleichmodus.
Jeder Fehler erzeugt einen stabilen ERR-PROXY-NNN-Code. Diese Codes sind Teil der öffentlichen Schnittstelle des Proxys – Agenten und Betreiber können sie für Benachrichtigungen und zur Fehlerbehebung abgleichen.
| Bereich | Kategorie |
|---|---|
001–019 | Einrichtung (Konfiguration, Initialisierung, CA-Generierung, WASM) |
020–029 | Daemon-Lebenszyklus |
030–049 | Sitzhalterauflösung (clavitor://-URIs) |
050–069 | URL-Abgleich-Einfügung |
070–089 | Upstream / TLS |
Identitätsfelder sind unerreichbar
Tresoreinträge unterstützen drei Verschlüsselungsebenen. Felder mit Tresor-Verschlüsselung sind Klartext-Metadaten. Felder mit Anmeldedaten-Verschlüsselung werden mit dem Schlüssel des Agenten entschlüsselt. Felder mit Identitäts-Verschlüsselung werden mit einem Schlüssel verschlüsselt, den der Server und der Proxy noch nie gesehen haben. Nur der Tresorbesitzer kann sie über seinen Hardware-Schlüssel entschlüsseln.
Wenn ein Sitzhalter auf ein Feld mit Identitäts-Verschlüsselung verweist, gibt der Proxy ERR-PROXY-035 zurück. Kein Fallback, kein Teilergebnis. Das Feld ist architektonisch vom Proxy aus unerreichbar.
Wogegen der Proxy nicht schützt
Das Bedrohungsmodell des Proxys ist eine kompromittierte Fähigkeit oder Prompt-Injection, die einen authentifizierten Agenten dazu bringt, Anmeldedaten zu ernten. Die Tresor-Ratenbegrenzungen pro Agent, die Quoten für eindeutige Einträge und die Zwei-Fehler-Sperre sind die primären Abwehrmaßnahmen. Der Proxy fügt einen Netzwerk-Layer-Durchsetzungspunkt hinzu, an dem Anmeldedaten pro Anfrage aufgelöst und niemals vom Agenten gehalten werden.
Der Proxy läuft auf derselben Maschine wie der Agent. Ein Angreifer mit Root-Zugriff kann den Prozessspeicher lesen, einen Debugger anhängen oder Loopback-Verkehr abfangen. Der Proxy ist eine Anmeldedaten-Injektionsschicht, keine Hardware-Sicherheitsgrenze.
Wenn die Upstream-API die Anmeldedaten in ihrer Antwort zurückgibt (z. B. ein "whoami"-Endpunkt), sieht der Agent sie. Der Proxy fügt Anmeldedaten in Anfragen ein, nicht in Antworten. Er filtert nicht, was zurückkommt.
Protokollierung
Der Proxy protokolliert eine Zeile pro akzeptiertem CONNECT und gibt Fehlerzeilen für Fehler aus. Er protokolliert niemals:
- Entschlüsselte Anmeldedatenwerte
- Vollständige Anforderungs-URLs (Abfragezeichenfolgen können Geheimnisse enthalten – nur Schema + Host + Pfad werden protokolliert)
- Anforderungs- oder Antwortkörper
- Der Schlüssel zur Entschlüsselung von Anmeldedaten oder der Inhalt der Sidecar-Konfiguration
Wenn der Proxy erkennt, dass eine 400-Antwort von Upstream authentifizierungsbezogene Schlüsselwörter enthält (unauthorized, invalid token usw.), protokolliert er einen Diagnosehinweis, der darauf hindeutet, dass die eingefügten Anmeldedaten veraltet sein könnten. Die Antwort wird unverändert weitergeleitet.
Kryptografie
Die gesamte Clavitor-Protokollkryptografie – AES-GCM-Feldentschlüsselung, HKDF-Schlüsselableitung, Base62-Kodierung, CVT-Token-Erstellung, CLV1-Konfigurationspaket/-entpackung – wird innerhalb eines einzigen WebAssembly-Moduls (clavis_crypto.wasm) ausgeführt, das über wazero, eine reine Go WASM-Laufzeit, geladen wird. Kein CGO. Keine Go-Neuerstellung von Clavitor-Primitiven.
Das WASM-Modul wird aus demselben Rust-Crate (clavis-crypto) kompiliert, das vom Browser, der CLI und den Browsererweiterungen verwendet wird. Eine Quelle der Wahrheit, eine Binärdatei, eine Audit-Oberfläche.
Der Proxy verwendet Go's crypto/tls für die TLS-Leitung und crypto/ecdsa für die MITM-Zertifikatgenerierung. Dies sind Transportbelange, keine Clavitor-Protokolloperationen.
Geheimnisse (Schlüssel zur Entschlüsselung von Anmeldedaten, Agenten-ID, Geräte-ID, Tresor-URL) befinden sich in der verschlüsselten CLV1-Sidecar-Konfiguration, die einmal während clavitor-proxy init geschrieben wird. Betriebsschalter befinden sich in Umgebungsvariablen:
| Variable | Standard | Zweck |
|---|---|---|
CLAVITOR_PROXY_LISTEN | 127.0.0.1 | Schnittstelle zum Lauschen. Auf 0.0.0.0 für gemeinsam genutzte Bereitstellungen oder auf eine bestimmte Schnittstellen-IP setzen. |
CLAVITOR_PROXY_PORT | 1983 | Port zum Lauschen |
CLAVITOR_PROXY_ALLOW_PRIVATE | false | Verbindungen zu RFC-1918 / privaten Netzwerken zulassen |
CLAVITOR_PROXY_MAX_BODY_MB | 64 | Anforderungs-Body-Größenbegrenzung |
CLAVITOR_PROXY_WRITE_TIMEOUT | 300 | Timeout für das Schreiben von Antworten in Sekunden |
CLAVITOR_CONFIG | (exe-Verzeichnis) | Pfad zur Sidecar-Konfiguration überschreiben |
Betriebsschalter sind keine Geheimnisse. Sie gehören nicht in die verschlüsselte Konfiguration. Sie gehören dorthin, wo Bereitstellungstools sie bereits verwalten – die Umgebung.
Überprüfen Sie dies selbst.
Die Kryptografie ist ein einzelnes, auditierbares WASM-Artefakt. Das Bedrohungsmodell ist dokumentiert. Wenn Sie etwas finden, das wir übersehen haben, möchten wir davon hören.