È disponibile una nuova versione dell'API di reporting. È più privato e ha maggiori probabilità di essere supportato su tutti i browser.
L'API di reporting informa gli errori che si verificano sul tuo sito quando i visitatori lo utilizzano. Ti offre visibilità su interventi del browser, arresti anomali del browser, violazioni dei criteri di sicurezza dei contenuti, violazioni delle norme COOP/COEP, avvisi sul ritiro e altro ancora.
È disponibile una nuova versione dell'API di reporting. La nuova API è più sana e ha maggiori probabilità di essere supportata su tutti i browser.
Riepilogo
Sviluppatori di siti
Se disponi già della funzionalità di generazione di report per il tuo sito: esegui la migrazione alla v1 utilizzando la nuova intestazione
(Reporting-Endpoints
), ma mantieni l'intestazione legacy per un po' di tempo (Report-To
).
Consulta Migrazione: codice di esempio.
Se stai aggiungendo la funzionalità di generazione di report al tuo sito adesso: utilizza solo la nuova intestazione
(Reporting-Endpoints
).
⚠️ In entrambi i casi, assicurati di impostare l'intestazione Reporting-Endpoints
su tutte le risposte che potrebbero generare report.
Sviluppatori di servizi di reporting
Se gestisci un servizio endpoint o ne gestisci uno autonomamente, aspettati più traffico man mano che
tu o gli sviluppatori esterni esegui la migrazione alla versione 1 dell'API di reporting (intestazione Reporting-Endpoints
).
Continua a leggere per dettagli e codice di esempio.
Registrazione degli errori di rete
Verrà sviluppato un nuovo meccanismo per la registrazione degli errori di rete. Quando sarà disponibile, passa dall'API di reporting v0 al nuovo meccanismo.
Demo e codice
- Sito dimostrativo: nuova API di reporting (v1)
- Codice del sito dimostrativo
Differenze tra v0 e v1
Che cosa cambia
- La superficie API è diversa.
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] } Document-Policy: ...; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Document-Policy: ...; report-to main-endpoint
- L'ambito del report è diverso.
Con la versione v0, puoi impostare endpoint di reporting solo per alcune risposte. Altri documenti (pagine) su questa origine userebbero automaticamente questi endpoint ambient.
Con la versione 1, devi impostare l'intestazione Reporting-Endpoints
per tutte le risposte che potrebbero generare
report.
- Entrambe le API supportano gli stessi tipi di report, con una sola eccezione: la versione 1 non supporta i report sugli errori di rete. Leggi ulteriori informazioni nella procedura di migrazione.
- La versione v0 non è e non sarà supportata su tutti i browser. È più probabile che la versione v1 venga supportata su più browser in futuro.
Che cosa rimane invariato
- Il formato e la struttura dei report rimangono invariati.
- La richiesta inviata dal browser all'endpoint rimane una richiesta
POST
perContent-type
application/reports+json
. - Sia nella versione v0 che nella versione 1 la mappatura di alcuni endpoint a determinati tipi di report è supportata.
- Il ruolo dell'endpoint
default
non è stato modificato. La versione 1 dell'API di reporting non ha alcun impatto su
ReportingObserver
.ReportingObserver
continua ad accedere a tutti i report osservabili e il loro formato è identico.
Tutte le differenze tra v0 e v1
API di reporting legacy (v0) Intestazione Report-To |
Nuova API di reporting (v1) Intestazione Reporting-Endpoints |
|
---|---|---|
Supporto del browser | Chrome 69 e versioni successive ed Edge 69 e versioni successive. | Chrome 96 e versioni successive ed Edge 96 e versioni successive. Firefox supporta. Safari non contesta. Visualizza gli indicatori del browser. |
Endpoint | Invia i report a uno dei più raccoglitori di report (più URL definiti per gruppo di endpoint). | Invia i report a raccoglitori di report specifici (è definito un solo URL per endpoint). |
Piattaforma API | Utilizza l'intestazione `Report-To` per configurare gruppi di endpoint denominati. |
Utilizza l'intestazione `Reporting-Endpoints` per configurare gli endpoint denominati. |
Tipi di report che possono essere generati tramite questa API |
|
Invariato, ad eccezione di Network Error Logging (NEL): non supportato nella nuova API di reporting (v1). |
Ambito del report | origine. L'intestazione Report-To di un documento influisce su altri documenti (pagine) provenienti da quell'origine.
Il campo url di un report continua a variare in base al documento.
|
Documento. L'intestazione Reporting-Endpoints di un documento ha effetto solo su quel documento.
Il campo url di un report continua a variare in base al documento.
|
Isolamento dei report (batch) | I diversi documenti (pagine) o siti/origini che generano un report nello stesso periodo e che hanno lo stesso endpoint di report verranno raggruppati: verranno inviati nello stesso messaggio all'endpoint di reporting. |
|
Supporto per bilanciamento del carico / priorità | Sì | No |
Sviluppatori di endpoint: aspettarsi più traffico
Se hai configurato il tuo server come endpoint di reporting o se stai sviluppando o mantenendo un raccoglitore di report come servizio, aspettati più traffico verso quell'endpoint.
Questo perché i report non vengono raggruppati nell'API di reporting v1, ma non nell'API di reporting v0. Pertanto, man mano che gli sviluppatori di applicazioni iniziano a eseguire la migrazione all'API di reporting v1, il numero di report rimarrà simile, ma il volume di richieste al server endpoint aumenterà.
Sviluppatori di applicazioni: esegui la migrazione a Reporting-Endpoints
(v1)
Cosa dovreste fare?
Usare la nuova API di reporting (v1) offre diversi vantaggi ✅:
- Gli indicatori del browser sono positivi, il che significa che la versione 1 (a differenza della versione v0, supportata solo in Chrome ed Edge) è prevista per il supporto di più browser.
- L'API è più snella.
- Gli strumenti sono stati sviluppati sulla base della nuova API di reporting (v1).
Tenendo conto di questo:
- Se il tuo sito utilizza già l'API di reporting v0 con l'intestazione
Report-To
, esegui la migrazione all'API di reporting v1 (consulta la procedura di migrazione). Se il tuo sito utilizza già la funzionalità di generazione di report per violazioni delle norme di sicurezza dei contenuti, consulta la procedura di migrazione specifica per i report CSP. - Se il tuo sito non utilizza già l'API di reporting e stai aggiungendo la funzionalità di generazione di report, utilizza la nuova API di reporting (v1) (l'intestazione
Reporting-Endpoints
). C'è un'eccezione a questo: se devi utilizzare la registrazione degli errori di rete, usaReport-To
(v0). Il logging degli errori di rete non è attualmente supportato nell'API di reporting v1. Verrà sviluppato un nuovo meccanismo per il logging degli errori di rete, finché non sarà disponibile, utilizza l'API di reporting v0. Se hai bisogno del logging degli errori di rete oltre ad altri tipi di report, utilizza entrambi i valoriReport-To
(v0) eReporting-Endpoints
(v1). La versione v0 fornisce la registrazione degli errori di rete, mentre la versione 1 fornisce report di tutti gli altri tipi.
Passi per la migrazione
L'obiettivo di questa migrazione è non perdere i report che utilizzavi con la versione v0.
Passaggio 1 (da adesso): utilizza entrambe le intestazioni:
Report-To
(v0) eReporting-Endpoints
(v1).che ti offre:
- Report dai client Chrome ed Edge più recenti grazie a
Reporting-Endpoints
(v1). - Report da client Chrome ed Edge meno recenti grazie a
Report-To
(v0).
Le istanze del browser che supportano
Reporting-Endpoints
utilizzerannoReporting-Endpoints
, mentre le istanze che non supportanoReport-To
. Il formato della richiesta e del report è lo stesso per v0 e v1.- Report dai client Chrome ed Edge più recenti grazie a
Passaggio 2 (operazione da eseguire ora): assicurati che l'intestazione
Reporting-Endpoints
sia impostata su tutte le risposte che potrebbero generare report.Con la versione v0 puoi scegliere di impostare gli endpoint dei report solo per alcune risposte, mentre altri documenti (pagine) in quell'origine utilizzeranno questo endpoint "ambiente". Con la versione 1, a causa della differenza nell'ambito, devi impostare l'intestazione
Reporting-Endpoints
su tutte le risposte che potrebbero generare report.Passaggio 3 (inizia più tardi): dopo che tutti o la maggior parte degli utenti hanno eseguito l'aggiornamento alle installazioni di Chrome o Edge successive (96 e versioni successive), rimuovi
Report-To
(v0) e conserva soloReporting-Endpoints
.Una eccezione: se ti servono i report Logging degli errori di rete, mantieni
Report-To
fino a quando non verrà implementato un nuovo meccanismo per il logging degli errori di rete.
Consulta gli esempi di codice nel libro di ricette sulla migrazione.
Passaggi per la migrazione per i report CSP
Esistono due modi per configurare i report sulle violazioni dei Criteri di sicurezza dei contenuti:
- Con la sola intestazione CSP tramite l'istruzione
report-uri
. Offre un ampio supporto dei browser per Chrome, Firefox, Safari ed Edge. I report vengono inviati con il tipo di contenutoapplication/csp-report
e hanno un formato specifico per CSP. Questi report sono chiamati "Report CSP di livello 2" e non si basano sull'API di reporting. - Con l'API di reporting, tramite l'intestazione
Report-To
(legacy) o la più recenteReporting-Endpoints
(v1). Questa funzionalità è supportata solo in Chrome ed Edge. Le richieste di report hanno lo stesso formato delle altre richieste dell'API di reporting e lo stesso tipo di contenutoapplication/reports+json
.
L'utilizzo del primo approccio (solo report-uri
) non è più consigliato e il secondo approccio offre alcuni vantaggi. In particolare, consente di utilizzare un unico modo per configurare i report per tutti i tipi di report e di impostare un endpoint generico (perché tutte le richieste di report generate tramite l'API di reporting⏤CSP e altri hanno lo stesso formato application/reports+json
).
Tuttavia, solo alcuni browser supportano report-to
.
Pertanto, ti consigliamo di mantenere report-uri
accanto all'approccio dell'API di reporting (Report-To
o meglio, Reporting-Endpoints
) per ricevere segnalazioni di violazioni CSP da più browser. In un browser che riconosce report-uri
e report-to
, report-uri
verrà ignorato se è presente report-to
. In un browser che riconosce solo report-uri
, verrà preso in considerazione solo report-uri
.
Passaggio 1 (fai ora): se non l'hai ancora aggiunto, aggiungi
report-to
insieme areport-uri
. I browser che supportano soloreport-uri
(Firefox) utilizzerannoreport-uri
, mentre i browser che supportano anchereport-to
(Chrome, Edge) utilizzerannoreport-to
. Per specificare gli endpoint denominati che utilizzerai inreport-to
, utilizza entrambe le intestazioniReport-To
eReporting-Endpoints
. In questo modo, riceverai i report dei client Chrome ed Edge precedenti e più recenti.Passaggio 3 (inizia più tardi): dopo che tutti o la maggior parte degli utenti hanno eseguito l'aggiornamento alle installazioni di Chrome o Edge successive (96 e versioni successive), rimuovi
Report-To
(v0) e conserva soloReporting-Endpoints
. Mantienireport-uri
per continuare a ricevere report per i browser che lo supportano soltanto.
Consulta gli esempi di codice per questi passaggi nella migrazione dei report CSP.
Migrazione: codice di esempio
Panoramica
Se utilizzi la versione precedente dell'API di reporting (v0) per ricevere report sulle violazioni per un'intestazione COOP (Cross-Origin-Opener-Policy
), COEP (Cross-Origin-Embedder-Policy
) o un criterio documento (Document-Policy
intestazione), non è necessario modificare personalmente queste intestazioni dei criteri durante la migrazione all'API di reporting v1. È necessario eseguire la migrazione dall'intestazione Report-To
legacy alla nuova
intestazione Reporting-Endpoints
.
Se utilizzi la versione precedente dell'API di reporting (v0) per ricevere report sulle violazioni per un CSP (intestazione Content-Security-Policy
), potresti dover modificare Content-Security-Policy
nell'ambito della migrazione alla nuova API di reporting (v1).
Migrazione di base
Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Tieni presente che con la versione 1 puoi comunque inviare tipi di report specifici a endpoint specifici. Ma puoi avere un solo URL per endpoint.
Osservazione di tutte le pagine
app.get("/", (request, response) => { response.set("Report-To", …) response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
// Use a middleware to set the reporting endpoint(s) for *all* requests. app.use(function(request, response, next) { response.set("Reporting-Endpoints", …); next(); }); app.get("/", (request, response) => { response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
Migrazione dei report CSP
Content-Security-Policy: ...; report-uri https://reports.example/main
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Report-To: main-endpoint="https://reports.example/main"
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Reporting-Endpoints: main-endpoint="https://reports.example/main" Report-To: ...
Per approfondire
- Monitorare l'applicazione web con l'API di reporting (post principale sull'API di reporting)
- Specifica: API di reporting precedente (v0)
- Specifica: nuova API di reporting (v1)
Immagine hero di Nine Koepfer / @enka80 su Unsplash, modificata. Grazie mille a Ian Clelland, Eiji Kitamura e Milica Mihajlija per le loro recensioni e suggerimenti su questo articolo.