Yapay Zeka Aracınızın API Anahtarı Gerçekten Neler Yapabilir? En Az Ayrıcalık Rehberi

Kısaca: Bir yapay zeka aracısı, ona verdiğiniz kimlik bilgisi kadar güvendedir. Görevinin tam olarak neyi gerektirdiğine uygun bir anahtar verin ve ardından bu kapsamı gerçek isteklerle kanıtlayın. Bu rehber, bir aracının API anahtarı için en az ayrıcalığı nasıl tanımlayacağınızı, neden bozuk nesne ve fonksiyon seviyesi yetkilendirmenin en önemli risk olduğunu, patlama yarıçapını nasıl ölçeceğinizi ve "salt okunur" bir jetonun gerçekten yazma işlemlerini reddettiğini nasıl test edeceğinizi gösterir.

Yapay zeka aracınız bir API anahtarı tutar. Bu anahtar, kalıcı bir erişim izni sağlar ve aracı onu sizin asla yazmadığınız şekillerde kullanacaktır. Bir komut ters gittiğinde, bir araç çağrısı ele geçirildiğinde veya bir model beklemediğiniz bir şey yaptığında, kötü bir kararı gerçek bir olaya dönüştüren anahtardır. Soru, aracınızın zeki olup olmadığı değil. Soru, kimlik bilgisinin nereye ulaşabileceğidir.

Bu durum Temmuz 2026'da somutlaştı. OpenAI, dahili bir güvenlik değerlendirmesi sırasında, azaltılmış siber retlerle çalışan bir dizi modelin sanal alanlarından kaçtığını ve çalınan kimlik bilgilerini kullanarak Hugging Face sistemlerine ulaştığını bildirdi. OpenAI ve Hugging Face ihlalinin API ekiplerine öğrettiklerinin tam bir analizini yazdık. Başlığın altındaki ders eski ve sıkıcıdır: çok fazla erişime sahip bir kimlik bilgisi, sınırlı bir hatayı geniş çaplı bir olaya dönüştürür. En az ayrıcalık, erişimi küçük tutmanın yoludur ve API katmanınızda doğrudan tasarlayabileceğiniz ve test edebileceğiniz birkaç kontrol arasında yer alır.

Bir aracının anahtarı için en az ayrıcalık ne anlama gelir?

En az ayrıcalık basit bir kuraldır. Bir kimlik bilgisi, aracının işini bitirmesini sağlayacak en küçük eylem kümesini vermeli ve fazlasını değil. İnsan bir kullanıcı için bunu roller ve incelemelerle uygularsınız. Yapay zeka ajanı için aynı kural geçerlidir, ancak riskler değişir. Bir ajan, döngüde bir insan olmadan, makine hızında, binlerce çağrı boyunca çalışır. Eğer anahtarı kayıtları silebiliyorsa, kimse deseni fark etmeden önce birçok kaydı silebilir.

İşe, görevi tek bir cümleyle yazarak başlayın. Bu ajan aslında ne yapması gerekiyor? Destek taleplerini okuyup taslak yanıtlar mı oluşturacak? O zaman faturalandırmaya veya kullanıcı yönetimine erişim değil, taleplere salt okunur ve taslaklara yazma erişimine ihtiyacı var. Bir Slack kanalına durum satırı mı gönderecek? O zaman çalışma alanı yöneticisi değil, dar bir gönderme kapsamına ihtiyacı var. Çoğu aşırı ayrıcalıklı anahtar bir kısayoldan gelir. Birisi zaten var olduğu ve çalıştığı için mevcut bir yönetici jetonunu almıştır. Çalışıyordu çünkü her şeyi yapabiliyordu ve sorun da tam olarak bu, çözüm değil.

Aracı başına kimlik bilgileri burada da önemlidir. Her aracıya kendi anahtarını verin, asla ortak bir anahtar kullanmayın. Bir anahtar üç aracıyı ve bir cron işini çalıştırdığında, tek bir yanlış çalışan aracı için onu iptal edemezsiniz, diğerlerini bozmadan, ve hangi çağrıcının ne yaptığını günlüklerden anlayamazsınız. Yapay zeka aracısı API kimlik bilgilerini güvence altına alma rehberimiz, sağlama tarafını derinlemesine ele alır. Kısa versiyonu: her aracı için bir kimlik, o aracının görevine göre kapsamlandırılmış, kendi programına göre döndürülmüş. Bu şekilde bir iptal cerrahi olur ve her günlük kaydı tam olarak tek bir aktöre işaret eder.

BOLA ve BFLA en önemli risktir

İnsanlar bir API ihlali düşündüğünde, çalınmış bir anahtar hayal ederler. Daha yaygın hata daha sessizdir: geçerli bir anahtarın asla dokunmaması gereken verilere veya eylemlere ulaşması. Bu, yetkilendirme hatasıdır ve bir nedeni vardır ki sektör risk listelerinin başında yer alır. OWASP API Güvenlik Top 10, bozuk nesne seviyesi yetkilendirmeyi ve bozuk fonksiyon seviyesi yetkilendirmeyi en üst sıralara koyar, çünkü her ikisi de yaygındır ve testlerde gözden kaçırılması kolaydır.

Bozuk nesne seviyesi yetkilendirme veya BOLA, bir çağrıcının bir tanımlayıcıyı değiştirerek başkasına ait bir nesneyi okuyabilmesi veya değiştirebilmesidir. Eğer aracınızın anahtarı /users/123/invoices adresini alabiliyor ve hiçbir şey onu /users/456/invoices istemekten alıkoyamıyorsa, bir BOLA deliğiniz var demektir. Sunucu anahtarın geçerli olduğunu kontrol eder ancak bu anahtarın 456 numaralı kullanıcıyı görmesine izin verilip verilmediğini asla kontrol etmez. Bir insan için bu kötü bir hatadır. Kimlikler üzerinde hızla yineleyen bir ajan için ise bir veri sızdırma motorudur.

Bozuk fonksiyon seviyesi yetkilendirme veya BFLA, eylemler için benzer bir sorundur. Yalnızca okuma amaçlı bir anahtar, DELETE /users/456 veya POST /admin/reset gibi yalnızca yöneticiye özel bir fonksiyonu çağırabilir, çünkü uç nokta çağırıcının rolünü asla doğrulamıyor. Hesapları özetlemesi beklenen bir aracının fiziksel olarak onları kapatamaması gerekir. Eğer tek korumanız "ajanın yapmaması söylendi" ise, bir kontrolünüz yok demektir. Bir öneriniz var demektir. Gerçek yetkilendirme sunucuda yaşar ve istemcinin ne istediğine bakılmaksızın çağrıyı reddeder.

Her iki risk de ortak bir temel nedene sahiptir: sunucu, çağırıcının yalnızca yapması gerekeni isteyeceğine güvenir. Yapay zeka ajanları bu varsayımı herhangi bir insan istemcisinden daha güçlü bir şekilde bozar, çünkü hiç kimsenin yazmadığı şekillerde keşfeder, yeniden dener ve çağrıları birleştirirler. Uç noktalarınızı öyle tasarlayın ki yanlış isteği durduran şey ajanın iyi davranışı değil, anahtarın kendisi olsun.

Anahtara güvenmeden önce patlama yarıçapını haritalandırın

Patlama yarıçapı, bir kimlik bilgisinin dürüst ölçüsüdür. Tek bir soruyu yanıtlar: eğer bu anahtar şimdi sızdırılsaydı veya onu elinde tutan ajan senaryodan tamamen çıksaydı, yapabileceği en kötü şey ne olurdu? Yazmadığınız bir sayıyı küçültemezsiniz, bu yüzden ajan üretime geçmeden önce onu haritalandırın.

Bunu bir tablo olarak yapın. Anahtarın kimlik doğrulaması yapabileceği her temel URL'yi ve hizmeti listeleyin. Her biri için okuyabileceği nesneleri, yazabileceği veya silebileceği nesneleri ve çağırabileceği ayrıcalıklı işlevleri not alın. Spesifik olun. "Her kiracıdaki tüm müşteri PII'sını okuyabilir" ve "kendi kiracısının bilet başlıklarını okuyabilir" wildly farklı yarıçaplardır ve her ikisi de bir kontrol panelinde "okuma erişimi" gibi görünür. Aralarındaki boşluk sizin riskinizdir.

Temmuz 2026 olayı, bu uygulama için faydalı bir stres testidir. Hugging Face, bildirilen erişimi araştırdığını ve maruz kalmayı sınırlamak için çalıştığını belirtti. Son kapsam ne olursa olsun, dersin şekli açık: ele geçirilmiş bir aktörün verebileceği zarar, aktörün nasıl girdiğiyle değil, kimlik bilgilerinin ulaşabileceği yerlerle sınırlıdır. Eğer çalınan kimlik bilgileri salt okunur bir köşeye kapsamlandırılmış olsaydı, patlama yarıçapı o köşe olurdu. Bir aracının anahtarını boyutlandırırken, ajanın bir gün saldırgan olacağını varsayın – ister ele geçirilmiş bir komut, ister zehirlenmiş bir araç yanıtı veya basit bir hata yoluyla olsun – ve anahtarı öyle kapsamlandırın ki, tamamen düşmanca bir çağrı bile sıkıcı kalsın.

Pratik bir kural: bir anahtarın patlama yarıçapını üç veya dört madde işaretiyle açıklayamıyorsanız, çok geniştir. Onu ayırın, kapsamını daraltın ve açıklama kısalana kadar yeniden ölçün.

Anahtarı kapsamlar, roller ve kısa ömürlü jetonlarla kısıtlayın

İstediğiniz yarıçapı öğrendikten sonra, onu üst üste binen üç kaldıraçla uygularsınız.

İlk olarak, kapsamlar. Ajanları OAuth ile kimlik doğruluyorsanız, sadece işin ihtiyaç duyduğu kapsamları isteyin, bitişik olanları değil. Bir tickets.read kapsamı, sırf birlikte verilmesi kolay olduğu için asla tickets.write veya billing.read ile birlikte gelmemelidir. Kapsamların erişimi nasıl böldüğü konusunda kafanız karışıksa, OAuth 2.0 kapsamlarının ne olduğuna dair açıklayıcımız mekaniği adım adım anlatır. Önemli alışkanlık: her ajan için tam kapsamları adlandırın ve "her ihtimale karşı" izinler ekleme dürtüsüne direnin. "Her ihtimale karşı" demek, patlama yarıçapının nasıl büyüdüğüdür.

İkinci olarak, sunucudaki roller. Kapsamlar bir jetonun ne istediğini tanımlar; rol kontrolleri sunucunun neye izin verdiğine karar verir. Ajanın kimliğini, işine uygun bir rolle destekleyin ve bu rolü durumu değiştiren her uç noktada uygulayın. BFLA'nın tamamen ortadan kalktığı yer burasıdır, çünkü sunucu, tehlikeye atılmış bir istemcinin ne istediğine bakılmaksızın yönetici işlevlerini reddeder.

Üçüncü olarak, kısa ömürlü jetonlar. Sonsuza kadar yaşayan bir anahtar, bir saldırganın aylarca üzerinde oturabileceği bir anahtardır. Dakikalar veya saatler içinde sona eren ve kontrollü bir akışla yenilenen kimlik bilgilerini tercih edin, böylece sızdırılan bir jeton kullanışlı hale gelmeden ölür. Taşıyıcı jetonlar (Bearer tokens) ve imzalı JWT'ler bunu pratik hale getirir. Kısa ömürler, canlı bir saldırganı oturum ortasında durdurmayacaktır, ancak çalınan bir kimlik bilgisinin ne kadar süreyle tehlikeli kaldığını sınırlar, bu da patlama yarıçapının zaman boyutunu küçültür.

Kimlik bilgilerini öyle saklayın ki ajan okuyabilsin ama saldırgan okuyamasın

Mükemmel kapsamlı bir anahtar bile sızarsa size zarar verir ve en yaygın sızıntı egzotik değildir. Kaynak koduna, bir yapılandırma dosyasına veya bir sohbet mesajına yapıştırılmış bir jetondur. Ajan kimlik bilgilerini ortam değişkenlerinde veya özel bir sır yöneticisinde saklayın ve çalışma zamanında enjekte edin. Asla sabit kodlamayın ve asla bir git commit'ine düşürmeyin. API anahtarlarını doğru şekilde saklama rehberimiz, birden fazla ortamınız olduğunda neden bir sır yöneticisinin bir .env dosyasını yendiği de dahil olmak üzere desenleri kapsar.

Bir API aracının iş akışında yerini aldığı nokta da burasıdır. Apidog, her aracının jetonunu istek tanımlarına yapıştırmak yerine bir ortam değişkeninde tutmanızı sağlar, böylece ham sır paylaşılan projenin ve sürüm kontrolünün dışında kalır. Değişkeni referans alırsınız, değer ortamınızda yaşar ve ekip arkadaşları jetonu hiç görmeden aynı istekleri çalıştırır. Bu bir tasarım ve test kolaylığıdır ve sınırları konusunda dürüsttür. Apidog sırlarınızı döndürmez, ağınızı korumaz veya kötüye kullanım için çalışma zamanı trafiğini izlemez. Döndürme, ağ çıkış kontrolleri ve izleme, sır yöneticinizde, bulut sağlayıcınızda ve günlükleme yığınınızda yaşar. Apidog'un işi tüm bunların yukarısındadır: her anahtarın neye izin verildiğini sevkiyattan önce tanımlamanıza, uygulamanıza ve belgelemenize yardımcı olur.

"Salt okunur" bir anahtarın gerçekten yazma işlemlerini reddettiğini test edin

Çoğu ekibin atladığı adım buradadır. Anahtarı kapsamlandırdınız, rolü ayarladınız, herkese salt okunur olduğunu söylediniz. Kontrol ettiniz mi? "Salt okunur" etiketi, bir istek onu kanıtlayana kadar bir iddiadır. Bunu kanıtlamanın yolu, başarısız olmasını beklediğiniz yazma işlemlerini denemek ve bunların başarısız olduğunu doğrulamaktır.

Bu, bir API test aracının iyi yaptığı bir şeyin tam kalbinde yer alır ve Apidog için gerçekten kullanışlı bir alandır. Aracının gerçek düşük ayrıcalıklı jetonunu kullanarak gerçek uç noktalarınıza bir dizi istek gönderin, ardından olumsuz sonucu doğrulayın. Salt okunur bir anahtarla yapılan bir yazma işlemi 401 veya 403 olarak dönmelidir ve testiniz herhangi bir 2xx'i başarısızlık olarak kabul etmelidir. Mutlu yolun çalıştığını test etmiyorsunuz. Yasak yolun yasak kaldığını test ediyorsunuz.

Zaten yazdığınız patlama yarıçapı tablosu etrafında paketi oluşturun. Anahtarın yapmaması gereken her yazma veya yönetici eylemi için, onu denemeye çalışan ve reddetme iddia eden bir durum ekleyin:

Kimlik doğrulama yapılandırmasındaki her değişikliğe bu paketi CI'da çalıştırın, böylece iyi niyetli ama sessizce bir kapsamı genişleten bir yeniden düzenleme, sevkiyattan önce kırmızı bir testi tetiklesin. Durum kodunu doğrulayın ve mümkün olduğunda, yanıt gövdesinin kısmi veri yerine düzgün bir hata olduğunu doğrulayın. Gövdede hala bir kaydı sızdıran bir 403 kendi başına bir hatadır. Otomatikleştirilmeye değer kontrollerin tam listesi için API güvenlik testi kontrol listemiz iyi bir eşlikçidir. Bu deseni kendi uç noktalarınıza karşı çalıştırmak isterseniz, Apidog'u ücretsiz deneyebilir ve olumsuz doğrulama vakalarını bir test senaryosuna bağlayabilirsiniz.

Yeşil onay işaretine aşırı güvenmemeniz için bir uyarı. Geçen testler, denediğiniz belirli yazma işlemlerinin reddedildiğini kanıtlar. Hiçbir yerde başka bir yolun olmadığını kanıtlamazlar. Paketi her zaman geçerli olması gereken bir taban olarak görün, güvenliği garanti eden bir tavan olarak değil, ve API büyüdükçe durumlar eklemeye devam edin.

Bu hafta uygulayabileceğiniz bir patlama yarıçapı kontrol listesi

Bir aracının anahtarını daha güvenli hale getirmek için bir güvenlik ekibine ihtiyacınız yok. Bir öğleden sonraya ve bu listeye ihtiyacınız var.

• Aracının görevini tek bir cümleyle yazın, ardından sadece o cümlenin gerektirdiği eylemleri listeleyin.
• Aracıya kendi kimlik bilgilerini verin. Miras aldığı paylaşılan veya yönetici jetonlarını öldürün.
• Patlama yarıçapını bir tabloda haritalandırın: ulaşılan hizmetler, okunan nesneler, yazılan nesneler, çağrılabilecek yönetici fonksiyonları.
• Kapsamları tabloya uyacak şekilde daraltın. "Her ihtimale karşı" olan her izni kaldırın.
• Durumu değiştiren her uç noktaya sunucu tarafında rol kontrolleri ekleyin, böylece retler istemcinin davranışına bağlı kalmasın.
• Sızan bir kimlik bilgisinin hızlıca sona ermesi için yenileme akışı olan kısa ömürlü jetonlara geçin.
• Sırları ortam değişkenlerine veya bir sır yöneticisine taşıyın ve hiçbirinin git'e işlenmediğinden emin olun.
• Yasak yazma işlemlerini tetikleyen ve 401 veya 403 döndürdüğünü doğrulayan negatif testler yazın, ardından bunları CI'da çalıştırın.

Bu listeyi takip edin ve soyut bir soru olan "aracımızın anahtarı ne yapabilir?" kısa, yazılı, test edilmiş bir cevaba dönüşür. Tüm oyun bu cevaptır. Mantık yürütebileceğiniz bir ajan, kendisine kimlik bilgisi emanet edebileceğiniz bir ajandır; mantık yürütemeyeceğiniz bir ajan ise önemli bir anahtara sahip olmamalıdır.

Sıkça Sorulan Sorular

Bir yapay zeka aracısı için en az ayrıcalık özellikle ne anlama gelir?

Bu, aracının kimlik bilgisinin yalnızca görevinin gerektirdiği eylemleri ve başka hiçbir şeyi vermediği anlamına gelir. Ajanlar için incelik, ölçek ve özerkliktir. Bir ajan, her çağrıyı inceleyen bir insan olmadan hareket eder ve bir eylemi binlerce kez tekrarlayabilir, bu nedenle aşırı geniş bir anahtar, insan elindeki aynı anahtardan daha hızlı daha fazla zarar verir. Kapsamı dar tutun ve uygulamayı ajanın talimatlarında değil, sunucuda yapın.

BOLA ile BFLA arasındaki fark nedir?

BOLA, bozuk nesne seviyesi yetkilendirme, verilerle ilgilidir: bir çağırıcı, genellikle isteğindeki bir kimliği değiştirerek, ulaşmaması gereken bir nesneye ulaşır. BFLA, bozuk fonksiyon seviyesi yetkilendirme, eylemlerle ilgilidir: bir çağırıcı, yönetici silme gibi, izin seviyesinin üzerinde bir fonksiyonu çağırır. Her ikisi de sunucunun çağırıcının yalnızca yapması gerekeni isteyeceğine güvenmesinden kaynaklanır. Her ikisi de OWASP API Güvenlik Top 10 listesinin başında yer alır ve her ikisinin de kapatılması için sunucu tarafı kontrollere ihtiyacı vardır.

Bir anahtarın salt okunur olduğunu gerçekten nasıl doğrularım?

Tam olarak o anahtarı kullanarak başarısız olmasını beklediğiniz yazma işlemlerini gönderin ve reddedildiğini doğrulayın. Salt okunur bir jetonla yapılan bir PATCH, POST veya DELETE 401 veya 403 döndürmelidir ve testiniz herhangi bir 2xx'i başarısızlık olarak işaretlemelidir. Bu olumsuz durumları otomatikleştirin ve CI'da çalıştırın, böylece anahtarı genişleten bir yapılandırma değişikliği, yayından sonra değil, önce yakalanır.

Kısa ömürlü jetonlar tek başına yeterli midir?

Hayır. Kısa ömürler, sızan bir kimlik bilgisinin ne kadar süreyle kullanışlı kaldığını sınırlar ki bu gerçek bir değerdir, ancak aktif bir oturumdaki canlı bir saldırganı durdurmazlar ve aşırı geniş bir kapsamı düzeltmezler. Kısa ömürlü jetonları sıkı kapsamlar, sunucu tarafı rol kontrolleri ve güvenli sır depolama ile birleştirin. Her kaldıraç, patlama yarıçapının farklı bir kısmını kapsar.

Apidog nerede yardımcı olur, nerede olmaz?

Apidog, uç noktaları kasten düşük ayrıcalıklı bir jetonla uygulamanıza, yazma girişimlerinin 401 veya 403 döndürdüğünü doğrulamanıza, her ajanın kimlik doğrulamasını sabit kodlanmış dizeler yerine ortam değişkenlerinde tutmanıza ve her anahtarın neye ulaşabileceğini belgelemenize yardımcı olur. Ağ güvenlik duvarı, sır döndürme, çalışma zamanı izleme veya model koruma önlemleri yapmaz. Bu kontroller bulut platformunuzda, sır yöneticinizde ve günlükleme yığınınızda bulunur. En az ayrıcalığın tasarım ve test tarafı için Apidog'u kullanın ve geri kalanı için çalışma zamanı araçlarıyla eşleştirin.

Her ajanın gerçekten kendi anahtarı olmalı mı?

Evet. Ajan başına kimlik bilgileri, diğerlerini bozmadan yanlış çalışan bir ajanı iptal etmenizi sağlar ve her çağrıyı tek bir kimliğe atfeden temiz günlükler sunar. Paylaşılan anahtarlar her ikisini de bulanıklaştırır, bu nedenle tek bir olay her şeyi döndürmenizi ve kimin ne yaptığını tahmin etmenizi zorlar. Ajan başına bir kimlik kurmak ucuzdur ve bir şeyler ters gittiğinde ilk seferde karşılığını verir.