כדאי להשתמש ב-Reporting API כדי לעקוב אחר הפרות אבטחה, קריאות ל-API שהוצאו משימוש ועוד.
חלק מהשגיאות מתרחשות רק בסביבת הייצור. לא תראו אותם באופן מקומי או במהלך הפיתוח, כי משתמשים אמיתיים, רשתות אמיתיות ומכשירים אמיתיים משנים את המשחק. ה-Reporting API עוזר לאתר חלק מהשגיאות האלה, כמו הפרות אבטחה או קריאות ל-API שהוצאו משימוש ובקרוב יוצאו משימוש, ומעביר אותן לנקודת קצה שציינתם.
היא מאפשרת להצהיר אחרי מה רוצים לעקוב באמצעות כותרות HTTP, והיא מופעלת על ידי הדפדפן.
הגדרה של Reporting API מאפשרת לכם לדעת כשמשתמשים חווים שגיאות מהסוגים האלה, כדי שתוכלו לתקן אותן.
בפוסט הזה נסביר מה ה-API הזה יכול לעשות ואיך להשתמש בו. קדימה, מתחילים!
הדגמה (דמו) וקוד
אפשר לראות את Reporting API בפעולה החל מ-Chrome 96 ואילך (Chrome בטא או Canary, החל מאוקטובר 2021).
סקירה כללית
![תרשים שמסכם את השלבים הבאים, מיצירת דוח ועד גישה לדוחות של המפתח](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/diagram-summarizing-step-7115c265c2e02.png?authuser=5&hl=he)
נניח שלאתר שלך, site.example
, יש מדיניות אבטחה-תוכן ומדיניות מסמכים. לא ידוע לך מה הערכים האלה עושים? זה בסדר, עדיין תוכלו להבין את הדוגמה הזו.
אתם מחליטים לעקוב אחרי האתר כדי לדעת מתי כללי המדיניות מופרות, אבל גם כי אתם רוצים לשים לב לממשקי 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 הגדיר נקודות קצה לדיווח, והדוח הזה יישלח לנקודת הקצה ששרת ה-iframe הגדיר.](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/if-reporting-endpoints-h-c4facaee3ba26.png?authuser=5&hl=he)
תמיכת דפדפן
בטבלה הבאה מוצג סיכום של התמיכה בדפדפן עבור Reporting API v1, כלומר עם הכותרת Reporting-Endpoints
. התמיכה של הדפדפן ב-Reporting API v0 (הכותרת Report-To
) זהה, מלבד סוג דוח אחד: ב-Reporting API החדש אין תמיכה ב-Network Error Logging.
פרטים נוספים זמינים במדריך להעברת נתונים.
סוג הדוח | 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, והיא יכולה לקבל ולהציג דוחות.
עוברים אל אוסף הדוחות הרגילים.
לוחצים על רמיקס לעריכה כדי שיהיה אפשר לערוך את הפרויקט.
עכשיו יש לך שכפול! אתם יכולים להתאים אותו אישית לצורכיכם.
אם אתם לא משתמשים בתבנית סטנדרטית ואתם בונים שרת משלכם:
- מחפשים בקשות
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) בשם default
.
אם בכותרת Reporting-Endpoints
לא מוגדרת נקודת קצה (endpoint) של default
, דוחות מהסוג הזה לא יישלחו (אבל הם ייווצרו).
ערכים (כתובות אתרים)
כל ערך הוא כתובת 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-Endpoints
מוגדרת, צריך להוסיף הוראה report-to
לכל כותרת מדיניות שעבורה רוצים לקבל דוחות על הפרות. הערך של report-to
צריך להיות אחת מנקודות הקצה בעלות השם שהגדרתם.
אפשר להשתמש במספר נקודות קצה בכמה כללי מדיניות, או להשתמש בנקודות קצה שונות בכמה כללי מדיניות.
אין צורך ב-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
קוד לדוגמה
כדי לראות את כל זה בהקשר, הנה דוגמה לשרת צמתים שמשתמש ב-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. בקטע 'ניסויים' לוחצים על הפעלת החלונית של Reporting API בחלונית האפליקציות.
- טעינה מחדש של כלי הפיתוח.
- צריך לטעון מחדש את הדף. דוחות שנוצרו על ידי הדף שבו פתוח כלי הפיתוח יופיעו בחלונית Application ב-Chrome DevTools, בקטע Reporting API.
![צילום מסך של כלי הפיתוח שבהם מופיעים הדוחות](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/screenshot-devtools-list-adb1aaa437b6b.png?authuser=5&hl=he)
סטטוס דוח
בעמודה סטטוס אפשר לראות אם הדוח נשלח בהצלחה.
סטטוס | תיאור |
---|---|
Success |
הדפדפן שלח את הדוח ונקודת הקצה השיבה עם קוד הצלחה (200 או קוד אחר לתגובת הצלחה 2xx ). |
Pending |
הדפדפן מנסה לשלוח את הדוח כרגע. |
Queued |
הדוח נוצר והדפדפן לא מנסה לשלוח אותו כרגע. הדוח מופיע בתור Queued באחד משני המקרים הבאים:
|
MarkedForRemoval |
לאחר ניסיון חוזר למשך זמן מה (Queued ), הדפדפן הפסיק לשלוח את הדוח ובקרוב הוא יסיר אותו מרשימת הדוחות לשליחה. |
דוחות מוסרים לאחר זמן מה, גם אם הם נשלחו בהצלחה וגם אם לא.
פתרון בעיות
האם הדוחות לא נוצרים או לא נשלחים כמצופה לנקודת הקצה? ריכזנו כאן כמה טיפים כדי לפתור את הבעיה.
לא נוצרים דוחות
הדוחות שמופיעים בכלי הפיתוח נוצרו כראוי. אם הדוח שציפית לראות לא מופיע ברשימה הזו:
- יש לבדוק את
report-to
במדיניות. אם המדיניות הזו מוגדרת באופן שגוי, לא יווצר דוח. כדי לפתור את הבעיה, עברו לקטע עריכת המדיניות. דרך נוספת לפתור את הבעיה היא לבדוק את מסוף כלי הפיתוח ב-Chrome: אם מופיעה במסוף שגיאה לגבי ההפרה הרצויה, זה אומר שסביר להניח שהמדיניות מוגדרת בצורה תקינה. - חשוב לזכור שרק הדוחות שנוצרו עבור המסמך שבו פותחים את כלי הפיתוח יופיעו ברשימה הזו. דוגמה אחת: אם באתר
site1.example
מוטמע iframesite2.example
שמפר מדיניות ולכן הדוח יוצר דוח, הדוח יופיע בכלי הפיתוח רק אם פותחים את ה-iframe בחלון משלו ופותחים את כלי הפיתוח בחלון הזה.
דוחות נוצרים אבל לא נשלחים או לא מתקבלים
מה קורה אם אפשר לראות דוח בכלי הפיתוח, אבל נקודת הקצה (endpoint) לא מקבלת אותו?
- הקפידו להשתמש בעיכובים קצרים. יכול להיות שהסיבה שלא רואים את הדוח היא שהוא עדיין לא נשלח.
צריך לבדוק את ההגדרה של הכותרת
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
.
נקודת הקצה
default
חסרה. סוגי דוחות מסוימים, כמו דוחות על הוצאה משימוש ודוחות התערבות, יישלחו רק לנקודת הקצה בשםdefault
. מידע נוסף זמין במאמר הגדרת הכותרת Reporting-Endpoints.צריך לחפש בעיות בתחביר של כותרות המדיניות, למשל מירכאות חסרות. לפרטים.
בודקים שנקודת הקצה (endpoint) יכולה לטפל בבקשות נכנסות.
צריך לוודא שנקודת הקצה תומכת בבקשות קדם-הפעלה של 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
לא אוכפות את המדיניות: שום דבר לא יושבר ולא ייחסם בפועל, אבל תקבלו דוחות על מה שהיה פגום או נחסם.
ReportingObserver
JavaScript API של ReportingObserver
יכול לעזור לכם לזהות אזהרות בצד הלקוח.
ReportingObserver
והכותרת Reporting-Endpoints
יוצרות דוחות שנראים אותו דבר, אבל הם מאפשרים שימושים מעטים שונים בתרחישים שונים.
שימוש ב-ReportingObserver
מתאים לכם אם:
- אתם רוצים לעקוב רק אחרי הוצאה משימוש ו/או התערבות של דפדפנים.
ב-
ReportingObserver
מוצגות אזהרות בצד הלקוח כמו הוצאה משימוש והתערבות בדפדפן, אבל בניגוד ל-Reporting-Endpoints
, הוא לא מתעד סוגים אחרים של דוחות, כמו הפרות של CSP או של COOP/COEP. - יש להגיב להפרות האלה בזמן אמת. אפשר להשתמש ב-
ReportingObserver
כדי לצרף קריאה חוזרת לאירוע של הפרה. - אתם רוצים לצרף לדוח מידע נוסף כדי לסייע בניפוי באגים, באמצעות קריאה חוזרת (callback) בהתאמה אישית.
הבדל נוסף הוא ש-ReportingObserver
מוגדר רק בצד הלקוח: אפשר להשתמש בו גם אם אין לכם שליטה על הכותרות בצד השרת ולא תוכלו להגדיר Reporting-Endpoints
.
קריאה נוספת
- מדריך להעברת הנתונים (מיגרציה) מ-Reporting API v0 לגרסה 1
- ReportingObserver
- מפרט: מדור קודם של Reporting API (גרסה 0)
- מפרט: גרסה חדשה של Reporting API (גרסה 1)
תמונה ראשית (Hero) מאת Nine Koepfer / @enka80 ב-UnFlood, נערכה. תודה רבה לאיאן קללנד, אייג'י קיטמורה ומיליקה מיהג'ליג'ה על הביקורות וההצעות שלהם לגבי המאמר הזה.