Påloggingsinformasjon-proxy — teknisk
Slik fungerer proxyen.
Hva den beskytter mot. Hva den ikke beskytter mot.
Denne siden er for sikkerhetsgjennomgangere, penetrasjonstestere og ingeniører som evaluerer proxyens trusselmodell. Den beskriver hva proxyen gjør på protokollnivå, hvor påloggingsinformasjon eksisterer i minnet, og hvilke angrepsflater som gjenstår.
Arkitektur
Proxyen er en CONNECT-basert HTTPS MITM-proxy. En AI-agent setter HTTPS_PROXY til å peke på den. Når agenten utfører en HTTPS-forespørsel, avskjærer proxyen TLS-tilkoblingen, inspiserer forespørselsheadere for referanser til påloggingsinformasjon, løser dem mot Clavitor sitt hvelv, og videresender forespørselen med innsatt påloggingsinformasjon til oppstrøms API-et.
Proxyen lytter på 127.0.0.1:1983 som standard — sidecar-mønsteret der proxyen og agenten deler en vert. For delte utrullinger (én proxy som betjener flere agenter på et privat nettverk, container sidecar til flere arbeidslaster, dedikert proxy-vert), kan lyttegrensesnittet konfigureres via CLAVITOR_PROXY_LISTEN.
Proxyen er en frittstående Go-binærfil. Ingen CGO. All Clavitor protokollkryptografi rutes gjennom en kanonisk Rust-implementasjon kompilert til WebAssembly og lastet via wazero ved oppstart.
TLS-håndtering
Proxyen genererer en selvsignert ECDSA P-256 rot-CA ved første kjøring, lagret i binærfilens katalog med modus 0600. For hver oppstrøms vert, utstedes et blad-sertifikat ved behov, signert av denne CA-en, og cachelagret i minnet med begrenset utskifting (1 000 verter). Blad-sertifikater er gyldige i 24 timer og regenereres transparent ved 23-timers merket for å forhindre utløp midt i en sesjon.
Agenten må stole på proxyens CA-sertifikat. Eksporter det med clavitor-proxy ca.
Oppstrøms tilkoblinger bruker minimum TLS 1.3 med ALPN-forhandling for HTTP/2 og HTTP/1.1. Systemets sertifikatpool brukes for oppstrøms verifisering. Ingen sertifikatfesting — proxyen stoler på det operativsystemet stoler på.
Påloggingsinformasjon lagres aldri i cache, aldri skrevet til disk, og aldri beholdt lenger enn én HTTP-forespørsel.
| Fase | Hvor påloggingsinformasjonen eksisterer | Varighet |
|---|---|---|
| I hvilemodus i hvelvet | AES-GCM chiffertekst i hvelvdatabasen | Inntil slettet |
| Under transport til proxy | TLS-kryptert JSON-respons fra hvelv API | Én HTTP rundtur |
| Dekryptert i proxy | Prosessminne (Go-streng på heap) | Én HTTP-forespørsel |
| Innsatt i oppstrøms forespørsel | TLS-krypterte bytes på nettverket til oppstrøms | Én HTTP-forespørsel |
Proxyen holder agentens påloggingsinformasjons-dekrypteringsnøkkel (16 bytes) i minnet under hele kjøretiden. Den lastes fra den krypterte sidecar-konfigurasjonen (CLV1-format) ved oppstart og slettes ved en ryddig nedstengning. Nøkkelen forlater aldri prosessen.
Sidecar-konfigurasjonen er kryptert med AES-128-GCM og HMAC-SHA256 ved bruk av deterministiske nøkler utledet fra et statisk frø. Dette er obfuskering, ikke konfidensialitet — sikkerhetsgrensen er filrettigheter (0600) og eierskap av filen. CLV1-formatet deles mellom proxyen, CLI-en og nettleserutvidelsen.
Løsningsmoduser
Modus 1 — eksplisitt plassholder
Agenten inkluderer en clavitor://Entry/field-referanse i en forespørselsheader. Proxyen søker i hvelvet etter oppføringen etter navn, henter den, dekrypterer det navngitte feltet, og erstatter plassholderen med den virkelige verdien.
Hvis søket returnerer null eller mer enn ett resultat, returnerer proxyen 502 med en stabil feilkode. Plassholderen blir aldri strippet og videresendt som den er.
Modus 2 — URL-match
Når ingen plassholder er til stede, spør proxyen hvelvet om oppføringer hvis URL-felt samsvarer med oppstrøms verten. Hvis nøyaktig én match eksisterer med en gjenkjennbar feltform, setter proxyen inn påloggingsinformasjon automatisk.
Null treff → passthrough (ingen forventning om påloggingsinformasjon). Flere treff → 502 med veiledning for disambiguering. Ukjent feltform → 502.
Beslutningstreet er deterministisk: plassholder til stede → løs eller feil. Ingen plassholder → URL-match eller passthrough. Det er ingen stille fallback-bane der en mislykket løsning resulterer i at en forespørsel går oppstrøms uten påloggingsinformasjon.
Som standard ser hvelvet proxyens egen agent-ID på hver forespørsel. Rate-begrensninger, omfangskontroller og revisjonsoppføringer tilskrives proxyen.
Når flere agenter deler én proxy-instans, kan plassholderen inkludere en agent-ID: clavitor://agentid@Entry/field. Proxyen sender denne agent-ID-en til hvelvet, som bruker den agentens omfang og rate-begrensninger og logger tilgangen mot den. Agent-ID-en er den 32-tegns heksadesimale verdien som vises på agentdetaljsiden i hvelv-UI-en.
# 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
| Utrulling | Identitetsmodell | Isolasjon |
|---|---|---|
| Én proxy per agent | Proxy-ID = agent-ID (standard) | Full — separat binærfil, konfigurasjon, omfang, rate-begrensninger |
| Delt proxy, ingen agent-ID i URL | Alle agenter deler proxyens ID | Delt omfang og rate-begrensninger |
Delt proxy + agentid@ i URL | Per-agent identitet | Per-agent omfang, rate-begrensninger og revisjon |
Agent-ID-en i URL-en er ikke en autentiseringsmekanisme — proxyens CVT-token autentiserer tilkoblingen. Agent-ID-en bestemmer tilskrivning: hvis omfang gjelder, hvis rate-begrensninger teller, hvis revisjonsspor registrerer tilgangen. Hvelvet avviser ukjente agent-ID-er med en tydelig feil.
Nettverkssikkerhet
SSRF-beskyttelse
Som standard blokkerer proxyen oppstrøms tilkoblinger til private nettverk (RFC 1918), skyinstans metadata (169.254.169.254), loopback, link-local og carrier-grade NAT-områder. DNS løses først; alle returnerte IP-er valideres før TCP-tilkoblingen opprettes, og lukker DNS-rebindings TOCTOU-vinduet.
Overstyr med CLAVITOR_PROXY_ALLOW_PRIVATE=true for agenter som legitimt når private API-er.
Mål-pinning
CONNECT-målverten fanges opp ved etablering av tunnelen og brukes for hele tunnelens levetid. Etterfølgende forespørsler innenfor tunnelen kan ikke omdirigeres til en annen vert ved å manipulere Host-headeren. En uoverensstemmelse resulterer i 502.
Dette forhindrer en agent i å etablere en tunnel til api.openai.com og deretter sende forespørsler til internal-service.corp.
Header-håndtering
Hop-by-hop headere strippes fra både forespørsler og svar i henhold til RFC 7230 §6.1: Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailers, Transfer-Encoding, Upgrade.
Set-Cookie strippes fra oppstrøms svar for å forhindre at oppstrøms-systemer planter cookies i agentens HTTP-klient.
Forespørsels- og svar-kropper strømmer gjennom uten buffering. Forespørsels-kropper er begrenset til 64 MB som standard (CLAVITOR_PROXY_MAX_BODY_MB). Svar-kropper strømmer uten en hard grense; en loggadvarsel sendes når Content-Length overstiger 100 MB.
I URL-match-modus mapper proxyen hvelvfeltetiketter til HTTP-headere:
| Feltetikett | Innsatt header |
|---|---|
key, apikey, api_key, token, secret, bearer, access_token | Authorization: Bearer <value> |
x-api-key, api-key | X-API-Key: <value> |
username + password (paret) | Authorization: Basic base64(user:pass) |
| Alt annet | Avvist — ERR-PROXY-052 |
I plassholdermodus kontrollerer agenten hvilket felt som løses og hvor det går. Mappingen ovenfor gjelder kun for URL-match-modus.
Hver feil produserer en stabil ERR-PROXY-NNN-kode. Disse kodene er en del av proxyens offentlige grensesnitt — agenter og operatører kan matche dem for varsling og feilsøking.
| Område | Kategori |
|---|---|
001–019 | Oppsett (konfig, init, CA-generering, WASM) |
020–029 | Daemon livssyklus |
030–049 | Plassholder-løsning (clavitor:// URI-er) |
050–069 | URL-match-innsetting |
070–089 | Oppstrøms / TLS |
Identitetsfelt er utilgjengelige
Hvelvoppføringer støtter tre krypteringsnivåer. Hvelvkrypterte felt er klartekst metadata. Felt med Kryptering av påloggingsinformasjon dekrypteres med agentens nøkkel. Felt med Identitetskryptering er kryptert med en nøkkel serveren og proxyen aldri har sett. Kun hvelveieren, via sin maskinvarenøkkel, kan dekryptere dem.
Hvis en plassholder refererer til et identitetskryptert felt, returnerer proxyen ERR-PROXY-035. Ingen fallback, ingen delvis resultat. Feltet er arkitektonisk utilgjengelig fra proxyen.
Hva proxyen ikke beskytter mot
Proxyens trusselmodell er en kompromittert ferdighet eller prompt-injeksjon som får en autentisert agent til å høste påloggingsinformasjon. Hvelvets per-agent rate-begrensninger, unike oppføringskvoter og to-stegs nedlåsing er de primære forsvarsmekanismene. Proxyen legger til et nettverkslagshåndhevelsespunkt der påloggingsinformasjon løses per forespørsel og aldri holdes av agenten.
Proxyen kjører på samme maskin som agenten. En angriper med root-tilgang kan lese prosessminne, koble til en debugger, eller avskjære loopback-trafikk. Proxyen er et lag for innsetting av påloggingsinformasjon, ikke en maskinvaresikkerhetsgrense.
Hvis oppstrøms API-et speiler påloggingsinformasjonen tilbake i sitt svar (f.eks. et «whoami»-endepunkt), ser agenten den. Proxyen setter inn påloggingsinformasjon i forespørsler, ikke svar. Den filtrerer ikke hva som kommer tilbake.
Logging
Proxyen logger én linje per akseptert CONNECT og sender feillinjer for feil. Den logger aldri:
- Dekrypterte verdier for påloggingsinformasjon
- Fullstendige forespørsels-URL-er (spørringstrenger kan inneholde hemmeligheter — kun skjema + vert + sti logges)
- Forespørsels- eller svar-kropper
- Påloggingsinformasjons-dekrypteringsnøkkelen eller innholdet i sidecar-konfigurasjonen
Når proxyen oppdager at et 400-svar fra oppstrøms inneholder autentiseringsrelaterte nøkkelord (unauthorized, invalid token, etc.), logger den et diagnostisk hint som antyder at den innsatte påloggingsinformasjonen kan være utdatert. Svaret videresendes uendret.
Kryptografi
All Clavitor protokollkryptografi — AES-GCM feltdekryptering, HKDF nøkkelutledning, base62-koding, CVT token-utstedelse, CLV1 konfigurasjonspakke/utpakking — utføres inne i en enkelt WebAssembly-modul (clavis_crypto.wasm) lastet via wazero, en ren Go WASM-kjøretid. Ingen CGO. Ingen Go-reimplementering av Clavitor-primitiver.
WASM-modulen er kompilert fra samme Rust-crate (clavis-crypto) som brukes av nettleseren, CLI-en og nettleserutvidelsene. Én sannhetskilde, én binærfil, én revisjonsflate.
Proxyen bruker Go's crypto/tls for TLS-nettverket og crypto/ecdsa for MITM-sertifikatgenerering. Dette er transporthensyn, ikke Clavitor protokolloperasjoner.
Hemmeligheter (påloggingsinformasjons-dekrypteringsnøkkel, agent-ID, enhets-ID, hvelv-URL) lever i den krypterte CLV1 sidecar-konfigurasjonen, skrevet én gang under clavitor-proxy init. Operasjonelle brytere lever i miljøvariabler:
| Variabel | Standard | Formål |
|---|---|---|
CLAVITOR_PROXY_LISTEN | 127.0.0.1 | Lyttende grensesnitt. Sett til 0.0.0.0 for delte utrullinger, eller til en spesifikk grensesnitt-IP. |
CLAVITOR_PROXY_PORT | 1983 | Lyttende port |
CLAVITOR_PROXY_ALLOW_PRIVATE | false | Tillat tilkoblinger til RFC-1918 / private nettverk |
CLAVITOR_PROXY_MAX_BODY_MB | 64 | Begrensning for forespørsels-kroppsstørrelse |
CLAVITOR_PROXY_WRITE_TIMEOUT | 300 | Tidsavbrudd for svar-skriving i sekunder |
CLAVITOR_CONFIG | (exe-katalog) | Overstyr sti til sidecar-konfigurasjon |
Operasjonelle brytere er ikke hemmeligheter. De hører ikke hjemme i den krypterte konfigurasjonen. De hører hjemme der utrullingsverktøy allerede administrerer dem — miljøet.
Gjennomgå dette selv.
Kryptografien er en enkelt revisjonsvennlig WASM-artefakt. Trusselmodellen er dokumentert. Hvis du finner noe vi har oversett, vil vi gjerne høre om det.