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 ti informa sugli errori che si verificano nel tuo sito quando i visitatori lo utilizzano. Offre visibilità su interventi e arresti anomali del browser, violazioni dei criteri di sicurezza dei contenuti Violazioni COOP/COEP, avvisi di ritiro e altro ancora.

È disponibile una nuova versione dell'API di reporting. La nuova API è più snella e ha maggiori probabilità supportati 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 versione 1 utilizzando la nuova intestazione (Reporting-Endpoints), ma mantieni l'intestazione precedente per un po' di tempo (Report-To). Consulta Migrazione: codice di esempio.

Se aggiungi subito la funzionalità di generazione di report al tuo sito: 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 di endpoint o ne utilizzi uno proprio, puoi aspettarti più traffico man mano che o sviluppatori esterni eseguono la migrazione all'API di reporting v1 (intestazione Reporting-Endpoints).

Continua a leggere per ulteriori dettagli e per conoscere il codice di esempio.

Logging degli errori di rete

Verrà sviluppato un nuovo meccanismo per il logging degli errori di rete. Una volta disponibile, passa dalla versione 0 dell'API di reporting al nuovo meccanismo.

Demo e codice

• Sito demo: nuova API di reporting (v1)
• Codice per il sito demo

Differenze tra v0 e v1

Che cosa cambia

• La superficie dell'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. Per saperne di più, consulta la procedura di migrazione.
• La versione v0 non è e non sarà supportata nei browser. La versione v1 ha maggiori probabilità di essere supportata su più browser in futuro.

Che cosa rimane invariato

• Il formato e la struttura dei report non subiranno modifiche.
• La richiesta inviata dal browser all'endpoint rimane una richiesta POST di Content-type application/reports+json.
• La mappatura di alcuni endpoint a determinati tipi di report è supportata sia nella versione v0 che nella versione v1.
• Il ruolo dell'endpoint default non è stato modificato.

• La versione 1 dell'API di reporting non ha alcun impatto su ReportingObserver. ReportingObserver continua ad avere accesso a tutti i report osservabili e il suo formato è identici.

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 gestendo una Raccogliere report come servizio, aspettarsi più traffico verso quell'endpoint.

Questo perché i report non vengono raggruppati con l'API di reporting v1 come lo sono con l'API di reporting v0. Pertanto, man mano che gli sviluppatori di applicazioni iniziano a eseguire la migrazione alla versione 1 dell'API di reporting, il numero di report rimangono simili, ma il volume di richieste al server endpoint aumenterà.

Sviluppatori di applicazioni: eseguire la migrazione a Reporting-Endpoints (v1)

Cosa dovresti fare?

Usare la nuova API di reporting (v1) offre diversi vantaggi ✅:

• Gli indicatori del browser sono positivi, il che significa il supporto tra browser è previsto per la versione v1 (a differenza della versione v0 supportata solo in Chrome e Edge).
• L'API è più fluida.
• È in corso lo sviluppo di strumenti relativi alla nuova API di reporting (v1).

Alla luce di questo:

• Se il tuo sito utilizza già la versione v0 dell'API di reporting con l'intestazione Report-To, esegui la migrazione alla API di reporting v1 (consulta la procedura di migrazione). Se il tuo sito utilizza già funzionalità di segnalazione in caso di violazioni delle norme sulla sicurezza dei contenuti, consulta la procedura di migrazione specifica per la generazione di report CSP.
• Se il tuo sito non utilizza già l'API di reporting e ora aggiungi la funzionalità di generazione di report: Utilizzare la nuova API di reporting (v1) (intestazione Reporting-Endpoints). C'è un'eccezione questo: se devi usare il logging degli errori di rete, usa Report-To (v0). Logging degli errori di rete al momento non è supportato nella versione 1 dell'API di reporting. Un nuovo meccanismo per il logging degli errori di rete da sviluppare, fino a quando non sarà disponibile, utilizza la versione 0 dell'API di reporting. Se hai bisogno del logging degli errori di rete insieme ad altri tipi di report, utilizza entrambi i tipi di report: Report-To (v0) e Reporting-Endpoints (v1). v0 fornisce il logging degli errori di rete, mentre v1 fornisce report di tutti gli altri tipi.

Passi per la migrazione

L'obiettivo di questa migrazione è non perdere i report che utilizzavi nella versione 0.

1. Passaggio 1 (fai ora): utilizza entrambe le intestazioni: Report-To (v0) e Reporting-Endpoints (v1).

   In questo modo ottieni:

   • Report dei client Chrome ed Edge più recenti grazie a Reporting-Endpoints (v1).
   • Report dai client Chrome ed Edge meno recenti grazie a Report-To (v0).

   Le istanze del browser che supportano Reporting-Endpoints utilizzeranno Reporting-Endpoints e istanze che non faranno di riserva a Report-To. Il formato della richiesta e del report è lo stesso per v0 e v1.

2. Passaggio 2 (da fare ora): assicurati che l'intestazione Reporting-Endpoints sia impostata su tutte le risposte che potrebbe generare report.

   Con la versione v0, puoi scegliere di impostare gli endpoint di segnalazione solo su alcune risposte e altri documenti (pagine) su quell'origine userebbero il filtro "ambient" endpoint. Con v1, a causa della differenza devi impostare l'intestazione Reporting-Endpoints su tutte le risposte che potrebbero generare report.

3. Passaggio 3 (inizia più tardi): dopo che tutti gli utenti o la maggior parte degli utenti avranno eseguito l'aggiornamento a Chrome o Edge successivi installazioni (96 e successive), rimuovi Report-To (v0) e conserva solo Reporting-Endpoints.

   Un'eccezione: se hai bisogno di report di Logging degli errori di rete, mantieni Report-To fino a quando per il logging degli errori di rete.

Guarda esempi di codice nel libro di ricette sulla migrazione.

Passaggi di migrazione per i report CSP

Ci sono due modi per Content-Security-Policy le segnalazioni di violazioni possono essere configurate:

• Con l'intestazione CSP da sola tramite l'istruzione report-uri. Questo ha un ampio supporto browser, su Chrome, Firefox, Safari ed Edge. I report vengono inviati con il tipo di contenuti application/csp-report e avere un formato specifico per CSP. Questi report sono chiamati "Report CSP di livello 2" e fare non fare affidamento sull'API di reporting.
• Con l'API di reporting, è tramite l'intestazione Report-To (legacy) o una versione più recente Reporting-Endpoints (v1). Questa funzionalità è supportata solo in Chrome ed Edge. Le richieste di report hanno stesso formato delle altre richieste dell'API di reporting e dello 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 impostare i report per tutti i tipi di report, nonché 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 insieme all'approccio basato sull'API di reporting (Report-To o migliore, Reporting-Endpoints) per poter ottenere segnalazioni di violazioni CSP da più browser. In un browser che riconosce report-uri e report-to, report-uri verrà ignorato se report-to è presente. In un browser che riconosce solo report-uri, verrà considerato 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 e i browser che supportano supporto report-to(Chrome, Edge) utilizzerà report-to. Per specificare gli endpoint denominati, utilizzerai in report-to, utilizza entrambe le intestazioni Report-To e Reporting-Endpoints. In questo modo avrai la certezza report dei client Chrome ed Edge più vecchi e più recenti.

2. Passaggio 3 (inizia più tardi): dopo che tutti o la maggior parte degli utenti avranno eseguito l'aggiornamento a Chrome o Edge successivi installazioni (96 e successive), rimuovi Report-To (v0) e conserva solo Reporting-Endpoints. Conserva report-uri in modo da continuare a ricevere report per i browser che lo supportano.

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 segnalazioni di violazioni per un COOP (Cross-Origin-Opener-Policy intestazione), un COEP (Cross-Origin-Embedder-Policy) o un criterio del documento (intestazione Document-Policy): non è necessario modificare le intestazioni dei criteri durante la migrazione all'API di reporting v1. Ti serve soltanto eseguire la migrazione dall'intestazione Report-To precedente alla nuova Intestazione Reporting-Endpoints.

Se utilizzi la versione precedente dell'API di reporting (v0) per ricevere segnalazioni di violazioni per un CSP (intestazione Content-Security-Policy), potrebbe essere necessario modificare Content-Security-Policy come parte della la 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 può 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 Annulla schermata, modificata. Grazie mille a Ian Clelland, Eiji Kitamura e Milica Mihajlija per le loro recensioni e suggerimenti al riguardo. .