ใช้ Reporting API เพื่อตรวจสอบการละเมิดความปลอดภัย การเรียก API ที่เลิกใช้งาน และอื่นๆ
ข้อผิดพลาดบางอย่างจะเกิดขึ้นในเวอร์ชันที่ใช้งานจริงเท่านั้น คุณจะไม่เห็นข้อบกพร่องเหล่านี้ในเครื่องหรือระหว่างการพัฒนา เนื่องจากผู้ใช้จริง เครือข่ายจริง และอุปกรณ์จริงจะเปลี่ยนแปลงสถานการณ์ 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, รายงานการละเมิดนโยบายเอกสาร และรายงานการเลิกใช้งานที่บันทึกปัญหาเหล่านี้
จากนั้นเบราว์เซอร์จะส่งรายงานไปยังปลายทางที่กำหนดค่าไว้สําหรับการละเมิดประเภทนี้โดยมีความล่าช้าสั้นๆ ไม่เกิน 1 นาที รายงานจะส่งนอกแบนด์โดยเบราว์เซอร์เอง (ไม่ใช่จากเซิร์ฟเวอร์หรือเว็บไซต์ของคุณ)
ปลายทางจะรับรายงานเหล่านี้
ตอนนี้คุณเข้าถึงรายงานเกี่ยวกับอุปกรณ์ปลายทางเหล่านี้และตรวจสอบสิ่งที่ผิดพลาดได้แล้ว คุณพร้อมเริ่มแก้ปัญหาที่ส่งผลกระทบต่อผู้ใช้แล้ว
รายงานตัวอย่าง
{
"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 ที่เลิกใช้งานแล้วหรือกำลังจะเลิกใช้งาน โดยเรียกใช้ API ดังกล่าวโดยตรงหรือผ่านสคริปต์ของบุคคลที่สามระดับบนสุด |
การแทรกแซง | หน้าเว็บพยายามทําสิ่งที่เบราว์เซอร์ตัดสินใจไม่ดำเนินการด้วยเหตุผลด้านความปลอดภัย ประสิทธิภาพ หรือประสบการณ์ของผู้ใช้ ตัวอย่างใน Chrome: หน้าเว็บใช้ document.write ในเครือข่ายที่ช้า หรือเรียกใช้ navigator.vibrate ในเฟรมข้ามแหล่งที่มาที่ผู้ใช้ยังไม่ได้โต้ตอบ |
รถชน | เบราว์เซอร์ขัดข้องขณะที่เว็บไซต์เปิดอยู่ |
รายงาน
รายงานมีลักษณะอย่างไร
เบราว์เซอร์จะส่งรายงานไปยังปลายทางที่คุณกําหนดค่าไว้ โดยจะส่งคำขอที่มีลักษณะต่อไปนี้
POST
Content-Type: application/reports+json
เพย์โหลดของคําขอเหล่านี้คือรายการรายงาน
ตัวอย่างรายการรายงาน
[
{
"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 ของคําขอที่สร้างรายงาน |
รายงานที่มีข้อมูลเข้าสู่ระบบ
ปลายทางการรายงานที่มีต้นทางเดียวกันกับหน้าเว็บที่สร้างรายงานจะได้รับข้อมูลเข้าสู่ระบบ (คุกกี้) ในคำขอที่มีรายงาน
ข้อมูลเข้าสู่ระบบอาจให้บริบทเพิ่มเติมที่เป็นประโยชน์เกี่ยวกับรายงาน เช่น บัญชีของผู้ใช้รายหนึ่งทริกเกอร์ข้อผิดพลาดอย่างต่อเนื่องหรือไม่ หรือการดำเนินการตามลําดับบางอย่างในหน้าอื่นๆ ทริกเกอร์รายงานในหน้านี้หรือไม่
เบราว์เซอร์จะส่งรายงานเมื่อใดและอย่างไร
รายงานจะส่งผ่านช่องทางอื่นจากเว็บไซต์ของคุณ: เบราว์เซอร์จะควบคุมเวลาการส่งรายงานไปยังอุปกรณ์ปลายทางที่กําหนดค่าไว้ นอกจากนี้ คุณยังควบคุมเวลาที่เบราว์เซอร์ส่งรายงานไม่ได้ เนื่องจากเบราว์เซอร์จะบันทึก จัดคิว และส่งรายงานโดยอัตโนมัติในเวลาที่เหมาะสม
ซึ่งหมายความว่าข้อกังวลด้านประสิทธิภาพแทบจะไม่มีเลยเมื่อใช้ Reporting API
ระบบจะส่งรายงานโดยมีความล่าช้าสูงสุด 1 นาที เพื่อเพิ่มโอกาสในการส่งรายงานเป็นกลุ่ม วิธีนี้จะช่วยประหยัดแบนด์วิดท์เพื่อไม่ให้รบกวนการเชื่อมต่อเครือข่ายของผู้ใช้ ซึ่งสำคัญอย่างยิ่งบนอุปกรณ์เคลื่อนที่ นอกจากนี้ เบราว์เซอร์ยังอาจเลื่อนเวลาการแสดงผลหากกำลังประมวลผลงานที่มีความสำคัญมากกว่า หรือหากผู้ใช้ใช้เครือข่ายที่ช้าและ/หรือแออัดอยู่ในขณะนั้น
ปัญหาของบุคคลที่สามและบุคคลที่หนึ่ง
ระบบจะส่งรายงานที่สร้างขึ้นเนื่องจากการละเมิดหรือการเลิกใช้งานในหน้าเว็บของคุณไปยังปลายทางที่คุณกำหนดค่าไว้ ซึ่งรวมถึงการละเมิดที่เกิดจากสคริปต์ของบุคคลที่สามที่ทำงานอยู่ในหน้าเว็บของคุณ
การละเมิดหรือการเลิกใช้งานที่เกิดขึ้นใน 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
แบบใหม่เท่านั้น อ่านเคล็ดลับการย้ายข้อมูลการรายงาน CSP หากต้องการย้ายข้อมูลไปยัง Reporting-Endpoints
การใช้ Reporting API
เลือกปลายทางที่จะส่งรายงาน
คุณมี 2 ตัวเลือกต่อไปนี้
- ส่งรายงานไปยังบริการเครื่องมือรวบรวมรายงานที่มีอยู่
- ส่งรายงานไปยังเครื่องมือรวบรวมข้อมูลการรายงานที่คุณสร้างและดําเนินการเอง
ตัวเลือกที่ 1: ใช้บริการรวบรวมรายงานที่มีอยู่
ตัวอย่างบริการเครื่องมือรวบรวมรายงาน ได้แก่
หากทราบวิธีแก้ปัญหาอื่นๆ โปรดเปิดปัญหาเพื่อแจ้งให้เราทราบ แล้วเราจะอัปเดตโพสต์นี้
นอกเหนือจากการกำหนดราคา ให้พิจารณาสิ่งต่อไปนี้เมื่อเลือกเครื่องมือรวบรวมรายงาน 🧐
- เครื่องมือรวบรวมนี้รองรับรายงานทุกประเภทไหม ตัวอย่างเช่น โซลูชันปลายทางการรายงานบางรายการไม่รองรับรายงาน COOP/COEP
- คุณสะดวกใจที่จะแชร์ URL ของแอปพลิเคชันกับเครื่องมือรวบรวมรายงานของบุคคลที่สามไหม แม้ว่าเบราว์เซอร์จะนําข้อมูลที่ละเอียดอ่อนออกจาก URL เหล่านี้ แต่ข้อมูลที่ละเอียดอ่อนก็อาจรั่วไหลด้วยวิธีนี้ หากวิธีนี้เสี่ยงเกินไปสำหรับแอปพลิเคชันของคุณ ให้กำหนดปลายทางการรายงานของคุณเอง
ตัวเลือกที่ 2: สร้างและดําเนินการเครื่องมือรวบรวมรายงานของคุณเอง
การสร้างเซิร์ฟเวอร์ของคุณเองซึ่งจะรับรายงานนั้นไม่ใช่เรื่องง่าย หากต้องการเริ่มต้นใช้งาน ให้ฟอร์กไฟล์เริ่มต้นแบบเบาของเรา ซึ่งสร้างขึ้นด้วย Express และสามารถรับและแสดงรายงานได้
คลิกรีมิกซ์เพื่อแก้ไขเพื่อให้โปรเจ็กต์แก้ไขได้
ตอนนี้คุณมีโคลนของคุณแล้ว! คุณปรับแต่งเพื่อวัตถุประสงค์ของคุณเองได้
หากคุณไม่ได้ใช้ 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
ค่าต้องเป็นคู่คีย์-ค่า 1 รายการหรือชุดที่คั่นด้วยคอมมา ดังนี้
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
หากคุณกําลังย้ายข้อมูลจาก Reporting API เดิมไปยัง Reporting API ใหม่ คุณอาจต้องตั้งค่า Reporting-Endpoints
และ Report-To
ทั้ง 2 รายการ ดูรายละเอียดได้ในคำแนะนำในการย้ายข้อมูล โดยเฉพาะอย่างยิ่ง หากคุณใช้การรายงานการละเมิด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
ระบบจะไม่ส่งรายงานประเภทนี้ (แต่จะได้รับการสร้างขึ้น)
ค่า (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-Endpoints
แล้ว ให้เพิ่มคําสั่ง 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 คุณอาจต้องจงใจละเมิดนโยบายเพื่อตรวจสอบว่าระบบสร้างและส่งรายงานตามที่คาดไว้หรือไม่ หากต้องการดูตัวอย่างโค้ดที่ละเมิดนโยบายและทำสิ่งอื่นๆ ที่ไม่ดีซึ่งจะสร้างรายงานทุกประเภท ให้ดูเดโม
ประหยัดเวลา
ระบบอาจส่งรายงานล่าช้าประมาณ 1 นาที ซึ่งถือว่านานเมื่อแก้ไขข้อบกพร่อง 😴 แต่โชคดีที่เมื่อแก้ไขข้อบกพร่องใน Chrome คุณสามารถใช้ Flag
--short-reporting-delay
เพื่อรับรายงานทันทีที่สร้างขึ้น
เรียกใช้คําสั่งนี้ในเทอร์มินัลเพื่อเปิดใช้ Flag นี้
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 ในแผงแอปพลิเคชัน
- โหลดเครื่องมือสำหรับนักพัฒนาเว็บซ้ำ
- โหลดหน้าเว็บซ้ำ รายงานที่สร้างขึ้นจากหน้าเว็บที่เครื่องมือสำหรับนักพัฒนาเว็บเปิดอยู่จะแสดงในแผงแอปพลิเคชันของเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome ในส่วน Reporting API
รายงานสถานะ
คอลัมน์สถานะจะแจ้งให้ทราบว่ารายงานส่งสำเร็จหรือไม่
สถานะ | คำอธิบาย |
---|---|
Success |
เบราว์เซอร์ส่งรายงานและปลายทางตอบกลับพร้อมรหัสสำเร็จ (200 หรือรหัสตอบกลับความสำเร็จอื่น 2xx ) |
Pending |
เบราว์เซอร์กำลังพยายามส่งรายงานอยู่ในขณะนี้ |
Queued |
สร้างรายงานแล้วและเบราว์เซอร์ไม่ได้พยายามส่งรายงานอยู่ในขณะนี้ รายงานจะปรากฏเป็น Queued ในกรณีใดกรณีหนึ่งต่อไปนี้
|
MarkedForRemoval |
หลังจากพยายามส่งอีกครั้งเป็นเวลานาน (Queued ) เบราว์เซอร์ได้หยุดพยายามส่งรายงานและจะนํารายงานออกจากรายการรายงานที่จะส่งในไม่ช้า |
ระบบจะนำรายงานออกหลังจากผ่านไประยะหนึ่ง ไม่ว่าจะส่งรายงานสำเร็จหรือไม่ก็ตาม
การแก้ปัญหา
ระบบไม่สร้างหรือส่งรายงานไปยังอุปกรณ์ปลายทางตามที่คาดไว้ใช่ไหม เคล็ดลับในการแก้ปัญหามีดังนี้
ระบบไม่สร้างรายงาน
รายงานที่แสดงในเครื่องมือสําหรับนักพัฒนาเว็บสร้างขึ้นอย่างถูกต้อง หากรายงานที่คุณต้องการไม่ปรากฏในรายการนี้ ให้ทำดังนี้
- ตรวจสอบ
report-to
ในนโยบาย หากกําหนดค่าไม่ถูกต้อง ระบบจะไม่สร้างรายงาน โปรดไปที่แก้ไขนโยบายเพื่อแก้ไขปัญหานี้ อีกวิธีในการแก้ปัญหานี้คือการตรวจสอบคอนโซลเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome หากข้อผิดพลาดปรากฏขึ้นในคอนโซลสำหรับการละเมิดที่คุณคาดไว้ แสดงว่านโยบายอาจได้รับการกําหนดค่าอย่างถูกต้อง - โปรดทราบว่าเฉพาะรายงานที่สร้างสําหรับเอกสารที่เครื่องมือสํารวจเว็บเปิดอยู่เท่านั้นที่จะปรากฏในรายการนี้ ตัวอย่างเช่น หากเว็บไซต์
site1.example
ฝัง iframesite2.example
ซึ่งละเมิดนโยบายและสร้างรายงาน รายงานนี้จะปรากฏในเครื่องมือสำหรับนักพัฒนาเว็บก็ต่อเมื่อคุณเปิด iframe ในหน้าต่างของตนเองและเปิด DevTools สำหรับหน้าต่างนั้น
ระบบสร้างรายงานแล้วแต่ไม่ได้รับหรือไม่ได้ส่ง
จะเกิดอะไรขึ้นหากคุณเห็นรายงานในเครื่องมือสําหรับนักพัฒนาซอฟต์แวร์ แต่ปลายทางไม่ได้รับการรายงาน
- อย่าลืมใช้การหน่วงเวลาสั้นๆ สาเหตุที่คุณไม่เห็นรายงานอาจเป็นเพราะยังไม่มีการส่งรายงาน
ตรวจสอบการกำหนดค่าส่วนหัว
Reporting-Endpoints
หากมีปัญหา ระบบจะไม่ส่งรายงานที่สร้างขึ้นอย่างถูกต้อง ในกรณีนี้ สถานะของรายงานในเครื่องมือสำหรับนักพัฒนาเว็บจะยังคงเป็นQueued
(อาจเปลี่ยนเป็นPending
แล้วกลับไปเป็นQueued
อย่างรวดเร็วเมื่อมีการพยายามนำส่ง) ข้อผิดพลาดที่พบบ่อยซึ่งอาจทำให้เกิดปัญหานี้มีการใช้ปลายทางแต่ไม่ได้กำหนดค่า ตัวอย่าง
Document-Policy: document-write=?0;report-to=endpoint-1;
Reporting-Endpoints: default="https://reports.example/default"
ไม่มีปลายทาง
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
ได้ด้วย
นอกจากนี้ ผู้ดูแลระบบยังจะได้รับรายงานเมื่อมีการละเมิดนโยบายเหล่านี้ด้วย
แม้ว่าจะส่งรายงานทั้ง 2 กรณี แต่ส่วนหัวของ -Report-Only
จะไม่บังคับใช้นโยบาย กล่าวคือ ไม่มีอะไรเสียหายหรือถูกบล็อก แต่คุณจะได้รับรายงานว่าสิ่งที่จะเสียหายหรือถูกบล็อก
ReportingObserver
ReportingObserver
JavaScript API ช่วยให้คุณสังเกตเห็นคำเตือนฝั่งไคลเอ็นต์ได้
ส่วนส่วนหัว ReportingObserver
และ Reporting-Endpoints
จะสร้างรายงานที่ดูเหมือนกัน แต่มีกรณีการใช้งานที่แตกต่างกันเล็กน้อย
ใช้ ReportingObserver
ในกรณีต่อไปนี้
- คุณต้องการติดตามการเลิกใช้งานและ/หรือการแทรกแซงเบราว์เซอร์เท่านั้น
ReportingObserver
แสดงคำเตือนฝั่งไคลเอ็นต์ เช่น การเลิกใช้งานและการแทรกแซงเบราว์เซอร์ แต่จะไม่แสดงรายงานประเภทอื่นๆ เช่น การละเมิด CSP หรือ COOP/COEP ซึ่งต่างจากReporting-Endpoints
- คุณต้องดำเนินการกับกรณีการละเมิดเหล่านี้แบบเรียลไทม์
ReportingObserver
ช่วยให้คุณแนบการเรียกกลับกับเหตุการณ์การละเมิดได้ - คุณต้องการแนบข้อมูลเพิ่มเติมในรายงานเพื่อช่วยในการแก้ไขข้อบกพร่องผ่านการเรียกกลับที่กําหนดเอง
อีกความแตกต่างหนึ่งคือ ReportingObserver
จะกําหนดค่าได้เฉพาะฝั่งไคลเอ็นต์เท่านั้น คุณจึงใช้ ReportingObserver
ได้แม้ว่าจะควบคุมส่วนหัวฝั่งเซิร์ฟเวอร์ไม่ได้และตั้งค่า Reporting-Endpoints
ไม่ได้
อ่านเพิ่มเติม
- คู่มือการย้ายข้อมูลจาก Reporting API v0 ไปยัง v1
- ReportingObserver
- ข้อกําหนด: Reporting API เดิม (v0)
- ข้อกําหนด: Reporting API เวอร์ชันใหม่ (v1)
รูปภาพหลักโดย Nine Koepfer / @enka80 จาก Unsplash ผ่านการแก้ไข ขอขอบคุณ Ian Clelland, Eiji Kitamura และ Milica Mihajlija สำหรับรีวิวและคำแนะนำในบทความนี้