Memantau aplikasi web dengan Reporting API

Gunakan Reporting API untuk memantau pelanggaran keamanan, panggilan API yang tidak digunakan lagi, dan lainnya.

Maud Nalpas

Beberapa error hanya terjadi dalam produksi. Anda tidak akan melihatnya secara lokal atau selama pengembangan karena pengguna sungguhan, jaringan sungguhan, dan perangkat sungguhan mengubah permainan. Reporting API membantu mendeteksi beberapa error ini, seperti pelanggaran keamanan atau panggilan API yang tidak digunakan lagi dan akan segera tidak digunakan lagi di seluruh situs Anda, dan mengirimkannya ke endpoint yang telah Anda tentukan.

Dengan fitur ini, Anda dapat mendeklarasikan apa yang ingin dipantau menggunakan header HTTP, dan dioperasikan oleh browser.

Menyiapkan Reporting API akan memberi Anda ketenangan pikiran bahwa saat pengguna mengalami jenis error ini, Anda akan mengetahuinya, sehingga Anda dapat memperbaikinya.

Postingan ini membahas kemampuan API ini dan cara menggunakannya. Mari kita mulai!

Ringkasan

Misalkan situs Anda, site.example, memiliki Content-Security-Policy dan Document-Policy. Tidak tahu apa fungsinya? Tidak masalah, Anda tetap dapat memahami contoh ini.

Anda memutuskan untuk memantau situs Anda agar mengetahui kapan kebijakan ini dilanggar, tetapi juga karena Anda ingin mengawasi API yang tidak digunakan lagi atau akan segera tidak digunakan lagi yang mungkin digunakan oleh codebase Anda.

Untuk melakukannya, Anda mengonfigurasi header Reporting-Endpoints, dan memetakan nama endpoint ini menggunakan direktif report-to dalam kebijakan Anda jika diperlukan.

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

Terjadi hal yang tidak terduga, dan kebijakan ini dilanggar oleh beberapa pengguna Anda.

Contoh pelanggaran

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, dimuat oleh 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;

Browser membuat laporan pelanggaran CSP, laporan pelanggaran Document-Policy, dan laporan Penghentian penggunaan yang mencatat masalah ini.

Dengan penundaan singkat—hingga satu menit—browser kemudian mengirimkan laporan ke endpoint yang dikonfigurasi untuk jenis pelanggaran ini. Laporan dikirim di luar band oleh browser itu sendiri (bukan oleh server Anda maupun oleh situs Anda).

Endpoint menerima laporan ini.

Anda kini dapat mengakses laporan di endpoint ini dan memantau apa yang salah. Anda siap untuk mulai memecahkan masalah yang memengaruhi pengguna Anda.

Contoh laporan

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

Kasus penggunaan dan jenis laporan

Reporting API dapat dikonfigurasi untuk membantu Anda memantau berbagai jenis peringatan atau masalah menarik yang terjadi di seluruh situs Anda:

Laporan

Seperti apa tampilan laporan?

Browser mengirimkan laporan ke endpoint yang telah Anda konfigurasi. Tindakan ini mengirim permintaan yang terlihat seperti berikut:

POST
Content-Type: application/reports+json

Payload permintaan ini adalah daftar laporan.

Contoh daftar laporan

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

Berikut data yang dapat Anda temukan di setiap laporan ini:

Laporan dengan kredensial

Endpoint pelaporan yang memiliki origin yang sama dengan halaman yang membuat laporan menerima kredensial (cookie) dalam permintaan yang berisi laporan.

Kredensial dapat memberikan konteks tambahan yang berguna tentang laporan; misalnya, apakah akun pengguna tertentu memicu error secara konsisten, atau apakah urutan tindakan tertentu yang dilakukan di halaman lain memicu laporan di halaman ini.

Kapan dan bagaimana browser mengirim laporan?

Laporan dikirimkan di luar jalur dari situs Anda: browser mengontrol kapan laporan dikirim ke endpoint yang dikonfigurasi. Tidak ada cara untuk mengontrol kapan browser mengirim laporan; browser akan mengambil, mengantrekan, dan mengirimkannya secara otomatis pada waktu yang sesuai.

Artinya, tidak ada atau hanya ada sedikit masalah performa saat menggunakan Reporting API.

Laporan dikirim dengan penundaan—hingga satu menit—untuk meningkatkan peluang pengiriman laporan dalam batch. Hal ini menghemat bandwidth untuk menghormati koneksi jaringan pengguna, yang sangat penting di perangkat seluler. Browser juga dapat menunda pengiriman jika sedang memproses pekerjaan dengan prioritas yang lebih tinggi, atau jika pengguna menggunakan jaringan yang lambat atau padat pada saat itu.

Masalah pihak ketiga dan pihak pertama

Laporan yang dibuat karena pelanggaran atau penghentian penggunaan yang terjadi di halaman Anda akan dikirim ke endpoint yang telah Anda konfigurasi. Hal ini mencakup pelanggaran yang dilakukan oleh skrip pihak ketiga yang berjalan di halaman Anda.

Pelanggaran atau penghentian penggunaan yang terjadi di iframe lintas origin yang disematkan di halaman Anda tidak akan dilaporkan ke endpoint Anda (setidaknya tidak secara default). Iframe dapat menyiapkan pelaporannya sendiri dan bahkan melaporkan ke layanan pelaporan situs Anda, yaitu layanan pelaporan pihak pertama; tetapi hal itu bergantung pada situs yang di-frame. Perhatikan juga bahwa sebagian besar laporan hanya dibuat jika kebijakan halaman dilanggar, dan kebijakan halaman Anda dan kebijakan iframe berbeda.

Contoh dengan penghentian penggunaan

Dukungan browser

Tabel berikut merangkum dukungan browser untuk Reporting API v1, yaitu dengan header Reporting-Endpoints. Dukungan browser untuk Reporting API v0 (header Report-To) sama, kecuali untuk satu jenis laporan: Pencatatan Error Jaringan tidak didukung di Reporting API baru. Baca panduan migrasi untuk mengetahui detailnya.

Tabel ini hanya merangkum dukungan untuk report-to dengan header Reporting-Endpoints baru. Baca tips migrasi pelaporan CSP jika Anda ingin bermigrasi ke Reporting-Endpoints.

Menggunakan Reporting API

Tentukan tujuan pengiriman laporan

Anda memiliki dua opsi:

• Mengirim laporan ke layanan pengumpul laporan yang ada.
• Kirim laporan ke pengumpul pelaporan yang Anda buat dan operasikan sendiri.

Opsi 1: Menggunakan layanan pengumpul laporan yang ada

Beberapa contoh layanan pengumpul laporan adalah:

• report-uri
• uriports

Jika Anda mengetahui solusi lain, buka masalah untuk memberi tahu kami, dan kami akan memperbarui postingan ini.

Selain harga, pertimbangkan poin-poin berikut saat memilih pengumpul laporan: 🧐

• Apakah pengumpul ini mendukung semua jenis laporan? Misalnya, tidak semua solusi endpoint pelaporan mendukung laporan COOP/COEP.
• Apakah Anda bersedia membagikan URL aplikasi Anda kepada pengumpul laporan pihak ketiga? Meskipun browser menghapus informasi sensitif dari URL ini, informasi sensitif dapat bocor dengan cara ini. Jika hal ini terlalu berisiko bagi aplikasi Anda, operasikan endpoint pelaporan Anda sendiri.

Opsi 2: Membuat dan mengoperasikan pengumpul laporan Anda sendiri

Membuat server Anda sendiri yang menerima laporan tidaklah mudah. Untuk memulai, Anda dapat membuat fork boilerplate ringan kami. Aplikasi ini dibuat dengan Express dan dapat menerima dan menampilkan laporan.

Saat Anda membuat pengumpul laporan Anda sendiri:

• Periksa permintaan POST dengan Content-Type application/reports+json untuk mengenali permintaan laporan yang dikirim oleh browser ke endpoint Anda.
• Jika endpoint Anda berada di origin yang berbeda dengan situs Anda, pastikan endpoint tersebut mendukung permintaan pra-penerbangan CORS.

Opsi 3: Gabungkan Opsi 1 dan 2

Anda mungkin ingin membiarkan penyedia tertentu menangani beberapa jenis laporan, tetapi memiliki solusi internal untuk jenis laporan lainnya.

Dalam hal ini, tetapkan beberapa endpoint sebagai berikut:

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

Mengonfigurasi header Reporting-Endpoints

Tetapkan header respons Reporting-Endpoints. Nilainya harus berupa satu atau serangkaian pasangan nilai kunci yang dipisahkan koma:

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

Jika Anda bermigrasi dari Reporting API lama ke Reporting API baru, sebaiknya tetapkan kedua Reporting-Endpoints dan Report-To. Lihat detailnya dalam panduan migrasi. Khususnya, jika Anda menggunakan pelaporan untuk pelanggaran Content-Security-Policy hanya menggunakan perintah report-uri, lihat langkah-langkah migrasi untuk pelaporan CSP.

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

Kunci (nama endpoint)

Setiap kunci dapat berupa nama pilihan Anda, seperti main-endpoint atau endpoint-1. Anda dapat memutuskan untuk menetapkan endpoint bernama yang berbeda untuk berbagai jenis laporan, misalnya, my-coop-endpoint, my-csp-endpoint. Dengan demikian, Anda dapat merutekan laporan ke berbagai endpoint, bergantung pada jenisnya.

Jika Anda ingin menerima laporan intervensi, penghentian, error, atau kombinasi laporan tersebut, tetapkan endpoint bernama default.

Jika header Reporting-Endpoints tidak menentukan endpoint default, laporan jenis ini tidak akan dikirim (meskipun akan dibuat).

Nilai (URL)

Setiap nilai adalah URL pilihan Anda, tempat laporan akan dikirim. URL yang akan ditetapkan di sini bergantung pada keputusan Anda di Langkah 1.

URL endpoint:

• Harus dimulai dengan garis miring (/). Jalur relatif tidak didukung.
• Dapat berupa lintas origin; tetapi dalam hal ini, kredensial tidak dikirim dengan laporan.

Contoh

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

Kemudian, Anda dapat menggunakan setiap endpoint bernama dalam kebijakan yang sesuai, atau menggunakan satu endpoint di semua kebijakan.

Di mana header harus ditetapkan?

Di Reporting API baru—yang dibahas dalam postingan ini— laporan dicakup ke dokumen. Artinya, untuk satu origin tertentu, dokumen yang berbeda, seperti site.example/page1 dan site.example/page2, dapat mengirim laporan ke endpoint yang berbeda.

Untuk menerima laporan pelanggaran atau penghentian penggunaan yang terjadi di halaman mana pun di situs Anda, tetapkan header sebagai middleware di semua respons.

Berikut contohnya di 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();
});

Mengedit kebijakan Anda

Setelah header Reporting-Endpoints dikonfigurasi, tambahkan direktif report-to ke setiap header kebijakan yang ingin Anda terima laporan pelanggarannya. Nilai report-to harus berupa salah satu endpoint bernama yang telah Anda konfigurasi.

Anda dapat menggunakan beberapa endpoint untuk beberapa kebijakan, atau menggunakan endpoint yang berbeda di seluruh kebijakan.

report-to tidak diperlukan untuk laporan penghentian penggunaan, intervensi, dan error. Laporan ini tidak terikat pada kebijakan apa pun. Laporan dibuat selama endpoint default disiapkan dan dikirim ke endpoint default ini.

Contoh

# 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

Men-debug penyiapan pelaporan

Membuat laporan secara sengaja

Saat menyiapkan Reporting API, Anda mungkin perlu melanggar kebijakan secara sengaja untuk memeriksa apakah laporan dibuat dan dikirim sesuai harapan.

Hemat waktu

Laporan mungkin dikirim dengan penundaan—sekitar satu menit, yang merupakan waktu yang lama saat men-debug. 😴 Untungnya, saat men-debug di Chrome, Anda dapat menggunakan tanda --short-reporting-delay untuk menerima laporan segera setelah laporan dibuat.

Jalankan perintah ini di terminal Anda untuk mengaktifkan tanda ini:

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

Menggunakan DevTools

Di Chrome, gunakan DevTools untuk melihat laporan yang telah dikirim atau akan dikirim.

Mulai Oktober 2021, fitur ini bersifat eksperimental. Untuk menggunakannya, ikuti langkah-langkah berikut:

1. Gunakan Chrome versi 96 dan yang lebih baru (periksa dengan mengetik chrome://version di browser Anda)
2. Ketik atau tempel chrome://flags/#enable-experimental-web-platform-features di kolom URL Chrome.
3. Klik Enabled.
4. Mulai ulang browser.
5. Buka Chrome DevTools.
6. Di Chrome DevTools, buka Setelan. Di bagian Experiments, klik Enable Reporting API panel in the Application panel.
7. Muat ulang DevTools.
8. Muat ulang halaman Anda. Laporan yang dibuat oleh halaman tempat DevTools dibuka akan dicantumkan di panel Application Chrome DevTools, di bagian Reporting API.

Status laporan

Kolom Status memberi tahu Anda apakah laporan telah berhasil dikirim.

Laporan akan dihapus setelah beberapa saat, baik berhasil dikirim maupun tidak.

Pemecahan masalah

Apakah laporan tidak dibuat atau tidak dikirim sesuai harapan ke endpoint Anda? Berikut beberapa tips untuk memecahkan masalah ini.

Laporan tidak dibuat

Laporan yang muncul di DevTools telah dibuat dengan benar. Jika laporan yang Anda harapkan tidak muncul dalam daftar ini:

• Periksa report-to dalam kebijakan Anda. Jika salah dikonfigurasi, laporan tidak akan dibuat. Buka Edit kebijakan Anda untuk memperbaiki masalah ini. Cara tambahan untuk memecahkan masalah ini adalah dengan memeriksa konsol DevTools di Chrome: jika error muncul di konsol untuk pelanggaran yang Anda harapkan, berarti kebijakan Anda mungkin dikonfigurasi dengan benar.
• Perlu diingat bahwa hanya laporan yang dibuat untuk dokumen tempat DevTools dibuka yang akan muncul dalam daftar ini. Salah satu contoh: jika situs site1.example menyematkan iframe site2.example yang melanggar kebijakan dan oleh karena itu menghasilkan laporan, laporan ini akan muncul di DevTools hanya jika Anda membuka iframe di jendela sendiri dan membuka DevTools untuk jendela tersebut.

Laporan dibuat, tetapi tidak dikirim atau tidak diterima

Bagaimana jika Anda dapat melihat laporan di DevTools, tetapi endpoint Anda tidak menerimanya?

• Pastikan untuk menggunakan penundaan singkat. Mungkin alasan Anda tidak dapat melihat laporan adalah karena laporan tersebut belum dikirim.

• Periksa konfigurasi header Reporting-Endpoints Anda. Jika ada masalah, laporan yang telah dibuat dengan benar tidak akan dikirim. Di DevTools, status laporan akan tetap Queued (mungkin berubah menjadi Pending, lalu kembali dengan cepat menjadi Queued saat upaya pengiriman dilakukan) dalam kasus ini. Beberapa kesalahan umum yang dapat menyebabkan hal ini:

• Endpoint digunakan, tetapi tidak dikonfigurasi. Contoh:

 Document-Policy: document-write=?0;report-to=endpoint-1;
 Reporting-Endpoints: default="https://reports.example/default"

• Endpoint default tidak ada. Beberapa jenis laporan, seperti laporan penghentian penggunaan dan intervensi, hanya akan dikirim ke endpoint bernama default. Baca selengkapnya di Mengonfigurasi header Reporting-Endpoints.

• Cari masalah dalam sintaksis header kebijakan Anda, seperti tanda petik yang tidak ada. Lihat detailnya.

• Pastikan endpoint Anda dapat menangani permintaan masuk.

  • Pastikan endpoint Anda mendukung permintaan preflight CORS. Jika tidak, laporan tidak dapat diterima.

  • Uji perilaku endpoint Anda. Untuk melakukannya, alih-alih membuat laporan secara manual, Anda dapat meniru browser dengan mengirimkan permintaan yang terlihat seperti yang akan dikirimkan browser ke endpoint Anda. Jalankan perintah berikut:

  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
  

  Endpoint Anda harus merespons dengan kode keberhasilan (200 atau kode respons keberhasilan 2xx lainnya). Jika tidak, ada masalah dengan konfigurasinya.

Mekanisme pelaporan terkait

Hanya Laporan

Header kebijakan -Report-Only dan Reporting-Endpoints bekerja sama.

Endpoint yang dikonfigurasi di Reporting-Endpoints dan ditentukan di kolom report-to Content-Security-Policy, Cross-Origin-Embedder-Policy dan Cross-Origin-Opener-Policy, akan menerima laporan jika kebijakan ini dilanggar.

Endpoint yang dikonfigurasi di Reporting-Endpoints juga dapat ditentukan di kolom report-to dari Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only dan Cross-Origin-Opener-Policy-Report-Only. Mereka juga akan menerima laporan jika kebijakan ini dilanggar.

Meskipun laporan dikirim dalam kedua kasus, header -Report-Only tidak menerapkan kebijakan: tidak ada yang akan rusak atau benar-benar diblokir, tetapi Anda akan menerima laporan tentang apa yang akan rusak atau diblokir.

ReportingObserver

ReportingObserver JavaScript API dapat membantu Anda mengamati peringatan sisi klien.

ReportingObserver dan header Reporting-Endpoints menghasilkan laporan yang terlihat sama, tetapi keduanya memungkinkan kasus penggunaan yang sedikit berbeda.

Gunakan ReportingObserver jika:

• Anda hanya ingin memantau penghentian penggunaan atau intervensi browser. ReportingObserver menampilkan peringatan sisi klien seperti penghentian penggunaan dan intervensi browser, tetapi tidak seperti Reporting-Endpoints, ReportingObserver tidak merekam jenis laporan lain seperti pelanggaran CSP atau COOP/COEP.
• Anda harus bereaksi terhadap pelanggaran ini secara real-time. ReportingObserver memungkinkan Anda melampirkan callback ke peristiwa pelanggaran.
• Anda ingin melampirkan informasi tambahan ke laporan untuk membantu proses penelusuran bug, menggunakan callback kustom.

Perbedaan lainnya adalah ReportingObserver hanya dikonfigurasi di sisi klien: Anda dapat menggunakannya meskipun Anda tidak memiliki kontrol atas header sisi server dan tidak dapat menetapkan Reporting-Endpoints.

Bacaan lebih lanjut

• Panduan migrasi dari Reporting API v0 ke v1
• ReportingObserver
• Spesifikasi: Reporting API lama (v0)
• Spesifikasi: Reporting API baru (v1)

Gambar banner besar oleh Nine Koepfer / @enka80 di Unsplash, diedit. Terima kasih banyak kepada Ian Clelland, Eiji Kitamura, dan Milica Mihajlija atas ulasan dan saran mereka terkait dokumen ini.