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