SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor

Yapay zeka ajanlarında API anahtarı güvenliği nasıl

Yapay zeka ajanları API anahtarlarını tool çağrıları üzerinden sızdırabilir. Gerçek anahtarlar yerine kısa ömürlü tokenlar ve kimlik doğrulama ağ geçitleri kullanın.

Yapay zeka ajanlarından sırları uzak tutmak ne anlama gelir

Yapay zeka ajanı, komutları çalıştıran standart bir Linux sürecidir. Sürecin sahip olduğu her ortam değişkeni, çalıştırdığı kod tarafından okunabilir; bu nedenle ajanın ortamındaki bir API anahtarı, ajanın erişebildiği herhangi bir sunucuya gönderebileceği bir anahtardır. Sırları ajandan uzak tutmak, ona anahtar yerine bir tutamaç (handle) vermek demektir: kısa ömürlü, kapsamı sınırlandırılmış bir token veya ağ sınırında başka bir mekanizmanın gerçek değerle değiştireceği bir yer tutucu.

Bu, bir modelin kötü niyetli hale gelmesiyle ilgili bir hikaye değildir. Mekanizma çok daha basittir. Bir ajan; talimatlar içeren bir web sayfasını, bir README dosyasını veya bir sorun kaydı yorumunu okur ve bunları uygular; çünkü dil modeli için sizin yazdığınız metin ile kendi getirdiği metin arasında hiçbir fark yoktur. Buna prompt injection denir. Bu durum gerçekleştiğinde, verilecek hasar tam olarak tek bir şeyle sınırlıdır: sürecin okuyabildiği veriler. Henüz bir sınır belirlemediyseniz, bir kodlama ajanını sunucuda güvenli bir şekilde çalıştırmak başlıklı rehber, bu kılavuzun üzerine inşa edildiği izolasyon basamaklarını kapsamaktadır.

Tehdit modeli basit terimlerle

Bunu, aracınızın (agent) çalıştığı kullanıcı ile çalıştırın.

tr '\0' '\n' < /proc/self/environ | grep -iE 'key|token|secret|password'

Yazdırdığı her satır, yabancı bir sunucuya gönderilen bir HTTP isteği kadar uzaktadır. Şimdi aracın yakınındaki diskte neler olduğuna bakın.

grep -rIl --exclude-dir=.git -e 'API_KEY' -e 'SECRET' ~/projects
find ~ -maxdepth 3 -name '.env' -o -name 'credentials' -o -name '*.pem'

Shell erişimine sahip bir araç, verileri dışarı çıkarmak için zekice bir exploit'e ihtiyaç duymaz. Dört sıradan yol bu işi görür ve dördü de loglarda normal bir çalışma gibi görünür:

  • Değerin sorgu dizisinde (query string) yer aldığı, herhangi bir sunucuya yönelik giden bir curl veya fetch isteği.
  • Aracın yazma yetkisine sahip olduğu bir depoya yönelik git commit ve git push işlemi.
  • Aracın kullanıcısı yetkileriyle rastgele kod çalıştıran bir paket yükleme betiği.
  • HTTP çıkışı engellendiğinde bile çalışan, değerin hostname içinde yer aldığı bir DNS sorgusu.

Bu durumdan sadece inceleme yaparak kurtulamazsınız. Çözüm, aracın erişebileceği mesafede değerli hiçbir şeyin bulunmadığından emin olmaktır.

Çalışma dizinindeki bir gizli anahtar, bağlam penceresindeki bir gizli anahtardır

Bir ajan dosyaları okur. Çalıştığı depodaki bir .env dosyası okunacaktır ve okunduğu anda bağlam penceresine girer; bu da dosyanın transkripte, tuttuğunuz herhangi bir günlüğe ve ajanın bir sonraki adımda yazdığı her şeye dahil olduğu anlamına gelir.

Öncesinde, anahtar ajanın çalıştığı dizinde dururken:

cd ~/projects/billing
cat .env
# STRIPE_SECRET_KEY=sk_live_...
# DATABASE_URL=postgres://app:hunter2@127.0.0.1:5432/billing

Sonrasında, dosya erişilemeyecek bir yere taşındığında:

sudo install -d -m 700 -o root -g root /etc/agent-review
sudo install -m 600 -o root -g root ~/projects/billing/.env /etc/agent-review/billing.env
rm ~/projects/billing/.env

Ajanın kullanıcısı artık dosyayı açamaz, çünkü çalışma dizininin dışındaki kopyaya yalnızca root erişebilir. Ajanın kendi yapılandırmasındaki reddetme kuralları ilk değil, ikinci bir katmandır. Claude Code, izin kurallarını projedeki .claude/settings.json dosyasından okur:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Read(./**/*.pem)"]
  }
}

Bu, ajanın keşif yaparken bir dosyayı açması gibi dürüst hataları engeller ve dosya araçlarının ötesine geçer: Claude Code, bu kuralları Bash içinde tanıdığı cat ve head gibi dosya komutlarına ve < .env gibi yönlendirmelerin hedeflerine karşı da kontrol eder. Bu durum, enjekte edilmiş bir talimatın proje dizini içinde grep -r KEY . çalıştırmasını veya .env dosyasını kendi başına açan kısa bir Python betiğini engellemez; çünkü izin belgeleri, reddetme kurallarının isimlerini belirtmeden dosya okuyan komutlar veya dosyaları kendi başına açan alt süreçler için geçerli olmadığını belirtir. Bu tür durumlar için belgeler, engellemeyi işletim sistemi seviyesinde uygulayan Claude Code sandbox yapısına işaret eder. Böyle bir komut çalışmadan önce size sorulup sorulmayacağı, oturumun izin moduna bağlıdır ve otomatik mod, Claude Code v2.1.283 ve sonraki sürümlerde etkileşimli terminal ve VS Code oturumları için yerleşik başlangıç modudur; etkileşimli olmayan claude -p oturumları ise aksi yapılandırılmadıkça Manuel modda başlar. Aynı sınırlama, ajanın izinlerinden ziyade alışkanlıklarını şekillendiren her şey için geçerlidir: ajanı çalışan en küçük değişikliğe bağlı tutan bir yetenek, bir çalıştırmanın açmaması gereken dosyalara girmesini engeller ancak bu yine de modelin ikna edilerek vazgeçirilebileceği bir tavsiyedir. Yapılandırmayı bir korkuluk, dosya sistemi iznini ise duvar olarak kabul edin. Aynı ayrım konteynerler içinde de geçerlidir: Docker Compose içindeki env dosyaları ve gizli anahtarlar, bu sorunun bir katman alttaki versiyonunu ele alır.

Her aracıya kendi yetkisiz kullanıcısını atayın

Aracı sizin kullanıcı adınızla çalışırsa, SSH anahtarlarınızı, bulut kimlik bilgilerinizi ve komut geçmişinizi devralır. Ayrı bir kullanıcı oluşturmak tek bir komut gerektirir ve tüm bu riskleri ortadan kaldırır.

sudo adduser --disabled-password --gecos "" agent-review
sudo chmod 700 /home/agent-review
sudo -u agent-review cat ~/.ssh/id_ed25519

Son satır cat: /home/you/.ssh/id_ed25519: Permission denied ile başarısız olmalıdır. Eğer bir anahtar çıktısı verirse, aracının kullanıcısı dosyaya erişebiliyor demektir. Bir dosyayı ismiyle açmak, dosyanın kendisinde okuma izni değil, üstündeki her dizinde arama (x) izni gerektirir; bu nedenle 711 modundaki bir ev dizini, başkaları tarafından listelenemese bile, dosya okunabilir olduğu sürece anahtarı sızdırabilir. chmod 700 ~ yolu kapatır ve chmod 600 ~/.ssh/id_ed25519 anahtarı düzeltir. Aracı kullanıcısını sudo grubuna eklemeyin ve ona gerçekten ihtiyaç duyduğu tek komuttan daha geniş bir NOPASSWD kuralı tanımlamayın. VPS üzerinde en az yetkili kullanıcılar rehberi, grup ve sudoers detaylarını açıklar. Sunucuda birden fazla oturum çalıştırdığınızda bu ayrımı göz önünde bulundurun; çünkü bir Claude Code oturumu doğrudan diğerine metin gönderebilir ve ilk oturumun elinde ne varsa tek bir mesajla bu kanaldan aktarılabilir.

Bulut VPS üzerinde bir sınır daha eklemekte fayda vardır. Örnek meta veri servisi, sabit bir yerel bağlantı adresinden yanıt verir ve genellikle talep eden her şeye rol kimlik bilgilerini dağıtır. Uç noktadaki hiçbir mekanizma yerel kullanıcıyı denetlemez: AWS, EC2 üzerinde IMDSv1 çağrılarının token gerektirmediğini belirtir ve bir kullanıcıyı bu servisten uzak tutmak için önerisi, kullanıcı kimliğine dayalı yerel bir güvenlik duvarı kuralıdır.

sudo iptables -I OUTPUT 1 -p tcp -m owner --uid-owner agent-review -d 169.254.169.254 -j REJECT

Kuralı -A ile sona eklemek yerine -I ile en başa yerleştirin. Varsayılan giden trafiğe izin verme politikasına sahip bir ufw üzerinde, ufw'nin son OUTPUT zinciri her yeni TCP bağlantısını kabul eder; bu nedenle sona eklenen bir kurala asla sıra gelmez. iptables kuralları, kalıcı hale getirilmedikçe yeniden başlatma sırasında silinir. Eğer meta veri servisinin IPv6 uç noktasını etkinleştirdiyseniz, [fd00:ec2::254], aynı kuralı ip6tables ile ekleyin.

Aracı tarafında kontrol edin. sudo -u agent-review curl -s --max-time 3 http://169.254.169.254/ hiçbir şey yazdırmamalı ve sıfırdan farklı bir değerle çıkmalıdır; çünkü paket sunucudan çıkmadan önce reddedilir. Eğer bir liste çıktısı verirse, kurala ulaşılamıyor demektir.

Kimlik bilgilerini sınırda enjekte edin

Bu sorunu fiilen çözen yöntem, kimlik bilgisi enjeksiyonudur. Ajan hiçbir zaman gerçek bir anahtarı elinde tutmaz. İsteğini yerel bir ağ geçidi üzerinden gönderir ve ağ geçidi, dışarı çıkarken yer tutucuyu gerçek gizli veriyle değiştirir. Gizli veri, ağ geçidinin depolama alanında, farklı bir süreçte ve farklı bir kullanıcıya ait olarak barındırılır.

OneCLI, bunun açık kaynaklı bir uygulamasıdır. ee/ dizinleri hariç Apache-2.0 lisansına sahiptir; bu dizinler, üretim ortamında kullanım için abonelik gerektiren ayrı bir kurumsal lisansa tabidir ve ajanla yan yana konteynerlerde çalışır. Ekim 2026 itibarıyla proje, compose dosyasının yanındaki bir .env dosyasından oluşturulan üç gizli veriyi okuyan şu Docker Compose kurulumunu belgelemektedir:

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
docker compose up -d --wait

Bu .env dosyasını yedekleyin; çünkü SECRET_ENCRYPTION_KEY dosyasını kaybetmek, onunla depolanan tüm gizli verileri yetim bırakır. Kontrol paneli 10254 numaralı portu, ağ geçidi ise 10255 numaralı portu dinler; her ikisi de varsayılan olarak 127.0.0.1 adresine bağlıdır. Gerçek kimlik bilgisini bir kez depolarsınız, ardından her ajana anahtar yerine bir yer tutucu değer ve ajanın kendi kapsamlı erişim belirtecini verirsiniz; ajan bunu bir Proxy-Authorization başlığında gönderir. Ağ geçidi, giden isteği ana bilgisayar ve yol bilgisine göre eşleştirir, eşleşen kimlik bilgisinin şifresini çözer ve yerini değiştirir. Ajanın ortamı, gerçek kimlik bilgisi yerine kapsamlı ağ geçidi belirtecini tutar.

Buradaki değer şifrelemeden gelmez. "Bu ajan neyi, ne zaman kullandı" sorusunun bir günlük sorgusuna dönüşmesinden gelir. Altı ortamdan hangisinin anahtarın bir kopyasını tuttuğunu tahmin etmek yerine, tek bir denetim izini okursunuz.

Gizli veriyi ortama değil, sürece iletin

Ajanı systemd altında çalıştırıyorsanız, ortam değişkenlerine hiç ihtiyaç duymazsınız. LoadCredential=, gizli veriyi yalnızca servis kullanıcısının ve süper kullanıcının okuyabildiği özel bir dizine yerleştirir; bu dizin birim dosyasında %d olarak, süreç içerisinde ise $CREDENTIALS_DIRECTORY olarak sunulur. Bu kısıtlama servise değil kullanıcıya özeldir, bu nedenle her ajan servisine kendi kullanıcısını atayın: aynı kullanıcıyla çalışan başka bir süreç, birim dosyasında PrivateMounts=yes gibi dosya sistemi isim alanlandırması (filesystem namespacing) kullanılmadığı sürece dizini açabilir; bu ayar dizini diğer servislerden gizler. Değer hiçbir zaman /proc/<pid>/environ içerisinde görünmez, bu nedenle ps eww bunu gösteremez ve servis durduğunda dizin ortadan kalkar.

Kimlik bilgisini öncelikle makineye özel şifreleyin. Bu komutlar systemd belgelerinden alınmıştır ve Ubuntu 24.04 ile Debian 13 sürümlerini kapsayan systemd 250 veya daha yeni sürümlerde çalışır:

echo -n 'sk-example-value' > /tmp/plain.txt
sudo systemd-creds encrypt --name=api_key /tmp/plain.txt /etc/credstore/api_key.cred
shred -u /tmp/plain.txt
sudo systemd-run -P --wait -p LoadCredentialEncrypted=api_key:/etc/credstore/api_key.cred \
  systemd-creds cat api_key

Son komut sk-example-value çıktısını verir. Bu, şifrelenmiş dosyanın bu ana makinede şifresinin çözülebildiğini kanıtlar. Ardından, birim dosyasından buna referans verin:

[Service]
User=agent-review
LoadCredentialEncrypted=api_key:/etc/credstore/api_key.cred
Environment=AGENT_KEY_FILE=%d/api_key
ExecStart=/usr/local/bin/agent-worker

Ajan kodunuz, değere ihtiyaç duyduğunda $AGENT_KEY_FILE konumundaki dosyayı açar. Kimlik bilgisi, servis çalıştığı sürece ajan ve onun alt süreçleri tarafından okunabilir durumda kalır. Bir ortam değişkeni ise, oluşturduğu her alt süreçte, sürecin yaşam döngüsü boyunca varlığını sürdürür.

Uzun ömürlü anahtarlar yerine kısa ömürlü belirteçleri tercih edin

Süresi asla dolmayan bir anahtar, aylar sonra bir günlük kaydında veya dökümde ortaya çıktığında dahi geçerliliğini korur. Servis bir oturum belirteci (session token) sunuyorsa, bu belirteci kullanın ve işin gerektirdiği en kısa ömrü atayın.

aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/agent-readonly \
  --role-session-name agent-review \
  --duration-seconds 900

On beş dakika, AWS STS (security token service) tarafından kabul edilen minimum süredir ve genellikle tek bir aracı görevi için yeterlidir. GitHub için, aracı kullanıcıya yalnızca üzerinde çalıştığı tek bir depo ile sınırlandırılmış, ayrıntılı yetkilendirilmiş bir belirtece sahip kendi gh girişini tanımlayın; böylece o oturum içindeki gh auth token komutu, diğer depolara yazma yetkisi olmayan bir sonuç döndürür. Kısıtlamaları önce kaynak bazında, ardından zaman bazında uygulayın.

Doğrulama yapın ve doğrulamaya devam edin

Bir ajanın kurulumunda yapılan herhangi bir değişiklikten sonra üç kontrolün yapılması yararlıdır. Bu kontrolleri kendi kullanıcınızla değil, ajanın kullanıcısıyla çalıştırın.

sudo -u agent-review env | grep -iE 'key|token|secret'
sudo -u agent-review ls -la /home/you/ 2>&1 | head -3
sudo -u agent-review curl -s -o /dev/null -w '%{http_code}\n' --max-time 5 https://api.github.com/user

İlk komut hiçbir çıktı üretmemelidir. İkinci komut ls: cannot open directory '/home/you/': Permission denied çıktısını vermelidir; ancak bu sadece dizinin listelenemediğini gösterir; içerisindeki bir dosyanın okunamadığını kanıtlayan işlem, daha önce yapılan cat testidir. Üçüncü komut, ajanın ağ yolunun hangi kimliği sunduğunu belirtir; bu, gateway modelinin yanıtlamak için var olduğu sorudur: 401, isteğin GitHub'a ulaştığını ancak GitHub tarafından kabul edilen bir kimlik bilgisinin sunulmadığını (hiç sunulmadığını, geçersiz olduğunu veya süresinin dolduğunu) gösterir. 200 ise geçerli bir kimlik bilgisinin iletildiğini gösterir; bu sayede hangi token'ın kullanıldığını bilmeniz gerekir. Ajanları gözetimsiz olarak çalıştırıyorsanız, bir VPS üzerinde yapay zeka ajanı maliyetlerini kontrol etme rehberi, bu erişim sınırlarıyla birlikte uygulanan bütçe limitlerini kapsar.

FAQ

Anahtar bilgilerimi sızdırmaması için modele güvenebilir miyim?

Hayır, çünkü bu tehdit modelinde saldırgan model değildir. Ajan; web sayfalarından, depolardan ve hata takip sistemlerinden metin okur ve bu metinler talimatlar içerebilir. Modelin, sizin verdiğiniz talimatları getirdiği metinlerden ayırt etmesi için güvenilir bir yolu yoktur. Modelin doğru seçim yapmasına dayanan her türlü denetim mekanizması, enjekte edilen bir talimat ikna edici olduğu anda başarısız olur. Bu nedenle denetim mekanizması işletim sistemi veya ağ katmanında yer almalıdır.

Ortam değişkenleri (environment variables) ajan sırları için gerçekten bu kadar kötü mü?

Belirli bir açıdan kötüdürler: miras alınırlar. Ajanın başlattığı her alt süreç (child process), derleme betikleri, test çalıştırıcıları ve paket kurulum kancaları dahil olmak üzere bu değişkenlerin bir kopyasını alır. Değişkenler aynı kullanıcı tarafından /proc/<pid>/environ üzerinden okunabilir; bu nedenle ajanın çalıştırdığı her şey, ajan herhangi bir aktarım yapmasa bile bu değişkenleri okuyabilir. LoadCredential=, sırrın ortama kopyalanmasını engeller ancak kimlik bilgisi dosyası servis çalıştığı sürece okunabilir kalır; bir ağ geçidi (gateway), gerçek kimlik bilgisini ajanın sürecinin dışında tutar.

Sırları bir kasada (vault) saklamak bu sorunu tek başına çözer mi?

Sadece kısmen. Kasa, depolama sorununu çözer. Eğer bu kasayı kendiniz barındırıyorsanız (self-host), kendi güvenlik sıkılaştırma sürecinden geçmesi gerekir; çünkü bir Vaultwarden sunucusu genellikle içindeki şifreli öğelerden değil, yönetici belirteci veya yedekleme dosyası üzerinden ele geçirilir. Bu yöntem, bir sürecin sırrı kasadan çekip ajana ortam değişkeni olarak verdiği son adımı düzeltmez; bu da sizi başladığınız noktaya geri döndürür. Önemli olan, yer değiştirme işlemini kimin yaptığıdır. Eğer sırrı ajan çekiyorsa, sır ajanın elindedir. Eğer yer değiştirme işlemi ajanın süreci dışında bir ağ geçidi tarafından yapılıyorsa, ajan sırra hiçbir zaman sahip olmaz. Eğer systemd bunu LoadCredential= üzerinden sağlıyorsa, ajan yine de kimlik bilgisi dosyasından sırrı okuyabilir.

Bir ajanın halihazırda bir şey sızdırıp sızdırmadığını nasıl anlarım?

Genellikle olay gerçekleştikten sonra bunu anlayamazsınız; ağ geçidi kullanmanın temel argümanı da budur. Ağ geçidi olmadan kanıtlarınız; kabuk geçmişi (shell history), ajanın transkripti ve muhtemelen tutmadığınız giden bağlantı kayıtları arasında dağılmış durumdadır. Bir kimlik bilgisi ağ geçidi ile, her kimlik bilgisi kullanımı ajan kimliği ve zaman damgası ile tek bir satırda kayıt altına alınır. Bir sızıntıdan şüpheleniyorsanız, önce anahtarı değiştirin (rotate), sonra araştırın. Anahtar değişimi ucuzdur, kesinlik ise değildir.

Bugün yapmam gereken en az şey nedir?

Her .env dosyasını ajanlarınızın çalıştığı dizinlerden taşıyın ve her ajan için ayrı, yetkisiz bir kullanıcı oluşturun. Bu iki değişiklik yaklaşık on dakika sürer ve en yaygın yolu kapatır; bu yol, ajanın kodun yanında durması için hiçbir neden olmayan bir kimlik bilgisi dosyasını okumasıdır. Ağ geçidi ve kısa ömürlü belirteçler (short lived tokens) ilk değil, bir sonraki adımdır. Aynı başlangıç noktası, otonom bir ajanı bir VPS üzerinde güvenli bir şekilde çalıştırmak dahil olmak üzere tüm ajan çalışma zamanları için geçerlidir.

Bu yazı işinize yaradı mı?