Esegui la migrazione all'API di reporting v1

È disponibile una nuova versione dell'API di reporting. È più privato e ha maggiori probabilità di essere supportato su tutti i browser.

Maud Nalpas

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.

• 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 per Content-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

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, usa Report-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 valori Report-To (v0) e Reporting-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.

1. Passaggio 1 (da adesso): utilizza entrambe le intestazioni: Report-To (v0) e Reporting-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 utilizzeranno Reporting-Endpoints, mentre le istanze che non supportano Report-To. Il formato della richiesta e del report è lo stesso per v0 e v1.

2. 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.

3. 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 solo Reporting-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 contenuto application/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ù recente Reporting-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 contenuto application/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.

1. Passaggio 1 (fai ora): se non l'hai ancora aggiunto, aggiungi report-to insieme a report-uri. I browser che supportano solo report-uri (Firefox) utilizzeranno report-uri, mentre i browser che supportano anche report-to(Chrome, Edge) utilizzeranno report-to. Per specificare gli endpoint denominati che utilizzerai in report-to, utilizza entrambe le intestazioni Report-To e Reporting-Endpoints. In questo modo, riceverai i report dei client Chrome ed Edge precedenti e più recenti.

2. 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 solo Reporting-Endpoints. Mantieni report-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.