Tunnistetietojen välityspalvelin — tekninen

Miten välityspalvelin toimii.

Mitä vastaan se suojaa. Mitä vastaan ei.

Tämä sivu on tietoturva-arvioijille, tunkeutumistestaajille ja insinööreille, jotka arvioivat välityspalvelimen uhkamallia. Se kuvaa, mitä välityspalvelin tekee protokollatasolla, missä tunnistetiedot esiintyvät muistissa ja mitä hyökkäyspintoja jää jäljelle.

Rakenne

Välityspalvelin on CONNECT-pohjainen HTTPS MITM -välityspalvelin. Tekoälyagentti asettaa HTTPS_PROXY-muuttujan osoittamaan siihen. Kun agentti tekee HTTPS-pyynnön, välityspalvelin sieppaa TLS-yhteyden, tarkastaa pyyntöotsakkeet tunnistetietoviitteiden varalta, ratkaisee ne Clavitorin holvia vasten ja välittää pyynnön injektoiduilla tunnistetiedoilla ylävirran API:lle.

Välityspalvelin kuuntelee oletusarvoisesti osoitteessa 127.0.0.1:1983 — sidecar-malli, jossa välityspalvelin ja agentti jakavat isännän. Jaetuissa käyttöönotoissa (yksi välityspalvelin palvelee useita agentteja yksityisessä verkossa, konttisidecar useille työkuormille, dedikoitu välityspalvelinisäntä) kuuntelu-rajapinta on määritettävissä CLAVITOR_PROXY_LISTEN-muuttujalla.

illustration: unknown name=proxy-sequence

Välityspalvelin on itsenäinen Go-binääri. Ei CGO:ta. Kaikki Clavitor-protokollan kryptografia kulkee kanonisen Rust-toteutuksen kautta, joka käännetään WebAssemblyksi ja ladataan wazero:lla käynnistyksen yhteydessä.

TLS-käsittely

Välityspalvelin luo itse allekirjoitetun ECDSA P-256 -juurivarmenteen ensimmäisellä käynnistyksellä, tallentaa sen binäärin hakemistoon tilalla 0600. Jokaiselle ylävirran isännälle luodaan pyydettäessä lehtisertifikaatti, jonka tämä CA allekirjoittaa, ja se välimuistitaan muistiin rajallisella poistolla (1 000 isäntää). Lehtisertifikaatit ovat voimassa 24 tuntia ja ne luodaan läpinäkyvästi uudelleen 23 tunnin kohdalla istunnon aikaisen vanhentumisen estämiseksi.

Agentin on luotettava välityspalvelimen CA-sertifikaattiin. Vie se komennolla clavitor-proxy ca.

Ylävirran yhteydet käyttävät vähintään TLS 1.3:a ALPN-neuvottelulla HTTP/2:lle ja HTTP/1.1:lle. Järjestelmän sertifikaattivarastoa käytetään ylävirran varmennukseen. Ei sertifikaattien kiinnitystä — välityspalvelin luottaa siihen, mihin käyttöjärjestelmä luottaa.

Credential lifecycle

Tunnistetietoja ei koskaan välimuistita, ei koskaan kirjoiteta levylle, eikä niitä säilytetä pidempään kuin yhden HTTP-pyynnön ajan.

Vaihe	Missä tunnistetieto esiintyy	Kesto
Levossa holvissa	AES-GCM-salattu teksti holvin tietokannassa	Kunnes poistettu
Siirrossa välityspalvelimeen	TLS-salattu JSON-vastaus holvin API:sta	Yksi HTTP-edestakainen matka
Purettu välityspalvelimessa	Prosessimuisti (Go-merkkijono keossa)	Yksi HTTP-pyyntö
Injektoitu ylävirran pyyntöön	TLS-salattu data johdolla ylävirtaan	Yksi HTTP-pyyntö

Välityspalvelin pitää agentin tunnistetietojen purkuavaimen (16 tavua) muistissa koko suoritusaikansa. Se ladataan salatusta sidecar-konfiguraatiosta (CLV1-muoto) käynnistyksen yhteydessä ja tyhjennetään hallitussa sammutuksessa. Avain ei koskaan poistu prosessista.

Sidecar-konfiguraatio on salattu AES-128-GCM:llä ja HMAC-SHA256:lla käyttäen deterministisiä avaimia, jotka on johdettu staattisesta siemenestä. Tämä on hämäystä, ei luottamuksellisuutta — turvallisuusraja on tiedosto-oikeudet (0600) ja tiedoston hallussapito. CLV1-muoto on jaettu välityspalvelimen, CLI:n ja selainlaajennuksen kesken.

Ratkaisutilat

Tila 1 — eksplisiittinen paikkamerkki

Agentti sisällyttää clavitor://Entry/field -viitteen pyyntöotsakkeeseen. Välityspalvelin etsii holvista merkintää nimen perusteella, noutaa sen, purkaa nimetyn kentän ja korvaa paikkamerkin todellisella arvolla.

Jos haku palauttaa nolla tai enemmän kuin yhden tuloksen, välityspalvelin palauttaa 502 vakaalla virhekoodilla. Paikkamerkkiä ei koskaan poisteta ja välitetä sellaisenaan.

Tila 2 — URL-haku

Kun paikkamerkkiä ei ole, välityspalvelin pyytää holvista merkintöjä, joiden URL-kenttä vastaa ylävirran isäntää. Jos täsmälleen yksi osuma löytyy tunnistettavalla kentän muodolla, välityspalvelin injektoi tunnistetiedot automaattisesti.

Nolla osumaa → läpivienti (ei tunnistetietojen odotusta). Useita osumia → 502 selvennysopastuksella. Tuntematon kentän muoto → 502.

Päätöspuu on deterministinen: paikkamerkki läsnä → ratkaise tai epäonnistu. Ei paikkamerkkiä → URL-haku tai läpivienti. Ei ole hiljaista varapolkuja, jossa epäonnistunut ratkaisu johtaa pyynnön menemiseen ylävirtaan ilman tunnistetietoja.

Agent identity

Oletusarvoisesti holvi näkee välityspalvelimen oman agenttitunnuksen jokaisessa pyynnössä. Nopeusrajoitukset, laajuustarkistukset ja auditointimerkinnät kohdistetaan välityspalvelimeen.

Kun useat agentit jakavat yhden välityspalvelininstanssin, paikkamerkki voi sisältää agenttitunnuksen: clavitor://agentid@Entry/field. Välityspalvelin lähettää tämän agenttitunnuksen holviin, joka soveltaa kyseisen agentin laajuuksia ja nopeusrajoituksia ja kirjaa pääsyn sen perusteella. Agenttitunnus on 32-merkkinen heksadesimaaliarvo, joka näkyy agentin tietosivulla holvin käyttöliittymässä.

# 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

Käyttöönotto	Identiteettimalli	Eristys
Yksi välityspalvelin per agentti	Välityspalvelimen ID = agentin ID (oletus)	Täysi — erillinen binääri, konfiguraatio, laajuus, nopeusrajoitukset
Jaettu välityspalvelin, ei agenttitunnusta URL-osoitteessa	Kaikki agentit jakavat välityspalvelimen ID:n	Jaettu laajuus ja nopeusrajoitukset
Jaettu välityspalvelin + `agentid@` URL-osoitteessa	Agenttikohtainen identiteetti	Agenttikohtainen laajuus, nopeusrajoitukset ja auditointi

URL-osoitteen agenttitunnus ei ole todennusmekanismi — välityspalvelimen CVT-token todentaa yhteyden. Agenttitunnus määrittää kohdistuksen: kenen laajuudet ovat voimassa, kenen nopeusrajoitukset lasketaan, kenen auditointijälki kirjaa pääsyn. Holvi hylkää tuntemattomat agenttitunnukset selkeällä virheellä.

Verkkoturvallisuus

SSRF-suojaus

Oletusarvoisesti välityspalvelin estää ylävirran yhteydet yksityisiin verkkoihin (RFC 1918), pilvipalvelun instanssimetatietoihin (169.254.169.254), loopbackiin, link-local-osoitteisiin ja operaattoritason NAT-alueisiin. DNS ratkaistaan ensin; kaikki palautetut IP-osoitteet validoidaan ennen TCP-yhteyden muodostamista, sulkien DNS-uudelleensidonta-TOCTOU-ikkunan.

Ohita asettamalla CLAVITOR_PROXY_ALLOW_PRIVATE=true agenteille, jotka tavoittavat laillisesti yksityisiä API:ita.

Kohdepinnitys

CONNECT-kohdeisäntä kaapataan tunnelin muodostamisen yhteydessä ja sitä käytetään koko tunnelin elinkaaren ajan. Myöhemmät pyynnöt tunnelin sisällä eivät voi uudelleenohjata toiseen isäntään manipuloimalla Host-otsaketta. Epäsuhta johtaa 502-virheeseen.

Tämä estää agenttia muodostamasta tunnelia api.openai.com-osoitteeseen ja lähettämästä sitten pyyntöjä internal-service.corp-osoitteeseen.

Otsakkeiden käsittely

Hop-by-hop-otsakkeet poistetaan pyynnöistä ja vastauksista RFC 7230 §6.1 mukaisesti: Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailers, Transfer-Encoding, Upgrade.

Set-Cookie poistetaan ylävirran vastauksista, jotta estetään ylävirran palveluita istuttamasta evästeitä agentin HTTP-asiakkaaseen.

Pyyntö- ja vastausrunkojen virta kulkee läpi ilman puskurointia. Pyyntöjen rungot on rajoitettu 64 Mt:iin oletusarvoisesti (CLAVITOR_PROXY_MAX_BODY_MB). Vastausten rungot virtaavat ilman kovaa rajaa; lokivaroitus annetaan, kun Content-Length ylittää 100 Mt.

Field-to-header mapping

URL-hakutilassa välityspalvelin vastaa holvin kenttien nimiä HTTP-otsakkeisiin:

Kentän nimi	Injektoitu otsake
`key`, `apikey`, `api_key`, `token`, `secret`, `bearer`, `access_token`	`Authorization: Bearer <value>`
`x-api-key`, `api-key`	`X-API-Key: <value>`
`username` + `password` (parina)	`Authorization: Basic base64(user:pass)`
Mikä tahansa muu	Hylätty — `ERR-PROXY-052`

Paikkamerkkitilassa agentti hallitsee, mikä kenttä ratkaistaan ja mihin se menee. Yllä oleva vastaavuus koskee vain URL-hakutilaa.

Error codes

Jokainen virhe tuottaa vakaan ERR-PROXY-NNN-koodin. Nämä koodit ovat osa välityspalvelimen julkista rajapintaa — agentit ja operaattorit voivat kohdistaa niihin hälytyksiä ja vianmääritystä varten.

Alue	Luokka
`001–019`	Asennus (konfiguraatio, alustus, CA-generointi, WASM)
`020–029`	Daemonin elinkaari
`030–049`	Paikkamerkin ratkaisu (`clavitor://` URI:t)
`050–069`	URL-haun injektointi
`070–089`	Ylävirta / TLS

Identiteettikentät ovat saavuttamattomissa

Holvin merkinnät tukevat kolmea salauskerrosta. Holvin salaus -kentät ovat selväkielistä metatietoa. Tunnistetietojen salaus -kentät puretaan agentin avaimella. Identiteetin salaus -kentät salataan avaimella, jota palvelin ja välityspalvelin eivät ole koskaan nähneet. Vain holvin omistaja voi purkaa ne laitteistoavaimellaan.

Jos paikkamerkki viittaa identiteetillä salattuun kenttään, välityspalvelin palauttaa ERR-PROXY-035. Ei varapolkua, ei osittaista tulosta. Kenttä on arkkitehtonisesti saavuttamaton välityspalvelimelta.

Mitä välityspalvelin ei suojaa

Välityspalvelimen uhkamalli on vaarantunut taito tai kehotteen injektointi, joka saa todennetun agentin keräämään tunnistetietoja. Holvin agenttikohtaiset nopeusrajoitukset, uniikkien merkintöjen kiintiöt ja kahden virheen lukitus ovat ensisijaisia puolustuskeinoja. Välityspalvelin lisää verkkotason toteutuspisteen, jossa tunnistetiedot ratkaistaan pyyntökohtaisesti eikä agentti koskaan säilytä niitä.

Vaarantunut isäntä

Välityspalvelin suoritetaan samalla koneella kuin agentti. Hyökkääjä, jolla on pääkäyttäjän oikeudet, voi lukea prosessimuistia, liittää debuggerin tai siepata loopback-liikennettä. Välityspalvelin on tunnistetietojen injektointikerros, ei laitteistoturvallisuusraja.

Tunnistetietojen vuotaminen API-vastauksen kautta

Jos ylävirran API toistaa tunnistetiedon vastauksessaan (esim. "kuka minä olen" -päätepiste), agentti näkee sen. Välityspalvelin injektoi tunnistetietoja pyyntöihin, ei vastauksiin. Se ei suodata sitä, mikä tulee takaisin.

Lokitus

Välityspalvelin kirjaa yhden rivin per hyväksytty CONNECT ja lähettää virherivejä epäonnistumisille. Se ei koskaan kirjaa lokiin:

Puretut tunnistetietojen arvot
Täydelliset pyyntö-URL-osoitteet (kyselymerkkijonot voivat sisältää salaisuuksia — vain skeema + isäntä + polku kirjataan)
Pyyntö- tai vastausrunkoja
Tunnistetietojen purkuavain tai sidecar-konfiguraation sisältöä

Kun välityspalvelin havaitsee, että 400-vastaus ylävirrasta sisältää todennukseen liittyviä avainsanoja (unauthorized, invalid token jne.), se kirjaa diagnostiikkavihjeen, joka viittaa siihen, että injektoitu tunnistetieto saattaa olla vanhentunut. Vastaus välitetään muuttumattomana.

Kryptografia

Kaikki Clavitor-protokollan kryptografia — AES-GCM-kentän purku, HKDF-avaimen johdanto, base62-koodaus, CVT-tokenin luonti, CLV1-konfiguraatiopaketin pakkaus/purku — suoritetaan yhden WebAssembly-moduulin (clavis_crypto.wasm) sisällä, joka ladataan wazero:n kautta, joka on puhdas Go-pohjainen WASM-suoritusympäristö. Ei CGO:ta. Ei Go:n uudelleentoteutusta Clavitor-primitiiveille.

WASM-moduuli käännetään samasta Rust-crate:sta (clavis-crypto), jota selain, CLI ja selainlaajennukset käyttävät. Yksi totuuden lähde, yksi binääri, yksi auditointipinta.

Välityspalvelin käyttää Go:n crypto/tls-kirjastoa TLS-liikenteeseen ja crypto/ecdsa:ta MITM-sertifikaattien luomiseen. Nämä ovat kuljetushuolia, eivät Clavitor-protokollan operaatioita.

Configuration

Salaisuudet (tunnistetietojen purkuavain, agenttitunnus, laitetunnus, holvin URL) sijaitsevat salatussa CLV1-sidecar-konfiguraatiossa, joka kirjoitetaan kerran clavitor-proxy init -komennon aikana. Toiminnalliset kytkimet sijaitsevat ympäristömuuttujissa:

Muuttuja	Oletus	Tarkoitus
`CLAVITOR_PROXY_LISTEN`	`127.0.0.1`	Kuuntelu-rajapinta. Aseta `0.0.0.0` jaettuihin käyttöönottoihin tai tiettyyn rajapinnan IP-osoitteeseen.
`CLAVITOR_PROXY_PORT`	`1983`	Kuunteluportti
`CLAVITOR_PROXY_ALLOW_PRIVATE`	`false`	Salli yhteydet RFC-1918 / yksityisiin verkkoihin
`CLAVITOR_PROXY_MAX_BODY_MB`	`64`	Pyynnön rungon kokorajoitus
`CLAVITOR_PROXY_WRITE_TIMEOUT`	`300`	Vastausten kirjoitusajan rajoitus sekunneissa
`CLAVITOR_CONFIG`	(suoritettavan tiedoston hakemisto)	Ohita sidecar-konfiguraation polku

Toiminnalliset kytkimet eivät ole salaisuuksia. Ne eivät kuulu salattuun konfiguraatioon. Ne kuuluvat sinne, missä käyttöönotto-työkalut niitä jo hallitsevat — ympäristöön.

Tarkasta tämä itse.

Kryptografia on yksi auditoitava WASM-artefakti. Uhkamalli on dokumentoitu. Jos löydät jotain, minkä olemme jättäneet huomiotta, haluamme kuulla siitä.

Ilmoita löydöstä ← Liiketoiminnan yleiskatsaus