Giám sát ứng dụng web bằng API Báo cáo

Sử dụng API Báo cáo để theo dõi các lỗi vi phạm bảo mật, lệnh gọi API không dùng nữa và nhiều thông tin khác.

Maud Nalpas
Maud Nalpas

Một số lỗi chỉ xảy ra trong môi trường phát hành chính thức. Bạn sẽ không thấy các ứng dụng này trên thiết bị hoặc trong quá trình phát triển vì người dùng thực, mạng thựcthiết bị thực sẽ thay đổi trò chơi. API Báo cáo giúp phát hiện một số lỗi trong số này (chẳng hạn như lỗi vi phạm bảo mật hoặc các lệnh gọi API không dùng nữa và sẽ sớm bị ngừng sử dụng) trên trang web của bạn, đồng thời truyền các lỗi đó đến điểm cuối mà bạn đã chỉ định.

Thẻ này cho phép bạn khai báo những nội dung bạn muốn giám sát qua tiêu đề HTTP và được trình duyệt vận hành.

Việc thiết lập API Báo cáo giúp bạn yên tâm rằng khi người dùng gặp phải các loại lỗi này, bạn sẽ biết để khắc phục.

Bài đăng này trình bày những gì API này có thể làm và cách sử dụng API này. Hãy cùng tìm hiểu kỹ hơn nhé.

Bản minh hoạ và mã

Xem API Báo cáo hoạt động kể từ phiên bản Chrome 96 trở lên (Chrome Beta hoặc Canary, kể từ tháng 10 năm 2021).

Tổng quan

Sơ đồ tóm tắt các bước bên dưới, từ việc tạo báo cáo đến việc nhà phát triển truy cập vào báo cáo
Cách tạo và gửi báo cáo.

Giả sử trang web site.example của bạn có Content-Security-Policy và Document-Policy. Bạn không biết những tính năng này có tác dụng gì? Không sao, bạn vẫn có thể hiểu ví dụ này.

Bạn quyết định theo dõi trang web của mình để biết thời điểm vi phạm các chính sách này, nhưng cũng vì bạn muốn theo dõi các API không dùng nữa hoặc sắp không dùng nữa mà cơ sở mã của bạn có thể đang sử dụng.

Để làm như vậy, bạn định cấu hình tiêu đề Reporting-Endpoints và ánh xạ các tên điểm cuối này thông qua lệnh report-to trong chính sách của mình nếu cần.

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

Một sự cố không lường trước xảy ra và một số người dùng của bạn vi phạm các chính sách này.

Ví dụ về lỗi vi phạm

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, do index.html tải

// 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;

Trình duyệt sẽ tạo một báo cáo vi phạm CSP, một báo cáo vi phạm Chính sách tài liệu và một báo cáo về việc ngừng sử dụng để ghi lại các vấn đề này.

Sau một khoảng thời gian trễ ngắn (tối đa một phút), trình duyệt sẽ gửi báo cáo đến điểm cuối được định cấu hình cho loại lỗi vi phạm này. Các báo cáo được gửi ngoài phạm vi bởi chính trình duyệt (không phải máy chủ hoặc trang web của bạn).

(Các) điểm cuối sẽ nhận được các báo cáo này.

Giờ đây, bạn có thể truy cập vào các báo cáo về các điểm cuối này và theo dõi vấn đề xảy ra. Bạn đã sẵn sàng bắt đầu khắc phục sự cố đang ảnh hưởng đến người dùng.

Báo cáo mẫu

{
 
"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"
}

Trường hợp sử dụng và loại báo cáo

Bạn có thể định cấu hình API Báo cáo để giúp theo dõi nhiều loại cảnh báo hoặc vấn đề thú vị xảy ra trên trang web của mình:

Loại báo cáo Ví dụ về trường hợp báo cáo được tạo
Vi phạm Chính sách bảo mật nội dung (chỉ ở cấp 3) Bạn đã thiết lập Content-Security-Policy (CSP) trên một trong các trang của mình, nhưng trang đó đang cố tải một tập lệnh mà CSP của bạn không cho phép.
Vi phạm COOP Bạn đã đặt Cross-Origin-Opener-Policy trên một trang, nhưng một cửa sổ có nguồn gốc khác đang cố gắng tương tác trực tiếp với tài liệu.
Vi phạm COEP Bạn đã đặt Cross-Origin-Embedder-Policy trên một trang, nhưng tài liệu này chứa iframe trên nhiều nguồn gốc nhưng chưa chọn tải bằng các tài liệu nhiều nguồn gốc.
Vi phạm chính sách của tài liệu Trang có chính sách tài liệu ngăn việc sử dụng document.write, nhưng một tập lệnh lại cố gắng gọi document.write.
Lỗi vi phạm Chính sách về quyền Trang này có chính sách quyền ngăn chặn việc sử dụng micrô và một tập lệnh yêu cầu đầu vào âm thanh.
Cảnh báo về việc ngừng sử dụng Trang đang sử dụng một API không dùng nữa hoặc sẽ không dùng nữa; trang gọi API đó trực tiếp hoặc thông qua một tập lệnh cấp cao nhất của bên thứ ba.
Can thiệp Trang đang cố gắng thực hiện một việc mà trình duyệt quyết định không thực hiện, vì lý do bảo mật, hiệu suất hoặc trải nghiệm người dùng. Ví dụ trong Chrome: trang sử dụng document.write trên mạng chậm hoặc gọi navigator.vibrate trong một khung đa nguồn gốc mà người dùng chưa tương tác.
Sự cố Trình duyệt gặp sự cố khi trang web của bạn đang mở.

Báo cáo

Báo cáo có dạng như thế nào?

Trình duyệt sẽ gửi báo cáo đến điểm cuối mà bạn đã định cấu hình. Phương thức này gửi các yêu cầu có dạng như sau:

POST
Content-Type: application/reports+json

Tải trọng của các yêu cầu này là danh sách báo cáo.

Danh sách báo cáo mẫu

[
 
{
   
"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"
 
}
]

Dưới đây là dữ liệu bạn có thể tìm thấy trong từng báo cáo này:

Trường Mô tả
age Số mili giây giữa dấu thời gian của báo cáo và thời gian hiện tại.
body Dữ liệu báo cáo thực tế, được chuyển đổi tuần tự thành một chuỗi JSON. Các trường có trong body của một báo cáo là do type của báo cáo xác định. ⚠️ Báo cáo thuộc nhiều loại có nội dung khác nhau. Để xem nội dung chính xác của từng loại báo cáo, hãy xem điểm cuối báo cáo minh hoạ và làm theo hướng dẫn để tạo báo cáo mẫu.
type Loại báo cáo, ví dụ: csp-violation hoặc coep.
url Địa chỉ của tài liệu hoặc worker đã tạo báo cáo. Dữ liệu nhạy cảm như tên người dùng, mật khẩu và mảnh sẽ bị xoá khỏi URL này.
user_agent Tiêu đề User-Agent của yêu cầu tạo báo cáo.

Báo cáo có thông tin xác thực

Các điểm cuối báo cáo có nguồn gốc giống với trang tạo báo cáo sẽ nhận được thông tin xác thực (cookie) trong các yêu cầu chứa báo cáo.

Thông tin xác thực có thể cung cấp thêm ngữ cảnh hữu ích về báo cáo; ví dụ: liệu tài khoản của một người dùng cụ thể có liên tục kích hoạt lỗi hay không hoặc liệu một trình tự hành động nhất định được thực hiện trên các trang khác có đang kích hoạt báo cáo trên trang này hay không.

Trình duyệt gửi báo cáo khi nào và bằng cách nào?

Báo cáo được phân phối ngoài phạm vi trang web của bạn: trình duyệt sẽ kiểm soát thời điểm gửi báo cáo đến(các) điểm cuối đã định cấu hình. Ngoài ra, không có cách nào để kiểm soát thời điểm trình duyệt gửi báo cáo; trình duyệt sẽ ghi lại, xếp vào hàng đợi và tự động gửi báo cáo vào thời điểm phù hợp.

Điều này có nghĩa là bạn sẽ không gặp phải vấn đề gì về hiệu suất khi sử dụng API Báo cáo.

Báo cáo được gửi trễ (tối đa một phút) để tăng khả năng gửi báo cáo theo lô. Điều này giúp tiết kiệm băng thông để tôn trọng kết nối mạng của người dùng, điều này đặc biệt quan trọng trên thiết bị di động. Trình duyệt cũng có thể trì hoãn việc phân phối nếu đang bận xử lý công việc có mức độ ưu tiên cao hơn hoặc nếu người dùng tại thời điểm đó đang sử dụng một mạng chậm và/hoặc bị nghẽn.

Vấn đề của bên thứ ba và bên thứ nhất

Các báo cáo được tạo do lỗi vi phạm hoặc ngừng hoạt động xảy ra trên trang của bạn sẽ được gửi đến(các) điểm cuối mà bạn đã định cấu hình. Điều này bao gồm cả các lỗi vi phạm do tập lệnh của bên thứ ba chạy trên trang của bạn.

Các lỗi vi phạm hoặc ngừng sử dụng xảy ra trong một iframe trên nhiều nguồn gốc được nhúng trong trang của bạn sẽ không được báo cáo cho(các) điểm cuối của bạn (ít nhất là theo mặc định). Một iframe có thể thiết lập báo cáo riêng và thậm chí báo cáo cho dịch vụ báo cáo của trang web (tức là của bên thứ nhất); nhưng điều đó tuỳ thuộc vào trang web được đóng khung. Ngoài ra, xin lưu ý rằng hầu hết các báo cáo chỉ được tạo nếu trang của bạn vi phạm chính sách và chính sách của trang cũng như chính sách của iframe là khác nhau.

Ví dụ về các tính năng không dùng nữa

Nếu bạn thiết lập tiêu đề Reporting-Endpoints trên trang: API không dùng nữa do tập lệnh của bên thứ ba chạy trên trang gọi sẽ được báo cáo đến điểm cuối của bạn. API không dùng nữa được gọi bởi một iframe nhúng trong trang của bạn sẽ không được báo cáo đến điểm cuối. Báo cáo về việc ngừng sử dụng sẽ chỉ được tạo nếu máy chủ iframe đã thiết lập Điểm cuối báo cáo, đồng thời báo cáo này sẽ được gửi đến bất kỳ điểm cuối nào mà máy chủ của iframe đã thiết lập.
Nếu bạn thiết lập tiêu đề Reporting-Endpoints trên trang: API không dùng nữa do các tập lệnh của bên thứ ba chạy trên trang gọi sẽ được báo cáo đến điểm cuối của bạn. API không dùng nữa được gọi bởi một iframe nhúng trong trang của bạn sẽ không được báo cáo đến điểm cuối. Báo cáo về việc ngừng sử dụng sẽ chỉ được tạo nếu máy chủ iframe đã thiết lập Điểm cuối báo cáo và báo cáo này sẽ được gửi đến bất kỳ điểm cuối nào mà máy chủ của iframe đã thiết lập.

Hỗ trợ trình duyệt

Bảng dưới đây tóm tắt khả năng hỗ trợ trình duyệt cho API Báo cáo phiên bản 1, với tiêu đề Reporting-Endpoints. Khả năng hỗ trợ trình duyệt cho API Báo cáo phiên bản 0 (tiêu đề Report-To) cũng tương tự, ngoại trừ một loại báo cáo: tính năng Ghi nhật ký lỗi mạng không được hỗ trợ trong API Báo cáo mới. Đọc hướng dẫn di chuyển để biết thông tin chi tiết.

Loại báo cáo Chrome Chrome iOS Safari Firefox Edge
Vi phạm Chính sách quyền riêng tư (CSP) (Chỉ ở Cấp 3)* ✔ Có ✔ Có ✔ Có ✘ Không ✔ Có
Ghi nhật ký lỗi mạng ✘ Không ✘ Không ✘ Không ✘ Không ✘ Không
Vi phạm COOP/COEP ✔ Có ✘ Không ✔ Có ✘ Không ✔ Có
Tất cả các loại khác: Vi phạm Chính sách về tài liệu, Ngừng sử dụng, Can thiệp, Sự cố ✔ Có ✘ Không ✘ Không ✘ Không ✔ Có

Bảng này chỉ tóm tắt tính năng hỗ trợ cho report-to bằng tiêu đề Reporting-Endpoints mới. Hãy đọc các mẹo di chuyển báo cáo CSP nếu bạn muốn di chuyển sang Reporting-Endpoints.

Sử dụng API Báo cáo

Quyết định nơi gửi báo cáo

Bạn có hai lựa chọn:

  • Gửi báo cáo đến dịch vụ thu thập báo cáo hiện có.
  • Gửi báo cáo đến một trình thu thập báo cáo mà bạn tự tạo và vận hành.

Cách 1: Sử dụng một dịch vụ thu thập báo cáo hiện có

Sau đây là một số ví dụ về dịch vụ thu thập báo cáo:

Nếu bạn biết các giải pháp khác, hãy mở vấn đề để cho chúng tôi biết, chúng tôi sẽ cập nhật bài đăng này!

Ngoài giá cả, hãy cân nhắc những điểm sau khi chọn trình thu thập báo cáo: 🧐

  • Bộ thu thập này có hỗ trợ tất cả các loại báo cáo không? Ví dụ: không phải tất cả các giải pháp điểm cuối báo cáo đều hỗ trợ báo cáo COOP/COEP.
  • Bạn có cảm thấy thoải mái khi chia sẻ bất kỳ URL nào của ứng dụng với trình thu thập báo cáo của bên thứ ba không? Ngay cả khi trình duyệt xoá thông tin nhạy cảm khỏi các URL này, thông tin nhạy cảm vẫn có thể bị rò rỉ theo cách này. Nếu điều này có vẻ quá rủi ro đối với ứng dụng, hãy vận hành điểm cuối báo cáo của riêng bạn.

Lựa chọn 2: Tạo và vận hành trình thu thập báo cáo của riêng bạn

Việc xây dựng máy chủ nhận báo cáo của riêng bạn không hề đơn giản. Để bắt đầu, bạn có thể phân nhánh mẫu mã nhẹ của chúng tôi. Báo cáo được xây dựng bằng Express và có thể nhận cũng như hiển thị báo cáo.

  1. Chuyển đến trình thu thập báo cáo nguyên mẫu.

  2. Nhấp vào Phối lại để chỉnh sửa để có thể chỉnh sửa dự án.

  3. Bây giờ, bạn đã có bản sao! Bạn có thể tuỳ chỉnh thư viện này cho mục đích của riêng mình.

Nếu bạn không sử dụng bản mẫu và đang xây dựng máy chủ của riêng mình từ đầu:

  • Kiểm tra các yêu cầu POSTContent-Typeapplication/reports+json để nhận dạng các yêu cầu báo cáo mà trình duyệt gửi đến điểm cuối của bạn.
  • Nếu điểm cuối của bạn nằm trên một nguồn gốc khác với trang web, hãy đảm bảo điểm cuối đó hỗ trợ yêu cầu kiểm tra trước CORS.

Cách 3: Kết hợp Cách 1 và 2

Bạn có thể muốn một nhà cung cấp cụ thể xử lý một số loại báo cáo, nhưng có giải pháp nội bộ cho các loại báo cáo khác.

Trong trường hợp này, hãy đặt nhiều điểm cuối như sau:

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

Định cấu hình tiêu đề Reporting-Endpoints

Đặt tiêu đề phản hồi Reporting-Endpoints. Giá trị của thuộc tính này phải là một hoặc một loạt các cặp khoá-giá trị được phân tách bằng dấu phẩy:

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

Nếu đang di chuyển từ API Báo cáo cũ sang API Báo cáo mới, thì bạn nên đặt cả Reporting-EndpointsReport-To. Xem thông tin chi tiết trong hướng dẫn di chuyển. Cụ thể, nếu bạn chỉ sử dụng tính năng báo cáo lỗi vi phạm Content-Security-Policy thông qua lệnh report-uri, hãy xem các bước di chuyển để báo cáo CSP.

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

Khoá (tên điểm cuối)

Mỗi khoá có thể là một tên do bạn chọn, chẳng hạn như main-endpoint hoặc endpoint-1. Bạn có thể quyết định đặt các điểm cuối được đặt tên khác nhau cho các loại báo cáo khác nhau, ví dụ: my-coop-endpoint, my-csp-endpoint. Nhờ đó, bạn có thể định tuyến báo cáo đến các điểm cuối khác nhau tuỳ thuộc vào loại báo cáo.

Nếu bạn muốn nhận báo cáo can thiệp, ngừng sử dụng và/hoặc sự cố, hãy đặt một điểm cuối có tên là default.

Nếu tiêu đề Reporting-Endpoints xác định không có điểm cuối default, thì các báo cáo thuộc loại này sẽ không được gửi (mặc dù báo cáo sẽ được tạo).

Giá trị (URL)

Mỗi giá trị là một URL mà bạn chọn để gửi báo cáo. URL cần đặt tại đây phụ thuộc vào quyết định của bạn ở Bước 1.

URL điểm cuối:

Ví dụ

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

Sau đó, bạn có thể sử dụng từng điểm cuối được đặt tên trong chính sách thích hợp hoặc sử dụng một điểm cuối duy nhất trên tất cả chính sách.

Đặt tiêu đề ở đâu?

Trong API Báo cáo mới (được đề cập trong bài đăng này), báo cáo được giới hạn ở tài liệu. Điều này có nghĩa là đối với một nguồn gốc nhất định, các tài liệu khác nhau, chẳng hạn như site.example/page1site.example/page2, có thể gửi báo cáo đến các điểm cuối khác nhau.

Để nhận báo cáo về các lỗi vi phạm hoặc nội dung không dùng nữa xảy ra trên bất kỳ trang nào của trang web, hãy đặt tiêu đề làm phần mềm trung gian trên tất cả các phản hồi.

Dưới đây là ví dụ trong 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();
});

Chỉnh sửa chính sách

Giờ đây, khi tiêu đề Reporting-Endpoints đã được định cấu hình, hãy thêm một lệnh report-to vào từng tiêu đề chính sách mà bạn muốn nhận báo cáo vi phạm. Giá trị của report-to phải là một trong các điểm cuối được đặt tên mà bạn đã định cấu hình.

Bạn có thể sử dụng nhiều điểm cuối cho nhiều chính sách hoặc sử dụng nhiều điểm cuối cho nhiều chính sách.

Đối với mỗi chính sách, giá trị của report-to phải là một trong các điểm cuối được đặt tên mà bạn đã định cấu hình.

Bạn không cần report-to cho các báo cáo ngừng sử dụng, can thiệpsự cố. Các báo cáo này không liên quan đến bất kỳ chính sách nào. Các tệp này được tạo miễn là bạn thiết lập điểm cuối default và gửi đến điểm cuối default này.

Ví dụ:

# 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

Mã mẫu

Để xem tất cả những nội dung này trong ngữ cảnh, bên dưới là một máy chủ Node mẫu sử dụng Express và tập hợp tất cả các phần được thảo luận trong bài viết này. Bài viết này cho biết cách định cấu hình báo cáo cho một số loại báo cáo và hiển thị kết quả.

Gỡ lỗi chế độ thiết lập báo cáo

Tạo báo cáo một cách có chủ ý

Khi thiết lập API Báo cáo, có thể bạn sẽ cần cố tình vi phạm chính sách của mình để kiểm tra xem báo cáo có được tạo và gửi như dự kiến hay không. Để xem mã ví dụ vi phạm chính sách và thực hiện các hành vi xấu khác sẽ tạo ra báo cáo thuộc mọi loại, hãy xem bản minh hoạ.

Tiết kiệm thời gian

Báo cáo có thể bị trễ khi gửi – khoảng một phút, đây là khoảng thời gian dài khi gỡ lỗi. ➜ Thật may là khi gỡ lỗi trong Chrome, bạn có thể sử dụng cờ --short-reporting-delay để nhận báo cáo ngay khi báo cáo được tạo.

Chạy lệnh sau trong dòng lệnh để bật cờ này:

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

Sử dụng Công cụ cho nhà phát triển

Trong Chrome, hãy sử dụng DevTools để xem các báo cáo đã gửi hoặc sẽ gửi.

Tính đến tháng 10 năm 2021, tính năng này vẫn đang trong giai đoạn thử nghiệm. Để sử dụng, hãy làm theo các bước sau:

  1. Sử dụng Chrome phiên bản 96 trở lên (kiểm tra bằng cách nhập chrome://version vào trình duyệt)
  2. Nhập hoặc dán chrome://flags/#enable-experimental-web-platform-features vào thanh URL của Chrome.
  3. Nhấp vào Đã bật.
  4. Khởi động lại trình duyệt.
  5. Mở Công cụ của Chrome cho nhà phát triển.
  6. Trong Công cụ của Chrome cho nhà phát triển, hãy mở phần Cài đặt. Trong phần Thử nghiệm, hãy nhấp vào Bật bảng điều khiển API Báo cáo trong bảng điều khiển Ứng dụng.
  7. Tải lại Công cụ cho nhà phát triển.
  8. Tải lại trang. Các báo cáo do trang Công cụ cho nhà phát triển tạo ra đang mở sẽ được liệt kê trong bảng điều khiển Ứng dụng của Công cụ cho nhà phát triển của Chrome, trong phần API báo cáo.
Ảnh chụp màn hình DevTools liệt kê các báo cáo
Công cụ của Chrome cho nhà phát triển sẽ hiển thị các báo cáo được tạo trên trang của bạn và trạng thái của các báo cáo đó.

Trạng thái báo cáo

Cột Trạng thái cho bạn biết liệu báo cáo đã được gửi thành công hay chưa.

Trạng thái Mô tả
Success Trình duyệt đã gửi báo cáo và điểm cuối đã trả lời bằng một mã thành công (200 hoặc một mã phản hồi thành công khác 2xx).
Pending Trình duyệt hiện đang cố gắng gửi báo cáo.
Queued Báo cáo đã được tạo và trình duyệt hiện không cố gắng gửi báo cáo đó. Báo cáo sẽ xuất hiện dưới dạng Queued trong một trong hai trường hợp sau:
  • Báo cáo này là mới và trình duyệt đang chờ xem có thêm báo cáo nào đến hay không trước khi cố gắng gửi báo cáo.
  • Báo cáo này không phải là báo cáo mới; trình duyệt đã cố gắng gửi báo cáo này và không thành công và đang chờ trước khi thử lại.
MarkedForRemoval Sau khi thử lại một lúc (Queued), trình duyệt đã ngừng cố gắng gửi báo cáo và sẽ sớm xoá báo cáo đó khỏi danh sách báo cáo cần gửi.

Các báo cáo sẽ bị xoá sau một thời gian, cho dù báo cáo có được gửi thành công hay không.

Khắc phục sự cố

Báo cáo không được tạo hoặc không được gửi đến điểm cuối của bạn như mong đợi? Dưới đây là một vài mẹo để khắc phục sự cố này.

Báo cáo không được tạo

Các báo cáo xuất hiện trong DevTools đã được tạo chính xác. Nếu báo cáo mà bạn muốn xem không xuất hiện trong danh sách này:

  • Kiểm tra report-to trong chính sách của bạn. Nếu bạn định cấu hình không đúng, báo cáo sẽ không được tạo. Hãy chuyển đến phần Chỉnh sửa chính sách để khắc phục vấn đề này. Một cách khác để khắc phục sự cố này là kiểm tra bảng điều khiển DevTools trong Chrome: nếu lỗi xuất hiện trong bảng điều khiển cho lỗi vi phạm mà bạn dự kiến, thì điều này có nghĩa là chính sách của bạn có thể đã được định cấu hình đúng cách.
  • Xin lưu ý rằng chỉ những báo cáo được tạo cho tài liệu mà DevTools đang mở mới xuất hiện trong danh sách này. Ví dụ: nếu trang web site1.example của bạn nhúng một iframe site2.example vi phạm chính sách và do đó tạo ra một báo cáo, thì báo cáo này sẽ chỉ xuất hiện trong DevTools nếu bạn mở iframe trong cửa sổ riêng và mở DevTools cho cửa sổ đó.

Báo cáo được tạo nhưng không được gửi hoặc không được nhận

Nếu bạn có thể xem báo cáo trong Công cụ cho nhà phát triển nhưng điểm cuối của bạn không nhận được báo cáo thì sao?

  • Hãy nhớ sử dụng độ trễ ngắn. Có thể lý do bạn không thấy báo cáo là vì báo cáo đó chưa được gửi!
  • Kiểm tra cấu hình tiêu đề Reporting-Endpoints. Nếu có vấn đề, báo cáo đã được tạo đúng cách sẽ không được gửi. Trong DevTools, trạng thái của báo cáo sẽ vẫn là Queued (có thể chuyển sang Pending, sau đó nhanh chóng quay lại Queued khi có một lần phân phối) trong trường hợp này. Một số lỗi phổ biến có thể gây ra lỗi này:

  • Điểm cuối được sử dụng nhưng chưa được định cấu hình. Ví dụ:

Mã có lỗi
 Document-Policy: document-write=?0;report-to=endpoint-1;
 
Reporting-Endpoints: default="https://reports.example/default"

Báo cáo vi phạm Chính sách về tài liệu phải được gửi đến endpoint-1, nhưng tên điểm cuối này không được định cấu hình trong Reporting-Endpoints.

  • Thiếu điểm cuối default. Một số loại báo cáo, chẳng hạn như báo cáo về việc ngừng sử dụng và báo cáo can thiệp, sẽ chỉ được gửi đến điểm cuối có tên là default. Hãy đọc thêm trong phần Định cấu hình tiêu đề Reporting-Endpoints.

  • Tìm các vấn đề trong cú pháp tiêu đề chính sách, chẳng hạn như thiếu dấu ngoặc kép. Xem thông tin chi tiết.

  • Kiểm tra để đảm bảo điểm cuối của bạn có thể xử lý các yêu cầu đến.

    • Đảm bảo rằng điểm cuối của bạn hỗ trợ các yêu cầu trước khi bay của CORS. Nếu không, tài khoản đó sẽ không nhận được báo cáo.

    • Kiểm thử hành vi của điểm cuối. Để làm như vậy, thay vì tạo báo cáo theo cách thủ công, bạn có thể mô phỏng trình duyệt bằng cách gửi đến các yêu cầu điểm cuối giống như những gì trình duyệt sẽ gửi. Chạy lệnh sau:

    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

    Điểm cuối của bạn sẽ phản hồi bằng một mã thành công (200 hoặc một mã phản hồi thành công khác 2xx). Nếu không, cấu hình của điểm cuối đó có vấn đề.

Chỉ báo cáo

Các tiêu đề chính sách -Report-OnlyReporting-Endpoints hoạt động cùng nhau.

Các điểm cuối được định cấu hình trong Reporting-Endpoints và được chỉ định trong trường report-to của Content-Security-Policy, Cross-Origin-Embedder-PolicyCross-Origin-Opener-Policy sẽ nhận được báo cáo khi các chính sách này bị vi phạm.

Bạn cũng có thể chỉ định điểm cuối được định cấu hình trong Reporting-Endpoints trong trường report-to của Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-OnlyCross-Origin-Opener-Policy-Report-Only. Họ cũng sẽ nhận được báo cáo khi có hành vi vi phạm các chính sách này.

Mặc dù báo cáo được gửi trong cả hai trường hợp, nhưng tiêu đề -Report-Only không thực thi các chính sách: không có nội dung nào bị lỗi hoặc bị chặn, nhưng bạn sẽ nhận được báo cáo về nội dung sẽ bị lỗi hoặc bị chặn.

ReportingObserver

API JavaScript ReportingObserver có thể giúp bạn quan sát các cảnh báo phía máy khách.

ReportingObserver và tiêu đề Reporting-Endpoints tạo ra các báo cáo có giao diện giống nhau, nhưng hỗ trợ các trường hợp sử dụng hơi khác nhau.

Sử dụng ReportingObserver nếu:

  • Bạn chỉ muốn theo dõi các nội dung ngừng hoạt động và/hoặc các biện pháp can thiệp của trình duyệt. ReportingObserver hiển thị các cảnh báo phía máy khách, chẳng hạn như các cảnh báo ngừng sử dụng và can thiệp của trình duyệt, nhưng không giống như Reporting-Endpoints, ReportingObserver không ghi lại bất kỳ loại báo cáo nào khác, chẳng hạn như lỗi vi phạm CSP hoặc COOP/COEP.
  • Bạn cần phản ứng với những lỗi vi phạm này theo thời gian thực. ReportingObserver cho phép đính kèm lệnh gọi lại vào một sự kiện vi phạm.
  • Bạn muốn đính kèm thông tin bổ sung vào một báo cáo để hỗ trợ gỡ lỗi thông qua lệnh gọi lại tuỳ chỉnh.

Một điểm khác biệt nữa là ReportingObserver chỉ được định cấu hình phía máy khách: bạn có thể sử dụng ReportingObserver ngay cả khi không có quyền kiểm soát các tiêu đề phía máy chủ và không thể đặt Reporting-Endpoints.

Tài liệu đọc thêm

Hình ảnh chính của Nine Koepfer / @enka80 trên Unsplash, đã chỉnh sửa. Cảm ơn Ian Clelland, Eiji Kitamura và Milica Mihajlija đã xem xét và đưa ra đề xuất về bài viết này.