ACL-id ja vähima privileegi printsiip
Sellel lehel
Vähima privileegi printsiibi rakendamine API-dele
Vähima privileegi printsiip on üks vanimaid kontseptsioone küberturvalisuses: süsteemi igal komponendil peaks olema juurdepääs ainult neile ressurssidele, mis on selle toimimiseks hädavajalikud. Idee on intuitiivne, kui viia see füüsilisse maailma – sa ei anna hoone peavõtit inimesele, kes kastab fuajees taimi. xAI API-võtmete puhul tähendab see, et iga võti peab olema piiratud ainult nende lõpp-punktide ja mudelitega, mida seda kasutav rakendus tegelikult vajab. Kui see võti lekib, pärib ründaja selle õigused: võti, mis on piiratud vestlusega ühe mudeliga, tekitab lõpmata vähem kahju kui võti, mis avab kogu kataloogi.
xAI rakendab seda printsiipi granulaarse ACL-i (Access Control List – juurdepääsu kontrollnimekiri) süsteemi kaudu, mida vaatleme allpool detailselt.
xAI ACL-süsteem
ACL-id järgivad formaati api-key:{type}:{value}. Sind puudutavad igapäevatöös kaks tüüpi: api-key:endpoint:{endpoint} piirab ligipääsetavaid lõpp-punkte ja api-key:model:{model_id} piirab kasutatavaid mudeleid. Samuti on olemas metamärk api-key:endpoint:*, mis annab juurdepääsu kõigile lõpp-punktidele – see on arenduseks mugav, kuid tootmiskeskkonnas keelatud, täpselt seetõttu, et see tühistab vähima privileegi eelise.
Lõpp-punktid, mida saad individuaalselt lubada, on: chat (vestluse lõpetamine, kaugelt kõige levinum), embed (manuste genereerimine), image (piltide genereerimine ja muutmine), models (mudelite loendi päring), tokenize (teksti tokeniseerimine), documents (dokumentide haldus) ja sample (proovivõtt).
Vaatame, kuidas see reaalses näites välja näeb. Kujuta ette klienditoe vestlusrobotit, mis kasutab vestlusrežiimis ainult grok-4.3 mudelit. Selle ideaalne võti näeb välja selline:
{
"name": "support-chatbot-prod",
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.3"
],
"qps": 5,
"qpm": 100,
"tpm": 500000,
"expireTime": "2026-12-31T23:59:59Z"
}
Loe seda konfiguratsiooni lepinguna: võti pääseb ligi ainult vestluse lõpp-punktile – pilte ei saa, manuseid ei saa, seega on nende eesmärkide väärkasutamine võimatu. See saab kasutada ainult grok-4.3 mudelit, mis takistab juhuslikke (või pahatahtlikke) päringuid kallimatele mudelitele. See on piiratud 5 päringuga sekundis ja 100-ga minutis ning aegub teadaoleval kuupäeval. Kui projektis töötav arendaja üritab kunagi lisada piltide genereerimist ilma kedagi teavitamata, keeldub API seda tegemast: tehniline piirang jõustab arhitektuurilise otsuse.
Kiiruse piirangud: täiendav turvakiht
ACL-id vastavad küsimusele „mis“, kiiruse piirangud vastavad küsimusele „kui palju“. QPS (Queries Per Second – päringuid sekundis) seab ülempiiri päringute arvule sekundis: see on sinu kaitse juhuslike tõusude vastu – näiteks reede õhtul refaktoringu käigus tekkinud lõpmatu tsükkel või DDoS-rünnak, mis põrkab su rakendusest tagasi. QPM (Queries Per Minute – päringuid minutis) ühtlustab liiklust pikema perioodi vältel ja tabab kuritarvitusi, mis jääksid QPS radarist välja. TPM (Tokens Per Minute – tokeneid minutis) seab omakorda ülempiiri tarbitud tokenite mahule: see kaitseb väga pikkade üksikpäringute eest – näiteks kasutaja, kes kleepib sinu vestlusrobotisse 200-leheküljelise dokumendi –, mis kurnaksid su eelarve minutitega, ületamata seejuures kunagi lubatud päringute arvu.
Võtmestrategia keskkonna kohta
Praktikas ei konfigureeri sa mitte ühte võtit, vaid võtmepere, ja igal keskkonnal on oma loogika. Arenduses pöörad tootmisloogika tagurpidi: lai juurdepääs, ranged piirangud.
{
"name": "dev-team-alpha",
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 2,
"qpm": 30,
"tpm": 100000,
"expireTime": "2026-06-30T23:59:59Z"
}
Arendajad saavad kõike uurida, kuid madalad piirangud hoiavad ära arveüllatused, kui test läheb valesti. Ettevalmistuskeskkonnas (staging) seevastu kopeerid tootmise ACL-id täpselt (api-key:endpoint:chat, api-key:model:grok-4.3, QPS 5, QPM 100, TPM 500000): see on ainus viis tuvastada õiguste probleeme ülesvoolu – kui ettevalmistuskood üritab sooritada päringut, mille tootmine tagasi lükkab, on parem see avastada nüüd kui esimesel tunnil pärast live-minemist. Tootmisvõti aga ühendab ettevalmistuskeskkonna ranged õigused piirangutega, mis on mõõdistatud reaalse liikluse jaoks (näiteks QPS 20, QPM 600, TPM 2000000), ning planeeritud aegumiskuupäevaga – "expireTime": "2027-03-31T23:59:59Z" võtmel nimega prod-chatbot-v2.
Õiguste kontrollimine ja auditeerimine
Et näha, mida aktiivne võti tegelikult teha tohib, päri API-lt võtme enda abil:
curl https://api.x.ai/v1/api-key \
-H "Authorization: Bearer $XAI_API_KEY"
Vastus loetleb kehtivad ACL-id, olekud api_key_blocked ja api_key_disabled, võtme maskeeritud versiooni (redacted_api_key) ja team_id. Harjumuseks peaks saama nende ACL-ide regulaarne võrdlemine rakenduse tegelike vajadustega: õigused kipuvad ajas kuhjuma, mitte kunagi iseenesest vähenema. Mudelite poolelt tagastab lõpp-punkt GET /auth/teams/{teamId}/models sinu meeskonnale kättesaadavate mudelite loendi koos hindadega – väärtuslik teave asjakohaste mudeli-ACL-ide määratlemiseks ja kasutamata kallite mudelite välistamiseks.
Selle kõige kinnistamiseks vii läbi oma võtmete täielik audit. Loetle iga meeskonna aktiivsed võtmed ja päri seejärel igaüht: kas selle ACL-id on minimaalsed, ilma metamärkideta tootmiskeskkonnas? Kas selle kiiruse piirangud on mõistlikud? Kas aegumiskuupäev on määratud? Kas selle nimi identifitseerib rakendust ja keskkonda – „prod-chatbot-v2“ räägib loo, „key-test-2“ ei räägi midagi? Kustuta orbudeks jäänud võtmed ja dokumenteeri tulemus: see dokument serveerib lähtepunktina järgmisele auditile ja näed pilguga, mis on vahepeal muutunud.
Peamised punktid
- Igal võtmel peavad olema piiravad ACL-id: ainult vajalikud lõpp-punktid ja mudelid
- Ära kunagi kasuta tootmiskeskkonnas metamärki
* - Kombineeri ACL-id kiiruse piirangutega (QPS, QPM, TPM), mis on kohandatud reaalsele kasutusele
- Loo erinevad võtmed iga keskkonna (dev, staging, prod) ja iga rakenduse jaoks – ettevalmistuskeskkond samade ACL-idega kui tootmine
- Auditeeri regulaarselt oma aktiivsete võtmete õigusi kasutades
GET /v1/api-key