Gitleaks ve TruffleHog ile Sızan Sırları Yakalama Rehberi: Git Geçmişi Taraması, .gitleaks.toml, pre-commit Kancası, Doğrulamalı Tarama ve CI Entegrasyonu

Kaynak koda, yapılandırma dosyalarına ya da git geçmişine yanlışlıkla eklenen API anahtarları, parolalar ve token'lar, saldırganların en kolay kullandığı giriş yollarından biridir. Depo herkese açık olmasa bile bir dosya bir kez commit edildiğinde geçmişte kalır; dosyayı silmek, sırrı geçmişten silmez. Bu rehberde iki popüler açık kaynak aracı, Gitleaks ve TruffleHog, ile sızan sırları depoda, dosya sisteminde ve konteyner imajlarında nasıl tespit edeceğinizi, commit öncesinde ve CI hattında nasıl engelleyeceğinizi ele alıyoruz. Komutlar ve seçenekler her iki projenin resmî GitHub belgelerine dayanır.

Gitleaks ve TruffleHog: fark nedir?

Özellik	Gitleaks	TruffleHog
Yaklaşım	Kural (regex) ve entropi tabanlı tespit	Yüzlerce dedektör; bulunan sırrı doğrulama
Tarama hedefleri	git, dir, stdin	git, github, filesystem, s3, docker ve daha fazlası
Yapılandırma	.gitleaks.toml	Komut satırı seçenekleri
Doğrulama	Yok (yalnızca tespit)	Sırrın hâlâ geçerli olup olmadığını denetler
Çıkış kodu	0 temiz, 1 sızıntı veya hata	0 temiz, 183 sonuç bulundu (--fail ile)

İkisi birbirinin rakibi olmak zorunda değildir: Gitleaks hızlı ve yerel kural yazmaya elverişlidir, TruffleHog ise "bu anahtar gerçekten geçerli mi?" sorusuna cevap vererek gürültüyü azaltır.

Gitleaks ile tarama

Gitleaks üç tarama modu sunar:

CODE TERMINAL

# Git geçmişini tara (tüm commit'ler)
gitleaks git -v /yol/depo

# Belirli bir commit aralığını tara
gitleaks git -v --log-opts="--all commitA..commitB" /yol/depo

# Dizin veya dosya tara (git gerekmez)
gitleaks dir -v /yol/dizin

# Standart girdiden tara
cat dosya.txt | gitleaks -v stdin

Kurulum için macOS'ta brew install gitleaks, Docker imajı olarak zricethezav/gitleaks:latest ya da kaynaktan derleme (make build) kullanılabilir. Çıkış kodu sızıntı bulunduğunda 1, temiz taramada 0'dır; bu sayede CI adımı sızıntıda otomatik başarısız olur.

Yapılandırma: .gitleaks.toml

Varsayılan kural setini genişletip kendi kuralınızı ve istisnalarınızı tanımlayabilirsiniz:

CODE TERMINAL

title = "Kurum Gitleaks yapılandırması"

[extend]
useDefault = true
disabledRules = ["generic-api-key"]

[[rules]]
id = "kurum-ic-token"
description = "Kuruma ait iç servis token'ı"
regex = '''kurum_[A-Za-z0-9]{32}'''
entropy = 3.5
keywords = ["kurum_"]
tags = ["ic-servis"]

[[rules.allowlists]]
description = "Test dosyalarını yoksay"
paths = ['''testdata/''']

Burada keywords alanı, regex çalışmadan önce hızlı ön eleme yapar; entropy ise rastgelelik eşiğidir ve "örnek_parola" gibi düşük entropili yer tutucuların yanlış pozitif üretmesini azaltır.

Yanlış pozitifleri ve eski bulguları yönetmek

Satır içi istisna: Bilinen bir test sırrının satırına #gitleaks:allow yorumu eklenir.
.gitleaksignore: Belirli bir bulguyu parmak iziyle (fingerprint) yoksayar (v8.10.0 ve sonrası).
Baseline: Mevcut bulguları bir kez raporlayıp sonraki taramalarda yalnızca yeni sızıntıları görmenizi sağlar.

CODE TERMINAL

gitleaks git --report-path gitleaks-report.json
gitleaks git --baseline-path gitleaks-report.json --report-path findings.json

Rapor biçimleri JSON, CSV, JUnit, SARIF ve özel şablondur. Ek olarak --max-decode-depth ile kodlanmış (percent, hex, base64) içerik çözülerek taranabilir, --max-archive-depth ile ZIP ve tarball arşivlerinin içine bakılabilir.

Commit öncesi engelleme: pre-commit

Sızıntıyı depoya girmeden yakalamanın en ucuz yolu commit öncesi kancasıdır. .pre-commit-config.yaml dosyasına şunu ekleyin ve pre-commit install komutunu çalıştırın:

CODE TERMINAL

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks

Buradaki sürüm belgedeki örnektir; kullanacağınız sırada güncel sürüm etiketini yazın.

TruffleHog ile doğrulamalı tarama

CODE TERMINAL

# Git deposu
trufflehog git https://github.com/trufflesecurity/test_keys --results=verified

# GitHub organizasyonu
trufflehog github --org=trufflesecurity --results=verified

# Yerel dosya sistemi
trufflehog filesystem yol/dosya1.txt yol/dizin

# Docker imajı
trufflehog docker --image trufflesecurity/secrets --results=verified

# S3 kovası
trufflehog s3 --bucket= --results=verified,unknown

Sonuç türleri üçtür: verified (sırrın geçerli olduğu doğrulandı), unverified (tespit edildi, doğrulanamadı) ve unknown (doğrulama hata nedeniyle tamamlanamadı). Çıktı JSON (--json), SARIF (--sarif) veya GitHub Actions biçiminde alınabilir. Sonuç bulunduğunda sıfır olmayan çıkış kodu için --fail bayrağı eklenir; bu durumda çıkış kodu 183'tür.

GitHub Actions üzerinde kullanım örneği:

CODE TERMINAL

- uses: trufflesecurity/trufflehog@main
  with:
    extra_args: --results=verified,unknown

Sızıntı bulunursa ne yapılmalı?

Önce sırrı iptal edin ve yenileyin. Geçmişten silmek yeterli değildir; sızdığı andan itibaren ele geçmiş sayılmalıdır.
Sırrın kullanıldığı tüm sistemlerde erişim günlüklerini inceleyin.
Gerekirse git geçmişini yeniden yazın; ancak bu, çatalların ve kopyaların temizlendiği anlamına gelmez.
Sırları koda değil, bir gizli değişken yöneticisine veya ortam değişkenine taşıyın.
TruffleHog'un doğruladığı (verified) bulguları öncelikli ele alın.

Önerilen katmanlı yaklaşım

Geliştirici makinesinde: pre-commit kancası ile Gitleaks.
CI hattında: her çekme isteğinde tarama; sızıntıda derlemeyi başarısız yapma.
Periyodik: tüm organizasyon ve Docker imajları için TruffleHog ile doğrulamalı tarama.
Baseline ve allowlist dosyalarını depoda sürümleyip gözden geçirin; istisnalar zamanla kalıcı gizlenme yoluna dönüşmemeli.

Sırların taranması tek başına yeterli değildir, ancak en ucuz ve en hızlı kazanımlardan biridir. Bir anahtarın yayımlanması ile kötüye kullanılması arasındaki sürenin kısalığı, tespiti commit anına çekmeyi haklı çıkarır.

Kaynaklar

Gitleaks: https://github.com/gitleaks/gitleaks
TruffleHog: https://github.com/trufflesecurity/trufflehog

TR Siber Ekibi Yazar · TRSiber

← Ana sayfaya dön