Content-Security-Policy örnekleri: modern bir site için sıkı CSP nasıl oluşturulur

1. Content-Security-Policy ne yapar, ne yapmaz

Politika, noktalı virgülle ayrılmış direktifler listesidir. Her direktif bir kaynak türünü ve ona izin verilen kaynakları belirtir: JavaScript için script-src, CSS için style-src, img-src, font-src, fetch, XHR ve WebSocket bağlantıları için connect-src ve sayfanın gömdüğü çerçeveler için frame-src. default-src, belirli bir direktif eksik olduğunda bu fetch direktifleri için yedek değerdir (W3C CSP Level 3).

Üç önemli direktif default-src’ye düşmez: frame-ancestors (sayfanızı hangi siteler çerçeveleyebilir), base-uri (bir <base> öğesi neyi ayarlayabilir) ve form-action (formlar nereye gönderilebilir). Dolayısıyla yalnızca default-src 'self' içeren bir politika, her sitenin sayfayı çerçevelemesine ve enjekte edilmiş bir <base> etiketinin göreli URL’leri yönlendirmesine izin vermeye devam eder.

Kaynak değerleri üç türdür:

• Tek tırnak içindeki anahtar sözcükler: 'self' (sayfanın kendi origin’i), 'none' (hiçbir şey), 'unsafe-inline', 'unsafe-eval' ve 'strict-dynamic'.
• Hostlar ve şemalar: https://cdn.example.com, https://*.example.com, https: veya data:.
• Nonce ve hash’ler: 'nonce-…' ve 'sha256-…'; tüm hostlar yerine tek tek betik veya stil öğelerine izin verir.

Politikayı HTTP başlığı olarak gönderin. <meta http-equiv="Content-Security-Policy"> etiketi çoğu direktif için çalışır, ancak şartname orada frame-ancestors, report-uri ve sandbox direktiflerini dışarıda bırakır ve Report-Only politikası meta etiketiyle hiç iletilemez (MDN CSP rehberi). Beklentiyi gerçekçi tutun: CSP, enjekte edilen kodun yapabileceklerini sınırlar. Enjeksiyonu en başta durduran çıktı kaçışlamanın ve girdi doğrulamanın yerini almaz.

2. Başlangıç için üç Content-Security-Policy örneği

Örnek A: üçüncü taraf betiği olmayan site. Her betik ve stil dosyası kendi origin’inizdeyse allowlist politikası işe yarar:

Content-Security-Policy: default-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'; upgrade-insecure-requests

Her satır içi <script>’i, her style niteliğini ve başka hostlardan yüklenen her şeyi engeller; bu yüzden gömülü içeriği olmayan, elle yazılmış veya statik üretilmiş sitelere uygundur.

Örnek B: nonce kullanan, sunucuda render edilen site. web.dev’in sunucunun her istekte oluşturduğu sayfalar için önerdiği sıkı politikadır; çerçeveleme koruması da eklenmiştir:

Content-Security-Policy: script-src 'nonce-R4nd0mBase64Value' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'

Nonce her yanıtta değişir (bölüm 3). Neyi dışarıda bıraktığına dikkat edin: default-src olmadığı için stiller, görseller, yazı tipleri ve bağlantılar kısıtlanmaz. Bu bilinçli bir takastır: siteler arası betik çalıştırma zararının çoğunun yaşandığı betik yürütmeye odaklanır ve bir sağlayıcı alan adı değiştirdiğinde bozulan host listelerinden kaçınır.

Örnek C: hash’li statik veya önbelleğe alınmış sayfalar. Aynı HTML herkese sunuluyorsa satır içi betiklere hash’leriyle izin verin:

Content-Security-Policy: script-src 'sha256-BASE64_HASH_OF_INLINE_LOADER' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'

Hangisini seçerseniz seçin, bölüm 6’daki raporlama direktiflerini ekleyin ve önce Content-Security-Policy-Report-Only olarak gönderin.

3. 'unsafe-inline' yerine nonce ve hash

'unsafe-inline', saldırganın enjekte ettiği dahil her satır içi betiğe izin verir ve CSP’nin siteler arası betik çalıştırmaya karşı sunduğu korumanın çoğunu ortadan kaldırır. Nonce ve hash’ler yalnızca göndermeyi amaçladığınız satır içi koda izin verir. Tarayıcılar, nonce veya hash de içeren bir direktifte 'unsafe-inline' değerini yok sayar (MDN); bu yüzden çok eski tarayıcılar için yedek olarak sıkı bir politikada kalabilir.

Nonce

Nonce, sunucunun her yanıt için ürettiği, başlığa koyduğu ve çalıştırmayı amaçladığı her betiğin nonce niteliğine kopyaladığı rastgele bir değerdir. Tahmin edilemez ve her yanıtta yeni olmalıdır; web.dev, kriptografik olarak güvenli bir üreteçten en az 128 bit önerir. Bir Node.js uygulamasında:

import crypto from 'node:crypto';

app.use((req, res, next) => {
  const nonce = crypto.randomBytes(16).toString('base64');
  res.locals.nonce = nonce;
  res.setHeader('Content-Security-Policy',
    `script-src 'nonce-${nonce}' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'`);
  next();
});

Şablon ardından aynı değerle <script nonce="…" src="/app.js"></script> yazar. Nonce’u şablonlarınızın kendi betik etiketlerini yazdığı yere ekleyin; bitmiş HTML’deki her <script>’i yeniden yazarak asla eklemeyin: toptan yeniden yazım, saldırganın enjekte ettiği betiği de onaylar. İki tuzak yaygındır: HTML’i saklayan bir CDN veya sayfa önbelleği aynı nonce’u her ziyaretçiye tekrar gönderir ve derleme sırasında statik dosyaya gömülen değer hiçbir şekilde nonce değildir.

Hash

Hash, tek bir satır içi betiğe izin verir: betik etiketleri arasındaki metnin base64 kodlu SHA-256, SHA-384 veya SHA-512 özeti. Boşluklar ve satır sonları dahil her karakter önemlidir; bu yüzden bir minifier veya şablon değişikliği yeni hash üretir. Bu da içeriğin her yanıtta aynı olduğu statik ve önbelleğe alınmış sayfalar için hash’i daha uygun kılar. Chrome, satır içi betiği engellediğinde beklenen hash’i konsola yazar; kendiniz de hesaplayabilirsiniz:

printf '%s' 'console.log("hello")' | openssl dgst -sha256 -binary | openssl base64

İkisinin de izin vermedikleri

onclick="…" gibi satır içi olay işleyicileri ve javascript: URL’leri, nonce veya hash tabanlı politikada engellenir. Bu kodu betik dosyalarına taşıyın ve addEventListener ile bağlayın. 'unsafe-hashes' tek bir işleyiciye hash’iyle izin verebilir, ancak bunu geçici çözüm olarak görün. eval(), new Function() veya metinle setTimeout gibi metni kod olarak çalıştıran kod 'unsafe-eval' gerektirir; mümkün olduğunda değiştirin, yalnızca WebAssembly derlemesi gerekiyorsa daha dar olan 'wasm-unsafe-eval' kullanın (MDN script-src).

4. strict-dynamic: güvenilen betiklerin ihtiyaç duyduğunu yüklemesine izin verin

Çoğu site, başka betikler yükleyen betikler çalıştırır: etiket yöneticisi analitik ekler, onay bannerı kendi sağlayıcılarını ekler, sohbet bileşeni kendi paketini çeker. Kullanabilecekleri her hostu listelemek kırılgandır. 'strict-dynamic' farklı bir yol izler: nonce veya hash ile izin verilen bir betik başka betikler ekleyebilir ve onlara da güvenilir.

Destekleyen tarayıcılarda 'strict-dynamic', tarayıcının script-src içindeki host allowlist’lerini, 'self' ve 'unsafe-inline' değerlerini yok saymasını da sağlar (MDN). Üç sonuç doğar:

• HTML’inizdeki her <script> etiketi, kendi origin’inizdekiler dahil, nonce veya eşleşen bir hash gerektirir; çünkü 'self' artık onlara izin vermez.
• Güvenilen bir betiğin document.createElement('script') ile oluşturduğu betiklere izin verilir. document.write ile sayfaya yazılan betiklere (parser tarafından eklenen betikler) izin verilmez; dolayısıyla buna dayanan eski gömme kodları bozulur.
• Güven aktarılır. Etiket yöneticinizin yüklediği her şey çalışır; bu yüzden etiket yöneticisinde yayın yapabilen herkes fiilen sitenizde kod çalıştırabilir. Bu erişime dağıtım (deploy) erişimi gibi davranın.

Eski tarayıcılar için yeni tarayıcıların yok saydığı yedekler ekleyin:

script-src 'nonce-R4nd0mBase64Value' 'strict-dynamic' https: 'unsafe-inline'; object-src 'none'; base-uri 'none'

CSP Level 3 destekleyen bir tarayıcı yalnızca nonce ve 'strict-dynamic' değerlerini uygular. Nonce’u bilen ama 'strict-dynamic'’i bilmeyen bir tarayıcı nonce ve https: kullanır; çok eski bir tarayıcı ise 'unsafe-inline' https: değerine düşer. Google, nonce’u eklediği betiklere ileten, nonce destekli bir Tag Manager kod parçası belgeler ve Tag Manager’daki özel JavaScript değişkenlerinin hâlâ 'unsafe-eval' gerektirdiğini belirtir (Tag Manager CSP rehberi).

5. frame-ancestors, object-src 'none' ve base-uri: açıkça eklenmesi gereken direktifler

• frame-ancestors, sayfanızı hangi sitelerin çerçeveye gömebileceğine karar verir; clickjacking’e karşı savunmadır. Kimsenin sayfayı çerçevelemesi gerekmiyorsa 'none', yalnızca kendi sayfalarınız çerçeveleyecekse 'self' kullanın veya https://app.example.com gibi kesin origin’leri listeleyin. Yalnızca HTTP başlığında çalışır. X-Frame-Options (DENY veya SAMEORIGIN) eski tarayıcılar için yedek olarak kalır; ikisinin de aynı çerçevelemeye izin vermesini sağlayın (MDN frame-ancestors).
• object-src 'none', <object> ve <embed> öğelerini engeller. Eklentiler modern tarayıcılardan kalktı, ancak bu öğeler hâlâ içerik yükleyebilir ve default-src olmayan sıkı bir politika, siz belirtmedikçe onları kısıtsız bırakır.
• base-uri 'none', ya da sayfalarınız <base> öğesi kullanıyorsa 'self', enjekte edilmiş bir <base href>’in her göreli betik URL’sini başka bir hosta yönlendirmesini engeller.
• form-action 'self', formların nereye gönderilebileceğini sınırlar. Bir form ödeme veya giriş sağlayıcınıza gönderiyorsa o origin’i ekleyin ve değişiklikten sonra bu akışları test edin.
• upgrade-insecure-requests, tarayıcının http:// alt kaynaklarını HTTPS üzerinden almasını sağlar. Karışık içeriğe yardımcı olur ama HSTS’nin yerini tutmaz.

Bu direktifleri yukarıdaki B ve C örnekleri dahil her politikaya açıkça yazın. Neredeyse hiç bakım gerektirmezler ve betik kurallarının açık bıraktığı boşlukları kapatırlar.

6. report-to ve report-uri ile ihlalleri raporlama

İhlal raporları, bir politikanın gerçek ziyaretçilerin tarayıcılarında neyi engellediğini veya Report-Only modunda neyi engelleyeceğini söyler. CSP Level 3, Reporting-Endpoints başlığında tanımlanan bir uç noktayı adlandıran report-to’yu tanımlar ve doğrudan URL alan eski report-uri’yi kullanımdan kaldırır. MDN, report-to’yu 2026’dan itibaren güncel tarayıcılarda yeni kullanılabilir olarak listeler; eski tarayıcı sürümleri yalnızca report-uri’yi anlar. report-to destekleyen tarayıcılar report-uri’yi yok sayar; bu yüzden şimdilik ikisini de gönderin (MDN report-to):

Reporting-Endpoints: csp="https://example.com/csp-reports"
Content-Security-Policy-Report-Only: script-src 'nonce-R4nd0mBase64Value' 'strict-dynamic' 'report-sample'; object-src 'none'; base-uri 'none'; report-uri https://example.com/csp-reports; report-to csp

İki mekanizma farklı biçimlerde gönderir. report-uri, csp-report anahtarlı bir JSON nesnesini application/csp-report içerik türüyle gönderir. report-to ise application/reports+json gönderir: type değeri csp-violation olan ve gövdesinde documentURL, blockedURL, effectiveDirective ve disposition (enforce veya report) gibi alanlar bulunan raporlar dizisi. 'report-sample' ile engellenen satır içi kod raporu, kodun ilk 40 karakterini içerir. Aynı uç noktada her iki biçimi de kabul edin.

• Gürültü bekleyin. Tarayıcı eklentileri betik enjekte eder ve chrome-extension:// veya moz-extension:// gibi kaynak dosyalarla ihlal tetikler. Raporları direktife ve engellenen hosta göre gruplayın; tekil kayıtlar yerine örüntülere bakın.
• Raporları kişisel veri olarak değerlendirin. Belge URL’leri ve referrer’lar e-posta adresi veya token içeren sorgu dizeleri taşıyabilir. Bunları temizleyin veya kısaltın, raporları yalnızca kısa süre saklayın ve sebepsiz yere başkalarına aktarmayın.
• Uç noktayı koruyun. Herkes sahte rapor gönderebilir; boyut ve hız sınırları uygulayın ve rapor içeriğini yönetici ekranında asla kaçışlamadan göstermeyin.

7. Genellikle ne bozulur: analitik, yazı tipleri, satır içi betikler ve gömmeler

İlk günlerdeki ihlallerin çoğu birkaç kaynaktan gelir. Raporun effectiveDirective alanı hangi kurala bakmanız gerektiğini söyler:

Satır içi stiller satır içi betiklerden daha küçük bir risktir ama zararsız değildir: enjekte edilen CSS ziyaretçilerin gördüğünü değiştirebilir ve nitelik seçicileriyle bazı sayfa verilerini sızdırabilir. Birçok framework ve CSS-in-JS kütüphanesi çalışma anında stil öğeleri ekler; bu yüzden style-src’den 'unsafe-inline'’ı kaldırmadan önce kullandığınızın nonce destekleyip desteklemediğini kontrol edin. Yazı tiplerini ve kütüphaneleri kendiniz barındırmak bu satırların birkaçını birden ortadan kaldırır ve politikayı kısa tutar.

8. CSP’yi aşamalı olarak devreye alma

1. Envanter. Önemli sayfalarınızdaki betikleri, stilleri, yazı tiplerini, çerçeveleri ve bağlantı hedeflerini listeleyin: ana sayfa, giriş, hesap, ödeme ve gömülü bileşen içeren sayfalar. DevTools Network paneli ve etiket yöneticisi yapılandırmanız en hızlı kaynaklardır.
2. Report-Only. Taslağı raporlamayla birlikte Content-Security-Policy-Report-Only olarak gönderin. Hiçbir şey engellenmez; ihlaller konsolda ve uç noktanızda görünür. Az ziyaret edilen sayfaların ve kampanyaların ortaya çıkması için yeterince uzun, genellikle bir hafta veya daha fazla çalışır bırakın.
3. Politikayı değil kaynakları düzeltin. Nonce ekleyin, satır içi işleyicileri dosyalara taşıyın, yazı tiplerini kendiniz barındırın. Host veya 'unsafe-eval'’i yalnızca sahibi ve gerekçesi olan kayıtlı bir istisna olarak ekleyin.
4. Uygulayın. Başlık adını Content-Security-Policy olarak değiştirin. Bir sonraki sıkılaştırmayı test etmek için yanında daha sıkı bir Report-Only politikası çalıştırın: iki başlık birlikte geldiğinde tarayıcı birini uygular, diğerini yalnızca raporlar.
5. İzlemeye devam edin. Yeni bir pazarlama etiketi, eklenti güncellemesi veya framework yükseltmesi yeni satır içi kod getirebilir. Raporlama uç noktasını çalışır tutun ve her sunucu, CDN veya framework değişikliğinden sonra başlığı yeniden kontrol edin.

İki altyapı ayrıntısı birçok sürprize yol açar. Bir CDN veya framework kendi CSP başlığını ekliyorsa tarayıcı aldığı her politikayı uygular ve bir kaynağın hepsinden geçmesi gerekir; dolayısıyla ek bir başlık işleri yalnızca sıkılaştırabilir, asla gevşetemez (MDN). HTML uçta önbelleğe alınıyorsa nonce tabanlı politika, nonce’un sayfanın birleştirildiği yerde üretilmesini ya da hash’lere geçilmesini gerektirir. Bir sayfanın gerçekte ne gönderdiğini görmek için:

curl -sS -D - -o /dev/null https://example.com/ | grep -i content-security-policy

Güvenlik başlıkları kontrol rehberi CSP’nin yanında bulunması gereken başlıkları, web sitesi yayın güvenliği kontrol listesi ise bunları eksiksiz bir yayın öncesi incelemeye dönüştürür.

9. Yayındaki başlığı ücretsiz güvenlik başlıkları kontrolüyle doğrulama

Politika uygulandıktan sonra ücretsiz güvenlik başlıkları kontrolü, tarayıcının ana sayfanızdan ne aldığını gösterir. Ücretsiz Yayına Hazırlık Snapshot’ı üzerinden çalışır; kayıt gerektirmeden tek bir herkese açık alan adında sekiz pasif kontrol yapar ve başlık kontrolünü diğer yedisinin üstünde açar.

• Girdiğiniz origin’in ana sayfasını ister, en fazla beş yönlendirmeyi izler ve son yanıtı okur. Giriş veya ödeme gibi diğer sayfalar çoğu zaman farklı politikalar taşır; onları DevTools veya curl ile kontrol edin.
• Yalnızca uygulanan Content-Security-Policy başlığını okur. Report-Only aşamasında CSP’yi yine de eksik, orta düzeyde riskli olarak raporlar; çünkü yalnızca raporlayan bir politika hiçbir şeyi engellemez. Bu sonuç, siz uygulayana kadar beklenendir.
• Uygulanan politikadaki frame-ancestors direktifi, tıpkı X-Frame-Options gibi çerçeveleme koruması sayılır.
• Ayrı sertleştirme notunda (A–F), default-src veya bir script-src ya da style-src direktifi (-elem ve -attr varyantları dahil) 'unsafe-inline' içerdiğinde ya da default-src veya bir betik direktifi 'unsafe-eval' içerdiğinde CSP daha az puan alır. Not, politikayı yazıldığı gibi okur; bu yüzden nonce’un yanındaki bir 'unsafe-inline' yedeği, güncel tarayıcılar onu yok saysa da puanı düşürür.
• Nonce’ları, hash’leri, 'strict-dynamic'’i, object-src’yi, base-uri’yi veya raporlamayı değerlendirmez. Bunlar için tarayıcı konsolunu ve ihlal raporlarınızı kullanın.

Sonuç bir puan ve sekiz kontrolün her birinin sonucunu gösterir; böylece CSP sinyali HSTS, TLS ve diğer herkese açık kontrollerin yanında yer alır.