ตรวจสอบเว็บแอปพลิเคชันด้วย 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 ของคุณมีนโยบายรักษาความปลอดภัยเนื้อหาและนโยบายเอกสาร หากไม่ทราบว่าสิ่งนี้ใช้ทำอะไร ไม่เป็นไร คุณจะยังคง สามารถเข้าใจตัวอย่างนี้ได้

คุณตัดสินใจที่จะตรวจสอบเว็บไซต์ของคุณเพื่อที่จะทราบว่า เมื่อใดที่นโยบายเหล่านี้ละเมิดนโยบาย และเนื่องจาก คุณต้องการติดตาม 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 ตั้งค่าไว้
หากมีการตั้งค่าส่วนหัว 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 แบบใหม่เท่านั้น โปรดอ่านเคล็ดลับการย้ายข้อมูลการรายงาน CSP หากต้องการย้ายข้อมูลไปยัง Reporting-Endpoints

การใช้ Reporting API

ตัดสินใจว่าจะส่งรายงานที่ใด

คุณมี 2 ตัวเลือกต่อไปนี้

  • ส่งรายงานไปยังบริการเครื่องมือรวบรวมรายงานที่มีอยู่
  • ส่งรายงานไปยังผู้รวบรวมการรายงานที่คุณสร้างและดำเนินงานด้วยตนเอง

ตัวเลือกที่ 1: ใช้บริการเครื่องมือรวบรวมรายงานที่มีอยู่

ตัวอย่างบริการเครื่องมือรวบรวมรายงาน ได้แก่

หากคุณมีวิธีแก้ปัญหาอื่นๆ โปรดเปิดปัญหาเพื่อแจ้งให้เราทราบ แล้วเราจะอัปเดตโพสต์นี้!

นอกเหนือจากการกำหนดราคา ให้พิจารณาสิ่งต่อไปนี้เมื่อเลือกเครื่องมือรวบรวมรายงาน 🧐

  • เครื่องมือรวบรวมนี้รองรับรายงานทุกประเภทหรือไม่ เช่น ไม่ใช่โซลูชันปลายทางการรายงานทั้งหมด สนับสนุนรายงาน COOP/COEP
  • คุณสะดวกใจที่จะแชร์ URL ของแอปพลิเคชันกับเครื่องมือรวบรวมรายงานของบุคคลที่สามไหม แม้ว่าเบราว์เซอร์จะนำข้อมูลที่ละเอียดอ่อนออกจาก URL เหล่านี้ แต่ข้อมูลที่ละเอียดอ่อนอาจรั่วไหลในลักษณะนี้ หากฟังดูมีความเสี่ยงเกินไปสำหรับ ทำงานปลายทางการรายงานของคุณเอง

ตัวเลือกที่ 2: สร้างและดําเนินการเครื่องมือรวบรวมรายงานของคุณเอง

การสร้างเซิร์ฟเวอร์ของคุณเองเพื่อรับรายงานนั้นไม่ใช่เรื่องง่าย ในการเริ่มต้น คุณสามารถแยก ต้นแบบที่มีน้ำหนักเบา เป็นการสร้างด้วย Express จึงรับและแสดงรายงานได้

  1. ไปที่เครื่องมือรวบรวมรายงานสำเร็จรูป

  2. คลิกรีมิกซ์เพื่อแก้ไขเพื่อทำให้โปรเจ็กต์แก้ไขได้

  3. ตอนนี้คุณมีโคลนของคุณแล้ว! คุณสามารถปรับแต่งรายงานเพื่อวัตถุประสงค์ของคุณเอง

หากคุณไม่ได้ใช้ 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 ควรเป็นหนึ่งในปลายทางที่มีชื่อซึ่งคุณกำหนดค่าไว้

ไม่จำเป็นต้องใช้ 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 เป็นต้นไป หากต้องการใช้งาน โปรดทำตามขั้นตอนต่อไปนี้

  1. ใช้ Chrome เวอร์ชัน 96 ขึ้นไป (ตรวจสอบโดยพิมพ์ chrome://version ในเบราว์เซอร์)
  2. พิมพ์หรือวาง chrome://flags/#enable-experimental-web-platform-features ในแถบ URL ของ Chrome
  3. คลิกเปิดใช้
  4. รีสตาร์ทเบราว์เซอร์
  5. เปิดเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome
  6. เปิดการตั้งค่าใน Chrome DevTools ใต้การทดสอบ ให้คลิกเปิดใช้แผง Reporting API ใน แผงแอปพลิเคชัน
  7. โหลดเครื่องมือสำหรับนักพัฒนาเว็บซ้ำ
  8. โหลดหน้าเว็บซ้ำ รายงานที่สร้างจากหน้าเว็บที่เปิดเครื่องมือสำหรับนักพัฒนาเว็บจะ แสดงใน Chrome DevTools แผงแอปพลิเคชันภายใต้ Reporting API
ภาพหน้าจอของเครื่องมือสำหรับนักพัฒนาเว็บที่แสดงรายการรายงาน
เครื่องมือสำหรับนักพัฒนาเว็บใน Chrome จะแสดงรายงานที่สร้างขึ้นในหน้าเว็บและสถานะของรายงาน

สถานะรายงาน

คอลัมน์สถานะจะช่วยให้คุณทราบว่าส่งรายงานเรียบร้อยแล้วหรือไม่

สถานะ คำอธิบาย
Success เบราว์เซอร์ส่งรายงานและปลายทางตอบกลับพร้อมรหัสสำเร็จ (200 หรือรหัสตอบกลับความสำเร็จอื่น 2xx)
Pending เบราว์เซอร์กำลังพยายามส่งรายงานอยู่ในขณะนี้
Queued สร้างรายงานแล้วและเบราว์เซอร์ไม่ได้พยายามส่งรายงานอยู่ในขณะนี้ รายงานจะปรากฏเป็น Queued ใน 1 ใน 2 กรณีต่อไปนี้
  • รายงานนี้เป็นรายงานใหม่ และเบราว์เซอร์จะรอดูว่าจะมีรายงานมาเพิ่มหรือไม่ก่อนที่จะพยายามส่ง
  • รายงานนี้ไม่ใช่รายงานใหม่ เบราว์เซอร์ได้พยายามส่งรายงานนี้แล้ว แต่ล้มเหลว และกำลังรอก่อนที่จะลองอีกครั้ง
MarkedForRemoval หลังจากลองอีกครั้งอยู่ระยะหนึ่ง (Queued) เบราว์เซอร์ได้หยุดพยายามส่งรายงานแล้ว และจะนำรายงานออกจากรายการรายงานที่จะส่งในอีกไม่ช้า

ระบบจะนํารายงานออกหลังจากผ่านไประยะหนึ่ง ไม่ว่าจะมีการส่งสําเร็จหรือไม่ก็ตาม

การแก้ปัญหา

ระบบไม่สร้างรายงานหรือไม่ได้ส่งไปยังปลายทางตามที่คาดไว้ ต่อไปนี้เป็นเคล็ดลับบางประการสำหรับการแก้ปัญหานี้

ระบบจะไม่สร้างรายงาน

รายงานที่แสดงในเครื่องมือสำหรับนักพัฒนาเว็บได้รับการสร้างขึ้นอย่างถูกต้อง หากรายงานที่คุณคาดไว้ไม่ปรากฏในรายการนี้ ให้ทำดังนี้

  • โปรดอ่านreport-toในนโยบาย หากมีการกำหนดค่าไม่ถูกต้อง จะไม่มีการสร้างรายงาน โปรดไปที่แก้ไขนโยบายเพื่อ แก้ไขปัญหานี้ อีกวิธีหนึ่งในการแก้ปัญหานี้คือการตรวจสอบคอนโซลเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome หาก ปรากฏขึ้นในคอนโซลสำหรับการละเมิดที่คุณคาดไว้ ซึ่งหมายความว่านโยบายของคุณอาจ กำหนดค่าอย่างถูกต้อง
  • โปรดทราบว่าระบบจะเปิดเฉพาะรายงานที่สร้างขึ้นสำหรับเอกสาร DevTools เท่านั้น แสดงในรายการนี้ ตัวอย่าง: หากเว็บไซต์ site1.example ฝัง iframe site2.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

อ่านเพิ่มเติม

รูปภาพหลักโดย Nine Koepfer / @enka80 ใน แก้ไข Unแยกต่างหาก แล้ว ขอขอบคุณ Ian Clelland, Eiji Kitamura และ Milica Mihajlija สำหรับรีวิวและคำแนะนำในบทความนี้