Reporting API ile web uygulamanızı izleme

Güvenlik ihlallerini, desteği sonlandırılan API çağrılarını ve daha fazlasını izlemek için Reporting API'yi kullanın.

Maud Nalpas

Bazı hatalar yalnızca üretimde ortaya çıkar. Gerçek kullanıcılar, gerçek ağlar ve gerçek cihazlar oyunu değiştirdiği için bu sorunları yerel olarak veya geliştirme sırasında görmezsiniz. Reporting API, sitenizdeki güvenlik ihlalleri veya desteği sonlandırılmış ve yakında sonlandırılacak API çağrıları gibi bazı hataları yakalamaya yardımcı olur ve bunları belirttiğiniz bir uç noktaya iletir.

HTTP üstbilgilerini kullanarak neleri izlemek istediğinizi belirtmenize olanak tanır ve tarayıcı tarafından çalıştırılır.

Reporting API'yi ayarladığınızda kullanıcılar bu tür hatalarla karşılaştığında haberdar olacağınızdan ve hataları düzeltebileceğinizden emin olabilirsiniz.

Bu yayında, bu API'nin neler yapabileceği ve nasıl kullanılacağı açıklanmaktadır. Haydi başlayalım.

Genel Bakış

Sitenizin (site.example) bir Content-Security-Policy ve Document-Policy'si olduğunu varsayalım. Bu ayarların ne işe yaradığını bilmiyor musunuz? Sorun değil, bu örneği yine de anlayabilirsiniz.

Bu politikaların ne zaman ihlal edildiğini öğrenmek için sitenizi izlemeye karar veriyorsunuz. Ayrıca kod tabanınızın kullanıyor olabileceği, desteği sonlandırılmış veya yakında sonlandırılacak API'leri de takip etmek istiyorsunuz.

Bunun için bir Reporting-Endpoints üstbilgisi yapılandırır ve gerektiğinde politikalarınızdaki report-to yönergesini kullanarak bu uç nokta adlarını eşlersiniz.

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint

Beklenmedik bir durum yaşanır ve bu politikalar, kullanıcılarınızdan bazıları için ihlal edilir.

Örnek ihlaller

index.html

<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>

script.js, index.html tarafından yüklendi

// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
  document.write('<h1>hi</h1>');
} catch (e) {
  console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;

Tarayıcı, bu sorunları yakalayan bir CSP ihlali raporu, bir belge politikası ihlali raporu ve bir kullanım dışı bırakma raporu oluşturur.

Tarayıcı, kısa bir gecikmeyle (bir dakikaya kadar) raporları bu ihlal türü için yapılandırılmış uç noktaya gönderir. Raporlar, tarayıcının kendisi tarafından bant dışı olarak gönderilir (sunucunuz veya siteniz tarafından değil).

Uç noktalar bu raporları alır.

Artık bu uç noktalardaki raporlara erişebilir ve neyin yanlış gittiğini izleyebilirsiniz. Kullanıcılarınızı etkileyen sorunu gidermeye başlayabilirsiniz.

Örnek rapor

{
  "age": 2,
  "body": {
    "blockedURL": "https://site2.example/script.js",
    "disposition": "enforce",
    "documentURL": "https://site.example",
    "effectiveDirective": "script-src-elem",
    "originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
    "referrer": "https://site.example",
    "sample": "",
    "statusCode": 200
  },
  "type": "csp-violation",
  "url": "https://site.example",
  "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}

Kullanım alanları ve rapor türleri

Reporting API, sitenizde gerçekleşen birçok ilginç uyarı veya sorunu izlemenize yardımcı olacak şekilde yapılandırılabilir:

Raporlar

Tarayıcı, yapılandırdığınız uç noktaya rapor gönderir. Aşağıdaki gibi görünen istekler gönderir:

POST
Content-Type: application/reports+json

Bu isteklerin yükü, raporların listesidir.

Örnek rapor listesi

[
  {
    "age": 420,
    "body": {
      "columnNumber": 12,
      "disposition": "enforce",
      "lineNumber": 11,
      "message": "Document policy violation: document-write is not allowed in this document.",
      "policyId": "document-write",
      "sourceFile": "https://site.example/script.js"
    },
    "type": "document-policy-violation",
    "url": "https://site.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  },
  {
    "age": 510,
    "body": {
      "blockedURL": "https://site.example/img.jpg",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://dummy.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  }
]

Bu raporların her birinde bulabileceğiniz veriler şunlardır:

Kimlik bilgisi raporları

Raporu oluşturan sayfayla aynı kaynağa sahip raporlama uç noktaları, raporları içeren isteklerde kimlik bilgilerini (çerezler) alır.

Kimlik bilgileri, raporla ilgili yararlı ek bağlam sağlayabilir. Örneğin, belirli bir kullanıcının hesabının sürekli olarak hata tetikleyip tetiklemediği veya diğer sayfalarda gerçekleştirilen belirli bir işlem dizisinin bu sayfada bir rapor tetikleyip tetiklemediği gibi.

Tarayıcı ne zaman ve nasıl rapor gönderir?

Raporlar, sitenizden bant dışı olarak gönderilir: Tarayıcı, yapılandırılmış uç noktalara ne zaman gönderileceğini kontrol eder. Tarayıcının raporları ne zaman göndereceğini kontrol etmenin bir yolu da yoktur. Tarayıcı, raporları yakalar, sıraya alır ve uygun bir zamanda otomatik olarak gönderir.

Bu, Reporting API'yi kullanırken performansla ilgili neredeyse hiç sorun yaşanmayacağı anlamına gelir.

Raporların toplu olarak gönderilme olasılığını artırmak için raporlar bir dakikaya kadar gecikmeyle gönderilir. Bu, kullanıcının ağ bağlantısına saygılı olmak için bant genişliğinden tasarruf sağlar. Bu, özellikle mobil cihazlarda önemlidir. Tarayıcı, daha yüksek öncelikli işleri işlemekle meşgulse veya kullanıcı o sırada yavaş ya da yoğun bir ağdaysa teslimatı geciktirebilir.

Üçüncü taraf ve birinci taraf sorunları

Sayfanızda gerçekleşen ihlaller veya desteği sonlandırılan özellikler nedeniyle oluşturulan raporlar, yapılandırdığınız uç noktalara gönderilir. Sayfanızda çalışan üçüncü taraf komut dosyaları tarafından işlenen ihlaller de buna dahildir.

Sayfanıza yerleştirilmiş bir kaynaklar arası iFrame'de meydana gelen ihlaller veya desteği sonlandırılan özellikler, uç noktalarınıza bildirilmez (en azından varsayılan olarak). Bir iFrame kendi raporlamasını ayarlayabilir ve hatta sitenizin (yani birinci tarafın) raporlama hizmetine rapor gönderebilir. Ancak bu, çerçeveli siteye bağlıdır. Ayrıca, çoğu raporun yalnızca bir sayfanın politikası ihlal edilirse oluşturulduğunu ve sayfanızın politikaları ile iFrame'in politikalarının farklı olduğunu unutmayın.

Kullanımdan kaldırılan özelliklerin yer aldığı örnek

Tarayıcı desteği

Aşağıdaki tabloda, Reporting API v1 için tarayıcı desteği özetlenmektedir. Bu, Reporting-Endpoints başlığıyla birlikte sunulur. Reporting API v0 (Report-To başlığı) için tarayıcı desteği, bir rapor türü dışında aynıdır: Ağ Hatası Günlüğü, yeni Reporting API'de desteklenmez. Ayrıntılar için taşıma kılavuzunu okuyun.

Bu tabloda yalnızca yeni Reporting-Endpoints başlığıyla report-to desteği özetlenmektedir. Reporting-Endpoints hizmetine geçiş yapmak istiyorsanız CSP raporlama taşıma ipuçlarını okuyun.

Reporting API'yi kullanma

Raporların nereye gönderileceğine karar verme

Bunun için iki seçeneğiniz bulunmaktadır:

• Raporları mevcut bir rapor toplayıcı hizmetine gönderme
• Raporları, kendiniz oluşturup çalıştırdığınız bir raporlama toplayıcısına gönderme

1. seçenek: Mevcut bir rapor toplayıcı hizmetini kullanma

Rapor toplayıcı hizmetlere bazı örnekler:

• report-uri
• uriports
• HeaderHawk
• Sentry

Başka çözümler biliyorsanız sorun kaydı açarak bize bildirin. Bu gönderiyi güncelleyelim.

Rapor toplayıcı seçerken fiyatlandırmanın yanı sıra aşağıdaki noktaları da göz önünde bulundurun: 🧐

• Bu toplayıcı tüm rapor türlerini destekliyor mu? Örneğin, tüm raporlama uç nokta çözümleri COOP/COEP raporlarını desteklemez.
• Uygulamanızın URL'lerinden herhangi birini üçüncü taraf rapor toplayıcıyla paylaşma konusunda rahat mısınız? Tarayıcı bu URL'lerden hassas bilgileri kaldırmış olsa bile hassas bilgiler bu şekilde sızabilir. Bu durum uygulamanız için çok riskli görünüyorsa kendi raporlama uç noktanızı çalıştırın.

2. seçenek: Kendi rapor toplayıcınızı oluşturup çalıştırma

Raporları alan kendi sunucunuzu oluşturmak o kadar da kolay değildir. Başlamak için basit şablonumuzu kopyalayabilirsiniz. Express ile oluşturulmuştur ve raporları alıp görüntüleyebilir.

Kendi rapor toplayıcınızı oluşturduğunuzda:

• Tarayıcı tarafından uç noktanıza gönderilen rapor isteklerini tanımak için POST Content-Type application/reports+json isteklerini kontrol edin.
• Uç noktanız sitenizden farklı bir kaynakta bulunuyorsa CORS ön kontrolü isteklerini desteklediğinden emin olun.

3. seçenek: 1. ve 2. seçeneği birleştirme

Bazı rapor türlerini belirli bir sağlayıcının hazırlamasını, diğerlerini ise şirket içinde hazırlamayı tercih edebilirsiniz.

Bu durumda, birden fazla uç noktayı aşağıdaki gibi ayarlayın:

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

Reporting-Endpoints üstbilgisini yapılandırma

Reporting-Endpoints yanıt başlığı ayarlayın. Değeri, virgülle ayrılmış bir veya daha fazla anahtar/değer çifti olmalıdır:

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Eski Reporting API'den yeni Reporting API'ye geçiş yapıyorsanız Reporting-Endpoints ve Report-To her ikisini de ayarlamanız mantıklı olabilir. Ayrıntılar için geçiş rehberine bakın. Özellikle, yalnızca report-uri yönergesini kullanarak Content-Security-Policy ihlalleriyle ilgili raporlama yapıyorsanız CSP raporlamasıyla ilgili taşıma adımlarını inceleyin.

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: ...

Anahtarlar (uç nokta adları)

Her anahtar, seçtiğiniz bir ad (ör. main-endpoint veya endpoint-1) olabilir. Farklı rapor türleri için farklı adlandırılmış uç noktalar ayarlayabilirsiniz (ör. my-coop-endpoint, my-csp-endpoint). Bu sayede, raporları türlerine bağlı olarak farklı uç noktalara yönlendirebilirsiniz.

Müdahale, destek sonlandırma, kilitlenme raporları veya bunların bir kombinasyonunu almak istiyorsanız default adlı bir uç nokta ayarlayın.

Reporting-Endpoints başlığı bir default uç noktası tanımlamıyorsa bu tür raporlar oluşturulsa da gönderilmez.

Değerler (URL'ler)

Her değer, raporların gönderileceği ve sizin seçtiğiniz bir URL'dir. Burada ayarlanacak URL, 1. adımda neye karar verdiğinize bağlıdır.

Bir uç nokta URL'si:

• Eğik çizgiyle (/) başlamalıdır. Göreli yollar desteklenmez.
• Çapraz kaynak olabilir ancak bu durumda kimlik bilgileri raporlarla birlikte gönderilmez.

Örnekler

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

Daha sonra, her bir adlandırılmış uç noktayı uygun politikada veya tüm politikalarda tek bir uç nokta olarak kullanabilirsiniz.

Üstbilgi nerede ayarlanır?

Bu yayında ele alınan yeni Reporting API'de raporlar belgeler kapsamındadır. Bu, belirli bir kaynak için site.example/page1 ve site.example/page2 gibi farklı dokümanların farklı uç noktalara rapor gönderebileceği anlamına gelir.

Sitenizin herhangi bir sayfasında gerçekleşen ihlaller veya desteği sonlandırılan özelliklerle ilgili rapor almak için üstbilgiyi tüm yanıtlarda ara katman yazılımı olarak ayarlayın.

Express'te bir örnek:

const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;

app.use(function (request, response, next) {
  // Set up the Reporting API
  response.set(
    'Reporting-Endpoints',
    `main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
  );
  next();
});

Politikalarınızı düzenleme

Reporting-Endpoints üstbilgisi yapılandırıldığına göre, ihlal raporları almak istediğiniz her politika üstbilgisine bir report-to yönergesi ekleyin. report-to değeri, yapılandırdığınız adlandırılmış uç noktalardan biri olmalıdır.

Birden fazla politika için birden fazla uç nokta kullanabilir veya politikalar arasında farklı uç noktalar kullanabilirsiniz.

Kullanımdan kaldırma, müdahale ve kilitlenme raporları için report-to gerekli değildir. Bu raporlar herhangi bir politikaya bağlı değildir. Bu raporlar, bir default uç noktası ayarlandığı sürece oluşturulur ve bu default uç noktasına gönderilir.

Örnek

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint

Raporlama kurulumunuzda hata ayıklama

Kasıtlı olarak rapor oluşturma

Raporlama API'sini ayarlarken raporların beklendiği gibi oluşturulup gönderildiğini kontrol etmek için politikalarınızı kasıtlı olarak ihlal etmeniz gerekebilir.

Zamandan kazanın

Raporlar gecikmeli olarak (yaklaşık bir dakika) gönderilebilir. Bu, hata ayıklama sırasında uzun bir süredir. 😴 Neyse ki Chrome'da hata ayıklama yaparken --short-reporting-delay işaretini kullanarak raporlar oluşturulur oluşturulmaz bunları alabilirsiniz.

Bu işareti etkinleştirmek için terminalinizde şu komutu çalıştırın:

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

Geliştirici Araçları'nı kullanma

Chrome'da, gönderilen veya gönderilecek raporları görmek için Geliştirici Araçları'nı kullanın.

Bu özellik, Ekim 2021 itibarıyla deneyseldir. Bu özelliği kullanmak için aşağıdaki adımları uygulayın:

1. Chrome 96 ve daha yeni sürümleri kullanın (tarayıcınıza chrome://version yazarak kontrol edin)
2. Chrome'un adres çubuğuna chrome://flags/#enable-experimental-web-platform-features yazın veya yapıştırın.
3. Etkin'i tıklayın.
4. Tarayıcınızı yeniden başlatın.
5. Chrome Geliştirici Araçları'nı açın.
6. Chrome Geliştirici Araçları'nda Ayarlar'ı açın. Denemeler bölümünde Uygulama panelinde Reporting API panelini etkinleştir'i tıklayın.
7. Geliştirici Araçları'nı yeniden yükleyin.
8. Sayfanızı yeniden yükleyin. Geliştirici Araçları'nın açık olduğu sayfada oluşturulan raporlar, Chrome Geliştirici Araçları'nın Application (Uygulama) panelindeki Reporting API (Raporlama API'si) altında listelenir.

Rapor durumu

Durum sütununda, raporun başarıyla gönderilip gönderilmediği belirtilir.

Raporlar, başarıyla gönderilip gönderilmediklerine bakılmaksızın bir süre sonra kaldırılır.

Sorun giderme

Raporlar oluşturulmuyor veya uç noktanıza beklendiği gibi gönderilmiyor mu? Bu sorunu gidermek için birkaç ipucu aşağıda verilmiştir.

Raporlar oluşturulmadı

Geliştirici Araçları'nda gösterilen raporlar doğru şekilde oluşturulmuştur. Beklediğiniz rapor bu listede görünmüyorsa:

• Politikalarınızda report-to değerini kontrol edin. Bu ayar yanlış yapılandırılırsa rapor oluşturulmaz. Bu sorunu düzeltmek için Politikalarınızı düzenleyin bölümüne gidin. Bu sorunu gidermenin bir başka yolu da Chrome'daki Geliştirici Araçları konsolunu kontrol etmektir: Beklediğiniz ihlalle ilgili konsolda bir hata görünüyorsa politikanız muhtemelen doğru şekilde yapılandırılmıştır.
• Bu listede yalnızca DevTools'un açık olduğu doküman için oluşturulan raporların gösterileceğini unutmayın. Örneğin, siteniz site1.example bir politikayı ihlal eden ve bu nedenle rapor oluşturan bir iframe site2.example yerleştiriyorsa bu rapor, yalnızca iframe'i kendi penceresinde açıp o pencere için Geliştirici Araçları'nı açarsanız Geliştirici Araçları'nda gösterilir.

Raporlar oluşturuluyor ancak gönderilmiyor veya alınmıyor

DevTools'ta bir rapor görüyorsanız ancak uç noktanız bu raporu almıyorsa ne yapmalısınız?

• Kısa gecikmeler kullandığınızdan emin olun. Raporu görememenizin nedeni, henüz gönderilmemiş olması olabilir.

• Reporting-Endpoints üstbilgi yapılandırmanızı kontrol edin. E-posta adresinde sorun varsa doğru şekilde oluşturulan rapor gönderilmez. Bu durumda, DevTools'ta raporun durumu Queued olarak kalır (Pending durumuna geçebilir ve ardından bir teslimat denemesi yapıldığında hızla Queued durumuna geri dönebilir). Buna neden olabilecek bazı yaygın hatalar şunlardır:

• Uç nokta kullanılıyor ancak yapılandırılmamış. Örnek:

 Document-Policy: document-write=?0;report-to=endpoint-1;
 Reporting-Endpoints: default="https://reports.example/default"

• default uç noktası eksik. Kullanımdan kaldırma ve müdahale raporları gibi bazı rapor türleri yalnızca default adlı uç noktaya gönderilir. Daha fazla bilgi için Raporlama uç noktaları üstbilgisini yapılandırma başlıklı makaleyi inceleyin.

• Politika başlıklarınızın söz diziminde eksik tırnak işaretleri gibi sorunlar olup olmadığını kontrol edin. Ayrıntıları inceleyin.

• Uç noktanızın gelen istekleri işleyebildiğinden emin olun.

  • Uç noktanızın CORS ön kontrol isteklerini desteklediğinden emin olun. Aksi takdirde rapor alamaz.

  • Uç noktanızın davranışını test edin. Bunu yapmak için raporları manuel olarak oluşturmak yerine, uç noktanıza tarayıcının göndereceği isteklere benzeyen istekler göndererek tarayıcıyı taklit edebilirsiniz. Aşağıdakileri çalıştırın:

  curl --header "Content-Type: application/reports+json" \
    --request POST \
    --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \
    YOUR_ENDPOINT
  

  Uç noktanız, bir başarı koduyla (200 veya başka bir başarı yanıt kodu 2xx) yanıt vermelidir. Aksi takdirde, yapılandırmasında bir sorun vardır.

İlgili raporlama mekanizmaları

Yalnızca Rapor

-Report-Only politika başlıkları ve Reporting-Endpoints birlikte çalışır.

Reporting-Endpoints içinde yapılandırılan ve Content-Security-Policy, Cross-Origin-Embedder-Policy ve Cross-Origin-Opener-Policy alanının report-to alanında belirtilen uç noktalar, bu politikalar ihlal edildiğinde rapor alır.

Reporting-Endpoints içinde yapılandırılan uç noktalar, Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only ve Cross-Origin-Opener-Policy-Report-Only'un report-to alanında da belirtilebilir. Ayrıca bu politikalar ihlal edildiğinde rapor alırlar.

Her iki durumda da raporlar gönderilir ancak -Report-Only başlıkları politikaları zorunlu kılmaz. Hiçbir şey bozulmaz veya engellenmez ancak nelerin bozulmuş veya engellenmiş olabileceğine dair raporlar alırsınız.

ReportingObserver

ReportingObserver JavaScript API, istemci tarafı uyarılarını gözlemlemenize yardımcı olabilir.

ReportingObserver ve Reporting-Endpoints başlığı aynı görünen raporlar oluşturur ancak biraz farklı kullanım alanlarına olanak tanır.

ReportingObserver özelliğini şu durumlarda kullanın:

• Yalnızca desteği sonlandırılan özellikleri veya tarayıcı müdahalelerini izlemek istiyorsunuz. ReportingObserver, desteği sonlandırılan özellikler ve tarayıcı müdahaleleri gibi istemci tarafı uyarılarını gösterir ancak Reporting-Endpoints'ün aksine CSP veya COOP/COEP ihlalleri gibi başka rapor türlerini yakalamaz.
• Bu ihlallere anında müdahale etmeniz gerekir. ReportingObserver, bir ihlal etkinliğine geri çağırma eklemeyi mümkün kılar.
• Özel geri çağırma işlevini kullanarak hata ayıklamaya yardımcı olması için rapora ek bilgi eklemek istiyorsunuz.

Başka bir fark ise ReportingObserver özelliğinin yalnızca istemci tarafında yapılandırılmasıdır: Sunucu tarafı başlıkları üzerinde kontrolünüz olmasa ve Reporting-Endpoints özelliğini ayarlayamasanız bile bu özelliği kullanabilirsiniz.

Daha fazla bilgi

• Reporting API v0'dan v1'e geçiş rehberi
• ReportingObserver
• Spesifikasyon: eski Reporting API (v0)
• Spesifikasyon: yeni Reporting API (v1)

Bu belgeyle ilgili incelemeleri ve önerileri için Ian Clelland, Eiji Kitamura ve Milica Mihajlija'ya çok teşekkür ederiz.