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

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

Maud Nalpas
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) זהה, מלבד סוג דוח אחד: אין תמיכה ביומן שגיאות רשת ב-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 ויכול לקבל ולציג דוחות.

  1. עוברים אל אוסף הדוחות הסטנדרטיים.

  2. לוחצים על Remix to Edit כדי לאפשר עריכה של הפרויקט.

  3. עכשיו יש לכם את העותק. אתם יכולים להתאים אותו אישית למטרות שלכם.

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

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

ערכים (כתובות 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.

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

דוגמה ב-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-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

קוד לדוגמה

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

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

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

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

חוסכים זמן

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

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

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

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

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

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

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

סטטוס דוח

בעמודה סטטוס מצוין אם הדוח נשלח בהצלחה.

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

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

פתרון בעיות

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

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

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

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

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

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

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

ReportingObserver

אתם יכולים להשתמש ב-JavaScript API של ReportingObserver כדי לזהות אזהרות מצד הלקוח.

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

כדאי להשתמש ב-ReportingObserver אם:

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

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

קריאה נוספת

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