Express.js projelerinizdeki gizli API’leri tespit eden CLI aracı nasıl kullanılır?

Geliştirme sürecinde karşılaşılan en yaygın güvenlik zafiyetlerinden biri, gölge API’ler adı verilen ve genellikle geçici olarak eklenen ancak unutulan, belgelenmeyen ve yetkilendirme içermeyen API uç noktalarıdır. Bu API’ler, kod tabanında kalmayı sürdürerek üretim ortamına sessizce geçebilir ve ağ tarayıcılarından bile gizlenerek güvenlik ekiplerinin dikkatinden kaçabilir.

Express.js projelerinizde bu sorunu çözmek için ShadowAudit adlı yeni bir statik analiz aracı devreye giriyor. Bu CLI tabanlı araç, OpenAPI/Swagger belgelerinizle gerçek kod yapınızı karşılaştırarak belgelenmemiş ya da yetkilendirme içermeyen API uç noktalarını otomatik olarak tespit ediyor. Böylece, birleştirme talebinizi (PR) üretime göndermeden önce güvenlik açıklarını yakalayıp müdahale etme şansı sunuyor.

Gölge API’ler neden tehlikeli?

Geliştiriciler hızlıca test etmek amacıyla geçici API’ler ekleyebilir, ancak sonrasında bunları silmeyi unutabilir. Bu API’ler genellikle:

• Belgelendirme dışında kalır — OpenAPI/Swagger belgelerinde yer almaz.
• Yetkilendirme içermez — varsayılan olarak herkese açık olur.
• Üretim ortamına geçer — ağ taramalarından kaçabilir, çünkü statik olarak kodda bulunur.
• Güvenlik ekiplerinden gizlenir — çünkü otomatik araçlar tarafından tespit edilmesi zordur.

ShadowAudit, bu riskleri minimize etmek için tasarlandı. Araç, yalnızca Express.js projelerinde değil, yakın zamanda desteklenecek olan FastAPI ve Django projelerinde de kullanılabilecek.

ShadowAudit nasıl çalışır?

ShadowAudit, kod tabanınızdaki tüm API uç noktalarını statik olarak analiz eder ve bunları OpenAPI 3.x / Swagger 2.0 belgelerinizle karşılaştırır. Ardından, aşağıdaki durumları tespit eder:

• Belgelendirilmemiş API uç noktaları
• Yetkilendirme middleware’i olmayan ve belgelenmemiş uç noktalar
• Farklı yetkilendirme desenlerine sahip API’ler

Araç, bu tespitleri CI/CD borularında (pipeline) kullanarak birleştirme talebinizin engellenmesini sağlar. Böylece, üretim ortamına zararlı kodun geçişi önlenir.

Kurulum ve kullanım adımları

ShadowAudit’i projenize eklemek oldukça basit. Aşağıdaki komutlarla aracı global olarak ya da proje bazında kurabilirsiniz:

# Global olarak kurulum
npm install -g shadowaudit

# Proje bazında kurulum (geliştirme bağımlılığı olarak)
npm install --save-dev shadowaudit

Ardından, aracı projenizde çalıştırarak OpenAPI belgelerinizle karşılaştırma yapabilirsiniz:

# Temel kullanım
shadowaudit --dir ./src --spec ./openapi.json

# Belirli bir framework için zorlama
shadowaudit --dir ./src --spec ./openapi.json --framework express

# JSON formatında çıktı almak (CI entegrasyonları için)
shadowaudit --dir ./src --spec ./openapi.json --format json | jq '.findings | length'

# SARIF formatında çıktı almak (GitHub Code Scanning için)
shadowaudit --dir ./src --spec ./openapi.json --format sarif > results.sarif

CI/CD borularına entegrasyon

ShadowAudit, GitHub Actions gibi CI/CD platformlarına kolayca entegre edilebilir. Örneğin, aşağıdaki örnek bir GitHub Action workflow dosyasında nasıl kullanılacağını gösteriyor:

- uses: darkmaster0345/shadow-audit@v0.1.0-beta-2
  with:
    dir: './src'
    spec: './openapi.json'
    fail-on: 'critical'

Bu entegrasyon sayesinde, geliştiriciler birleştirme taleplerini gönderirken ShadowAudit’in tarama sonuçlarına göre otomatik olarak engellenebilir. Araç, aşağıdaki ciddiyet seviyelerine göre boruları durdurabilir:

• CRITICAL: Belgelenmemiş ve yetkilendirme içermeyen API uç noktaları.
• HIGH: Belgelenmemiş, ancak yetkilendirme middleware’i bulunan uç noktalar (inceleme önerilir).
• INFO: Bilgi düzeyinde bulgular.

Desteklenen çıktılar ve raporlama seçenekleri

ShadowAudit, farklı formatlarda çıktı üretebilir. Bunlar arasında:

• Tablo formatı (varsayılan): Renkli, okunabilir bir tablo halinde bulguları sunar. Her bulgu için ciddiyet, HTTP metodu, yol, dosya, satır ve yetkilendirme durumu gösterilir.
• JSON formatı: CI panelleri ve log toplama sistemleri için yapılandırılmış JSON çıktısı üretir.
• SARIF 2.1.0 formatı: GitHub Code Scanning, Azure DevOps gibi platformlarla entegrasyon için endüstri standardı bir format sunar.

Örnek bir taramadan elde edilen çıktılar

Aşağıda, ShadowAudit’in bir Express.js projesinde yaptığı gerçek bir tarama çıktısı yer alıyor:

[INFO] Yapılandırma dosyası bulunamadı, varsayılanlar kullanılıyor
╔════════════════════════════════╗
║ shadowaudit v0.1.0            ║
║ API Gölge Uç Noktası Tarayıcısı ║
╚════════════════════════════════╝
[INFO] Dizin: /tmp/auth-test
[INFO] Belge dosyası: /tmp/auth-test/openapi.json
[INFO] Format: tablo
[INFO] Hata durumu: kritik
[INFO] Framework: express
[INFO] Express.js uç noktası tarayıcısı çalıştırılıyor...

[✓] /tmp/auth-test dizininde 7 uç nokta bulundu
[INFO] GET /public/health → routes.js:6 [yetkilendirme var]
[INFO] GET /public/products → routes.js:7 [yetkilendirme var]
[INFO] GET /api/users → routes.js:9 [yetkilendirme var]
[INFO] POST /api/users → routes.js:13 [yetkilendirme var]
[INFO] GET /api/admin/dashboard → routes.js:17 [yetkilendirme var]
[INFO] GET /api/debug/reset → routes.js:21 [yetkilendirme YOK]
[INFO] POST /api/test/seed → routes.js:22 [yetkilendirme YOK]

Bu çıktıda görüldüğü gibi, araç iki adet belgelenmemiş ve yetkilendirme içermeyen uç nokta tespit etmiş. Bu bulgular, borunun durdurulmasına ve geliştiricilerin sorunu düzeltmesine olanak tanır.

Geleceğe dair bakış

ShadowAudit, sadece Express.js projeleriyle sınırlı kalmayacak. Geliştirici ekibi, yakın zamanda FastAPI ve Django projeleri için de destek eklemeyi planlıyor. Bu sayede, farklı framework’lerde geliştirilen projelerde de güvenlik açıklarının tespit edilmesi kolaylaşacak.

Ayrıca, araç sürekli olarak güncelleniyor ve kullanıcı geri bildirimleriyle daha da geliştirilmeye devam ediyor. Geliştiricilerin proje güvenliğini artırmak için ShadowAudit’i kullanmaları, üretim ortamında karşılaşılabilecek riskleri önemli ölçüde azaltacaktır.