Credential proxy — teknisk
Hur proxyn fungerar.
Vad den skyddar mot. Vad den inte gör.
Den här sidan är för säkerhetsgranskare, penetrationstestare och ingenjörer som utvärderar proxyns hotmodell. Den beskriver vad proxyn gör på protokollnivå, var inloggningsuppgifter finns i minnet och vilka attackytor som återstår.
Arkitektur
Proxyn är en CONNECT-baserad HTTPS MITM-proxy. En AI-agent ställer in HTTPS_PROXY så att den pekar på den. När agenten gör en HTTPS-begäran avlyssnar proxyn TLS-anslutningen, inspekterar request-headers efter referenser till inloggningsuppgifter, löser upp dem mot Clavitor valv och vidarebefordrar begäran med injicerade inloggningsuppgifter till uppströms-API:et.
Proxyn lyssnar på 127.0.0.1:1983 som standard — sidecar-mönstret där proxyn och agenten delar en värd. För delade driftsättningar (en proxy som betjänar flera agenter i ett privat nätverk, container-sidecar till flera arbetsbelastningar, dedikerad proxy-värd) är lyssningsgränssnittet konfigurerbart via CLAVITOR_PROXY_LISTEN.
Proxyn är en fristående Go-binärfil. Ingen CGO. All Clavitor-protokollkryptografi går via en kanonisk Rust-implementation kompilerad till WebAssembly och laddad via wazero vid uppstart.
TLS-hantering
Proxyn genererar en självsignerad ECDSA P-256 root CA vid första körningen, beständig i binärfilens katalog med läge 0600. För varje uppströmsvärd skapas ett leaf-certifikat vid behov, signerat av denna CA, och cachas i minnet med begränsad borttagning (1 000 värdar). Leaf-certifikat är giltiga i 24 timmar och regenereras transparent vid 23-timmarsmärket för att förhindra utgång mitt under en session.
Agenten måste lita på proxyns CA-certifikat. Exportera det med clavitor-proxy ca.
Uppströmsanslutningar använder TLS 1.3 minimum med ALPN-förhandling för HTTP/2 och HTTP/1.1. Systemets certifikatpool används för uppströmsverifiering. Ingen certifikat-pinning — proxyn litar på vad operativsystemet litar på.
Inloggningsuppgifter cachas aldrig, skrivs aldrig till disk och hålls aldrig längre än en HTTP-begäran.
| Fas | Var inloggningsuppgiften finns | Varaktighet |
|---|---|---|
| I vila i valv | AES-GCM-chiffertext i valvdatabasen | Tills raderad |
| Under överföring till proxy | TLS-krypterat JSON-svar från valv-API | En HTTP-tur och retur |
| Dekrypterad i proxy | Processminne (Go-sträng på heap) | En HTTP-begäran |
| Injektion i uppströmsbegäran | TLS-krypterade byte på tråden till uppströms | En HTTP-begäran |
Proxyn håller agentens inloggningsuppgifts-dekrypteringsnyckel (16 byte) i minnet under hela sin körtid. Den laddas från den krypterade sidecar-konfigurationen (CLV1-format) vid uppstart och rensas vid en graciös avstängning. Nyckeln lämnar aldrig processen.
Sidecar-konfigurationen är krypterad med AES-128-GCM och HMAC-SHA256 med deterministiska nycklar härledda från ett statiskt frö. Detta är obfuskering, inte konfidentialitet — säkerhetsgränsen är filrättigheter (0600) och innehav av filen. CLV1-formatet delas mellan proxyn, CLI och webbläsartillägget.
Upplösningslägen
Läge 1 — explicit platshållare
Agenten inkluderar en clavitor://Entry/field-referens i en request-header. Proxyn söker i valvet efter posten med namnet, hämtar den, dekrypterar det namngivna fältet och ersätter platshållaren med det verkliga värdet.
Om sökningen ger noll eller fler än ett resultat returnerar proxyn 502 med en stabil felkod. Platshållaren tas aldrig bort och vidarebefordras som den är.
Läge 2 — URL-matchning
När ingen platshållare finns, frågar proxyn valvet efter poster vars URL-fält matchar uppströmsvärden. Om exakt en matchning finns med en igenkänd fältform, injicerar proxyn inloggningsuppgifter automatiskt.
Noll matchningar → genomströmning (ingen förväntan på inloggningsuppgifter). Flera matchningar → 502 med vägledning för disambiguering. Okänd fältform → 502.
Beslutsträdet är deterministiskt: platshållare finns → lös upp eller misslyckas. Ingen platshållare → URL-matchning eller genomströmning. Det finns ingen tyst fallback-väg där en misslyckad upplösning resulterar i att en begäran går till uppströms utan inloggningsuppgifter.
Som standard ser valvet proxyns egen agent-ID på varje begäran. Hastighetsbegränsningar, omfångskontroller och granskningsposter tillskrivs proxyn.
När flera agenter delar en proxyinstans kan platshållaren inkludera ett agent-ID: clavitor://agentid@Entry/field. Proxyn skickar detta agent-ID till valvet, som tillämpar den agentens omfång och hastighetsbegränsningar och loggar åtkomsten mot den. Agent-ID är det 32-teckniga hexadecimala värdet som visas på agentens detaljsida i valv-UI:t.
# 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
| Drift | Identitetsmodell | Isolering |
|---|---|---|
| En proxy per agent | Proxy-ID = agent-ID (standard) | Fullständig — separat binärfil, konfiguration, omfång, hastighetsbegränsningar |
| Delad proxy, inget agent-ID i URL | Alla agenter delar proxyns ID | Delat omfång och hastighetsbegränsningar |
Delad proxy + agentid@ i URL | Per-agentidentitet | Per-agentomfång, hastighetsbegränsningar och granskning |
Agent-ID:t i URL:en är inte en autentiseringsmekanism — proxyns CVT-token autentiserar anslutningen. Agent-ID bestämmer tillskrivning: vems omfång gäller, vems hastighetsbegränsningar räknas, vems granskningslogg registrerar åtkomsten. Valvet avvisar okända agent-ID:n med ett tydligt fel.
Nätverkssäkerhet
SSRF-skydd
Som standard blockerar proxyn uppströmsanslutningar till privata nätverk (RFC 1918), molninstansmetadata (169.254.169.254), loopback, länk-lokala och carrier-grade NAT-intervall. DNS löses först; alla returnerade IP-adresser valideras innan TCP-anslutningen upprättas, vilket stänger DNS-återbindningsfönstret TOCTOU.
Åsidosätt med CLAVITOR_PROXY_ALLOW_PRIVATE=true för agenter som legitimt når privata API:er.
Mål-pinning
CONNECT-mål-värden fångas vid tunnelupprättande och används under hela tunnelns livslängd. Efterföljande begäranden inom tunneln kan inte omdirigeras till en annan värd genom att manipulera Host-headern. En avvikelse resulterar i 502.
Detta förhindrar en agent från att upprätta en tunnel till api.openai.com och sedan skicka begäranden till internal-service.corp.
Header-hantering
Hop-by-hop-headers tas bort från både begäranden och svar enligt RFC 7230 §6.1: Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailers, Transfer-Encoding, Upgrade.
Set-Cookie tas bort från uppströms-svar för att förhindra att uppströms-tjänster planterar cookies i agentens HTTP-klient.
Request- och response-kroppar strömmas igenom utan buffring. Request-kroppar är begränsade till 64 MB som standard (CLAVITOR_PROXY_MAX_BODY_MB). Response-kroppar strömmas utan en hård gräns; en loggvarning ges när Content-Length överstiger 100 MB.
I URL-matchningsläge mappar proxyn valv-fältetiketter till HTTP-headers:
| Fältetikett | Injicerad header |
|---|---|
key, apikey, api_key, token, secret, bearer, access_token | Authorization: Bearer <value> |
x-api-key, api-key | X-API-Key: <value> |
username + password (parade) | Authorization: Basic base64(user:pass) |
| Allt annat | Avvisat — ERR-PROXY-052 |
I platshållarläge kontrollerar agenten vilket fält som ska lösas upp och vart det ska gå. Mappningen ovan gäller endast för URL-matchningsläge.
Varje fel ger en stabil ERR-PROXY-NNN-kod. Dessa koder är en del av proxyns publika gränssnitt — agenter och operatörer kan matcha dem för larm och felsökning.
| Omfång | Kategori |
|---|---|
001–019 | Installation (konfiguration, initiering, CA-generering, WASM) |
020–029 | Daemon-livscykel |
030–049 | Platshållarupplösning (clavitor://-URI:er) |
050–069 | URL-matchningsinjektion |
070–089 | Uppströms / TLS |
Identitetsfält är oåtkomliga
Valvposter stöder tre krypteringsnivåer. Valvkrypterade fält är klartextmetadata. Inloggningsuppgiftskrypterade fält dekrypteras med agentens nyckel. Identitetskrypterade fält krypteras med en nyckel som servern och proxyn aldrig har sett. Endast valvägaren, via sin hårdvarusäkerhetsnyckel, kan dekryptera dem.
Om en platshållare refererar till ett identitetskrypterat fält returnerar proxyn ERR-PROXY-035. Ingen fallback, inget partiellt resultat. Fältet är arkitektoniskt oåtkomligt från proxyn.
Vad proxyn inte skyddar mot
Proxyns hotmodell är en komprometterad färdighet eller promptinjektion som får en autentiserad agent att skörda inloggningsuppgifter. Valvets per-agent-hastighetsbegränsningar, unika postkvoter och två-varningar-låsning är de primära försvaren. Proxyn lägger till en nätverksnivå-verkställningspunkt där inloggningsuppgifter löses upp per-begäran och aldrig hålls av agenten.
Proxyn körs på samma maskin som agenten. En angripare med root-åtkomst kan läsa processminnet, koppla en debugger eller avlyssna loopback-trafik. Proxyn är ett lager för injicering av inloggningsuppgifter, inte en hårdvarusäkerhetsgräns.
Om uppströms-API:et ekar inloggningsuppgifterna tillbaka i sitt svar (t.ex. en "whoami"-slutpunkt), ser agenten det. Proxyn injicerar inloggningsuppgifter i begäranden, inte svar. Den filtrerar inte vad som kommer tillbaka.
Loggning
Proxyn loggar en rad per accepterad CONNECT och ger felrader för misslyckanden. Den loggar aldrig:
- Dekrypterade inloggningsuppgiftsvärden
- Fullständiga request-URL:er (frågesträngar kan bära hemligheter — endast schema + värd + sökväg loggas)
- Request- eller response-kroppar
- Inloggningsuppgifts-dekrypteringsnyckeln eller innehållet i sidecar-konfigurationen
När proxyn upptäcker att ett 400-svar från uppströms innehåller autentiseringsrelaterade nyckelord (unauthorized, invalid token, etc.), loggar den en diagnostisk ledtråd som antyder att den injicerade inloggningsuppgiften kan vara föråldrad. Svaret vidarebefordras oförändrat.
Kryptografi
All Clavitor-protokollkryptografi — AES-GCM fältdekryptering, HKDF nyckelderivering, base62-kodning, CVT-token-minting, CLV1 konfigurationspackning/uppackning — körs inuti en enda WebAssembly-modul (clavis_crypto.wasm) laddad via wazero, en ren Go WASM-runtime. Ingen CGO. Ingen Go-reimplementering av Clavitor-primitiver.
WASM-modulen kompileras från samma Rust-crate (clavis-crypto) som används av webbläsaren, CLI och webbläsartilläggen. En sanningskälla, en binärfil, en granskningsyta.
Proxyn använder Go:s crypto/tls för TLS-tråden och crypto/ecdsa för MITM-certifikatgenerering. Dessa är transportfrågor, inte Clavitor-protokolloperationer.
Hemligheter (inloggningsuppgifts-dekrypteringsnyckel, agent-ID, enhets-ID, valv-URL) finns i den krypterade CLV1 sidecar-konfigurationen, skriven en gång under clavitor-proxy init. Operativa reglage finns i miljövariabler:
| Variabel | Standard | Syfte |
|---|---|---|
CLAVITOR_PROXY_LISTEN | 127.0.0.1 | Lyssningsgränssnitt. Ställ in på 0.0.0.0 för delade driftsättningar, eller till en specifik gränssnitts-IP. |
CLAVITOR_PROXY_PORT | 1983 | Lyssningsport |
CLAVITOR_PROXY_ALLOW_PRIVATE | false | Tillåt anslutningar till RFC-1918 / privata nätverk |
CLAVITOR_PROXY_MAX_BODY_MB | 64 | Begränsning av request-kroppsstorlek |
CLAVITOR_PROXY_WRITE_TIMEOUT | 300 | Svarsskrivningstid i sekunder |
CLAVITOR_CONFIG | (exe-katalog) | Åsidosätt sökväg till sidecar-konfiguration |
Operativa reglage är inte hemligheter. De hör inte hemma i den krypterade konfigurationen. De hör hemma där driftsättningsverktyg redan hanterar dem — miljön.
Granska detta själv.
Kryptografin är en enda granskningsbar WASM-artefakt. Hotmodellen är dokumenterad. Om du hittar något vi har missat vill vi höra det.