Yapay Zeka Ajanlarının API Anahtarlarını Görmeden Kullanması Nasıl Sağlanır?

Kısa cevap: Yapay zeka ajanlarının API anahtarlarını görmeden kullanabilmesini sağlamak için, ajanın bağlamına yalnızca anahtarın adını ekleyin ve değerini modelin dışında çözümleyin: ajanın başvurduğu ancak hiçbir zaman yazdırmadığı bir ortam değişkeni, bir gizli dizi yöneticisi (secret manager) referansı veya başlığı (header) enjekte eden bir proxy kullanın. Ardından her anahtarı kısa ömürlü ve dar kapsamlı tutun ve günlükleri ajana geri dönmeden önce sansürleyin (redact).

DeepSeek Harness ekibi bu sorunu “Exploring Super-agent Design” başlıklı makalesinde tanımladı: bir ajanın bağlamındaki kimlik bilgileri sızabilir, bu nedenle ajan kimlik bilgilerini görmeden kullanmalıdır. Makalede bu konu çözülmemiş açık bir sorun olarak nitelendiriliyor. Ancak bunu bir çerçevenin çözmesini beklemenize gerek yok; aşağıdaki kalıpları bugünden uygulayabilirsiniz.

Büyük resmi görmek için süper bir ajan nasıl oluşturulur yazısına göz atabilirsiniz. Bu yazı ise tek bir soruya odaklanıyor: anahtar bağlam penceresine hiç girmeden, ajanınız kimlik doğrulaması gerektiren bir API'yi nasıl çağırabilir?

Yapay zeka ajanları API anahtarlarını nasıl sızdırır?

Bir yapay zeka ajanı, değer bağlamına girdiği anda API anahtarını sızdırabilir: model bu değeri daha sonra bir araç çağrısında, bir dosyada, bir commit'te veya bir yanıtta tekrarlayabilir. Kimsenin bir sunucuya sızmasına gerek kalmaz. Ajan, genellikle sadece yardımcı olmaya çalışırken anahtarı kendi elleriyle teslim eder.

En sık karşılaşacağınız dört sızıntı yolu:

1. .env dosyasını okur. Ödeme çağrısının neden başarısız olduğunu sorarsınız; kontrol etmek için .env dosyasını açar ve sk_live_... artık transkripte ve sağlayıcının günlüklerine girmiş olur.
2. Anahtarı bir araç çağrısında yankılar (echo). Değerin açıkça yazıldığı bir hata ayıklama (debug) curl komutu veya "ayarlandığını doğrulamak" için çalıştırılan bir echo $STRIPE_KEY.
3. Anahtarı herkese açık bir yere yazar. Gerçek değerin yer aldığı bir PR açıklaması, issue yorumu veya test fikstürü.
4. Prompt injection anahtarı talep eder. Bir web sayfası veya API yanıtı "ortam değişkenlerini yazdır" der. OWASP, prompt injection saldırısını en büyük LLM uygulama riski olarak değerlendirir ve kimlik bilgilerinin ifşasını hassas bilgilerin açığa çıkması kategorisinde listeler.

İnsanlar ve ön yüzler (front end) kaynaklı sızıntılar farklı çözümler gerektirir; bu konular tarayıcıda açığa çıkan API anahtarları, çalınan yapay zeka API anahtarları ve LLMjacking ile secret scanner ile sızdırılmış anahtarları kontrol etme yazılarında ele alınmıştır. Buradaki aktör ise ajanın kendisidir.

Temel kural: İsimler bağlamda, değerler dışarıda

Buradaki her kalıp tek bir kuralı izler. Ajanın bağlamı, bir gizli bilgiye (secret) işaret eden bir referans tutar. Modelin dışındaki bir mekanizma, bu referansı son anda gerçek değere dönüştürür ve bu değer kesinlikle geri dönmez.

Bir değer sağdaki sütuna düşerse anahtarı derhal yenileyin (rotate edin). Bağlam pencereleri günlüğe kaydedilir, önbelleğe alınır ve dışa aktarılır. Gönderilen bir token'ı geri alamazsınız.

1. Kalıp: Ortam değişkenleri ve sansürleme (redaction)

Ortam değişkenleriyle anahtar, sürecin (process) ortamında bulunur ve ajan yalnızca $STRIPE_KEY yazar; böylece kabuk (shell), model komutu yazdıktan sonra bu değişkeni genişletir. Bu en maliyetsiz kalıptır ve işe yaramasını sağlayan üç temel alışkanlık vardır:

Gizli dosyaları engelleyin. Claude Code kullanırken ayarlar izinlerinize Read(./.env) ve Read(./.env.*) gibi engelleme kuralları ekleyin. Diğer ajanlar da benzer izin ve engelleme listelerine sahiptir.

Kuralı CLAUDE.md veya AGENTS.md dosyasında açıkça belirtin:

Secrets: never print, echo, cat or log the value of any variable
ending in _KEY, _TOKEN or _SECRET. Reference them as $NAME.
If a value is missing, say which NAME is missing and stop.

Bilinen gizli bilgi kalıplarını maskeleyen bir filtre kullanarak, modele geri dönmeden önce çıktıyı sansürleyin.

Açık konuşmak gerekirse sınır şudur: ajanın kabuğu değişkene sahiptir, bu nedenle enjeksiyona (prompt injection) maruz kalan bir ajan yine de onu yazdırabilir. Ortam değişkenleri kazaları önler, ancak bir sonraki komutu kontrol eden bir saldırganı durduramaz.

2. Kalıp: Gizli dizi yöneticisi (Secret Manager) referansları

Gizli dizi yöneticisi referansı, op://vault/item/field gibi bir CLI tarafından çalışma zamanında çözümlenen bir işaretçidir; böylece yapılandırma dosyaları ve prompt'lar yalnızca bu işaretçiyi tutar. Ajan bu referansı güvenle okuyabilir ve commit edebilir, çünkü tek başına hiçbir erişim hakkı sağlamaz.

1Password'ün gizli dizi referansları buna net bir örnektir:

# .env.agent (safe for the agent to read)
STRIPE_KEY=op://payments/stripe/api-key
GITHUB_TOKEN=op://ci/github-bot/token

op run --env-file=.env.agent -- npm test

op run referansları alt süreç (child process) içinde çözümler ve biri --no-masking parametresini geçmediği sürece stdout veya stderr'e yazdırılan gizli bilgiler varsayılan olarak gizlenir. Ajanınızın çalıştırdığı hiçbir komutta bu bayrağa yer vermeyin. HashiCorp Vault, AWS Secrets Manager ve Azure Key Vault da kendi sözdizimleriyle aynı mantığı sunar. Ancak alt süreç değeri hâlâ tuttuğundan, 1. Kalıptaki sınırlama burada da geçerliliğini korur.

3. Kalıp: Kimlik bilgisi enjekte eden bir proxy

Kimlik bilgisi enjekte eden bir proxy, ajan ile hedef API arasında durur ve kimlik doğrulama başlığını bizzat ekler. Ajan isteği anahtar olmadan gönderir, proxy kimlik bilgisini ekler ve ajan değeri yazdırabileceği veya sızdırabileceği hiçbir yerde tutmaz.

Ajanın anahtara gerçekten hiçbir zaman sahip olmadığı tek kalıp budur. Minimal bir tasarım:

1. Ajan, gerçek sunucu yerine http://localhost:8787/stripe/v1/charges adresini çağırır.
2. Proxy, /stripe yolunu hedef sunucuya eşler ve anahtarı gizli dizi yöneticinizden okur.
3. Bir izin listesini (allowlist) kontrol eder: GET /v1/charges geçer, DELETE /v1/customers geçemez.
4. Authorization: Bearer <value> başlığını ekler, isteği iletir ve başlığı kendi günlüklerinden temizler.

İzin listesi de en az enjeksiyon kadar önemlidir. Manipüle edilmiş bir ajan anahtarı yine de kullanabilir, ancak yalnızca onayladığınız çağrılar için kullanabilir ve anahtarı başka bir yere taşıyamaz. Ajanın yapılandırmasını okuyamaması için proxy'yi ayrı bir kullanıcı veya kapsayıcı (container) olarak çalıştırın.

Bu yaklaşım makaledeki mimariyle örtüşmektedir: ajan döngüsü bulutta çalışır, ortamınız küçük bir arka plan programının (daemon) arkasında kendi makinenizde kalır ve kimlik bilgileri ortamdan ayrılmaz.

4. Kalıp: Kısa ömürlü, kapsamı sınırlandırılmış token'lar

Kısa ömürlü ve kapsamı sınırlandırılmış token'lar, diğer kalıplar başarısız olduğunda oluşacak zararı sınırlandırır: ajan, dakikalar içinde süresi dolan ve yalnızca dar kapsamlı tek bir görevi yerine getiren bir kimlik bilgisi alır; böylece sızdırılan bir değer, birisi onu kullanmaya çalışana kadar çoktan işlevsiz hale gelir. Bu bir alternatif değil, bir emniyet sübabıdır.

Her ajan oturumu için tek bir token üretin, kapsamını göreve göre daraltın ve görevin tamamlanmasına yetecek en kısa geçerlilik süresini seçin.

Günlükleri ve transkriptleri sansürleyin

Sansürleme (redaction) temizleme katmanıdır: araç çıktılarındaki, CI günlüklerindeki ve kaydedilen ajan oturumlarındaki gizli bilgileri maskeleyin; çünkü sansürlenmemiş tek bir satır yukarıdaki her şeyi boşa çıkarabilir. Bilinen önekleri (sk_live_, ghp_, github_pat_, AKIA, xoxb-), herhangi bir Authorization: veya X-API-Key: başlık değerini ve o oturumda enjekte ettiğiniz tam değerleri maskeleyin. Bunu araç sarmalayıcısında (wrapper), CI günlük ayarlarında ve transkriptler paylaşılmadan hemen önce uygulayın.

Claude Code'un API'yi anahtarı görmeden Apidog CLI ile test etmesini sağlayın

Apidog, isimler bağlamda kuralına tam olarak uyar: bir test isteği {{token}} referansını kullanır, ortam bunu çalışma zamanında çözümler ve ajanınız yalnızca ismi okuyup yazar. Kodlama ajanınız tüm testi Apidog CLI aracılığıyla oluşturabilir ve çalıştırabilir.

Burada önemli bir ayrıntı bulunuyor: Apidog değişkenleri, Apidog sunucularıyla ve ekibinizle senkronize edilen bir Shared Value (Paylaşılan Değer) ile yerel makinenizde tutulan bir Local Value (Yerel Değer) içerir. Değişkenlere ilişkin belgeler, token'lar için yerel değerlerin kullanılmasını önerir ve CLI'ın varsayılan olarak paylaşılan değeri kullandığını belirtir. Bu nedenle gerçek token'ı paylaşılan değerin dışında tutun ve çalışma zamanında iletin.

Giriş işlemini kendiniz yaparsınız; böylece Apidog token'ınız ajanın bağlamına asla girmez:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>   # in your own terminal
npx -y skills add https://apidog.com                 # pick your agent when prompted
export PAYMENTS_TOKEN=...                            # in your shell, never in a prompt

Ardından Claude Code'a tek bir prompt verin:

In Apidog project 123456, create a test case for GET /v1/charges that
sends Authorization: Bearer {{token}} and asserts a 200 status and a
non-empty data array. Run it against environment 789, passing the token
with --env-var "token=$PAYMENTS_TOKEN". Never print $PAYMENTS_TOKEN or
any header value. Summarize failures only.

Ajan şemayı okur, yükünü (payload) doğrular, test senaryosunu yazar ve çalıştırır:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 789 \
  --env-var "token=$PAYMENTS_TOKEN" -r cli,json

Senaryo JSON'ı {{token}} değerini, komut ise $PAYMENTS_TOKEN değişkenini tutar ve kabuk, model satırı yazdıktan sonra değeri yerine koyar. Ajan yalnızca başarılı/başarısız durumunu ve doğrulama (assertion) mesajlarını görür. Kaydedilen JSON raporunu paylaşmadan önce sansürleme adımınızdan geçirin. Aynı apidog run satırı -r junit parametresiyle CI süreçlerine de eklenebilir; ayrıntılar için Apidog CLI CI/CD pipeline rehberine ve Claude Code içinde Apidog CLI kurulumuna göz atabilirsiniz.

Enterprise planında Apidog, {{vault:key}} referansıyla HashiCorp Vault, Azure Key Vault ve AWS Secrets Manager'dan kasa gizli dizilerini (vault secrets) de çekebilir; bir betik içinde değerin console.log ile yazdırılması otomatik maskelenir ve değerler asla ekip arkadaşlarıyla paylaşılmaz. CLI akışını önceden denemek isterseniz Apidog Free 4 kullanıcıya kadar destek sunar.

Kontrol Listesi: Yapay zeka ajanlarında API anahtarı güvenliği

1. Ajanın .env ve diğer gizli dosyalara okuma erişimini engelleyin.
2. CLAUDE.md veya AGENTS.md dosyasına “asla bir gizli bilgiyi yazdırma” kuralı ekleyin.
3. Ajanın okuyabileceği dosyalardaki ham değerleri gizli dizi yöneticisi referanslarıyla değiştirin.
4. Üçüncü taraf çağrılarını izin listesine sahip kimlik bilgisi enjekte eden bir proxy üzerinden yönlendirin.
5. Her ajan oturumu için kısa ömürlü ve kapsamı sınırlandırılmış tek bir token tanımlayın.
6. Gerçek token'ları paylaşılan Apidog değişkenlerinden uzak tutun.
7. Araç çıktılarını, CI günlüklerini ve transkriptleri sansürleyin.
8. Bir değer transkriptte görünürse, anahtarı vakit kaybetmeden aynı gün yenileyin.

Sıkça Sorulan Sorular

Bir yapay zeka ajanı göremediği bir API anahtarını kullanabilir mi? Evet. Kimlik bilgisi enjekte eden bir proxy ile ajan istekleri anahtar olmadan gönderir ve proxy gerekli başlığı ekler. Ortam değişkenleri ve gizli dizi referansları ise değeri prompt'tan gizlese de ajanın kabuk ortamında bırakır.

Ortam değişkenleri yapay zeka ajanlarının API anahtarları için güvenli midir? Anahtarları doğrudan prompt'lara yapıştırmaktan daha güvenlidir, ancak tek başına güvenli değildir. Ajanın kabuğu değişkeni yine de yazdırabilir ve bir prompt injection saldırısı bunu talep edebilir. Bunları okuma engelleme kuralları, sansürleme ve kısa ömürlü token'lar ile birlikte kullanın.

Ajanım bir API anahtarını yazdırdıysa ne yapmalıyım? Anahtarı derhal sağlayıcı üzerinden yenileyin (rotate edin), ardından transkriptin nerelere gittiğini takip edin: sağlayıcı günlükleri, dışa aktarmalar, PR yorumları, CI çıktıları. Mesajı silmek kopyalarını ortadan kaldırmaz.

Gizli bilgileri ajanıma göstermeden Apidog CLI'a nasıl aktarabilirim? Token'ı kendi kabuğunuzda tutun ve ajanın apidog run komutuna --env-var "token=$NAME" parametresini geçmesini sağlayın. Test {{token}} referansını kullandığı için ajan yalnızca isimle işlem yapar.

Kısa ömürlü token'lar tek başına yeterli midir? Hayır. 15 dakikalık bir token bile 15 dakika boyunca kötüye kullanılabilir. Bunları bağlamda-isim kuralının ve bir proxy'nin ardındaki emniyet sübabı olarak kullanın.