API Dokümantasyonu Güvenliği: Git'teki Spesifikasyonlarınız Güvende mi?

API dokümantasyonu güvenliği, API programınızın neredeyse hiç kimsenin denetlemediği bir parçasıdır. API'nin kendisini kimlik doğrulama, hız sınırlamaları ve güvenlik testleri ile güçlendirirsiniz. Ancak bu API'yi açıklayan belgeler – OpenAPI spesifikasyonu, Swagger UI sayfası, kimlik doğrulama akışınızı açıklayan markdown dosyaları – genellikle bir Git deposunda veya kimsenin kurulduğu günden beri incelemediği statik bir barındırıcıda yaşar. 20 Mayıs 2026'da GitHub, saldırganların yaklaşık 3.800 dahili kod deposundan veri çaldığını doğruladı. Giriş noktası, bir GitHub çalışanının dizüstü bilgisayarına yüklenen zararlı bir VS Code uzantısıydı. Bu ihlal, kendi kurulumunuz hakkında rahatsız edici bir soru sormanız için iyi bir nedendir: Eğer birisi yayınladığınız API belgelerinizi sessizce değiştirebilseydi, bunu fark eder miydiniz ve API tüketicileriniz fark eder miydi?

ÖZET

Güvenli API dokümantasyonu, belgelerinizin erişim kontrolüne, sürüm geçmişine, doğrulayabileceğiniz bütünlüğe ve bir denetim izine sahip olması anlamına gelir; böylece güvenliği ihlal edilmiş bir depo veya barındırıcı, yanlış uç noktaları, belirteçleri veya kimlik doğrulama talimatlarını üretim ortamına kopyalayan geliştiricilere sessizce besleyemez. Git'teki kod olarak belgeler (Docs-as-code) birçok ekip için uygundur ve size ücretsiz inceleme ve geçmiş sağlar. Ancak depo erişim kontrolü olmadan herkese açık olduğunda, eski spesifikasyonlar canlı API'den saptığında veya değiştirilmiş bir örnek tüketicilere fark edilmeden ulaştığında bir sorumluluk haline gelir. Apidog gibi yönetilen bir dokümantasyon katmanı, parola koruması, IP ve e-posta beyaz listeleri, özel alan adları, sürüm kontrolü ve API tasarımınızla senkronize tutulan bir spesifikasyonu güvenilir bir kaynak olarak ekler.

GitHub ihlali neden API belgelerinize bakmanızı sağlamalı?

GitHub olayı, paniğe kapılmadan önce anlaşılmaya değer. Tehdit grubu TeamPCP, GitHub'ın dahili depolarını sızdırdı ve şimdi veri setini bir yeraltı forumunda 50.000 dolardan fazla bir fiyata satıyor. BleepingComputer'ın haberine göre, kötü amaçlı VS Code uzantısının doğrudan resmi pazardan geldiği ve bir çalışanın cihazında çalıştığı doğrulandı. GitHub, dahili depolarının dışında depolanan müşteri verilerinin etkilendiğine dair hiçbir kanıt bulunmadığını ve soruşturmanın devam ettiğini belirtiyor.

İhlalin yaptığı şey, size bir uyarı sunmaktır. Bu, API dokümantasyonunuzun nerede ve nasıl yaşadığına ve üzerinde değişiklik yapılıp yapılamayacağına bakmak için bir hatırlatmadır. Çoğu ekip bunu hiç sormamıştır. Üç yıl önce Swagger UI'yi GitHub Pages'a yayınladılar, ona bir CNAME yönlendirdiler ve yollarına devam ettiler. Depo herkese açık. Spesifikasyon, en son birleştirilen ne ise o. Hiç kimse, uygulama koduna gösterdiği özenle belgeler sitesindeki değişiklikleri incelemiyor.

Bu boşluk önemlidir çünkü API dokümantasyonu talimatlardır. Bir geliştirici API'nizle entegre olduğunda, uç nokta yollarını, istek şekillerini, kimlik doğrulama başlıklarını ve genellikle örnek değerleri doğrudan belgelerinizden kendi kodlarına kopyalar. Eğer bir saldırgan bu talimatları değiştirebilirse, bir pazarlama sayfasını bozmuş olmaz. Başkalarının çalıştıracağı kodu düzenliyor olurlar. Aynı mantık, 2026'daki diğer ihlallerin olay sonrası incelemelerinde de görülüyor; Vercel ihlalinden alınan API güvenlik dersleri hakkındaki yazımız, güvenilen bir yüzeydeki küçük bir değişikliğin nasıl yayıldığını ele alıyor.

Bu makale dört konuyu ele alıyor: güvenliği ihlal edilmiş API belgelerinin tüketicilerinize somut olarak nasıl zarar verdiği, Git'teki kod olarak belgelerin ne zaman gerçekten iyi olduğu ve ne zaman bir sorumluluğa dönüştüğü, 'güvenli API dokümantasyonu'nun bir kontrol listesi olarak gerçekte ne anlama geldiği ve yönetilen bir dokümantasyon katmanının bu boşlukları nasıl kapattığı. İlgili açılara daha derinlemesine inen iki kardeş yazı: GitHub ihlalinin kendi kendine barındırılan API araçları için anlamı ve VS Code uzantısı API anahtarı güvenliği.

API belgeleri deponuz veya barındırıcınız ele geçirildiğinde neler ters gider?

Tehdit modeliyle başlayalım. API belgeleriniz bazı yüzeylerde bulunur: bir Git deposu, onları oluşturan bir CI hattı ve onları sunan bir barındırıcı. Bunlardan herhangi birinin güvenliğinin ihlal edilmesiyle birlikte belirli kötü sonuçlar ortaya çıkar. Bunların hiçbiri teorik değildir.

Dokümantasyon değişikliği üretim koduna ulaşır

Bu en kötü ve en az belirgin durumdur. Belgeler deponuza veya oluşturulan siteyi sunan barındırıcıya yazma erişimi olan bir saldırgan, küçük bir düzenleme yapar. https://api.payments.acme.com/v2/charge adresini kontrol ettikleri bir alana değiştirirler. 'Başlarken' sayfanızdaki örnek bearer token'ı, kendi proxy'leri üzerinden yönlendirilen bir token ile değiştirirler. OAuth bölümünüzdeki tek bir cümleyi yeniden yazarak token alışverişinin yanlış URL'ye gönderilmesini sağlarlar.

Bunların hiçbiri sitenizi bozmaz. Sayfa hala işlenir. CI hala geçer, çünkü spesifikasyon hala geçerli bir YAML'dir. Ancak API'nizle entegre olan bir sonraki geliştirici, bu uç noktayı veya bu akışı hizmetine kopyalar. Değişiklik artık onların üretim ortamında çalışıyor ve resmi belgelerinizden geldiği için ona güvendiler.

Gerçekçi bir OpenAPI parçasını düşünün. Bir ekip, bir ödeme uç noktasını şu şekilde belgeliyor:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

O `servers` URL'sine yapılan tek bir düzenleme, güvenliği ihlal edilmiş bir hesap aracılığıyla birleştirildiğinde veya ele geçirilmiş bir barındırıcıya itildiğinde, spesifikasyondan bir istemciyi yeniden oluşturan her tüketici artık kart verilerini saldırganın alan adına gönderir. Fark iki kelimedir. Hiç kimse bir belge commit'inde iki kelimeyi işaretlemez.

Dahili ve belgelenmemiş uç noktalar sızar

Belge depoları bir şeyler biriktirir. Herkese açık API olarak başlayan bir spesifikasyon, genellikle yayınlanması amaçlanmayan yalnızca dahili yollar, yönetici uç noktaları, hata ayıklama rotaları veya yalnızca iş ortağına özel işlemlerle genişler. Depo herkese açıksa veya yanlış bir yapılandırma nedeniyle herkese açık hale gelirse, bu uç noktalar artık saldırı yüzeyinizi tarayan herkes için bir harita haline gelir.

Özel bir depo bile burada bir sorundur. GitHub'ınki gibi bir ihlal, özel depoları dışarı sızdırır. Dahili API spesifikasyonunuz çalınan bir depoda olduğu an, bir saldırgan uç noktalarınızın, parametrelerinizin ve beklenen yüklerinizin kesin bir envanterine sahip olur. Tahmin etmek zorunda kalmazlar. Şemayı onlara siz verdiniz. Başka biri bu boşlukları bulmadan önce bunları bulmak için bir çerçeve istiyorsanız, 2026 için API güvenlik test kontrol listemiz tam olarak bu tür bir yüzey incelemesi etrafında oluşturulmuştur.

Herkese Açık GitHub Pages'ın erişim kontrolü yoktur

GitHub Pages statik bir barındırıcıdır. Dosyaları sunar. Kimin okuduğuna dair hiçbir kavramı yoktur. Gerçekten herkese açık bir API için bu doğru ve sorunsuzdur. Ancak yalnızca ücretli müşterilere, belirli bir ortak grubuna veya kendi ekibinize görünmesi gereken belgeler için yanlış bir araçtır, çünkü hiçbir geçit yoktur.

Ekipler bunu 'tahmin etmesi zor bir URL aracılığıyla güvenlik' ile aşmaya çalışır. Belgeler kimsenin bağlamadığı bir yolda bulunur. Bu bir erişim kontrolü değildir. URL'ler tarayıcı geçmişi, referrer başlıkları, proxy günlükleri ve paylaşılan yer imleri aracılığıyla sızar. Bağlantıyı bulan herkes her şeyi, sonsuza dek görür ve sizin bunu bildiğinizi öğrenmenizin hiçbir yolu yoktur.

Eski ve doğrulanamaz belgeler

Daha sessiz başarısızlık modu hiç saldırgan gerektirmez. Git deposundaki belgeler sapar. Birisi bir API değişikliği yayınlar, spesifikasyonu güncellemeyi unutur ve markdown artık üretimde farklı davranan bir uç noktayı tanımlar. Tüketiciler belgelenmiş davranışa göre entegre olur, gerçek davranışla karşılaşır ve bir günü hata ayıklamayla geçirir.

Belgeler ele geçirildiğinde bu sorun daha da kötüleşir, çünkü sapmayı manipülasyondan ayırt etme yeteneğinizi kaybedersiniz. Bu uç nokta her zaman mı yanlıştı, yoksa birisi mi değiştirdi? Gerçek API tasarımınıza bağlı doğrulanabilir bir geçmiş olmadan buna cevap veremezsiniz. Belgeler doğrulanamaz hale gelir ve doğrulanamaz belgeler hiç belgeden daha iyi değildir.

Git'teki kod olarak belgeler ne zaman uygundur ve ne zaman bir sorumluluktur?

Kod olarak belgeler (Docs-as-code) yasal, popüler bir uygulamadır ve bu bölüm buna karşı bir argüman değildir. OpenAPI spesifikasyonunuzu ve markdown'ınızı bir Git deposuna koymak, CI ile Swagger UI veya Redoc oluşturmak ve statik bir barındırıcıya dağıtmak size gerçek faydalar sağlar. Belge değişiklikleri üzerinde çekme isteği incelemesi alırsınız. Kimin neyi ne zaman değiştirdiğine dair tam bir geçmişe sahip olursunuz. Belgeleri kodla birlikte sürüm kontrolüne alırsınız. İş akışı takip edildiğinde manipülasyonu tespit edilebilir kılan tam da bu özelliklerdir.

Dolayısıyla soru 'Git mi, değil mi' değil. Soru 'bu belirli kurulum, bu belirli API için güvenli mi' şeklindedir. İşte iki durumun ayrımı.

Git'teki kod olarak belgeler şu durumlarda uygundur:

Uygulama belirli koşullar altında iyi çalışır:

• API tamamen herkese açıksa, gizlenecek bir şey yoksa ve erişim kontrolüne gerek yoksa.
• Depo, dal korumasına, zorunlu incelemelere ve yazma erişimine sahip küçük, denetlenmiş bir kişi grubuna sahipse.
• Belge değişiklikleri kodla aynı inceleme titizliğinden geçiyorsa, böylece değiştirilen bir URL veya token incelemede yakalanır.
• Derleme hattı kilitliyse: sabitlenmiş eylemler, incelenmemiş üçüncü taraf adımlar yok, kapsamlı dağıtım kimlik bilgileri.
• Spesifikasyon gerçek API'den oluşturulmuş veya ona karşı doğrulanmışsa, elle düzenlenip umut edilmemişse.
• Birisi spesifikasyonu güncel tutmaktan sorumluysa, böylece sapma birikmez.

Eğer bunların hepsi geçerliyse, Git'te barındırılan belgeler güçlü ve şeffaf bir sistemdir. Geçmişiniz denetim izinizdir. İncelemeleriniz bütünlük kontrolünüzdür.

Git'teki kod olarak belgeler şu durumlarda bir sorumluluğa dönüşür:

Aynı kurulum, koşullar gevşediğinde riskli hale gelir:

• Belgeler özel veya yalnızca iş ortağına özel olmalı, ancak barındırıcının erişim kontrolü yoksa, "özel" kelimesi "bağlantısız" anlamına gelir.
• Yazma erişimi genişse veya kimsenin takip etmediği hizmet hesaplarını ve CI token'larını içeriyorsa.
• Belge commit'leri, "sadece belge" olduğu için damgalanıyorsa, böylece kötü amaçlı bir fark kolayca geçer.
• Spesifikasyon elle sürdürülüyor ve canlı API'den sapıyorsa, bu nedenle tüketiciler ona güvenemez.
• Depo, herkese açık uç noktaların yanı sıra dahili veya belgelenmemiş uç noktaları barındırıyorsa.
• Bütünlük sinyali yoksa: dağıtılan sitenin incelenen kaynakla eşleşip eşleşmediğini kimse söyleyemez.

GitHub ihlali tam olarak bu başarısızlık modlarına denk geliyor. Saldırı bir geliştirici uç noktası aracılığıyla geldi ve dahili depolara ulaştı. Eğer özel API spesifikasyonunuz bu depolardan birinde yaşasaydı, inceleme süreciniz ne kadar dikkatli olursa olsun ihlal şemanızı açığa çıkarırdı. Git size şeffaflık sağlar; ancak depo çalındığında gizlilik sağlamaz. Farklı kendi kendine barındırılan dokümantasyon yaklaşımlarının bu ödünleşimlerde nerede durduğuna dair daha kapsamlı bir karşılaştırma için, kendi kendine barındırılan API belgeleri karşılaştırmamıza bakın.

Çıkarım bilinçli olarak dengelidir. API'niz herkese açıksa ve hattınız disiplinliyse kod olarak belgelere devam edin. Belgelerinizin erişim kontrolüne ihtiyacı varsa, inceleme süreciniz belgeleri ikinci sınıf olarak ele alıyorsa veya 'canlı site incelenen kaynakla eşleşiyor mu?' sorusuna yanıt veremiyorsanız bunu yeniden gözden geçirin.

"Güvenli API dokümantasyonu" aslında ne anlama geliyor?

'Güvenli API dokümantasyonu', kontrol edebileceğiniz özelliklere ayırana kadar belirsizdir. Dördü ağırlık taşır.

Erişim kontrolü

Belgeler yalnızca onları görmesi gereken kişilere görünür. Herkese açık bir API için herkese açık. Yalnızca müşteriye özel, yalnızca iş ortağına özel veya dahili belgeler için kısıtlıdır. Kısıtlama, belirsiz bir URL değil, gerçek bir geçit, parola, IP beyaz listesi, e-posta beyaz listesi veya SSO olmalıdır. Test: Şu anda belgelerinizi kimlerin okuyabileceğini tam olarak adlandırabilir misiniz ve bunlardan birinin erişimini bir dakikadan kısa sürede iptal edebilir misiniz?

Sürümleme

Belgelerin yayınlanan her sürümü korunur ve tanımlanabilir. V1 API'nızdaki tüketiciler v1 belgelerini görür; v2 tüketicileri v2'yi görür. Belgelerin belirli bir tarihte ne söylediğini gösterebilirsiniz. Test: Eski API sürümünüzle entegre olan bir geliştirici, v2'ye sessizce güncellenen belgeler yerine, onun için hala doğru belgeleri bulabilir mi?

Bütünlük

Yayınlanan belgelerin amacınıza uygun olduğunu doğrulayabilirsiniz. Ya belgeler kontrollü bir doğruluk kaynağından üretilir ya da yetkisiz bir değişikliğin göze çarpmasını sağlayacak kadar güçlü bir inceleme ve geçmiş izi vardır. Test: Bir saat önce canlı belgelerinizdeki bir uç nokta URL'sini birisi değiştirseydi, size bir şey söyler miydi?

Denetim izi

Belgeleri kimin değiştirdiğini, neyi değiştirdiğini ve ne zaman değiştirdiğini yanıtlayabilirsiniz. Git geçmişi bunu depo için sağlar; ayrıca yayınlanan yüzey için de ihtiyacınız vardır, çünkü dağıtım adımı kendi başına bir saldırı noktasıdır. Test: Son 90 güne ait yayınlanmış belgeleriniz için bir değişiklik günlüğü oluşturabilir misiniz?

Bu dört özelliği de karşılayan bir kurulum güvenli dokümantasyondur. Git'te barındırılan belgeler, dal koruması ve geçmiş aracılığıyla sürümleme, bütünlük ve denetim izini sağlayabilir. Statik bir barındırıcıda genellikle kaçırdıkları ise erişim kontrolüdür ve bu boşluk, yönetilen bir dokümantasyon katmanı için geçerlidir.

Apidog size nasıl güvenli API dokümantasyonu sağlar?

Apidog, API'leri tasarlamak, hata ayıklamak, test etmek, taklit etmek ve belgelemek için hepsi bir arada bir API platformudur. Dokümantasyon tarafı, yukarıdaki dört özelliğin eklenen şeyler olmaktan ziyade varsayılan olarak gelmesi için tasarlanmıştır. Devam etmek için Apidog'u indirin ve bir API tanımı olan herhangi bir projeyi açın.

Kontrollü bir doğruluk kaynağından yayınlanan dokümantasyon

Apidog'da, dokümantasyon proje içindeki API tasarımınızdan oluşturulur. Uç noktaları, şemaları ve kimlik doğrulamasını görsel tasarımcıda tasarlarsınız ve Apidog, bu tanımdan dokümantasyonu otomatik olarak oluşturur. Yayınla'ya tıkladığınızda, 'Dene' konsolu ve çok dilli kod örnekleri içeren etkileşimli bir belge sitesi elde edersiniz.

Bütünlük faydası yapısal niteliktedir. Yayınlanan belgeler, kendi başına sapabilecek veya üzerinde oynanabilecek ayrı ayrı düzenlenebilir markdown dosyaları değildir. API tanımını yansıtırlar. Tanımı değiştirin, belgeler de değişir. Tüketicilerin gördüklerini değiştirmek için, statik bir barındırıcıdaki bağımsız bir dosyayı düzenlemek yerine, kendi izinleri ve değişiklik geçmişi olan projenin içindeki tasarımı değiştirirsiniz.

Dokümantasyon erişim kontrolü

Apidog, GitHub Pages boşluğunu işte burada kapatıyor. Yayınladığınızda görünürlüğü seçersiniz ve seçenekler gerçek kapılardır, belirsizlik değil:

• Herkese Açık: Bağlantısı olan herkes okuyabilir. Gerçekten açık bir API için doğrudur.
• Parola koruması: Bir parola belirleyin (veya rastgele bir parola oluşturun) ve paydaşlarla paylaşın. Yalnızca parolaya sahip kişiler erişebilir.
• IP beyaz listesi: Erişimi ofisiniz veya VPN'iniz gibi belirli IP'lerle veya aralıklarla kısıtlayın. Dahili belgeler için faydalıdır.
• E-posta beyaz listesi: İzin verilen e-posta adreslerini veya alan adlarını listeleyin; kullanıcılar tek kullanımlık bir kodla doğrular. *@sirketiniz.com gibi joker karakterler tüm bir kuruluşu kapsar.
• Özel giriş: Kendi kimlik doğrulama sisteminizi bağlayın; sunucunuz bir JWT yayınlar, Apidog bunu doğrular ve erişim geçerliliğe bağlıdır.

Apidog, beş yöntemi de API dokümantasyon erişimini kontrol etme rehberinde belgeler. Bu, erişim kontrolü testini doğrudan yanıtlar: belgeleri kimin okuyabileceğini belirtebilir ve bir parolayı iptal edebilir veya bir e-postayı beyaz listeden hemen çıkarabilirsiniz.

Özel alan adı

Yayınlanan belgeleri kendi alan adınızda sunabilirsiniz, böylece tüketiciler genel bir URL yerine developer.sirketiniz.com adresini görürler. Apidog, bir DNS CNAME (önerilen yol) veya ters proxy aracılığıyla özel bir alan adını destekler. Özel bir alan adı tek başına bir güvenlik kontrolü değildir, ancak belgelerinizi kimsenin sahip olmadığı ana bilgisayarlara dağıtmak yerine yönettiğiniz ve denetlediğiniz altyapıda tutar.

OpenAPI spesifikasyonu API tasarımınızla senkronize tutulur

Sapma, belgeleri doğrulanamaz hale getirdiği için bir dokümantasyon güvenlik sorunudur. Apidog, API tasarımını tek doğruluk kaynağı olarak kabul eder ve tasarım değiştikçe dokümantasyonu senkronize tutar. Apidog, OpenAPI 3.0, 3.1 ve Swagger 2.0'ı içe aktarır ve harici bir spesifikasyonun otomatik olarak güncel kalması için zamanlanmış içe aktarmaları destekler.

Şu anda bir spesifikasyonu bir Git deposunda elle tutuyorsanız, bu en yüksek sapma riski taşıyan, doğrulanması en zor kurulumdur. Spesifikasyonu doğruluk kaynağı olarak Apidog'a taşımak, yayınlanan belgelerin her zaman kontrol ettiğiniz bir tanıma uyması anlamına gelir. SwaggerHub'dan gelen ekipler, SwaggerHub API belgelerini Apidog'a taşıma rehberimizi takip edebilirler.

Dokümantasyon sürümleme

Apidog, dokümantasyon sürümlemeyi destekler, böylece birden çok sürümü yan yana yayınlayabilir ve tutabilirsiniz. V1 API'nızla entegre olan bir tüketici, v2 yayınlandıktan sonra bile doğru v1 belgelerini okur. Sürümleme, dallar ve değişiklik geçmişiyle bağlantılıdır, böylece API'nin ve belgelerinin evrimi takipte kalır. Bu hem sürümleme hem de denetim izi testlerini kapsar.

Bunların hiçbiri TeamPCP'nin bir geliştirici dizüstü bilgisayarını ele geçirmesini engelleyemezdi. Ancak farklı bir anlama gelir: belgelerinizi kimlerin okuyabileceğine, yayınlanan sürümün tasarımınızla eşleşip eşleşmediğine ve zaman içinde neyin değiştiğine dair net bir yanıt. GitHub ihlalinin sizi yapmaya itmesi gereken denetim budur.

Dokümantasyon barındırma seçeneklerini karşılaştırma

Dört güvenlik özelliğine göre yaygın yaklaşımların hızlı bir yan yana karşılaştırması.

Evrensel olarak doğru bir sıra yoktur. Herkese açık GitHub Pages, kilitli bir boru hattına sahip herkese açık bir API için iyi bir seçimdir. Kendi kendine barındırma, katı yerleşim veya izolasyon gereksinimleri olan ekipler için uygundur; kendi kendine barındırılan API belgeleri karşılaştırmamız ve Scalar vs SwaggerHub vs Apidog karşılaştırması bu ödünleşimleri ayrıntılı olarak ortaya koyar. Önemli olan, üç yıl önceki bir kurulumu miras almak ve bir daha asla bakmamak yerine, dört özelliğe karşı bilinçli bir seçim yapmaktır.

Sonuç

GitHub ihlali, kod olarak belgelerden vazgeçmek veya GitHub'a güvenmemek için bir neden değildir. Çoğu ekibin göz ardı ettiği bir yüzeyi denetlemek için bir uyarıdır: API dokümantasyonunuzun nerede yaşadığı ve üzerinde değişiklik yapılıp yapılamayacağı.

Sonraki adım: API belgelerinizin yayınlandığı her yeri listeleyin, her birini dört özelliğe göre kontrol edin ve en geniş boşluğu kapatın. Eğer erişim kontrolü boşluksa, Apidog'u indirin ve yönetilen bir katmanın bunu nasıl ele aldığını görmek için bir projenin belgelerini bir parola veya e-posta beyaz listesiyle yayınlayın.

Düğme