Security Blog

Miten annan tekoälyagentille API-avaimen näkemättä avainta itse?

#44

November 20, 2026 · By Mila

← All posts

Antakaa agentille viittaus avaimen sijaan ja antakaa samalla koneella toimivan välityspalvelimen lisätä oikea avain pyyntöön sen lähtiessä. Tässä perustelu sille, miksi ympäristömuuttujat eivät enää riitä, ja miten asennus tehdään.

Antakaa agentille viittaus avaimen sijaan ja antakaa pienen välityspalvelimen samalla koneella vaihtaa oikea avain pyyntöön sen lähtiessä. Agentti kirjoittaa salaisuuden paikalle clavitor://OpenAI/key. API vastaanottaa oikean avaimen. Agentti ei koskaan pidä sitä käsissään, joten se ei voi tulostaa sitä, kirjata sitä loktiin eikä suostutella luovuttamaan sitä.

Siinä koko idea. Loput tästä sivusta käsittelevät sitä, miksi se on tärkeää, ja miten asennus tehdään.

Miksi "laita se vain ympäristömuuttujaan" ei enää riitä

Vuosi sitten export OPENAI_API_KEY=sk-... oli normaali tapa antaa avain skriptille. Kukaan ei hämmästellyt.

Sitten skripti alkoi ajatella itse.

Tekoälyagentti lukee tiedostoja, ajaa työkaluja, kirjoaa lokeja ja puhuu vieraille internetissä. Jokainen näistä on ulospääsyreitti avaimelle, jonka se pitää hallussaan:

  • Ympäristö. Kaikki, mitä agentti ajaa, perii sen. Se näkyy hakemistossa /proc, kaatumisdumpeissa ja CI-tulosteessa.
  • Muisti. Noutakaa avain ajon aikana, ja se silti pysyy prosessissa niin kauan kuin agentti on käynnissä.
  • Keskustelu. Kehotteinjektio verkkosivulla tai issue-kommentissa pyytää agenttia "liittämään konfiguraationsa mukaan debuggausta varten". Avulias agentti tekee niin.

Mikään näistä ei vaadi bugia agentissa. Se vaatii vain, että avain on jossakin, johon agentti pääsee käsiksi.

Kaava: agentti pyytää, välityspalvelin allekirjoittaa

Ajatelkaa hotellin avainkorttia. Vieras voi avata huoneensa. Vieras ei koskaan näe pääavainta, ja ovi kirjaa jokaisen avauksen.

API-avaimen kohdalla se näyttää tältä:

  1. Oikea avain sijaitsee holvissa salattuna.
  2. Välityspalvelin toimii agentin vieressä samalla koneella.
  3. Agentti lähettää HTTPS-pyyntönsä viittauksella avaimen paikalla.
  4. Välityspalvelin noutaa arvon holvista, lisää sen pyyntöön ja välittää sen eteenpäin.
  5. Agentin puolella on vain viittaus.

Agentin lokit näyttävät viittauksen. Samoin sen konteksti-ikkuna. Ei ole mitään vuotettavaa.

Miten asennus tehdään Clavitorilla

Näin rakensimme sen. Yksi binääri, yksi ympäristömuuttuja, ei muutoksia agentin koodiin.

Luokaa agentille asiakas holviin tarvittavine oikeuksineen, rekisteröikää sitten välityspalvelin ja käynnistäkää se:

$ clavitor-proxy init
$ clavitor-proxy ca
$ clavitor-proxy serve

init rekisteröi välityspalvelimen kyseiseksi asiakkaaksi. ca tulostaa välityspalvelimen varmentajan: lisätkää se agentin HTTP-asiakkaan käyttämään luottamusvarastoon, koska välityspalvelin avaa agentin HTTPS-yhteyden itse. Osoittakaa sitten agentti välityspalvelimeen:

$ export HTTPS_PROXY="http://clavitor:$(cat proxy-auth)@127.0.0.1:1983"

$ curl -H "Authorization: Bearer clavitor://OpenAI/key" \
    https://api.openai.com/v1/chat/completions

proxy-auth on välityspalvelimen oma pääsytunnus, binäärin vieressä oleva tiedosto. Jokaisen yhteyden on kannettava sitä, jotta toinen käyttäjä samalla koneella ei voi lainata välityspalvelinta. Välityspalvelin kuuntelee osoitteessa 127.0.0.1:1983 ja vain sillä koneella, ellei sitä aseteta tarkoituksella luotettuun yksityisverkkoon.

Se toimii minkä tahansa agentin kanssa, jonka HTTP-asiakas noudattaa HTTPS_PROXY-muuttujaa: Claude Code, Codex, omat skriptinne. Tunnistetieto menee vain isäntään, jonka kohde listaa verkko-osoitteenaan, joten kehotteinjektiolla manipuloitu agentti ei voi osoittaa samaa viittausta vieraan palvelimelle. Vaihe vaiheelta -asennusohje on välityspalvelindokumentaatiossa.

Entä agentin muut salaisuudet?

Kaikki salaisuudet eivät kulje HTTP-otsakkeessa. Julkaisusalasana, SSH-avain, kaksivaiheisen kirjautumisen koodi.

Näiden kohdalla agentti pyytää holvilta yhden nimetyn kohteen kerrallaan clavitor-cli-työkalulla, ja vain kohteita, jotka sille on annettu:

$ clavitor-cli get "GitHub Deploy" --field password

$ clavitor-cli get "Stripe API" --field key
clavitor-cli: CV-2041: Access denied.

Agentti ei voi listata holvia. Nimellä etsintä näyttää enintään viisi osumaa, ja niiden yläpuolella vain lukumäärän.

Tunnistautujakoodit toimivat samalla tavalla. clavitor-cli totp "GitHub" laskee nykyisen koodin agentin koneella, joten se pääsee läpi kaksivaiheisesta kirjautumisesta ilman että kenenkään tarvitsee lukea puhelinta. Holvi pitää salaisuuden salattuna.

Mitä tämä ei ratkaise

Välityspalvelin pitää avaimen poissa agentilta. Se ei tee agentista luotettavaa.

  • Vaarannettu agentti voi silti käyttää annettua pääsyä. Se vain ei voi viedä avainta mukanaan.
  • Koneen järjestelmänvalvojan oikeudet omaava henkilö voi käyttää välityspalvelinta tai lukea sen muistin.
  • API, joka kaikuttaa avaimenne takaisin vastauksessaan, luovuttaa sen agentille. Välityspalvelin lisää avaimet pyyntöihin eikä suodata vastauksia.

Siksi ympärillä oleva pääsy on yhtä tärkeää kuin välityspalvelin:

  • Oikeudet. Jokainen agentti saa vain tarvitsemansa kohteet. Työagentti näkee GitHubin ja AWS:n. Julkaisuagentti näkee SSH-avaimet ja tietokannan.
  • Lukurajat. Jokainen agentti saa lukea vain tietyn määrän eri kohteita minuutissa ja tunnissa, ja te asetatte luvut. Agentti, joka ylittää tuntirajansa kahdesti kahden tunnin sisällä, lukitaan, kunnes avaatte sen.
  • Kirjanpito. Jokainen luku kirjataan lokiin: mikä agentti, mikä kohde, milloin.

Ajatteletteko useita agentteja? Antakaa jokaiselle oma välityspalvelin ja oma rekisteröinti. Kullakin on silloin omat oikeutensa, omat rajansa ja oma jälkensä, eikä agentti A näe agentin B avaimia.

Lyhyesti

Älkää antako agentille avaintanne. Antakaa sille avaimen nimi ja pitäkää avain askeleen päässä paikassa, joka päättää joka kerta, saako tämä agentti käyttää sitä juuri nyt.

Asentakaa välityspalvelin tai katsokaa, miten agenttien pääsy toimii.