Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

ตรวจสอบเว็บแอปพลิเคชันด้วย 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 นี้ทำได้และวิธีใช้ มาเริ่มกันเลย

ภาพรวม

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

สมมติว่าเว็บไซต์ site.example ของคุณมี Content-Security-Policy และ Document-Policy หากไม่รู้ว่าปุ่มเหล่านี้ใช้ทำอะไร ไม่เป็นไร คุณจะยังเข้าใจตัวอย่างนี้ได้อยู่

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

โดยคุณจะต้องกำหนดค่าส่วนหัว Reporting-Endpoints และแมปชื่อปลายทางเหล่านี้โดยใช้คำสั่ง report-to ในนโยบายตามที่จำเป็น

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint

เกิดเหตุการณ์ที่ไม่คาดคิดขึ้น และผู้ใช้บางรายละเมิดนโยบายเหล่านี้

ตัวอย่างการละเมิด

index.html

<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>

script.js โหลดโดย index.html

// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
  document.write('<h1>hi</h1>');
} catch (e) {
  console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;

เบราว์เซอร์จะสร้างรายงานการละเมิด CSP, รายงานการละเมิด Document-Policy และรายงานการเลิกใช้งานที่บันทึกปัญหาเหล่านี้

จากนั้นเบราว์เซอร์จะส่งรายงานไปยังปลายทางที่กำหนดค่าไว้สำหรับการละเมิดประเภทนี้โดยมีความล่าช้าเล็กน้อย (ไม่เกิน 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 ได้ตั้งค่า Reporting-Endpoints และจะส่งรายงานนี้ไปยังปลายทางใดก็ตามที่เซิร์ฟเวอร์ของ iframe ได้ตั้งค่าไว้ — หากตั้งค่าส่วนหัว Reporting-Endpoints ในหน้าเว็บ ระบบจะรายงานการเรียก API ที่เลิกใช้งานแล้วซึ่งเรียกใช้โดยสคริปต์ของบุคคลที่สามที่ทำงานในหน้าเว็บไปยังปลายทางของคุณ ระบบจะไม่รายงานการเรียก API ที่เลิกใช้งานแล้วซึ่งเรียกโดย iframe ที่ฝังในหน้าเว็บไปยังปลายทางของคุณ ระบบจะสร้างรายงานการเลิกใช้งานก็ต่อเมื่อเซิร์ฟเวอร์ iframe ได้ตั้งค่า Reporting-Endpoints ไว้ และจะส่งรายงานนี้ไปยังปลายทางที่เซิร์ฟเวอร์ของ iframe ตั้งค่าไว้

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

ตารางต่อไปนี้สรุปการรองรับเบราว์เซอร์สำหรับ Reporting API v1 ซึ่งมีส่วนหัว Reporting-Endpoints การรองรับเบราว์เซอร์สำหรับ Reporting API v0 (ส่วนหัว Report-To) จะเหมือนกัน ยกเว้นรายงานประเภทเดียวคือ Network Error Logging ซึ่งไม่รองรับใน 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: สร้างและใช้งานเครื่องมือรวบรวมรายงานของคุณเอง

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

เมื่อสร้างเครื่องมือรวบรวมรายงานของคุณเอง

ตรวจสอบคำขอ POST ที่มี Content-Type of application/reports+json เพื่อจดจำคำขอรายงานที่เบราว์เซอร์ส่ง ไปยังปลายทางของคุณ
หากปลายทางอยู่ในต้นทางที่แตกต่างจากเว็บไซต์ของคุณ ให้ตรวจสอบว่าปลายทางรองรับคำขอ Preflight ของ 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 ซึ่งจะช่วยให้คุณกำหนดเส้นทางรายงานไปยังปลายทางต่างๆ ได้ตามประเภทของรายงาน

หากต้องการรับรายงานการแทรกแซง การเลิกใช้งาน ข้อขัดข้อง หรือทั้ง 3 อย่างรวมกัน ให้ตั้งค่าปลายทางชื่อ default

หากส่วนหัว Reporting-Endpoints ไม่ได้กำหนดปลายทาง default ระบบจะไม่ส่งรายงานประเภทนี้ (แม้ว่าจะมีการสร้างรายงานก็ตาม)

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

ค่า (URL)

ค่าแต่ละค่าคือ URL ที่คุณเลือก ซึ่งเป็นปลายทางที่จะส่งรายงานไปให้ URL ที่จะตั้งค่าที่นี่ขึ้นอยู่กับสิ่งที่คุณตัดสินใจในขั้นตอนที่ 1

URL ปลายทาง

ต้องขึ้นต้นด้วยเครื่องหมายทับ (/) ไม่รองรับ Relative Path
สามารถเป็นแบบข้ามต้นทางได้ แต่ในกรณีนี้ระบบจะไม่ส่งข้อมูลเข้าสู่ระบบไปพร้อมกับรายงาน

ตัวอย่าง

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

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

สร้างรายงานโดยเจตนา

เมื่อตั้งค่า Reporting API คุณอาจต้องจงใจละเมิดนโยบาย เพื่อตรวจสอบว่าระบบสร้างและส่งรายงานตามที่คาดไว้หรือไม่

ประหยัดเวลา

ระบบอาจหน่วงเวลาการส่งรายงานไว้ประมาณ 1 นาที ซึ่งเป็นเวลาที่นานเมื่อแก้ไขข้อบกพร่อง 😴 โชคดีที่เมื่อแก้ไขข้อบกพร่องใน Chrome คุณสามารถใช้แฟล็ก --short-reporting-delay เพื่อรับรายงานทันทีที่สร้างขึ้น

เรียกใช้คำสั่งนี้ในเทอร์มินัลเพื่อเปิดใช้ Flag นี้

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

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

ใน Chrome ให้ใช้เครื่องมือสำหรับนักพัฒนาเว็บเพื่อดูรายงานที่ส่งไปแล้วหรือจะส่ง

ตั้งแต่เดือนตุลาคม 2021 ฟีเจอร์นี้อยู่ในขั้นทดลอง หากต้องการใช้ ให้ทำตามขั้นตอนต่อไปนี้

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

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

สถานะรายงาน

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

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

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

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

การแก้ปัญหา

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

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

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

ตรวจสอบ 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`

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

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

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

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

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

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

ขอขอบคุณ Ian Clelland, Eiji Kitamura และ Milica Mihajlija สำหรับ การตรวจสอบและคำแนะนำเกี่ยวกับเอกสารนี้

ภาพรวม

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

รายงาน

รายงานที่ต้องใช้ข้อมูลเข้าสู่ระบบ

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

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

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

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

การใช้ Reporting API

เลือกปลายทางที่จะส่งรายงาน

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

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

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

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

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

ค่า (URL)

ตัวอย่าง

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

แก้ไขนโยบาย

ตัวอย่าง

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

สร้างรายงานโดยเจตนา

ประหยัดเวลา

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

สถานะรายงาน

การแก้ปัญหา

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

ระบบสร้างรายงานแล้ว แต่ไม่ได้ส่งหรือผู้ใช้ไม่ได้รับ

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

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

ReportingObserver

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

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

`ReportingObserver`