Loginoplysningsproxy — teknisk
Sådan fungerer proxyen.
Hvad den beskytter imod. Hvad den ikke beskytter imod.
Denne side er til sikkerhedsanmeldere, penetrationstestere og ingeniører, der evaluerer proxyens trusselsmodel. Den beskriver, hvad proxyen gør på protokolniveau, hvor loginoplysninger findes i hukommelsen, og hvilke angrebsflader der forbliver.
Arkitektur
Proxyen er en CONNECT-baseret HTTPS MITM-proxy. En AI-agent sætter HTTPS_PROXY til at pege på den. Når agenten foretager en HTTPS-anmodning, aflytter proxyen TLS-forbindelsen, inspicerer anmodningsheadere for referencer til loginoplysninger, løser dem mod Clavitor-boksen og videresender anmodningen med indsatte loginoplysninger til den opstrøms API.
Proxyen lytter som standard på 127.0.0.1:1983 — sidecar-mønsteret, hvor proxyen og agenten deler en vært. For delte implementeringer (én proxy, der betjener flere agenter på et privat netværk, container sidecar til flere arbejdsbelastninger, dedikeret proxy-vært), kan lytteinterfacet konfigureres via CLAVITOR_PROXY_LISTEN.
Proxyen er en selvstændig Go-binærfil. Ingen CGO. Alle Clavitor protokol kryptografi ruter gennem en kanonisk Rust-implementering kompileret til WebAssembly og indlæst via wazero ved opstart.
TLS-håndtering
Proxyen genererer en selvsigneret ECDSA P-256 rod-CA ved første kørsel, gemt i binærfilens mappe med tilstand 0600. For hver opstrøms vært udstedes et bladcertifikat on-demand, signeret af denne CA og cachet i hukommelsen med begrænset udskiftning (1.000 værter). Bladcertifikater er gyldige i 24 timer og regenereres transparent ved 23-timers mærket for at forhindre udløb midt i en session.
Agenten skal stole på proxyens CA-certifikat. Eksporter det med clavitor-proxy ca.
Opstrømsforbindelser bruger minimum TLS 1.3 med ALPN-forhandling for HTTP/2 og HTTP/1.1. Systemets certifikatpulje bruges til opstrømsverifikation. Ingen certifikatfastgørelse — proxyen stoler på, hvad operativsystemet stoler på.
Loginoplysninger caches aldrig, skrives aldrig til disk og opbevares aldrig længere end én HTTP-anmodning.
| Fase | Hvor loginoplysningen findes | Varighed |
|---|---|---|
| I hvile i boks | AES-GCM chiffertekst i boksdatabasen | Indtil slettet |
| Under transport til proxy | TLS-krypteret JSON-respons fra boks-API | Én HTTP-rundtur |
| Dekrypteret i proxy | Proceshukommelse (Go-streng på heap) | Én HTTP-anmodning |
| Indsat i opstrømsanmodning | TLS-krypterede bytes på nettet til opstrøms | Én HTTP-anmodning |
Proxyen holder agentens loginoplysningsdekrypteringsnøgle (16 bytes) i hukommelsen i hele dens køretid. Den indlæses fra den krypterede sidecar-konfiguration (CLV1-format) ved opstart og slettes ved kontrolleret nedlukning. Nøglen forlader aldrig processen.
Sidecar-konfigurationen er krypteret med AES-128-GCM og HMAC-SHA256 ved hjælp af deterministiske nøgler afledt af et statisk seed. Dette er obfuskering, ikke fortrolighed — sikkerhedsgrænsen er filtilladelser (0600) og besiddelse af filen. CLV1-formatet deles mellem proxyen, CLI'en og browserudvidelsen.
Opløsningstilstande
Tilstand 1 — eksplicit pladsholder
Agenten inkluderer en clavitor://Entry/field reference i en anmodningsheader. Proxyen søger i boksen efter posten efter navn, henter den, dekrypterer det navngivne felt og erstatter pladsholderen med den faktiske værdi.
Hvis søgningen returnerer nul eller mere end ét resultat, returnerer proxyen 502 med en stabil fejlkode. Pladsholderen fjernes aldrig og videresendes som den er.
Tilstand 2 — URL-match
Når ingen pladsholder er til stede, beder proxyen boksen om poster, hvis URL-felt matcher den opstrøms vært. Hvis præcis ét match eksisterer med en genkendt feltform, indsætter proxyen automatisk loginoplysninger.
Nul matches → passthrough (ingen forventning om loginoplysninger). Flere matches → 502 med vejledning til tvetydighed. Ukendt feltform → 502.
Beslutningstræet er deterministisk: pladsholder til stede → løs eller fejle. Ingen pladsholder → URL-match eller passthrough. Der er ingen stille fallback-sti, hvor en mislykket opløsning resulterer i, at en anmodning sendes opstrøms uden loginoplysninger.
Som standard ser boksen proxyens egen agent-ID på hver anmodning. Ratebegrænsninger, omfangskontroller og auditposter tilskrives proxyen.
Når flere agenter deler én proxy-instans, kan pladsholderen inkludere et agent-ID: clavitor://agentid@Entry/field. Proxyen sender dette agent-ID til boksen, som anvender den agents omfang og ratebegrænsninger og logger adgangen mod den. Agent-ID'et er den 32-tegns hex-værdi, der vises på agentdetaljesiden i boksens UI.
# 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
| Implementering | Identitetsmodel | Isolation |
|---|---|---|
| Én proxy pr. agent | Proxy-ID = agent-ID (standard) | Fuld — separat binærfil, konfiguration, omfang, ratebegrænsninger |
| Delt proxy, intet agent-ID i URL | Alle agenter deler proxyens ID | Delt omfang og ratebegrænsninger |
Delt proxy + agentid@ i URL | Per-agent identitet | Per-agent omfang, ratebegrænsninger og audit |
Agent-ID'et i URL'en er ikke en autentificeringsmekanisme — proxyens CVT-token autentificerer forbindelsen. Agent-ID'et bestemmer tilskrivning: hvis omfang gælder, hvis ratebegrænsninger tæller, hvis auditspor registrerer adgangen. Boksen afviser ukendte agent-ID'er med en højlydt fejl.
Netværkssikkerhed
SSRF-beskyttelse
Som standard blokerer proxyen opstrømsforbindelser til private netværk (RFC 1918), cloud-instansmetadata (169.254.169.254), loopback, link-local og carrier-grade NAT-områder. DNS opløses først; alle returnerede IP'er valideres, før TCP-forbindelsen oprettes, hvilket lukker DNS-genbindingsvinduet TOCTOU.
Overskriv med CLAVITOR_PROXY_ALLOW_PRIVATE=true for agenter, der legitimt når private API'er.
Målfastgørelse
CONNECT-målhosten fanges ved tunneloprettelse og bruges til hele tunnelens levetid. Efterfølgende anmodninger inden for tunnelen kan ikke omdirigeres til en anden vært ved at manipulere Host-headeren. Et mismatch resulterer i 502.
Dette forhindrer en agent i at etablere en tunnel til api.openai.com og derefter sende anmodninger til internal-service.corp.
Header-håndtering
Hop-til-hop-headere fjernes fra både anmodninger og svar pr. RFC 7230 §6.1: Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailers, Transfer-Encoding, Upgrade.
Set-Cookie fjernes fra opstrømssvar for at forhindre opstrøms i at plante cookies i agentens HTTP-klient.
Anmodnings- og svarlegemer strømmer igennem uden buffering. Anmodningslegemer er begrænset til 64 MB som standard (CLAVITOR_PROXY_MAX_BODY_MB). Svarslegemer strømmer uden en hård grænse; en logadvarsel udsendes, når Content-Length overstiger 100 MB.
I URL-match-tilstand mapper proxyen boksfeltetiketter til HTTP-headere:
| Feltetiket | Indsat header |
|---|---|
key, apikey, api_key, token, secret, bearer, access_token | Authorization: Bearer <value> |
x-api-key, api-key | X-API-Key: <value> |
username + password (parret) | Authorization: Basic base64(user:pass) |
| Alt andet | Afvist — ERR-PROXY-052 |
I pladsholdertilstand styrer agenten, hvilket felt der løses, og hvor det går hen. Kortlægningen ovenfor gælder kun for URL-match-tilstand.
Hver fejl producerer en stabil ERR-PROXY-NNN kode. Disse koder er en del af proxyens offentlige grænseflade — agenter og operatører kan matche dem til alarmering og fejlfinding.
| Rækkevidde | Kategori |
|---|---|
001–019 | Opsætning (konfiguration, init, CA-generering, WASM) |
020–029 | Daemon livscyklus |
030–049 | Pladsholderopløsning (clavitor:// URI'er) |
050–069 | URL-match indsættelse |
070–089 | Opstrøms / TLS |
Identitetsfelter er uopnåelige
Boksoptegnelser understøtter tre krypteringstrin. Bokskrypterede felter er klartekst-metadata. Loginoplysnings-krypterede felter dekrypteres med agentens nøgle. Identitetskrypterede felter er krypteret med en nøgle, som serveren og proxyen aldrig har set. Kun boksejeren kan dekryptere dem via deres hardwarenøgle.
Hvis en pladsholder refererer til et identitets-krypteret felt, returnerer proxyen ERR-PROXY-035. Ingen fallback, intet delvist resultat. Feltet er arkitektonisk uopnåeligt fra proxyen.
Hvad proxyen ikke beskytter imod
Proxyens trusselsmodel er en kompromitteret skill eller prompt injection, der får en autentificeret agent til at høste loginoplysninger. Boksens per-agent ratebegrænsninger, unikke postkvoter og to-strikes-lås er de primære forsvar. Proxyen tilføjer et netværkslagshåndhævelsespunkt, hvor loginoplysninger løses pr. anmodning og aldrig opbevares af agenten.
Proxyen kører på samme maskine som agenten. En angriber med root-adgang kan læse proceshukommelse, vedhæfte en debugger eller aflytte loopback-trafik. Proxyen er et loginoplysningsindsættelseslag, ikke en hardware-sikkerhedsgrænse.
Hvis den opstrøms API gentager loginoplysningen i sit svar (f.eks. en "whoami"-endpoint), ser agenten den. Proxyen indsætter loginoplysninger i anmodninger, ikke svar. Den filtrerer ikke, hvad der kommer tilbage.
Logning
Proxyen logger én linje pr. accepteret CONNECT og udsender fejlmeddelelser for fejl. Den logger aldrig:
- Dekrypterede loginoplysningsværdier
- Fuldstændige anmodnings-URL'er (forespørgselsstrenge kan indeholde hemmeligheder — kun skema + vært + sti logges)
- Anmodnings- eller svarslegemer
- Loginoplysningsdekrypteringsnøglen eller sidecar-konfigurationens indhold
Når proxyen registrerer, at et 400-svar fra opstrøms indeholder autorisationsrelaterede nøgleord (unauthorized, invalid token osv.), logger den et diagnostisk hint, der antyder, at den indsatte loginoplysning kan være forældet. Svaret videresendes uændret.
Kryptografi
Al Clavitor protokol kryptografi — AES-GCM feltdekryptering, HKDF nøgleafledning, base62-kodning, CVT token-udstedelse, CLV1 konfigurationspakke/udpakkning — udføres inde i et enkelt WebAssembly-modul (clavis_crypto.wasm) indlæst via wazero, en ren Go WASM-runtime. Ingen CGO. Ingen Go-genimplementering af Clavitor-primitiver.
WASM-modulet er kompileret fra den samme Rust crate (clavis-crypto), som bruges af browseren, CLI'en og browserudvidelserne. Én sandhedskilde, én binærfil, én auditflade.
Proxyen bruger Go's crypto/tls til TLS-forbindelsen og crypto/ecdsa til MITM-certifikatgenerering. Dette er transportbekymringer, ikke Clavitor protokoloperationer.
Hemmeligheder (loginoplysningsdekrypteringsnøgle, agent-ID, enheds-ID, boks-URL) lever i den krypterede CLV1 sidecar-konfiguration, skrevet én gang under clavitor-proxy init. Operationelle knapper lever i miljøvariabler:
| Variabel | Standard | Formål |
|---|---|---|
CLAVITOR_PROXY_LISTEN | 127.0.0.1 | Lytteinterface. Indstillet til 0.0.0.0 for delte implementeringer eller til en specifik interface-IP. |
CLAVITOR_PROXY_PORT | 1983 | Lytteport |
CLAVITOR_PROXY_ALLOW_PRIVATE | false | Tillad forbindelser til RFC-1918 / private netværk |
CLAVITOR_PROXY_MAX_BODY_MB | 64 | Anmodningskropsstørrelsesgrænse |
CLAVITOR_PROXY_WRITE_TIMEOUT | 300 | Svarskrivningstidout i sekunder |
CLAVITOR_CONFIG | (exe-mappe) | Overskriv sti til sidecar-konfiguration |
Operationelle knapper er ikke hemmeligheder. De hører ikke hjemme i den krypterede konfiguration. De hører hjemme, hvor implementeringsværktøjer allerede administrerer dem — miljøet.
Gennemgå dette selv.
Kryptografien er en enkelt auditerbar WASM-artefakt. Trusselsmodellen er dokumenteret. Hvis du finder noget, vi har overset, vil vi gerne høre om det.