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

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

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

Maud Nalpas

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

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

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

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

הדגמה וקוד

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

סקירה כללית

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

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

דוגמה עם הוצאות משימוש

אם הכותרת Reporting-Endpoints מוגדרת בדף: ממשקי API שהוצאו משימוש וקובצי סקריפט של צד שלישי שפועלים בדף יתועדו בנקודת הקצה. קריאות ל-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 בלבד)*	✔ כן	✔ כן	✔ כן	✘ לא	✔ כן
רישום שגיאות ברשת ביומן	✘ לא	✘ לא	✘ לא	✘ לא	✘ לא
הפרה של COOP/COEP	✔ כן	✘ לא	✔ כן	✘ לא	✔ כן
כל שאר הסוגים: הפרת מדיניות של מסמך, הוצאה משימוש, התערבות, קריסה	✔ כן	✘ לא	✘ לא	✘ לא	✔ כן

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

שימוש ב-Reporting API

איך קובעים לאן יישלחו הדוחות

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

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

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

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

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

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

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

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

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

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

אם אתם לא משתמשים ב-boilerplate ובונים שרת משלכם מהתחלה:

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

קוד לדוגמה

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

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

סטטוס הדוח

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

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

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

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

פתרון בעיות

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

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

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

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

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

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

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

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

קוד עם שגיאה

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

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

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

קריאה נוספת

התמונה הראשית (Hero) של Nine Koepfer / @enka80 ב-Unsplash, ערוכה. תודה רבה ל-Ian Clelland, ‏ Eiji Kitamura ו-Milica Mihajlija על הביקורות וההצעות שלהם לגבי המאמר הזה.