ใช้ 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=19&hl=th)
สมมติว่าเว็บไซต์ site.example
ของคุณมีนโยบายรักษาความปลอดภัยเนื้อหาและนโยบายเอกสาร หากไม่ทราบว่าสิ่งนี้ใช้ทำอะไร ไม่เป็นไร คุณจะยังคง
สามารถเข้าใจตัวอย่างนี้ได้
คุณตัดสินใจที่จะตรวจสอบเว็บไซต์ของคุณเพื่อที่จะทราบว่า เมื่อใดที่นโยบายเหล่านี้ละเมิดนโยบาย และเนื่องจาก คุณต้องการติดตาม API ที่เลิกใช้งานแล้วหรือ 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"
}
Use Case และประเภทรายงาน
คุณกำหนดค่า 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
เพย์โหลดของคำขอเหล่านี้เป็นรายการของรายงาน
ตัวอย่างรายการของรายงาน
[
{
"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-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=19&hl=th)
การสนับสนุนเบราว์เซอร์
ตารางด้านล่างแสดงการสนับสนุนเบราว์เซอร์สำหรับ 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 รายการหรือ 1 ชุด
คู่คีย์-ค่า:
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
ระบบจะไม่ส่งรายงานประเภทนี้ (แต่จะได้รับการสร้างขึ้น)
ค่า (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 ใหม่ ซึ่งเป็นเวอร์ชันที่ครอบคลุมใน
post - รายงานจะกำหนดขอบเขตไว้เป็นเอกสาร ซึ่งหมายความว่าสำหรับ 1 คนที่
ต้นทาง เอกสารต่างๆ เช่น 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
โค้ดตัวอย่าง
หากต้องการดูทั้งหมดนี้ในบริบท ด้านล่างคือตัวอย่างเซิร์ฟเวอร์โหนดที่ใช้ Express และนำข้อมูลทั้งหมดที่พูดถึงในบทความนี้มารวมไว้ด้วยกัน ซึ่งแสดงวิธีการ กำหนดค่าการรายงานสำหรับรายงานประเภทต่างๆ และแสดงผลลัพธ์
แก้ไขข้อบกพร่องของการตั้งค่าการรายงาน
สร้างรายงานโดยเจตนา
เมื่อตั้งค่า Reporting API แล้ว คุณอาจต้องตั้งใจละเมิด นโยบายของคุณเพื่อดูว่ามีการสร้างและส่งรายงานตามที่คาดไว้หรือไม่ เพื่อดูโค้ดตัวอย่างที่ละเมิดนโยบายและทำสิ่งที่ไม่ดีอื่นๆ ที่จะ สร้างรายงานทุกประเภทได้ในการสาธิต
ประหยัดเวลา
ระบบอาจส่งรายงานล่าช้าประมาณ 1 นาที ซึ่งถือว่านาน
เมื่อแก้ไขข้อบกพร่อง 😊 โชคดีที่เมื่อแก้ไขข้อบกพร่องใน 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 DevTools ใต้การทดสอบ ให้คลิกเปิดใช้แผง Reporting API ใน แผงแอปพลิเคชัน
- โหลดเครื่องมือสำหรับนักพัฒนาเว็บซ้ำ
- โหลดหน้าเว็บซ้ำ รายงานที่สร้างจากหน้าเว็บที่เปิดเครื่องมือสำหรับนักพัฒนาเว็บจะ แสดงใน Chrome DevTools แผงแอปพลิเคชันภายใต้ Reporting API
![ภาพหน้าจอของเครื่องมือสำหรับนักพัฒนาเว็บที่แสดงรายการรายงาน](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/screenshot-devtools-list-adb1aaa437b6b.png?authuser=19&hl=th)
สถานะรายงาน
คอลัมน์สถานะจะช่วยให้คุณทราบว่าส่งรายงานเรียบร้อยแล้วหรือไม่
สถานะ | คำอธิบาย |
---|---|
Success |
เบราว์เซอร์ส่งรายงานและปลายทางตอบกลับพร้อมรหัสสำเร็จ (200 หรือรหัสตอบกลับความสำเร็จอื่น 2xx ) |
Pending |
เบราว์เซอร์กำลังพยายามส่งรายงานอยู่ในขณะนี้ |
Queued |
สร้างรายงานแล้วและเบราว์เซอร์ไม่ได้พยายามส่งรายงานอยู่ในขณะนี้ รายงานจะปรากฏเป็น Queued ใน 1 ใน 2 กรณีต่อไปนี้
|
MarkedForRemoval |
หลังจากลองอีกครั้งอยู่ระยะหนึ่ง (Queued ) เบราว์เซอร์ได้หยุดพยายามส่งรายงานแล้ว และจะนำรายงานออกจากรายการรายงานที่จะส่งในอีกไม่ช้า |
ระบบจะนํารายงานออกหลังจากผ่านไประยะหนึ่ง ไม่ว่าจะมีการส่งสําเร็จหรือไม่ก็ตาม
การแก้ปัญหา
ระบบไม่สร้างรายงานหรือไม่ได้ส่งไปยังปลายทางตามที่คาดไว้ ต่อไปนี้เป็นเคล็ดลับบางประการสำหรับการแก้ปัญหานี้
ระบบจะไม่สร้างรายงาน
รายงานที่แสดงในเครื่องมือสำหรับนักพัฒนาเว็บได้รับการสร้างขึ้นอย่างถูกต้อง หากรายงานที่คุณคาดไว้ไม่ปรากฏในรายการนี้ ให้ทำดังนี้
- โปรดอ่าน
report-to
ในนโยบาย หากมีการกำหนดค่าไม่ถูกต้อง จะไม่มีการสร้างรายงาน โปรดไปที่แก้ไขนโยบายเพื่อ แก้ไขปัญหานี้ อีกวิธีหนึ่งในการแก้ปัญหานี้คือการตรวจสอบคอนโซลเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome หาก ปรากฏขึ้นในคอนโซลสำหรับการละเมิดที่คุณคาดไว้ ซึ่งหมายความว่านโยบายของคุณอาจ กำหนดค่าอย่างถูกต้อง - โปรดทราบว่าระบบจะเปิดเฉพาะรายงานที่สร้างขึ้นสำหรับเอกสาร DevTools เท่านั้น
แสดงในรายการนี้ ตัวอย่าง: หากเว็บไซต์
site1.example
ฝัง iframesite2.example
ที่ละเมิดนโยบายและสร้างรายงาน รายงานนี้จะปรากฏในเครื่องมือสำหรับนักพัฒนาเว็บก็ต่อเมื่อคุณเปิด iframe ในหน้าต่างของตัวมันเองและเปิดเครื่องมือสำหรับนักพัฒนาเว็บสำหรับหน้าต่างนั้น
ระบบสร้างรายงานแต่ไม่ได้รับหรือไม่ได้ส่ง
จะเกิดอะไรขึ้นหากคุณดูรายงานในเครื่องมือสำหรับนักพัฒนาเว็บได้ แต่ปลายทางไม่ได้รับรายงาน
- อย่าลืมใช้ความล่าช้าสั้นๆ สาเหตุที่คุณไม่เห็นรายงานอาจเพราะ ยังไม่มีการส่ง
ตรวจสอบการกำหนดค่าส่วนหัว
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มองหาปัญหาในไวยากรณ์ของส่วนหัวนโยบาย เช่น ไม่มีเครื่องหมายคำพูด ดูรายละเอียด
ตรวจสอบว่าปลายทางจัดการคำขอที่เข้ามาใหม่ได้
ตรวจสอบว่าปลายทางรองรับคำขอการตรวจสอบล่วงหน้าสำหรับ 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
JavaScript API ของ ReportingObserver
ช่วยคุณได้
สังเกตคำเตือนฝั่งไคลเอ็นต์
ReportingObserver
และส่วนหัว Reporting-Endpoints
สร้างรายงานที่
มีลักษณะเหมือนกัน แต่มีกรณีการใช้งานต่างกันเล็กน้อย
ใช้ ReportingObserver
ในกรณีต่อไปนี้
- คุณเพียงต้องการตรวจสอบการเลิกใช้งานและ/หรือการแทรกแซงเบราว์เซอร์เท่านั้น
ReportingObserver
แสดงคำเตือนฝั่งไคลเอ็นต์ เช่น การเลิกใช้งาน และการใช้งานเบราว์เซอร์ แต่ต่างจากReporting-Endpoints
ตรงที่ไม่ได้ บันทึกรายงานประเภทอื่นๆ เช่น การละเมิด CSP หรือ COOP/COEP - คุณต้องดำเนินการกับการละเมิดเหล่านี้แบบเรียลไทม์
ReportingObserver
สร้าง คุณจะแนบ Callback ไปกับเหตุการณ์การละเมิดได้ - คุณต้องการแนบข้อมูลเพิ่มเติมไปกับรายงาน เพื่อช่วยในการแก้ไขข้อบกพร่อง ผ่านการติดต่อกลับที่กำหนดเอง
ข้อแตกต่างอีกประการหนึ่งคือ ReportingObserver
ได้รับการกำหนดค่าจากฝั่งไคลเอ็นต์เท่านั้น
ก็ใช้ได้แม้จะไม่สามารถควบคุมส่วนหัวฝั่งเซิร์ฟเวอร์และไม่สามารถ
ตั้งค่า Reporting-Endpoints
อ่านเพิ่มเติม
- คำแนะนำในการย้ายข้อมูลจาก Reporting API v0 ไปยัง v1
- ReportingObserver
- ข้อมูลจำเพาะ: Reporting API เดิม (v0)
- ข้อมูลจำเพาะ: Reporting API ใหม่ (v1)
รูปภาพหลักโดย Nine Koepfer / @enka80 ใน แก้ไข Unแยกต่างหาก แล้ว ขอขอบคุณ Ian Clelland, Eiji Kitamura และ Milica Mihajlija สำหรับรีวิวและคำแนะนำในบทความนี้