Reporting API की मदद से अपने वेब ऐप्लिकेशन की निगरानी करना

Reporting API का इस्तेमाल करके, सुरक्षा से जुड़े उल्लंघनों, बंद किए गए एपीआई कॉल वगैरह की निगरानी करें.

Maud Nalpas

चेतावनी:

यह Reporting API (v1) के लिए एपीआई गाइड है. इसमें इस्तेमाल के उदाहरणों के बारे में ज़्यादा जानकारी दी गई है. यह Reporting-Endpoints हेडर का इस्तेमाल करता है.

अगर लेगसी Reporting API (Report-To हेडर) का इस्तेमाल किया जा रहा है, तो इसके बजाय एपीआई माइग्रेशन के बारे में पढ़ें.

क्या आपको नेटवर्क की गड़बड़ी लॉग करने की सुविधा के बारे में जानकारी चाहिए? इसके बजाय, नेटवर्क की गड़बड़ी लॉग करने की सुविधा का इस्तेमाल करें.

कुछ गड़बड़ियां सिर्फ़ प्रोडक्शन में होती हैं. आपको ये बदलाव स्थानीय तौर पर या डेवलपमेंट के दौरान नहीं दिखेंगे, क्योंकि असल उपयोगकर्ता, असल नेटवर्क, और असल डिवाइस गेम को बदल देते हैं. Reporting API, इनमें से कुछ गड़बड़ियों का पता लगाने में मदद करता है. जैसे, आपकी साइट पर सुरक्षा से जुड़े उल्लंघनों या बंद हो चुके और जल्द ही बंद होने वाले एपीआई कॉल का पता लगाना. साथ ही, यह इन गड़बड़ियों को आपके तय किए गए एंडपॉइंट पर भेजता है.

इसकी मदद से, यह तय किया जा सकता है कि एचटीटीपी हेडर का इस्तेमाल करके किस चीज़ को मॉनिटर करना है. साथ ही, इसे ब्राउज़र से कंट्रोल किया जाता है.

Reporting API सेट अप करने से, आपको यह पता चल जाता है कि उपयोगकर्ताओं को इस तरह की गड़बड़ियां कब हो रही हैं, ताकि आप उन्हें ठीक कर सकें.

इस पोस्ट में बताया गया है कि यह एपीआई क्या-क्या कर सकता है और इसका इस्तेमाल कैसे किया जा सकता है. चलिए, शुरू करते हैं!

खास जानकारी

मान लें कि आपकी साइट site.example में Content-Security-Policy और Document-Policy मौजूद हैं. आपको नहीं पता कि ये क्या करते हैं? कोई बात नहीं, इस उदाहरण को अब भी समझा जा सकता है.

आपने अपनी साइट की निगरानी करने का फ़ैसला किया है, ताकि आपको पता चल सके कि इन नीतियों का उल्लंघन कब हुआ. हालांकि, ऐसा इसलिए भी किया गया है, क्योंकि आपको उन एपीआई पर नज़र रखनी है जिनका इस्तेमाल आपका कोडबेस कर रहा है. ये एपीआई बंद हो चुके हैं या जल्द ही बंद होने वाले हैं.

इसके लिए, आपको Reporting-Endpoints हेडर कॉन्फ़िगर करना होगा. साथ ही, अपनी नीतियों में report-to डायरेक्टिव का इस्तेमाल करके, इन एंडपॉइंट के नामों को मैप करना होगा.

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

कोई ऐसी समस्या आ जाती है जिसकी वजह से, आपके कुछ उपयोगकर्ताओं के लिए इन नीतियों का उल्लंघन हो जाता है.

उल्लंघनों के उदाहरण

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 ने लोड किया

// 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;

ब्राउज़र, सीएसएपी के उल्लंघन की रिपोर्ट, दस्तावेज़ की नीति के उल्लंघन की रिपोर्ट, और बंद होने की रिपोर्ट जनरेट करता है. इनमें इन समस्याओं की जानकारी होती है.

कुछ समय बाद—एक मिनट तक—ब्राउज़र, रिपोर्ट को उस एंडपॉइंट पर भेजता है जिसे इस तरह के उल्लंघन के लिए कॉन्फ़िगर किया गया था. ये रिपोर्ट, ब्राउज़र खुद आउट-ऑफ़-बैंड तरीके से भेजता है. इन्हें न तो आपका सर्वर भेजता है और न ही आपकी साइट.

एंडपॉइंट को ये रिपोर्ट मिलती हैं.

अब इन एंडपॉइंट पर मौजूद रिपोर्ट को ऐक्सेस किया जा सकता है. साथ ही, यह देखा जा सकता है कि क्या गड़बड़ी हुई है. अब आपके पास, उपयोगकर्ताओं पर असर डालने वाली समस्या को हल करने का विकल्प है.

उदाहरण के तौर पर दी गई रिपोर्ट

{
  "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"
}

इस्तेमाल के उदाहरण और रिपोर्ट के टाइप

Reporting API को कॉन्फ़िगर किया जा सकता है. इससे आपको अपनी पूरी साइट पर होने वाली कई तरह की दिलचस्प चेतावनियों या समस्याओं को मॉनिटर करने में मदद मिलती है:

रिपोर्ट का टाइप	ऐसी स्थिति का उदाहरण जिसमें रिपोर्ट जनरेट की जाएगी
सीएसपी का उल्लंघन (सिर्फ़ लेवल 3 के लिए)	आपने अपने किसी पेज पर `Content-Security-Policy` (CSP) सेट किया है, लेकिन पेज ऐसी स्क्रिप्ट लोड करने की कोशिश कर रहा है जिसे आपके CSP की अनुमति नहीं है.
COOP का उल्लंघन	आपने किसी पेज पर `Cross-Origin-Opener-Policy` सेट किया है, लेकिन क्रॉस-ऑरिजिन वाली कोई विंडो सीधे तौर पर दस्तावेज़ से इंटरैक्ट करने की कोशिश कर रही है.
COEP का उल्लंघन	आपने किसी पेज पर `Cross-Origin-Embedder-Policy` सेट किया है, लेकिन दस्तावेज़ में एक ऐसा क्रॉस-ऑरिजिन iframe शामिल है जिसने क्रॉस-ऑरिजिन दस्तावेज़ों से लोड होने का विकल्प नहीं चुना है.
दस्तावेज़ से जुड़ी नीति का उल्लंघन	पेज में एक दस्तावेज़ नीति है, जो `document.write` के इस्तेमाल को रोकती है. हालांकि, एक स्क्रिप्ट `document.write` को कॉल करने की कोशिश करती है.
अनुमतियों की नीति का उल्लंघन	पेज पर अनुमतियों से जुड़ी एक नीति है, जो माइक्रोफ़ोन के इस्तेमाल को रोकती है. साथ ही, एक स्क्रिप्ट है जो ऑडियो इनपुट का अनुरोध करती है.
इस्तेमाल बंद करने की चेतावनी	पेज ऐसे एपीआई का इस्तेमाल कर रहा है जो अब काम नहीं करता या जल्द ही काम करना बंद कर देगा. यह एपीआई को सीधे तौर पर या टॉप-लेवल की तीसरे पक्ष की स्क्रिप्ट का इस्तेमाल करके कॉल करता है.
हस्तक्षेप	पेज पर ऐसी गतिविधि करने की कोशिश की जा रही है जिसे ब्राउज़र अनुमति नहीं देता. ऐसा सुरक्षा, परफ़ॉर्मेंस या उपयोगकर्ता अनुभव से जुड़ी वजहों से किया जाता है. Chrome में उदाहरण: पेज, धीमे नेटवर्क पर `document.write` का इस्तेमाल करता है या ऐसे क्रॉस-ऑरिजिन फ़्रेम में `navigator.vibrate` को कॉल करता है जिससे उपयोगकर्ता ने अब तक इंटरैक्ट नहीं किया है.
क्रैश	आपकी साइट खुली होने पर ब्राउज़र क्रैश हो जाता है.

रिपोर्ट

रिपोर्ट कैसी दिखती हैं?

ब्राउज़र, रिपोर्ट को उस एंडपॉइंट पर भेजता है जिसे आपने कॉन्फ़िगर किया है. यह इस तरह के अनुरोध भेजता है:

POST
Content-Type: application/reports+json

इन अनुरोधों का पेलोड, रिपोर्ट की सूची होती है.

रिपोर्ट की सूची का उदाहरण

[
  {
    "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"
  }
]

यहां बताया गया है कि आपको इनमें से हर रिपोर्ट में कौन-कौनसा डेटा मिल सकता है:

फ़ील्ड	ब्यौरा
`age`	रिपोर्ट के टाइमस्टैंप और मौजूदा समय के बीच के मिलीसेकंड की संख्या.
`body`	रिपोर्ट का असल डेटा, जिसे JSON स्ट्रिंग में बदला गया है. रिपोर्ट के `body` में मौजूद फ़ील्ड, रिपोर्ट के `type` के हिसाब से तय किए जाते हैं. ⚠️ अलग-अलग तरह की रिपोर्ट के लिए, अलग-अलग निकाय होते हैं.
`type`	रिपोर्ट का टाइप, जैसे कि `csp-violation` या `coep`.
`url`	उस दस्तावेज़ या वर्कर का पता जिससे रिपोर्ट जनरेट की गई थी. संवेदनशील डेटा, जैसे कि उपयोगकर्ता नाम, पासवर्ड, और फ़्रैगमेंट को इस यूआरएल से हटा दिया जाता है.
`user_agent`	`User-Agent` अनुरोध का हेडर, जिससे रिपोर्ट जनरेट की गई थी.

क्रेडेंशियल वाली रिपोर्ट

रिपोर्टिंग एंडपॉइंट, रिपोर्ट जनरेट करने वाले पेज के एक ही ऑरिजिन के होने चाहिए. ऐसा होने पर, रिपोर्ट जनरेट करने वाले पेज को क्रेडेंशियल (कुकी) मिलते हैं. ये क्रेडेंशियल, रिपोर्ट जनरेट करने के अनुरोधों में शामिल होते हैं.

क्रेडेंशियल से, रिपोर्ट के बारे में काम की अतिरिक्त जानकारी मिल सकती है. उदाहरण के लिए, क्या किसी उपयोगकर्ता के खाते में लगातार गड़बड़ियां हो रही हैं या क्या अन्य पेजों पर की गई कार्रवाइयों के किसी क्रम की वजह से, इस पेज पर रिपोर्ट ट्रिगर हो रही है.

ब्राउज़र, रिपोर्ट कब और कैसे भेजता है?

रिपोर्ट, आपकी साइट से अलग तरीके से डिलीवर की जाती हैं: ब्राउज़र यह कंट्रोल करता है कि कॉन्फ़िगर किए गए एंडपॉइंट पर रिपोर्ट कब भेजी जाएं. यह भी कंट्रोल नहीं किया जा सकता कि ब्राउज़र रिपोर्ट कब भेजेगा. ब्राउज़र, रिपोर्ट को कैप्चर करता है, उन्हें लाइन में लगाता है, और सही समय पर अपने-आप भेज देता है.

इसका मतलब है कि Reporting API का इस्तेमाल करते समय, परफ़ॉर्मेंस से जुड़ी कोई समस्या नहीं आती.

रिपोर्ट भेजने में देरी होती है. ऐसा इसलिए होता है, ताकि रिपोर्ट को बैच में भेजने की संभावना बढ़ाई जा सके. इसमें एक मिनट तक का समय लग सकता है. इससे बैंडविड्थ की बचत होती है, ताकि उपयोगकर्ता के नेटवर्क कनेक्शन पर असर न पड़े. यह खास तौर पर मोबाइल पर ज़रूरी होता है. अगर ब्राउज़र ज़्यादा प्राथमिकता वाले काम को प्रोसेस करने में व्यस्त है, तो वह सूचनाएं भेजने में देरी कर सकता है. इसके अलावा, अगर उपयोगकर्ता उस समय धीमे या व्यस्त नेटवर्क पर है, तो भी सूचनाएं भेजने में देरी हो सकती है.

तीसरे और पहले पक्ष की समस्याएं

नीतियों के उल्लंघन या आपके पेज पर हो रही समस्याओं की वजह से जनरेट हुई रिपोर्ट, उन एंडपॉइंट पर भेजी जाएंगी जिन्हें आपने कॉन्फ़िगर किया है. इसमें आपके पेज पर चलने वाली तीसरे पक्ष की स्क्रिप्ट से हुए उल्लंघन भी शामिल हैं.

आपके पेज में एम्बेड किए गए क्रॉस-ऑरिजिन iframe में हुए उल्लंघनों या बंद की गई सुविधाओं के बारे में, आपके एंडपॉइंट को सूचना नहीं दी जाएगी. कम से कम डिफ़ॉल्ट रूप से ऐसा नहीं होगा. कोई iframe अपनी रिपोर्टिंग सेवा सेट अप कर सकता है. साथ ही, आपकी साइट यानी पहली पार्टी की रिपोर्टिंग सेवा को भी रिपोर्ट कर सकता है. हालांकि, यह फ़्रेम की गई साइट पर निर्भर करता है. यह भी ध्यान दें कि ज़्यादातर रिपोर्ट तब जनरेट होती हैं, जब किसी पेज की नीति का उल्लंघन होता है. साथ ही, आपके पेज की नीतियां और iframe की नीतियां अलग-अलग होती हैं.

बंद की गई सुविधाओं के साथ उदाहरण

अगर आपके पेज पर Reporting-Endpoints हेडर सेट अप है, तो आपके एंडपॉइंट को, आपके पेज पर चल रही तीसरे पक्ष की स्क्रिप्ट से कॉल किए गए बंद किए गए एपीआई की जानकारी मिलेगी. आपके पेज में एम्बेड किए गए iframe से कॉल किए गए बंद किए गए एपीआई की जानकारी, आपके एंडपॉइंट को नहीं भेजी जाएगी. किसी एपीआई या सुविधा के बंद होने की रिपोर्ट सिर्फ़ तब जनरेट होगी, जब iframe सर्वर ने Reporting-Endpoints सेट अप किए हों. यह रिपोर्ट उस एंडपॉइंट पर भेजी जाएगी जिसे iframe के सर्वर ने सेट अप किया है. — अगर आपके पेज पर Reporting-Endpoints हेडर सेट अप है, तो आपके पेज पर चल रही तीसरे पक्ष की स्क्रिप्ट से कॉल किए गए बंद किए गए एपीआई की जानकारी आपके एंडपॉइंट को भेजी जाएगी. आपके पेज में एम्बेड किए गए iframe से कॉल किए गए बंद किए गए एपीआई की जानकारी, आपके एंडपॉइंट को नहीं भेजी जाएगी. किसी एपीआई या सुविधा के बंद होने की रिपोर्ट सिर्फ़ तब जनरेट होगी, जब iframe सर्वर ने Reporting-Endpoints सेट अप किए हों. यह रिपोर्ट उस एंडपॉइंट पर भेजी जाएगी जिसे iframe के सर्वर ने सेट अप किया है.

ब्राउज़र समर्थन

नीचे दी गई टेबल में, Reporting-Endpoints हेडर के साथ Reporting API v1 के लिए ब्राउज़र सपोर्ट की खास जानकारी दी गई है. Reporting API v0 (Report-To हेडर) के लिए, ब्राउज़र सपोर्ट पहले जैसा ही है. हालांकि, एक रिपोर्ट टाइप अलग है: नए Reporting API में, नेटवर्क की गड़बड़ी लॉग करने की सुविधा काम नहीं करती. ज़्यादा जानकारी के लिए, माइग्रेशन गाइड पढ़ें.

रिपोर्ट का टाइप	Chrome	Chrome iOS	Safari	Firefox	Edge
सीएसपी का उल्लंघन (सिर्फ़ लेवल 3)*	✔ हां	✔ हां	✔ हां	✘ नहीं	✔ हां
नेटवर्क की गड़बड़ी लॉग करना	✘ नहीं	✘ नहीं	✘ नहीं	✘ नहीं	✘ नहीं
COOP/COEP का उल्लंघन	✔ हां	✘ नहीं	✔ हां	✘ नहीं	✔ हां
अन्य सभी तरह की समस्याएं: दस्तावेज़ की नीति का उल्लंघन, बंद होना, दखलअंदाज़ी, क्रैश होना	✔ हां	✘ नहीं	✘ नहीं	✘ नहीं	✔ हां

चेतावनी:

सीएसपी रिपोर्टिंग के लिए ब्राउज़र सपोर्ट, रिपोर्टिंग के अन्य टाइप से अलग होता है. इसकी वजह यह है कि सीएसपी कुछ समय से उपलब्ध है. सीएसपी रिपोर्ट जनरेट करने के लिए, इनका इस्तेमाल किया जा सकता है:

लेगसी report-uri डायरेक्टिव, जो Reporting API पर निर्भर नहीं होता.
नया report-to डायरेक्टिव, Reporting API और Reporting-To या नए Reporting-Endpoints हेडर पर निर्भर करता है.

इस टेबल में, सिर्फ़ नए Reporting-Endpoints हेडर के साथ report-to के साथ काम करने की सुविधा के बारे में खास जानकारी दी गई है. अगर आपको Reporting-Endpoints पर माइग्रेट करना है, तो सीएसपी रिपोर्टिंग को माइग्रेट करने से जुड़ी सलाह पढ़ें.

Reporting API का इस्तेमाल करना

तय करें कि रिपोर्ट कहां भेजी जानी चाहिए

आपके पास दो विकल्प हैं:

रिपोर्ट को, रिपोर्ट इकट्ठा करने वाली किसी मौजूदा सेवा पर भेजें.
रिपोर्टिंग कलेक्टर को रिपोर्ट भेजें. इसे आपको खुद बनाना और मैनेज करना होता है.

पहला विकल्प: रिपोर्ट इकट्ठा करने वाली किसी मौजूदा सेवा का इस्तेमाल करना

रिपोर्ट इकट्ठा करने वाली सेवाओं के कुछ उदाहरण यहां दिए गए हैं:

अगर आपको अन्य समाधानों के बारे में पता है, तो हमें बताने के लिए समस्या की जानकारी दें. इसके बाद, हम इस पोस्ट को अपडेट कर देंगे!

कीमत के अलावा, रिपोर्ट कलेक्टर चुनते समय इन बातों का ध्यान रखें: 🧐

क्या यह कलेक्टर, सभी तरह की रिपोर्ट के साथ काम करता है? उदाहरण के लिए, सभी रिपोर्टिंग एंडपॉइंट समाधान, COOP/COEP रिपोर्ट के साथ काम नहीं करते.
क्या आपको अपने ऐप्लिकेशन के किसी यूआरएल को तीसरे पक्ष की रिपोर्ट इकट्ठा करने वाली कंपनी के साथ शेयर करने में कोई परेशानी नहीं है? भले ही, ब्राउज़र इन यूआरएल से संवेदनशील जानकारी हटा देता हो, लेकिन इस तरह से संवेदनशील जानकारी लीक हो सकती है. अगर आपको लगता है कि यह तरीका आपके ऐप्लिकेशन के लिए बहुत जोखिम भरा है, तो अपना रिपोर्टिंग एंडपॉइंट इस्तेमाल करें.

दूसरा विकल्प: अपना रिपोर्ट कलेक्टर बनाना और उसे मैनेज करना

रिपोर्ट पाने वाला अपना सर्वर बनाना इतना आसान नहीं है. शुरू करने के लिए, हमारे हल्के-फुल्के बॉयलरप्लेट को फ़ोर्क किया जा सकता है. इसे Express की मदद से बनाया गया है. साथ ही, यह रिपोर्ट पा सकता है और उन्हें दिखा सकता है.

खुद का रिपोर्ट कलेक्टर बनाने पर:

POST के लिए POST वाले अनुरोधों की जांच करें, ताकि आपके एंडपॉइंट पर ब्राउज़र से भेजे गए रिपोर्ट के अनुरोधों की पहचान की जा सके.Content-Typeapplication/reports+json
अगर आपका एंडपॉइंट, आपकी साइट से अलग ऑरिजिन पर है, तो पक्का करें कि वह सीओआरएस प्रीफ़्लाइट अनुरोधों के साथ काम करता हो.

तीसरा विकल्प: पहले और दूसरे विकल्प को एक साथ इस्तेमाल करना

ऐसा हो सकता है कि आपको कुछ तरह की रिपोर्ट के लिए किसी खास सेवा देने वाली कंपनी की मदद लेनी हो, लेकिन अन्य रिपोर्ट के लिए आपके पास इन-हाउस समाधान हो.

इस मामले में, एक से ज़्यादा एंडपॉइंट इस तरह सेट करें:

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

`Reporting-Endpoints` हेडर को कॉन्फ़िगर करना

Reporting-Endpoints रिस्पॉन्स हेडर सेट करें. इसकी वैल्यू, कॉमा लगाकर अलग किए गए एक या एक से ज़्यादा कुंजी-वैल्यू पेयर होने चाहिए:

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

अगर आपको लेगसी Reporting API से नए Reporting API पर माइग्रेट करना है, तो दोनों Reporting-Endpoints और Report-To को सेट करना सही हो सकता है. ज़्यादा जानकारी के लिए, डेटा को दूसरी जगह भेजने से जुड़ी गाइड देखें. खास तौर पर, अगर आपने सिर्फ़ report-uri डायरेक्टिव का इस्तेमाल करके Content-Security-Policy उल्लंघन की रिपोर्टिंग की है, तो सीएसएपी रिपोर्टिंग के लिए माइग्रेशन के चरण देखें.

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

कुंजियां (एंडपॉइंट के नाम)

हर कुंजी को अपनी पसंद के हिसाब से नाम दिया जा सकता है. जैसे, main-endpoint या endpoint-1. अलग-अलग रिपोर्ट टाइप के लिए, अलग-अलग नाम वाले एंडपॉइंट सेट किए जा सकते हैं. उदाहरण के लिए, my-coop-endpoint, my-csp-endpoint. इसकी मदद से, रिपोर्ट को उनके टाइप के हिसाब से अलग-अलग एंडपॉइंट पर भेजा जा सकता है.

अगर आपको इंटरवेंशन, एपीआई या सुविधा के बंद होने, क्रैश की रिपोर्ट या इनमें से किसी भी कॉम्बिनेशन की रिपोर्ट चाहिए, तो default नाम का एंडपॉइंट सेट करें.

अगर Reporting-Endpoints हेडर में कोई default एंडपॉइंट तय नहीं किया गया है, तो इस तरह की रिपोर्ट नहीं भेजी जाएंगी. हालांकि, इन्हें जनरेट किया जाएगा.

अहम जानकारी: नाम से ऐसा लगता है कि default एक फ़ॉलबैक एंडपॉइंट है, लेकिन ऐसा नहीं है. उदाहरण के लिए, अगर आपने Document-Policy के लिए report-to my-endpoint सेट अप किया है और Reporting-Endpoints में my-endpoint को तय नहीं किया है, तो Document-Policy के उल्लंघन की रिपोर्ट जनरेट होंगी. हालांकि, इन्हें भेजा नहीं जाएगा, क्योंकि ब्राउज़र को यह नहीं पता कि इन्हें कहां भेजना है.

वैल्यू (यूआरएल)

हर वैल्यू आपकी पसंद का यूआरएल होता है. रिपोर्ट इसी यूआरएल पर भेजी जाएंगी. यहां सेट किया जाने वाला यूआरएल इस बात पर निर्भर करता है कि आपने पहले चरण में क्या तय किया था.

एंडपॉइंट यूआरएल:

यह स्लैश (/) से शुरू होना चाहिए. रेलेटिव पाथ का इस्तेमाल नहीं किया जा सकता.
यह क्रॉस-ऑरिजिन हो सकता है. हालांकि, ऐसे मामले में रिपोर्ट के साथ क्रेडेंशियल नहीं भेजे जाते.

उदाहरण

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

इसके बाद, हर नाम वाले एंडपॉइंट का इस्तेमाल सही नीति में किया जा सकता है. इसके अलावा, सभी नीतियों में एक ही एंडपॉइंट का इस्तेमाल किया जा सकता है.

हेडर कहां सेट करें?

इस पोस्ट में बताए गए नए Reporting API में, रिपोर्ट को दस्तावेज़ों के हिसाब से स्कोप किया जाता है. इसका मतलब है कि किसी दिए गए ऑरिजिन के लिए, अलग-अलग दस्तावेज़, जैसे कि site.example/page1 और site.example/page2, अलग-अलग एंडपॉइंट को रिपोर्ट भेज सकते हैं.

अगर आपको अपनी साइट के किसी भी पेज पर हुए उल्लंघनों या बंद की गई सुविधाओं के बारे में रिपोर्ट चाहिए, तो सभी जवाबों पर हेडर को मिडलवेयर के तौर पर सेट करें.

यहां Express में एक उदाहरण दिया गया है:

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();
});

ध्यान दें: यह लेगसी Reporting API (Report-To हेडर) से अलग है. इसमें, एक पेज के लिए "ऐम्बिएंट" एंडपॉइंट सेट किया जा सकता था. साथ ही, एक ही ऑरिजिन के किसी भी पेज के लिए रिपोर्ट अपने-आप मिल जाती थीं. अगर आपको लेगसी Reporting API से नए Reporting API पर माइग्रेट करना है, तो माइग्रेशन गाइड देखें.

अपनी नीतियों में बदलाव करना

Reporting-Endpoints हेडर कॉन्फ़िगर हो जाने के बाद, हर उस नीति हेडर में report-to डायरेक्टिव जोड़ें जिसके लिए आपको उल्लंघन की रिपोर्ट चाहिए. report-to की वैल्यू, कॉन्फ़िगर किए गए नाम वाले एंडपॉइंट में से एक होनी चाहिए.

एक से ज़्यादा नीतियों के लिए, एक से ज़्यादा एंडपॉइंट का इस्तेमाल किया जा सकता है. इसके अलावा, अलग-अलग नीतियों के लिए अलग-अलग एंडपॉइंट का इस्तेमाल किया जा सकता है.

हर नीति के लिए, report-to की वैल्यू, कॉन्फ़िगर किए गए नाम वाले एंडपॉइंट में से कोई एक होनी चाहिए.

बंद होने, कार्रवाई, और क्रैश की रिपोर्ट के लिए report-to की ज़रूरत नहीं होती. ये रिपोर्ट, किसी नीति से जुड़ी नहीं होती हैं. ये तब तक जनरेट होते रहते हैं, जब तक default एंडपॉइंट सेट अप किया जाता है. साथ ही, इन्हें इस 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

चेतावनी: report-to सिंटैक्स को सही तरीके से इस्तेमाल करना मुश्किल हो सकता है, क्योंकि सभी नीतियां एक ही हेडर स्ट्रक्चर का इस्तेमाल नहीं करती हैं. नीति के हिसाब से, सही सिंटैक्स report-to=main-endpoint या report-to main-endpoint हो सकता है.

रिपोर्टिंग सेटअप को डीबग करना

जान-बूझकर रिपोर्ट जनरेट करना

Reporting API सेट अप करते समय, आपको जान-बूझकर अपनी नीतियों का उल्लंघन करना पड़ सकता है. ऐसा इसलिए, ताकि यह देखा जा सके कि रिपोर्ट जनरेट हो रही हैं और उन्हें उम्मीद के मुताबिक भेजा जा रहा है या नहीं.

समय बचाएँ

रिपोर्ट भेजने में एक मिनट की देरी हो सकती है. डीबग करने के दौरान, यह बहुत समय होता है. 😴 अच्छी बात यह है कि Chrome में डीबग करते समय, --short-reporting-delay फ़्लैग का इस्तेमाल किया जा सकता है. इससे रिपोर्ट जनरेट होते ही आपको मिल जाती हैं.

इस फ़्लैग को चालू करने के लिए, अपने टर्मिनल में यह कमांड चलाएं:

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

DevTools का इस्तेमाल करना

Chrome में, DevTools का इस्तेमाल करके उन रिपोर्ट को देखें जिन्हें भेजा जा चुका है या भेजा जाएगा.

अक्टूबर 2021 तक, यह सुविधा एक्सपेरिमेंट के तौर पर उपलब्ध है. इसका इस्तेमाल करने के लिए, यह तरीका अपनाएं:

Chrome का वर्शन 96 और इसके बाद के वर्शन का इस्तेमाल करें. यह देखने के लिए कि आपके ब्राउज़र का वर्शन कौन-सा है, chrome://version टाइप करें
Chrome के पता बार में chrome://flags/#enable-experimental-web-platform-features टाइप करें या चिपकाएं.
चालू है पर क्लिक करें.
अपना ब्राउज़र रीस्टार्ट करें.
Chrome DevTools खोलें.
Chrome DevTools में, सेटिंग खोलें. 'एक्सपेरिमेंट' में जाकर, ऐप्लिकेशन पैनल में Reporting API पैनल चालू करें पर क्लिक करें.
DevTools को फिर से लोड करें.
पेज को फिर से लोड करें. जिस पेज पर DevTools खुला है उससे जनरेट हुई रिपोर्ट, Chrome DevTools के ऐप्लिकेशन पैनल में Reporting API के नीचे दिखेंगी.

DevTools में रिपोर्ट की सूची दिखाने वाले स्क्रीनशॉट — Chrome DevTools, आपके पेज पर जनरेट हुई रिपोर्ट और उनकी स्थिति दिखाता है.

शिकायत की स्थिति

स्टेटस कॉलम से पता चलता है कि रिपोर्ट भेजी गई है या नहीं.

स्थिति	ब्यौरा
`Success`	ब्राउज़र ने रिपोर्ट भेज दी है और एंडपॉइंट ने सक्सेस कोड (`200` या कोई अन्य सक्सेस रिस्पॉन्स कोड `2xx`) के साथ जवाब दिया है.
`Pending`	ब्राउज़र, रिपोर्ट भेजने की कोशिश कर रहा है.
`Queued`	रिपोर्ट जनरेट हो गई है और ब्राउज़र इसे भेजने की कोशिश नहीं कर रहा है. इन दो मामलों में से किसी एक में, रिपोर्ट `Queued` के तौर पर दिखती है: यह रिपोर्ट नई है और ब्राउज़र यह देखने के लिए इंतज़ार कर रहा है कि क्या और रिपोर्ट आती हैं. इसके बाद, वह इसे भेजने की कोशिश करेगा. यह नई रिपोर्ट नहीं है. ब्राउज़र पहले ही इस रिपोर्ट को भेजने की कोशिश कर चुका है और ऐसा नहीं कर सका. अब वह फिर से कोशिश करने से पहले इंतज़ार कर रहा है.
`MarkedForRemoval`	कुछ समय (`Queued`) तक फिर से कोशिश करने के बाद, ब्राउज़र ने रिपोर्ट भेजने की कोशिश करना बंद कर दिया है. साथ ही, वह जल्द ही इसे भेजने के लिए तैयार रिपोर्ट की सूची से हटा देगा.

रिपोर्ट कुछ समय बाद हटा दी जाती हैं. भले ही, उन्हें भेजा गया हो या नहीं.

अहम जानकारी: Queued स्टेटस से हमेशा सही जानकारी नहीं मिलती. इसकी वजह यह है कि इससे यह पता नहीं चलता कि ईमेल भेजने में समस्या आई है या उसे अब तक भेजा ही नहीं गया है. रिपोर्टिंग में कम समय लगने का इस्तेमाल करने से ये फ़ायदे मिलते हैं: अगर रिपोर्ट Queued बनी रहती है, तो इसका मतलब है कि ईमेल नहीं भेजा जा सका.

समस्या का हल

क्या रिपोर्ट जनरेट नहीं हो रही हैं या आपके एंडपॉइंट पर उम्मीद के मुताबिक नहीं भेजी जा रही हैं? इस समस्या को हल करने के लिए, यहां कुछ सुझाव दिए गए हैं.

रिपोर्ट जनरेट नहीं की जाती हैं

DevTools में दिखने वाली रिपोर्ट सही तरीके से जनरेट की गई हैं. अगर आपको जिस रिपोर्ट की ज़रूरत है वह इस सूची में नहीं दिख रही है, तो:

अपनी नीतियों में report-to देखें. अगर इसे गलत तरीके से कॉन्फ़िगर किया गया है, तो रिपोर्ट जनरेट नहीं होगी. इस समस्या को ठीक करने के लिए, अपनी नीतियों में बदलाव करें पर जाएं. इस समस्या को हल करने का एक और तरीका है. इसके लिए, Chrome में DevTools कंसोल देखें: अगर आपको लगता है कि नीति का उल्लंघन हुआ है और कंसोल में कोई गड़बड़ी दिखती है, तो इसका मतलब है कि आपकी नीति शायद सही तरीके से कॉन्फ़िगर की गई है.
ध्यान रखें कि इस सूची में सिर्फ़ वे रिपोर्ट दिखेंगी जो उस दस्तावेज़ के लिए जनरेट की गई हैं जिसमें DevTools खुला है. उदाहरण के लिए: अगर आपकी साइट site1.example में कोई ऐसा iframe site2.example एम्बेड किया गया है जो किसी नीति का उल्लंघन करता है और इस वजह से रिपोर्ट जनरेट होती है, तो यह रिपोर्ट DevTools में सिर्फ़ तब दिखेगी, जब आपने iframe को उसकी विंडो में खोला हो और उस विंडो के लिए DevTools खोला हो.

रिपोर्ट जनरेट हो गई हैं, लेकिन भेजी नहीं गई हैं या मिली नहीं हैं

अगर आपको DevTools में कोई रिपोर्ट दिखती है, लेकिन आपके एंडपॉइंट को वह नहीं मिलती है, तो क्या होगा?

अहम जानकारी: रिपोर्ट को ब्राउज़र खुद भेजता है, न कि कोई साइट. इसलिए, रिपोर्ट वाले POST अनुरोध, आपके डेवलपर टूल के नेटवर्क पैनल में नहीं दिखते.

पक्का करें कि आपने कम समय के लिए देरी का इस्तेमाल किया हो. ऐसा हो सकता है कि रिपोर्ट अभी तक भेजी न गई हो, इसलिए आपको वह नहीं दिख रही है!
अपने Reporting-Endpoints हेडर कॉन्फ़िगरेशन की जांच करें. अगर इसमें कोई समस्या है, तो सही तरीके से जनरेट की गई रिपोर्ट नहीं भेजी जाएगी. इस मामले में, DevTools में रिपोर्ट का स्टेटस Queued रहेगा. हालांकि, डिलीवरी की कोशिश किए जाने पर यह Pending पर जा सकता है और फिर तुरंत वापस Queued पर आ सकता है. यहां कुछ आम गलतियां दी गई हैं जिनकी वजह से ऐसा हो सकता है:
एंडपॉइंट का इस्तेमाल किया गया है, लेकिन इसे कॉन्फ़िगर नहीं किया गया है. उदाहरण:

गड़बड़ी वाला कोड

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

Document-Policy के उल्लंघन की रिपोर्ट, endpoint-1 को भेजी जानी चाहिए. हालांकि, इस एंडपॉइंट का नाम Reporting-Endpoints में कॉन्फ़िगर नहीं किया गया है.

default एंडपॉइंट मौजूद नहीं है. कुछ तरह की रिपोर्ट, जैसे कि बंद होने वाली सुविधा और इंटरवेंशन रिपोर्ट, सिर्फ़ default नाम वाले एंडपॉइंट को भेजी जाएंगी. Reporting-Endpoints हेडर कॉन्फ़िगर करना लेख में इसके बारे में ज़्यादा पढ़ें.
नीति के हेडर के सिंटैक्स में मौजूद समस्याओं का पता लगाएं. जैसे, कोटेशन मार्क मौजूद न होना. ज़्यादा जानकारी देखें.
देखें कि आपका एंडपॉइंट, आने वाले अनुरोधों को हैंडल कर सकता हो.
- पक्का करें कि आपका एंडपॉइंट, सीओआरएस प्रीफ़्लाइट अनुरोधों के साथ काम करता हो. अगर ऐसा नहीं होता है, तो उसे रिपोर्ट नहीं मिल सकतीं.
- अपने एंडपॉइंट के व्यवहार की जांच करें. इसके लिए, मैन्युअल तरीके से रिपोर्ट जनरेट करने के बजाय, ब्राउज़र को एम्युलेट किया जा सकता है. इसके लिए, अपने एंडपॉइंट पर ऐसे अनुरोध भेजें जो ब्राउज़र के भेजे गए अनुरोधों की तरह दिखते हों. यह कमांड चलाएं:
```
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
```
आपके एंडपॉइंट को 200 या अन्य सक्सेस रिस्पॉन्स कोड 2xx के साथ जवाब देना चाहिए. अगर ऐसा नहीं होता है, तो इसके कॉन्फ़िगरेशन में कोई समस्या है.

शिकायत करने के अन्य तरीके

सिर्फ़ रिपोर्ट

-Report-Only नीति के हेडर और Reporting-Endpoints एक साथ काम करते हैं.

Reporting-Endpoints में कॉन्फ़िगर किए गए और Content-Security-Policy, Cross-Origin-Embedder-Policy, और Cross-Origin-Opener-Policy के report-to फ़ील्ड में बताए गए एंडपॉइंट को, इन नीतियों के उल्लंघन की रिपोर्ट मिलेंगी.

Reporting-Endpoints में कॉन्फ़िगर किए गए एंडपॉइंट, Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only, और Cross-Origin-Opener-Policy-Report-Only के report-to फ़ील्ड में भी दिए जा सकते हैं. इन नीतियों का उल्लंघन होने पर, उन्हें रिपोर्ट भी मिलेंगी.

दोनों ही मामलों में रिपोर्ट भेजी जाती हैं. हालांकि, -Report-Only हेडर, नीतियों को लागू नहीं करते: कुछ भी नहीं टूटेगा या ब्लॉक नहीं होगा. हालांकि, आपको इस बात की रिपोर्ट मिलेगी कि क्या टूट गया है या ब्लॉक हो गया है.

ध्यान दें: अगर -Report-Only हेडर का इस्तेमाल किया जा रहा है और आपने लेगसी हेडर Report-To का इस्तेमाल करके रिपोर्टिंग एंडपॉइंट कॉन्फ़िगर किए हैं, तो Reporting-Endpoints पर माइग्रेट करें. ज़्यादा जानकारी के लिए, डेटा को दूसरी जगह भेजने से जुड़ी गाइड पढ़ें.

`ReportingObserver`

ReportingObserver JavaScript API की मदद से, क्लाइंट-साइड की चेतावनियों को देखा जा सकता है.

ReportingObserver और Reporting-Endpoints हेडर, एक जैसी रिपोर्ट जनरेट करते हैं. हालांकि, इनसे अलग-अलग तरह के इस्तेमाल के उदाहरण मिलते हैं.

इन स्थितियों में ReportingObserver का इस्तेमाल करें:

आपको सिर्फ़ बंद की जा रही सुविधाओं या ब्राउज़र के इंटरवेंशन को मॉनिटर करना है. ReportingObserver, क्लाइंट-साइड की चेतावनियां दिखाता है. जैसे, बंद की जा रही सुविधाएं और ब्राउज़र इंटरवेंशन. हालांकि, Reporting-Endpoints के उलट, यह CSP या COOP/COEP के उल्लंघन जैसी किसी भी अन्य तरह की रिपोर्ट को कैप्चर नहीं करता.
आपको इन उल्लंघनों पर रीयल-टाइम में कार्रवाई करनी होगी. ReportingObserver की मदद से, उल्लंघन से जुड़े इवेंट में कॉल बैक अटैच किया जा सकता है.
आपको डीबग करने में मदद पाने के लिए, रिपोर्ट में अतिरिक्त जानकारी जोड़नी है. इसके लिए, कस्टम कॉलबैक का इस्तेमाल करें.

एक और अंतर यह है कि ReportingObserver को सिर्फ़ क्लाइंट-साइड पर कॉन्फ़िगर किया जाता है: इसका इस्तेमाल तब भी किया जा सकता है, जब आपके पास सर्वर-साइड हेडर को कंट्रोल करने का अधिकार न हो और Reporting-Endpoints को सेट न किया जा सके.

इस बारे में और पढ़ें

हीरो इमेज, नाइन कोफ़र / @enka80 ने Unsplash पर पोस्ट की है. इसमें बदलाव किया गया है. इस दस्तावेज़ की समीक्षा करने और सुझाव देने के लिए, Ian Clelland, Eiji Kitamura, और Milica Mihajlija का बहुत-बहुत धन्यवाद.

खास जानकारी

इस्तेमाल के उदाहरण और रिपोर्ट के टाइप

रिपोर्ट

रिपोर्ट कैसी दिखती हैं?

क्रेडेंशियल वाली रिपोर्ट

ब्राउज़र, रिपोर्ट कब और कैसे भेजता है?

तीसरे और पहले पक्ष की समस्याएं

बंद की गई सुविधाओं के साथ उदाहरण

ब्राउज़र समर्थन

Reporting API का इस्तेमाल करना

तय करें कि रिपोर्ट कहां भेजी जानी चाहिए

पहला विकल्प: रिपोर्ट इकट्ठा करने वाली किसी मौजूदा सेवा का इस्तेमाल करना

दूसरा विकल्प: अपना रिपोर्ट कलेक्टर बनाना और उसे मैनेज करना

तीसरा विकल्प: पहले और दूसरे विकल्प को एक साथ इस्तेमाल करना

Reporting-Endpoints हेडर को कॉन्फ़िगर करना

कुंजियां (एंडपॉइंट के नाम)

वैल्यू (यूआरएल)

उदाहरण

हेडर कहां सेट करें?

अपनी नीतियों में बदलाव करना

उदाहरण

रिपोर्टिंग सेटअप को डीबग करना

जान-बूझकर रिपोर्ट जनरेट करना

समय बचाएँ

DevTools का इस्तेमाल करना

शिकायत की स्थिति

समस्या का हल

रिपोर्ट जनरेट नहीं की जाती हैं

रिपोर्ट जनरेट हो गई हैं, लेकिन भेजी नहीं गई हैं या मिली नहीं हैं

शिकायत करने के अन्य तरीके

सिर्फ़ रिपोर्ट

ReportingObserver

इस बारे में और पढ़ें

`Reporting-Endpoints` हेडर को कॉन्फ़िगर करना

`ReportingObserver`