דף זה תורגם על ידי Cloud Translation API.

מעקב אחר אפליקציית האינטרנט באמצעות Reporting API

אתם יכולים להשתמש ב-Reporting API כדי לעקוב אחרי הפרות אבטחה, קריאות ל-API שהוצאו משימוש ועוד.

Maud Nalpas

חלק מהשגיאות מתרחשות רק בסביבת הייצור. הם לא יופיעו באופן מקומי או במהלך כי משתמשים אמיתיים, רשתות אמיתיות ומכשירים אמיתיים לשנות את המשחק. Reporting API עוזר לזהות חלק מהשגיאות האלה, כמו הפרות אבטחה או API שהוצא משימוש ובקרוב יוצא משימוש שיחות באתר שלכם, ומשדרות אותן לנקודת קצה (endpoint) שצוין.

היא מאפשרת לך להצהיר אחרי מה ברצונך לעקוב באמצעות כותרות HTTP, מופעלים על ידי הדפדפן.

הגדרה של Reporting API מאפשרת לכם להיות בראש שקט כי כשמשתמשים חווים סוגים כאלה של שגיאות, כך שתוכלו לתקן אותן.

בפוסט הזה נסביר מה ה-API יכול לעשות ואיך להשתמש בו. קדימה, מתחילים!

הדגמה וקוד

מתחילים לראות את ה-Reporting API בפעולה Chrome 96 ואילך (Chrome בטא או Canary, החל מאוקטובר 2021).

סקירה כללית

תרשים שמסכם את השלבים הבאים, מיצירת דוחות ועד דיווח על גישה של המפתח — איך הדוחות נוצרים ונשלחים

נניח שלאתר שלך, site.example, יש מדיניות אבטחת תוכן וגם מדיניות מסמך. לא ברור לך מה הפעולות האלה? זה בסדר, עדיין תישארו כדי להבין את הדוגמה הזו.

אתם מחליטים לעקוב אחר האתר כדי לדעת מתי הוא מפר את המדיניות, אך גם כי אתם רוצים לעקוב אחרי ממשקי API שהוצאו משימוש או שיוצאו משימוש בקרוב, וש-Codebase שלכם עשוי להשתמש בהם.

כדי לעשות את זה, צריך להגדיר כותרת של 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;

הדפדפן מפיק דוח הפרות של מדיניות CSP, דוח הפרות של מדיניות המסמך והוצאה משימוש שמתייחס לבעיות האלה.

לאחר עיכוב קצר — עד דקה — הדפדפן שולח את הדוחות נקודת קצה (endpoint) שהוגדרה לסוג ההפרה הזה. הדוחות נשלחים מחוץ למסגרת של הדפדפן עצמו (לא על ידי השרת או על ידי האתר שלכם).

נקודות הקצה מקבלות את הדוחות האלה.

עכשיו אפשר לגשת לדוחות על נקודות הקצה האלה ולעקוב אחרי הבעיה. אתם יכולים להתחיל לפתור את הבעיה שמשפיעה על המשתמשים שלכם.

דוח לדוגמה

{
  "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 כדי לעקוב אחרי סוגים רבים של אזהרות או בעיות מעניינות שמתרחשות בכל האתר:

סוג הדוח	דוגמה למצב שבו המערכת יוצרת דוח
הפרה של CSP (רמה 3 בלבד)	הגדרת `Content-Security-Policy` (CSP) באחד מהדפים, אבל הדף מנסה לטעון סקריפט שלא הורשה על ידי ה-CSP.
הפרה של COOP	הגדרת `Cross-Origin-Opener-Policy` בדף, אבל חלון ממקורות שונים מנסה לבצע אינטראקציה ישירות עם המסמך.
הפרה של COEP	הגדרת `Cross-Origin-Embedder-Policy` בדף, אבל המסמך כולל iframe ממקורות שונים שלא הצטרף לטעינה באמצעות מסמכים ממקורות שונים.
הפרה של מדיניות המסמך	לדף יש מדיניות מסמך שמונעת שימוש ב-`document.write`, אבל סקריפט מנסה לקרוא ל-`document.write`.
הפרה של מדיניות ההרשאות	לדף יש מדיניות הרשאות שמונעת שימוש במיקרופון, וסקריפט שמבקש קלט אודיו.
אזהרה על הוצאה משימוש	הדף משתמש בממשק API שהוצא משימוש או שיצא משימוש. וקורא לו ישירות או באמצעות סקריפט של צד שלישי ברמה העליונה.
התערבות	הדף מנסה לבצע פעולה שהדפדפן מחליט שלא לפעול לפיה, מסיבות של אבטחה, ביצועים או חוויית משתמש. דוגמה ב-Chrome: הדף משתמש ב-`document.write` ברשתות איטיות או מפעיל קריאה ל-`navigator.vibrate` במסגרת ממקורות שונים שהמשתמש עדיין לא יצר איתה אינטראקציה.
תאונה	הדפדפן קורס בזמן שהאתר פתוח.

דוחות

איך נראים דוחות?

הדפדפן שולח דוחות לנקודת הקצה שהגדרתם. היא שולחת בקשות שנראות כך:

POST
Content-Type: application/reports+json

המטען הייעודי (Payload) של הבקשות האלה הוא רשימה של דוחות.

רשימת דוחות לדוגמה

[
  {
    "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`	כתובת המסמך או העובד שמהם נוצר הדוח. מידע אישי רגיש כמו שם משתמש, סיסמה ומקטע (מקטע) יוסר מכתובת ה-URL הזו.
`user_agent`	הכותרת `User-Agent` של הבקשה שממנה נוצר הדוח.

דוחות עם פרטי כניסה

נקודות הקצה לדיווח, בעלות אותו המקור של הדף שיוצר את הדוח, מקבלים את פרטי הכניסה (קובצי cookie) בבקשות שמכילות את הדוחות.

פרטי הכניסה יכולים לספק הקשר נוסף ומועיל לגבי הדוח. עבור לדוגמה, האם חשבון של משתמש מסוים מפעיל שגיאות באופן עקבי, או אם רצף מסוים מבין הפעולות שבוצעו בדפים אחרים, גורמות לדיווח על הדף הזה.

מתי ואיך הדפדפן שולח דוחות?

דוחות נשלחים מחוץ למסגרת מהאתר שלכם: הדפדפן קובע מתי הן נשלחות לנקודות הקצה שהוגדרו. אין גם דרך לקבוע מתי הדפדפן שולח דוחות. הוא מתעד, עוקב ושולח אותן באופן אוטומטי זמן מתאים.

המשמעות היא שאין פגיעה בביצועים כשמשתמשים ב-Reporting API.

הדוחות נשלחים בעיכוב — עד דקה — כדי להגדיל את הסיכויים לשליחת דוחות באצוות. כך חוסכים רוחב פס כדי לכבד את חיבור הרשת של המשתמש, בנייד. הדפדפן יכול גם לעכב את השליחה אם הוא עסוק בעיבוד בעדיפות גבוהה יותר פועלות, או אם המשתמש נמצא ברשת איטית או עמוסה באותו זמן.

בעיות שקשורות לצדדים שלישיים ולצדדים שלישיים

יישלחו דוחות שנוצרו עקב הפרות או הוצאה משימוש של הדף שלך לנקודות הקצה שהגדרתם. נכללות הפרות שבוצעו על ידי סקריפטים של צד שלישי שמוצגות בדף שלכם.

הפרות או הוצאות משימוש של הפרות שקרו ב-iframe ממקורות שונים שמוטמע בדף לא ידווחו לנקודות הקצה שלך (לפחות לא כברירת מחדל). ל-iframe יש אפשרות להגדיר לדווח ואפילו לדווח לאתר שלכם - כלומר, לשירות הדיווח של הצד הראשון. אבל זה הכול לאתר הממוסגר. כמו כן, רוב הדוחות נוצרים רק אם מפירים את המדיניות של דף מסוים, ושהמדיניות של הדף שונה מהמדיניות של ה-iframe.

דוגמה להוצאה משימוש

אם הכותרת Reporting-Endpoints מוגדרת בדף: ממשק API שהוצא משימוש, שנקרא על ידי סקריפטים של צד שלישי שפועלים בדף, ידווח לנקודת הקצה שלכם. ממשק API שהוצא משימוש נקרא על ידי iframe שמוטמע בדף לא ידווח לנקודת הקצה שלך. המערכת תיצור דוח הוצאה משימוש רק אם שרת ה-iframe הגדיר נקודות קצה לדיווח, והדוח הזה יישלח לכל נקודת קצה שהגדיר השרת של ה-iframe.

תמיכה בדפדפנים

בטבלה הבאה מוצג סיכום של תמיכת הדפדפן ב-Reporting API v1, עם הכותרת Reporting-Endpoints. תמיכת הדפדפן ב-Reporting API v0 (הכותרת Report-To) היא זהה, למעט סוג אחד של דוח: Network Error Logging לא נתמך ב-Reporting API החדש. פרטים נוספים זמינים במדריך להעברת נתונים (מיגרציה).

סוג הדוח	Chrome	Chrome iOS	Safari	Firefox	Edge
הפרה של CSP (רמה 3 בלבד)*	✔ כן	✔ כן	✔ כן	myactivity לא	✔ כן
רישום של שגיאות רשת	myactivity לא	myactivity לא	myactivity לא	myactivity לא	myactivity לא
הפרה של COOP/COEP	✔ כן	myactivity לא	✔ כן	myactivity לא	✔ כן
כל הסוגים האחרים: הפרה של מדיניות המסמכים, הוצאה משימוש, התערבות, קריסה	✔ כן	myactivity לא	myactivity לא	myactivity לא	✔ כן

הטבלה הזו מסכמת את התמיכה ב-report-to רק עם הכותרת החדשה Reporting-Endpoints. אם אתם רוצים לעבור אל Reporting-Endpoints, כדאי לקרוא את הטיפים להעברת נתוני דיווח של CSP.

שימוש ב-Reporting API

החלטה לאן לשלוח את הדוחות

עומדות לרשותך שתי אפשרויות:

לשלוח דוחות לשירות קיים לאיסוף דוחות.
לשלוח דוחות לאוסף דוחות שאתם יוצרים ומפעילים בעצמכם.

אפשרות 1: שימוש בשירות קיים לאיסוף דוחות

דוגמאות לשירותים לאיסוף דוחות:

אם ידוע לכם על פתרונות אחרים, תוכלו לפתוח בעיה כדי לספר לנו עליה, ואנחנו נעדכן את הפוסט הזה.

מלבד התמחור, כדאי להביא בחשבון את הנקודות הבאות כשבוחרים אוסף דוחות: 🧐

האם אוסף הדוחות הזה תומך בכל סוגי הדוחות? לדוגמה, לא כל הפתרונות לדיווח על נקודות קצה תמיכה בדוחות COOP/COEP.
האם אתם מרגישים בנוח לשתף כתובות URL של האפליקציה שלכם עם צד שלישי לאיסוף דוחות? גם אם הדפדפן מסיר מידע רגיש מכתובות ה-URL האלה, ייתכן שמידע רגיש יודלף בדרך הזו. אם זה נשמע מסוכן מדי להפעיל נקודת קצה משלכם לדיווח.

אפשרות 2: יצירה והפעלה של אוסף דוחות משלכם

יצירת שרת משלכם שמקבל דוחות לא פשוטה כל כך. כדי להתחיל, אפשר לחבר דוד חימום קליל. הוא נוצר באמצעות Express ויכול לקבל ולהציג דוחות.

תוכלו לעבור אל אוסף דוחות הסטנדרטיים.
לוחצים על רמיקס לעריכה כדי לערוך את הפרויקט.
יש לך עכשיו שכפול! אפשר להתאים אותו אישית למטרות שלך.

אם אתם לא משתמשים בסטנדרטיזציה ואתם בונים שרת משלכם:

צריך לחפש POST בקשות עם Content-Type במדד application/reports+json כדי לזהות דוחות בקשות שנשלחו על ידי הדפדפן לנקודת הקצה שלכם.
אם נקודת הקצה נמצאת במקור אחר מזה של האתר שלכם, אתם צריכים לוודא שהיא תומכת בבקשות קדם-הפעלה של CORS.

אפשרות 3: שילוב אפשרות 1 ו-2

מומלץ לתת לספק מסוים לטפל בסוגים מסוימים של דוחות, אבל כדאי לך להיעזר בספק פנימי את הפתרון עבור אחרים.

במקרה כזה, צריך להגדיר כמה נקודות קצה באופן הבא:

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. הפרטים מופיעים במדריך להעברת נתונים (מיגרציה). באופן ספציפי, אם אתם משתמשים בדיווח Content-Security-Policy הפרות רק בהוראת report-uri. יש לבדוק את שלבי ההעברה לדיווח על מדיניות CSP.

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. עכשיו אפשר יכולה לנתב דוחות לנקודות קצה (endpoint) שונות בהתאם לסוג שלהם.

אם אתם רוצים לקבל התערבות, הוצאה משימוש או קריסה מגדירים נקודת קצה (endpoint) בשם default.

אם בכותרת Reporting-Endpoints לא מוגדרת נקודת קצה (endpoint) default, דוחות מהסוג הזה לא יישלחו (אבל הם ייווצרו).

נקודה חשובה: למרות השם, default לא מהווה חלופה נקודת הקצה. לדוגמה, אם מגדירים את report-to my-endpoint עבור Document-Policy ולהשמיט את ההגדרה של my-endpoint ב- Reporting-Endpoints, Document-Policy הפרות דוחות יופקו אבל לא יישלחו כי הדפדפן לא יודע לאן לשלוח אותן.

ערכים (כתובות URL)

כל ערך הוא כתובת URL לבחירתכם, שאליה הדוחות יישלחו. כתובת ה-URL להגדיר כאן תלוי במה שהחלטתם בשלב 1.

כתובת URL של נקודת קצה:

השם חייב להתחיל בקו נטוי (/). אין תמיכה בנתיבים יחסיים.
יכול להיות חוצה-מקורות; אבל במקרה כזה פרטי הכניסה לא נשלחים יחד עם הדוחות.

דוגמאות

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

לאחר מכן אפשר להשתמש בכל נקודת קצה בעלת שם במדיניות המתאימה, או להשתמש בנקודת קצה נקודת קצה אחת בכל כללי המדיניות.

איפה להגדיר את הכותרת?

בממשק החדש של Reporting API, שכולל את post— הדוחות מתייחסים למסמכים. המשמעות היא שעבור אחת מקור, מסמכים שונים, כמו site.example/page1 site.example/page2, יכול לשלוח דוחות לנקודות קצה (endpoint) שונות.

כדי לקבל דוחות על הפרות או הוצאה משימוש בכל דף להגדיר את הכותרת כתווכה בכל התגובות.

הנה דוגמה ב-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) הקודם, שבו אפשר להגדיר 'סביבה' נקודת קצה (endpoint) לדף אחד, ולקבל באופן אוטומטי דוחות עבור כל דף באותו המקור. אם אתם עוברים מגרסת Reporting API הקודמת לממשק Reporting API החדש, כדאי לעיין במדריך להעברת נתונים (מיגרציה).

עריכת כללי המדיניות

עכשיו, כשהכותרת Reporting-Endpoints מוגדרת, צריך להוסיף report-to לכל כותרת מדיניות שעבורה ברצונך לקבל הפרה דוחות. הערך של report-to צריך להיות אחת מנקודות הקצה בעלות שם מוגדר.

אפשר להשתמש בנקודת קצה מרובות למספר כללי מדיניות, או להשתמש נקודות קצה (endpoints) בכל כללי מדיניות.

עבור כל מדיניות, הערך של report-to צריך להיות אחת מנקודות הקצה (endpoints) בעלות השם שהגדרתם.

אין צורך ב-report-to להוצאה משימוש, להתערבות ולקריסה דוחות. הדוחות האלה לא מחויבים לשום מדיניות. הם נוצרים כל עוד מוגדרת נקודת קצה (endpoint) 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. כדאי לעבור אל הדגמה כדי לקבל דוגמאות לקוד.

קוד לדוגמה

כדי לראות את כל זה בהקשר, בהמשך מוצגת דוגמה לשרת Node שמשתמש ב-Express והיא כוללת את כל הקטעים שמוזכרים במאמר הזה. הוא מראה איך להגדיר דיווח לכמה סוגי דוחות שונים ולהציג את התוצאות.

ניפוי באגים בהגדרת הדיווח

יצירת דוחות בכוונה

כשמגדירים את Reporting API, סביר להניח שיהיה צורך להפר באופן מכוון המדיניות שלכם כדי לבדוק אם הדוחות נוצרים ונשלחים כמצופה. כדי לראות קוד לדוגמה שמפר את כללי המדיניות ומבצע פעולות בעייתיות אחרות ליצור דוחות מכל הסוגים, לנסות את ההדגמה.

חוסכים זמן

ייתכן שהדיווחים יישלחו בעיכוב של כדקה, כלומר משך זמן ארוך במהלך ניפוי באגים. 😴 למרבה המזל, אפשר להשתמש בדגל במהלך ניפוי באגים ב-Chrome --short-reporting-delay כדי לקבל דוחות ברגע שהם נוצרים.

כדי להפעיל את הדגל הזה, מריצים את הפקודה הבאה בטרמינל:

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

שימוש בכלי פיתוח

ב-Chrome, אפשר להשתמש בכלי הפיתוח כדי לראות אילו דוחות נשלחו או יישלחו.

נכון לאוקטובר 2021, התכונה הזו היא ניסיונית. כדי להשתמש בו, יש לבצע את השלבים הבאים:

צריך להשתמש ב-Chrome בגרסה 96 ואילך (כדי לבדוק אותה, צריך להקליד chrome://version בדפדפן)
מקלידים או מדביקים את chrome://flags/#enable-experimental-web-platform-features בסרגל כתובות ה-URL של Chrome.
לוחצים על Enabled (מופעל).
מפעילים מחדש את הדפדפן.
פותחים את כלי הפיתוח ל-Chrome.
בכלי הפיתוח ל-Chrome, פותחים את ההגדרות. בקטע 'ניסויים', לוחצים על הפעלת החלונית של Reporting API חלונית האפליקציות.
טעינה מחדש של כלי הפיתוח.
לטעון מחדש את הדף. דוחות שנוצרו על ידי הדף שבו פותחים את כלי הפיתוח יהיו מופיע בכלי הפיתוח ל-Chrome בחלונית Application, בקטע Reporting API.

צילום מסך של כלי הפיתוח להצגת הדוחות — בכלי הפיתוח ל-Chrome מוצגים הדוחות שנוצרו בדף והסטטוס שלהם.

סטטוס דוח

בעמודה סטטוס אפשר לראות אם הדוח נשלח בהצלחה.

סטטוס	תיאור
`Success`	הדפדפן שלח את הדוח ונקודת הקצה השיבה עם קוד הצלחה (`200` או קוד תגובה אחר להצלחה, `2xx`).
`Pending`	הדפדפן מנסה כרגע לשלוח את הדוח.
`Queued`	הדוח נוצר והדפדפן לא מנסה לשלוח אותו. דוח מופיע בתור `Queued` באחד משני המקרים הבאים: הדוח חדש והדפדפן מחכה כדי לראות אם יגיעו דוחות נוספים לפני הניסיון לשלוח אותו. הדוח לא חדש. הדפדפן כבר ניסה לשלוח את הדוח הזה ונכשל, ומחכה לפני שמנסים שוב.
`MarkedForRemoval`	לאחר ניסיון חוזר למשך זמן מה (`Queued`), הדפדפן הפסיק לנסות לשלוח את הדוח, ובקרוב יסיר אותו מרשימת הדוחות לשליחה.

דוחות יוסרו לאחר זמן מה, גם אם הם לא נשלחו בהצלחה.

נקודה חשובה: הסטטוס Queued לא תמיד מספק מידע, כי הוא לא מציין במדויק אם השליחה נכשלה או שעדיין לא נעשה בו ניסיון. שימוש בעיכובים בדיווח קצרים יכול לעזור: אם הדוח יישאר Queued במקרה כזה, סביר להניח שהשליחה נכשלה.

פתרון בעיות

האם הדוחות לא נוצרים או לא נשלחים כמצופה לנקודת הקצה שלכם? ריכזנו כאן כמה טיפים לפתרון הבעיה.

לא נוצרים דוחות

הדוחות שמופיעים בכלי הפיתוח נוצרו בצורה תקינה. אם הדוח שאתם מצפים לו לא מופיע ברשימה הזו:

צריך לבדוק את report-to במדיניות. אם הגדרה זו שגויה, לא יופק דוח. אתם יכולים לעבור אל עריכת המדיניות כדי כדי לפתור את הבעיה. דרך נוספת לפתור בעיות היא לבדוק את מסוף כלי הפיתוח ב-Chrome: אם הופיעה שגיאה במסוף לגבי ההפרה הצפויה, המשמעות היא שסביר להניח שהמדיניות מוגדר כראוי.
חשוב לזכור שרק הדוחות שנוצרו עבור המסמך 'כלי הפיתוח' פתוחים מופיעים ברשימה הזאת. דוגמה אחת: אם באתר site1.example מוטמע iframe site2.example שמפר מדיניות ולכן יוצר דוח, הדוח הזה יופיע בכלי הפיתוח רק אם מוסיפים iframe בחלון משלו ופותחים את כלי הפיתוח בחלון הזה.

דוחות נוצרים אך לא נשלחים או לא התקבלו

מה קורה אם רואים דוח בכלי הפיתוח אבל נקודת הקצה לא מקבלת אותו?

נקודה חשובה: מכיוון שהדוח נשלח מחוץ למסגרת על ידי הדפדפן עצמו ולא על ידי באתר מסוים, בקשות ה-POST שמכילות את הדוחות לא מוצגות החלונית Network בכלי למפתחים.

הקפידו להשתמש בעיכובים קצרים. אולי הסיבה שלא רואים את הדוח היא עדיין לא נשלח
צריך לבדוק את הגדרת הכותרת של Reporting-Endpoints. אם יש בעיה, לא יישלחו כראוי. בכלי הפיתוח, הסטטוס של הדוח יישאר Queued (הוא עשוי לקפוץ אל Pending, ואז לחזור במהירות אל Queued כשיהיה ניסיון מסירה במקרה הזה. כמה שגיאות נפוצות שעלולות לגרום לכך:
נעשה שימוש בנקודת הקצה, אבל היא לא מוגדרת. דוגמה:

קוד עם טעות

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

יש לשלוח דוחות על הפרות של מדיניות המסמך אל endpoint-1, אבל השם של נקודת הקצה לא מוגדר ב- Reporting-Endpoints.

נקודת הקצה (endpoint) default חסרה. סוגים מסוימים של דוחות, כמו הוצאה משימוש והתערבות דוחות יישלחו רק לנקודת הקצה (endpoint) בשם default. מידע נוסף זמין בקטע הגדרת הכותרת Reporting-Endpoints.
צריך לחפש בעיות בתחביר של כותרות המדיניות, כמו מירכאות חסרות. לפרטים
בודקים שנקודת הקצה יכולה לטפל בבקשות נכנסות.
- ודאו שנקודת הקצה תומכת בבקשות קדם-הפעלה של CORS. אם הוא לא מקבל דוחות, הוא לא יכול לקבל דוחות.
- בודקים את ההתנהגות של נקודת הקצה. כדי לעשות את זה, במקום ליצור באופן ידני, אפשר לאמולה של הדפדפן על ידי שליחה של בקשות לנקודות קצה (endpoint) שנראות כך אלא מה הדפדפן ישלח. מריצים את הפקודה הבאה:
```
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 פועלות יחד.

נקודות הקצה (endpoints) שהוגדרו ב-Reporting-Endpoints וצוינו בשדה report-to של Content-Security-Policy, Cross-Origin-Embedder-Policy וגם Cross-Origin-Opener-Policy יקבל דוחות במקרים שבהם תהיה הפרה של המדיניות.

אפשר לציין נקודות קצה שהוגדרו ב-Reporting-Endpoints גם בקטע שדה report-to של Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only וגם Cross-Origin-Opener-Policy-Report-Only. בנוסף, הם יקבלו דיווחים כאשר תפרו את המדיניות.

הדוחות נשלחים בשני המקרים, אבל כותרות -Report-Only לא אוכפות את המדיניות: שום דבר לא ייכשל או ייחסם בפועל, אבל אתם תקבלו דיווחים על מה היו עלול לקרוס או להיחסם.

הערה: אם משתמשים בכותרת -Report-Only והגדרת את נקודות הקצה לדיווח דרך הכותרת הקודמת Report-To, צריך לעבור אל Reporting-Endpoints אם אפשר. מידע נוסף זמין במדריך להעברת נתונים (מיגרציה).

`ReportingObserver`

אפשר להיעזר ב-JavaScript API ReportingObserver תועדו אזהרות בצד הלקוח.

ReportingObserver והכותרת Reporting-Endpoints יוצרים דוחות נראות זהות, אבל הן מאפשרות שימושים שונים במקצת.

שימוש ב-ReportingObserver אם:

רוצים לעקוב רק אחרי הוצאות משימוש ו/או התערבות של הדפדפן. ב-ReportingObserver מוצגות אזהרות בצד הלקוח, כמו הוצאות משימוש והתערבות בדפדפן, אבל בניגוד ל-Reporting-Endpoints, לתעד כל סוג אחר של דיווח, כמו הפרות מדיניות ל-CSP או COOP/COEP.
עליכם להגיב להפרות האלה בזמן אמת. ReportingObserver יצרן אפשר לצרף קריאה חוזרת לאירוע של הפרה.
אתם רוצים לצרף מידע נוסף לדוח כדי לסייע בניפוי באגים, באמצעות הקריאה החוזרת (callback) בהתאמה אישית.

הבדל נוסף הוא ש-ReportingObserver מוגדר רק בצד הלקוח: אפשר להשתמש בו גם אם אין לכם שליטה על כותרות בצד השרת, ואתם לא יכולים מגדירים את Reporting-Endpoints.

קריאה נוספת

תמונה ראשית (Hero) של Nine Koepfer / @enka80 מופעלת ביטול הפתיחה, נערכה. תודה רבה לאיאן קללנד (Ian Clelland), אייג'י קיטמורה (Eiji Kitamura) ומיליקה מיהאג'ליה (Mihajlija) על הביקורות וההצעות שהם השתמשו במאמר הזה.