API Anahtar Saklama En İyi Pratikler: Güvenli Entegrasyon

Bir API anahtarı, onu taşıyan herkese senin adına işlem yapma yetkisi verir. Bu yüzden anahtarın nasıl oluşturulduğu kadar nerede ve nasıl saklandığı da önemlidir. Bu yazıda LLCBullet'teki kişisel API anahtarlarını ve webhook gizli anahtarlarını güvenle saklamak için uygulanabilir pratikleri, sızıntı şüphesinde izleyeceğin adımlarla birlikte anlatıyoruz.

Ne saklıyoruz?

LLCBullet entegrasyonlarında iki tür gizli değerle çalışırsın:

• Kişisel API anahtarı: Bir anahtar kimliği (lbk_ ile başlar) ve bir gizli anahtardan (lbs_ ile başlar) oluşur. Gizli anahtar yalnızca bir kez gösterilir ve imzalı istekle 15 dakika geçerli bir erişim jetonu almak için kullanılır.
• Webhook gizli anahtarı: whsec_ ile başlar, webhook görevi oluşturulurken bir kez gösterilir ve gelen isteklerin imzasını doğrulamak için kullanılır.

İki gizli değer de kaybolduğunda panelden yeniden görüntülenemez; bu, sızıntı riskini azaltan bilinçli bir tasarımdır. Anahtar kimliği tek başına işe yaramaz, asıl korunması gereken gizli kısımdır. Anahtarın genel tanımı için API anahtarı sözlük maddesine bakabilirsin.

Kesinlikle kaçınman gerekenler

• Gizli anahtarı kaynak koda ya da kod deposuna yazmak. Depo sonradan herkese açılırsa ya da bir kopyası sızarsa anahtar da sızar; silinen satırlar depo geçmişinde kalmaya devam eder.
• Anahtarı tarayıcıda çalışan koda koymak. İstemci tarafındaki her değer kullanıcı tarafından okunabilir.
• Anahtarı sohbet gruplarında, e-postada ya da ekran görüntüsünde paylaşmak.
• Hata ayıklarken isteğin tamamını başlıklarıyla birlikte log dosyasına yazdırmak.
• Tüm betikler için tek bir anahtar kullanmak; biri sızdığında hepsini aynı anda değiştirmen gerekir.

Güvenli saklama yöntemleri

Ortam değişkenleri

Küçük kurulumlar için en pratik yöntemdir. Değerleri sunucudaki bir .env dosyasında tutup uygulama başlarken okursun; dosyanın depoya girmemesi için .gitignore'a eklenmesi şarttır. Uygulama başlarken değerlerin varlığını kontrol etmek, eksik yapılandırmanın sessiz hatalara dönüşmesini engeller. Log yazarken gizli değeri maskelemek de iyi bir alışkanlıktır:

// .env dosyası depoya eklenmez: .gitignore içinde ".env" satırı olmalı
const REQUIRED = ["LB_KEY_ID", "LB_KEY_SECRET", "LB_API_BASE"];

for (const name of REQUIRED) {
  if (!process.env[name]) {
    throw new Error(`${name} ortam değişkeni tanımlı değil`);
  }
}

// Loglarda yalnızca önek görünsün: "lbs_****"
export function mask(secret) {
  return typeof secret === "string" && secret.length > 8
    ? `${secret.slice(0, 4)}****`
    : "****";
}

Gizli değer yöneticileri

Birden çok sunucu ya da ekip üyesi söz konusuysa HashiCorp Vault, AWS Secrets Manager veya kullandığın bulut sağlayıcının benzeri bir gizli değer yöneticisi daha güvenlidir. Erişim kişi ve servis bazında yetkilendirilir, kimin hangi değeri ne zaman okuduğu kayda geçer ve değer değiştiğinde tüm servislere tek yerden dağıtılır. Konteyner ortamlarında Docker ya da Kubernetes secret mekanizmaları, CI/CD hatlarında ise platformun kendi gizli değer deposu aynı amaca hizmet eder.

Depoya girişi baştan engelle

İnsan hatasını tamamen önlemek zordur; bu yüzden gizli değerlerin depoya girmesini otomatik olarak yakalayan bir kontrol eklemek mantıklıdır. gitleaks gibi bir tarayıcıya lbs_ ve whsec_ önekleri için özel kural ekleyip aracı commit öncesi kanca ya da CI adımı olarak çalıştırmak, bu değerlerin yanlışlıkla depoya gönderilmesini yakalamana yardımcı olur.

Ekip içinde erişim

Gizli anahtarı ekip içinde kimin görebildiği de saklama yönteminin parçasıdır. Anahtarı yalnızca onu kullanan servisin ve o servisi yöneten kişinin erişebileceği yerde tut. Bir ekip üyesi ayrıldığında ya da görevi değiştiğinde, erişebildiği anahtarları yenilemeyi işten çıkış kontrol listesine ekle. Anahtarı ekip arkadaşına iletmek gerekiyorsa sohbet yerine gizli değer yöneticisinin paylaşım özelliğini kullan.

Anahtarı daha az değerli hale getir

En iyi saklama yöntemi bile sızıntı olasılığını sıfırlamaz. Bu yüzden anahtarın ele geçirilmesi durumunda verebileceği zararı baştan sınırla:

• En az yetki: Yalnızca gereken kapsamları seç. Sadece paket bitişlerini okuyan bir betiğe run:automation vermene gerek yok. Kapsam sonradan genişletilemez; bu da seni baştan düşünmeye zorlar.
• IP izin listesi: Sabit IP'li bir sunucudan çağırıyorsan tek adres ya da aralık biçiminde en fazla 10 satırlık liste ekle. Liste hem jeton alırken hem her istekte kontrol edilir. Ayrıntılar IP izin listesi rehberinde.
• Geçerlilik süresi: Anahtara 1 ile 365 gün arasında bir süre tanımla; unutulan anahtarlar kendiliğinden devre dışı kalır.
• Ayrı anahtarlar: Her betik ya da ortam için ayrı anahtar oluştur. Hesap başına en fazla 10 etkin anahtar olabilir, bu çoğu kurulum için yeterlidir.

Düzenli yenileme (rotasyon)

Anahtarları belirli aralıklarla yenilemek, fark etmediğin bir sızıntının etkisini sınırlar. Kesintisiz bir yenileme için şu sırayı izle:

1. Panelde API anahtarları sayfasından aynı kapsamlarla yeni bir anahtar oluştur ve Telegram'a gelen onay isteğini onayla.
2. Yeni gizli anahtarı gizli değer deposuna kaydet ve uygulamanı yeni değerle yeniden başlat.
3. Yeni anahtarla jeton alınabildiğini ve isteklerin çalıştığını doğrula.
4. Eski anahtarı iptal et. İptal anında geçerlidir ve o anahtarla alınmış açık jetonlar da hemen geçersiz olur.

Sızıntı şüphesinde yapılacaklar

1. Panele gir ve şüpheli anahtarı hemen iptal et.
2. Telegram'daki güvenlik bildirimlerini gözden geçir; senin haberin olmadan oluşturulmuş bir anahtar varsa onu da iptal et.
3. Profil ve güvenlik sayfasından aktif oturumlarını kontrol et ve tanımadığın oturumları kapat.
4. Webhook gizli anahtarının sızdığından şüpheleniyorsan ilgili görevi sil ve yeni bir görev oluşturarak yeni anahtar al.
5. Sızıntının kaynağını bul: depo geçmişi, log dosyaları, paylaşılan belgeler. Kaynağı kapatmadan yeni anahtarı aynı yere koyma.

Sonuç

Güvenli entegrasyonun formülü basittir: gizli değeri koddan uzak tut, yetkisini ve kullanılabileceği yeri daralt, düzenli yenile ve sızıntıda hızlı davran. Anahtar oluşturma ve imzalı istek adımları için kişisel API anahtarları rehberimize göz at.

API anahtarlarını yönet