หน้านี้ได้รับการแปลโดย Cloud Translation API

ตรวจสอบเว็บแอปพลิเคชันด้วย Reporting API

ใช้ Reporting API เพื่อตรวจสอบการละเมิดด้านความปลอดภัย การเรียก API ที่เลิกใช้งานแล้ว และอื่นๆ

Maud Nalpas

ข้อควรระวัง

นี่คือคำแนะนำเกี่ยวกับ API ที่มีตัวอย่างการใช้งานโดยละเอียดสำหรับ Reporting API (v1) ซึ่งใช้ส่วนหัว Reporting-Endpoints

หากใช้ Reporting API เดิม (ส่วนหัว Report-To) โปรดอ่านเกี่ยวกับการย้ายข้อมูล API แทน

คุณกำลังมองหาเอกสารการบันทึกข้อผิดพลาดของเครือข่ายอยู่ใช่ไหม โปรดไปที่การบันทึกข้อผิดพลาดเกี่ยวกับเครือข่ายแทน

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

แพลตฟอร์มนี้ช่วยให้คุณประกาศสิ่งที่ต้องการตรวจสอบผ่านส่วนหัว HTTP และดำเนินการโดยเบราว์เซอร์ได้

การตั้งค่า Reporting API ช่วยให้คุณมั่นใจว่าเมื่อผู้ใช้พบข้อผิดพลาดประเภทเหล่านี้ คุณจะทราบและสามารถแก้ไขได้

โพสต์นี้อธิบายสิ่งที่ API นี้ทำได้และวิธีใช้ ก็เริ่มเลย

การสาธิตและโค้ด

ดูการทํางานของ Reporting API ตั้งแต่ Chrome 96 ขึ้นไป (Chrome เบต้าหรือ Canary ในเดือนตุลาคม 2021)

ลองใช้:

ปลายทางการรายงานสาธิต หน้านี้จะรับและแสดงรายงาน ตรวจสอบโค้ด
การสร้างรายงานสาธิต หน้านี้ใช้ Reporting API ใหม่ที่มีส่วนหัว Reporting-Endpoints นอกจากนี้ยังจงใจละเมิดนโยบายของตนเอง ใช้ API ที่เลิกใช้งานแล้ว และทำสิ่งเลวร้ายอื่นๆ เพื่อสร้างรายงานอีกด้วย Reporting-Endpoints ในหน้านี้ได้รับการตั้งค่าให้ส่งรายงานไปยังปลายทางการรายงานการสาธิตที่กล่าวถึงข้างต้น ตรวจสอบโค้ด

ภาพรวม

แผนภาพสรุปขั้นตอนด้านล่าง ตั้งแต่การสร้างรายงานไปจนถึงการเข้าถึงรายงานโดยนักพัฒนาซอฟต์แวร์ — วิธีสร้างและส่งรายงาน

สมมติว่าเว็บไซต์ 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 ตั้งค่าไว้ — หากมีการตั้งค่าส่วนหัว 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 ใหม่เท่านั้น โปรดอ่านเคล็ดลับการย้ายข้อมูลการรายงาน 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 ระบบจะไม่ส่งรายงานประเภทนี้ (แม้ว่าระบบจะสร้างขึ้นก็ตาม)

ประเด็นหลัก: แม้ว่าจะชื่อ default แต่ไม่ใช่ปลายทางสำรอง ตัวอย่างเช่น หากคุณตั้งค่า report-to my-endpoint สำหรับ Document-Policy และไม่ได้กำหนด my-endpoint ใน Reporting-Endpoints ระบบจะสร้างรายงานการละเมิด Document-Policy รายการ แต่จะไม่ส่งเนื่องจากเบราว์เซอร์ไม่รู้ว่าจะส่งรายงานดังกล่าวไปที่ใด

ค่า (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 API เดิม (ส่วนหัว Report-To) ที่คุณสามารถตั้งค่าปลายทาง "บรรยากาศ" สำหรับ 1 หน้า และรับรายงานโดยอัตโนมัติสำหรับหน้าเว็บต่างๆ ในต้นทางเดียวกัน หากคุณจะย้ายข้อมูลจาก Reporting API เดิมไปยัง Reporting API ใหม่ ให้ดูคำแนะนำในการย้ายข้อมูล

แก้ไขนโยบาย

เมื่อกำหนดค่าส่วนหัว 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

คำเตือน: การใช้ไวยากรณ์ report-to อย่างถูกต้องอาจเป็นเรื่องยาก เนื่องจากบางนโยบายใช้โครงสร้างส่วนหัวเดียวกัน ไวยากรณ์ที่ถูกต้องอาจเป็น report-to=main-endpoint หรือ report-to main-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

ภาพหน้าจอของเครื่องมือสำหรับนักพัฒนาเว็บที่แสดงรายงาน — Chrome DevTools จะแสดงรายงานที่สร้างขึ้นในหน้าเว็บและสถานะของรายงาน

สถานะรายงาน

คอลัมน์สถานะจะบอกคุณว่าส่งรายงานสำเร็จหรือไม่

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

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

ประเด็นหลัก: สถานะ Queued อาจไม่เป็นประโยชน์เสมอไป เนื่องจากไม่ได้ระบุอย่างเจาะจงว่าการส่งล้มเหลวหรือยังไม่ได้พยายาม การใช้ความล่าช้าในการรายงานที่สั้นสามารถช่วยได้: รายงานที่มีระยะเวลา Queued ในกรณีนั้นมีแนวโน้มบ่งชี้ว่าการส่งล้มเหลว

การแก้ปัญหา

ระบบสร้างรายงานหรือไม่ส่งไปยังปลายทางของคุณตามที่คาดไว้ไหม เคล็ดลับ 2-3 ข้อในการแก้ปัญหานี้มีดังนี้

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

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

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

สร้างรายงานแต่ไม่ได้รับหรือไม่ได้รับ

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

ประเด็นสำคัญ: เนื่องจากเบราว์เซอร์เป็นผู้ส่งรายงานนอกขอบเขต ไม่ใช่บางเว็บไซต์ คำขอ POST ที่มีรายงานจึงไม่แสดงในแผงเครือข่ายของเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์

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

หมายเหตุ: หากคุณใช้ส่วนหัว -Report-Only และได้กำหนดค่าปลายทางการรายงานผ่านส่วนหัวเดิม Report-To ให้ย้ายข้อมูลไปยัง Reporting-Endpoints หากทำได้ อ่านเพิ่มเติมในคำแนะนำในการย้ายข้อมูล

`ReportingObserver`

JavaScript API ของ ReportingObserver ช่วยให้คุณเห็นคำเตือนฝั่งไคลเอ็นต์ได้

ReportingObserver และส่วนหัว Reporting-Endpoints จะสร้างรายงานที่ดูเหมือนกัน แต่เปิดใช้กรณีการใช้งานที่แตกต่างกันเล็กน้อย

ใช้ ReportingObserver ในกรณีต่อไปนี้

คุณต้องการตรวจสอบเฉพาะการเลิกใช้งานและ/หรือการแทรกแซงของเบราว์เซอร์ ReportingObserver แสดงคำเตือนฝั่งไคลเอ็นต์ เช่น การเลิกใช้งานและการแทรกแซงเบราว์เซอร์ แต่ต่างจาก Reporting-Endpoints ตรงที่ไม่ได้สร้างรายงานประเภทอื่นๆ เช่น การละเมิด CSP หรือ COOP/COEP
คุณต้องจัดการกับการละเมิดเหล่านี้แบบเรียลไทม์ ReportingObserver ช่วยให้แนบการเรียกกลับกับเหตุการณ์การละเมิดได้
คุณต้องการแนบข้อมูลเพิ่มเติมไปกับรายงานเพื่อช่วยในการแก้ไขข้อบกพร่องผ่านการเรียกกลับที่กำหนดเอง

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

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

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

ตรวจสอบเว็บแอปพลิเคชันด้วย Reporting API

การสาธิตและโค้ด

ภาพรวม

กรณีการใช้งานและประเภทรายงาน

รายงาน

รายงานมีลักษณะอย่างไร

รายงานเข้าสู่ระบบ

เบราว์เซอร์จะส่งรายงานเมื่อใดและอย่างไร

ปัญหาบุคคลที่สามและบุคคลที่หนึ่ง

ตัวอย่างที่มีการเลิกใช้งาน

การสนับสนุนเบราว์เซอร์

การใช้ Reporting API

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

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

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

ตัวเลือกที่ 3: รวมตัวเลือก 1 และ 2

กำหนดค่าส่วนหัว Reporting-Endpoints

คีย์ (ชื่อปลายทาง)

ค่า (URL)

ตัวอย่าง

จะตั้งค่าส่วนหัวไว้ที่ใด

แก้ไขนโยบาย

ตัวอย่าง

โค้ดตัวอย่าง

แก้ไขข้อบกพร่องการตั้งค่าการรายงาน

สร้างรายงานโดยตั้งใจ

ประหยัดเวลา

ใช้เครื่องมือสำหรับนักพัฒนาเว็บ

สถานะรายงาน

การแก้ปัญหา

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

สร้างรายงานแต่ไม่ได้รับหรือไม่ได้รับ

กลไกการรายงานที่เกี่ยวข้อง

รายงานเท่านั้น

ReportingObserver

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

กำหนดค่าส่วนหัว `Reporting-Endpoints`

`ReportingObserver`