‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

Maud Nalpas

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

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

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

במאמר הזה מוסבר מה אפשר לעשות באמצעות ה-API הזה ואיך משתמשים בו. שנתחיל?

סקירה כללית

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

נניח שבאתר שלכם, site.example, יש Content-Security-Policy ו-Document-Policy. לא יודעים מה הם עושים? זה בסדר, עדיין תוכלו להבין את הדוגמה הזו.

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

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

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

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

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

דוח לדוגמה

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

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

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

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

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

שימוש ב-Reporting API

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

יש לך שתי אפשרויות:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמאות

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

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

לכל מדיניות, הערך של 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

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

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

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

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

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

סטטוס הדיווח

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

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

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

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

פתרון בעיות

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

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

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

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

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

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

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

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

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

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

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

קריאה נוספת

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