Monitorare l'applicazione web con l'API di reporting

Utilizza l'API di reporting per monitorare le violazioni della sicurezza, le chiamate API ritirate e altro ancora.

Maud Nalpas

Alcuni errori si verificano solo in produzione. Non li vedrai a livello locale o durante lo sviluppo, perché utenti reali, reti reali e dispositivi reali cambiano le regole del gioco. L'API di reporting consente di rilevare alcuni di questi errori, ad esempio violazioni della sicurezza o chiamate API deprecate e presto in fase di ritiro nel sito, e le trasmette a un endpoint da te specificato.

Ti consente di dichiarare cosa vuoi monitorare tramite intestazioni HTTP e viene gestito dal browser.

La configurazione dell'API di reporting ti dà la tranquillità che, quando gli utenti riscontrano questi tipi di errori, lo saprai e potrai correggerli.

Questo post spiega cosa può fare questa API e come utilizzarla. Iniziamo.

Demo e codice

Guarda l'API di reporting in azione a partire da Chrome 96 e versioni successive (Chrome beta o Canary, a partire da ottobre 2021).

Panoramica

Supponiamo che il tuo sito, site.example, abbia un criterio di sicurezza dei contenuti e un criterio di documento. Non sai a cosa servono? Questo esempio non è male.

Decidi di monitorare il tuo sito per sapere quando queste norme vengono violate, ma anche perché vuoi tenere d'occhio le API deprecate o che verranno presto ritirate dal tuo codebase.

Per farlo, configura un'intestazione Reporting-Endpoints e mappa i nomi di questi endpoint tramite l'istruzione report-to nei tuoi criteri, se necessario.

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

Si verifica un evento imprevisto e queste norme vengono violate per alcuni dei tuoi utenti.

Esempi di violazioni

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, caricato da 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;

Il browser genera un report sulle violazioni CSP, un report sulle violazioni delle norme relative ai documenti e un report sul ritiro che acquisiscono questi problemi.

Con un breve ritardo (fino a un minuto), il browser invia i report all'endpoint configurato per questo tipo di violazione. I report vengono inviati out-of-band dal browser stesso (non dal server né dal sito).

Gli endpoint ricevono questi report.

Ora puoi accedere ai report su questi endpoint e monitorare che cosa non ha funzionato. Puoi iniziare a risolvere il problema che interessa i tuoi utenti.

Report di esempio

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

Casi d'uso e tipi di report

L'API di reporting può essere configurata per aiutarti a monitorare molti tipi di avvisi o problemi interessanti che si verificano sul tuo sito:

Report

Che aspetto hanno i report?

Il browser invia i report all'endpoint che hai configurato. Invia richieste che hanno il seguente aspetto:

POST
Content-Type: application/reports+json

Il payload di queste richieste è un elenco di report.

Elenco di esempio di report

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

Di seguito sono riportati i dati che puoi trovare in ognuno di questi report:

Report con credenziali

Gli endpoint dei report che hanno la stessa origine della pagina che genera il report ricevono le credenziali (cookie) nelle richieste che contengono i report.

Le credenziali possono fornire un contesto aggiuntivo utile sul report, ad esempio se l'account di un determinato utente attiva in modo coerente errori o se una determinata sequenza di azioni intraprese su altre pagine attiva un report in questa pagina.

Quando e in che modo il browser invia le segnalazioni?

I report vengono pubblicati fuori banda dal tuo sito: il browser controlla quando vengono inviati agli endpoint configurati. Inoltre, non c'è modo di controllare quando il browser invia i report; li acquisisce, li mette in coda e li invia automaticamente al momento giusto.

Ciò significa che i problemi relativi alle prestazioni sono minimi o nulli quando si utilizza l'API di reporting.

I report vengono inviati con un ritardo (fino a un minuto) per aumentare le probabilità di inviarli in batch. Ciò consente di risparmiare larghezza di banda nel rispetto della connessione di rete dell'utente, il che è particolarmente importante sui dispositivi mobili. Il browser può anche ritardare la consegna se è impegnato a elaborare attività con priorità più alta o se l'utente si trova in una rete lenta e/o congestionata.

Problemi relativi a terze parti e proprietari

I report generati a causa di violazioni o deprecazioni in corso sulla tua pagina verranno inviati agli endpoint che hai configurato. Sono incluse le violazioni commesse da script di terze parti in esecuzione sulla tua pagina.

Le violazioni o le deprecazioni avvenute in un iframe multiorigine incorporato nella tua pagina non verranno segnalate ai tuoi endpoint (almeno non per impostazione predefinita). Un iframe potrebbe impostare i propri report e persino generare report al servizio di generazione di report del tuo sito, ovvero del proprietario, ma questo dipende dal sito con frame. Tieni inoltre presente che la maggior parte dei report viene generata solo in caso di violazione delle norme di una pagina e che le norme della pagina sono diverse da quelle dell'iframe.

Esempio con deprecazioni

Supporto del browser

La tabella riportata di seguito riassume il supporto dei browser per l'API di reporting v1, ossia con l'intestazione Reporting-Endpoints. Il supporto dei browser per l'API di reporting v0 (intestazione Report-To) è lo stesso, ad eccezione di un tipo di report: il logging degli errori di rete non è supportato nella nuova API di reporting. Leggi la guida alla migrazione per maggiori dettagli.

Questa tabella riassume solo il supporto per report-to con la nuova intestazione Reporting-Endpoints. Se intendi eseguire la migrazione a Reporting-Endpoints, leggi i suggerimenti per la migrazione dei report a CSP.

Utilizzo dell'API di reporting

Decidi dove inviare i report

Avete due opzioni:

• Inviare report a un servizio di raccolta report esistente.
• Invia i report a un raccoglitore di report che crei e gestisci autonomamente.

Opzione 1: utilizza un servizio di raccolta report esistente

Ecco alcuni esempi di servizi di raccolta dei report:

• report-uri
• uriport

Se conosci altre soluzioni, segnala un problema per comunicarcelo e provvederemo ad aggiornare questo post.

Oltre ai prezzi, considera i seguenti punti quando scegli un raccoglitore di report: 🧐

• Questo raccoglitore supporta tutti i tipi di report? Ad esempio, non tutte le soluzioni per endpoint di reporting supportano i report COOP/COEP.
• Sei a tuo agio nel condividere uno degli URL della tua applicazione con un raccoglitore di report di terze parti? Anche se il browser rimuove le informazioni sensibili da questi URL, le informazioni sensibili potrebbero essere divulgate in questo modo. Se questa situazione ti sembra troppo rischiosa per la tua applicazione, utilizza il tuo endpoint di reporting.

Opzione 2: crea e utilizza un raccoglitore di report personalizzato

Sviluppare un proprio server che riceve i report non è così banale. Per iniziare, puoi fork il nostro boilerplate leggero. È stata creata con Express e può ricevere e visualizzare i report.

1. Vai al raccoglitore di report boilerplate.

2. Fai clic su Remix per modificare per rendere il progetto modificabile.

3. Ora hai il tuo clone! Puoi personalizzarla per i tuoi scopi.

Se non utilizzi il boilerplate e stai creando il tuo server da zero:

• Verifica la presenza di richieste POST con un valore di Content-Type pari a application/reports+json per riconoscere le richieste di report inviate dal browser al tuo endpoint.
• Se l'endpoint si trova su un'origine diversa dal tuo sito, assicurati che supporti le richieste preflight CORS.

Opzione 3: combina l'opzione 1 e 2

Puoi scegliere di delegare alcuni tipi di report a un provider specifico, ma avere una soluzione interna per altri.

In questo caso, imposta più endpoint come segue:

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

Configura l'intestazione Reporting-Endpoints

Imposta un'intestazione della risposta Reporting-Endpoints. Il suo valore deve essere una o una serie di coppie chiave-valore separate da virgole:

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

Se stai eseguendo la migrazione dalla versione precedente dell'API di reporting alla nuova API di reporting, potrebbe essere opportuno impostare entrambi i valori Reporting-Endpoints e Report-To. Vedi i dettagli nella guida alla migrazione. In particolare, se utilizzi la segnalazione di violazioni Content-Security-Policy solo tramite l'istruzione report-uri, consulta la procedura di migrazione per i report CSP.

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

Chiavi (nomi di endpoint)

Ogni chiave può essere un nome a tua scelta, ad esempio main-endpoint o endpoint-1. Puoi decidere di impostare endpoint denominati diversi per tipi di report diversi, ad esempio my-coop-endpoint, my-csp-endpoint. In questo modo, puoi indirizzare i report a endpoint diversi a seconda del loro tipo.

Se vuoi ricevere report di interruzioni, deprecazione e/o arresto anomalo, imposta un endpoint denominato default.

Se l'intestazione Reporting-Endpoints non definisce alcun endpoint default, i report di questo tipo non verranno inviati (sebbene verranno generati).

Valori (URL)

Ogni valore è un URL a tua scelta a cui verranno inviati i report. L'URL da impostare qui dipende da ciò che hai deciso nel passaggio 1.

Un URL endpoint:

• Deve iniziare con una barra (/). I percorsi relativi non sono supportati.
• Può essere multiorigine, ma in questo caso le credenziali non vengono inviate con i report.

Esempi

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

Puoi quindi utilizzare ogni endpoint denominato nel criterio appropriato oppure utilizzare un singolo endpoint in tutti i criteri.

Dove impostare l'intestazione?

Nella nuova API di reporting, quella descritta in questo post, i report hanno come ambito documenti. Ciò significa che per una determinata origine, documenti diversi, come site.example/page1 e site.example/page2, possono inviare report a endpoint diversi.

Per ricevere report per violazioni o deprecazioni in qualsiasi pagina del sito, imposta l'intestazione come middleware su tutte le risposte.

Ecco un esempio in formato 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();
});

Modifica i tuoi criteri

Ora che l'intestazione Reporting-Endpoints è configurata, aggiungi un'istruzione report-to a ogni intestazione del criterio per cui vuoi ricevere i report sulle violazioni. Il valore di report-to deve essere uno degli endpoint denominati che hai configurato.

Puoi utilizzare più endpoint per più criteri o endpoint diversi nei vari criteri.

report-to non è necessario per i report sul ritiro, degli intervenzioni e sugli arresti anomali. Questi report non sono vincolati a nessun criterio. Vengono generati finché un endpoint default è configurato e vengono inviati a questo endpoint default.

Esempio

# 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

Codice di esempio

Per comprendere tutto questo nel contesto, di seguito è riportato un esempio di server nodo che utilizza Express e riunisce tutte le parti descritte in questo articolo. Mostra come configurare i report per diversi tipi di report e ne visualizza i risultati.

Esegui il debug della configurazione dei report

Generazione intenzionale di report

Durante la configurazione dell'API di reporting, è probabile che tu debba violare intenzionalmente le norme per verificare se i report vengono generati e inviati come previsto. Per vedere un codice di esempio che viola le norme e svolge altre azioni dannose che generano report di tutti i tipi, guarda la demo.

Risparmio di tempo

I report possono essere inviati con un ritardo di circa un minuto, ovvero un tempo lungo durante il debug. 🔍 Fortunatamente, durante il debug in Chrome puoi utilizzare il flag --short-reporting-delay per ricevere i report non appena vengono generati.

Per attivare il flag, esegui questo comando nel terminale:

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

Utilizza DevTools

In Chrome, utilizza DevTools per vedere i report che sono stati inviati o che verranno inviati.

A partire da ottobre 2021, questa funzionalità è sperimentale. Per utilizzarla, procedi nel seguente modo:

1. Utilizza Chrome 96 o versioni successive (controlla digitando chrome://version nel browser).
2. Digita o incolla chrome://flags/#enable-experimental-web-platform-features nella barra degli URL di Chrome.
3. Fai clic su Attivata.
4. Riavvia il browser.
5. Apri Chrome DevTools.
6. In Chrome DevTools, apri le Impostazioni. In Esperimenti, fai clic su Attiva il riquadro API di reporting nel riquadro Applicazione.
7. Ricarica DevTools.
8. Ricarica la pagina. I report generati dalla pagina in cui è aperto DevTools saranno elencati nel riquadro Applicazione di Chrome DevTools, nella sezione API di reporting.

Stato del report

La colonna Stato indica se un report è stato inviato correttamente.

I report vengono rimossi dopo un po' di tempo, indipendentemente dal fatto che siano stati inviati o meno.

Risoluzione dei problemi

I report non vengono generati o non vengono inviati come previsto all'endpoint? Ecco alcuni suggerimenti per risolvere questo problema.

I report non vengono generati

I report visualizzati in DevTools sono stati generati correttamente. Se il report previsto non è visualizzato in questo elenco:

• Controlla report-to nelle norme. Se non è configurata correttamente, non verrà generato un report. Vai a Modifica i criteri per risolvere questo problema. Un ulteriore modo per risolvere il problema è controllare la console DevTools in Chrome: se nella console viene visualizzato un errore per la violazione prevista, significa che probabilmente il criterio è configurato correttamente.
• Tieni presente che in questo elenco verranno visualizzati solo i report generati per il documento in cui è aperto DevTools. Ad esempio, se il tuo sito site1.example incorpora un iframe site2.example che viola una norma e quindi genera un report, questo report viene visualizzato in DevTools solo se apri l'iframe in una propria finestra e apri DevTools per quella finestra.

I report vengono generati, ma non inviati o non ricevuti

Cosa succede se riesci a visualizzare un report in DevTools, ma il tuo endpoint non lo riceve?

• Assicurati di utilizzare brevi ritardi. Forse non riesci a visualizzare una segnalazione perché non è stata ancora inviata.

• Controlla la configurazione dell'intestazione Reporting-Endpoints. In caso di problemi, un report generato correttamente non verrà inviato. In DevTools, lo stato del report rimarrà Queued (potrebbe passare a Pending e poi tornare rapidamente a Queued quando viene effettuato un tentativo di consegna) in questo caso. Ecco alcuni errori comuni che possono causare questa situazione:

• L'endpoint viene utilizzato, ma non configurato. Esempio:

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

• Endpoint default mancante. Alcuni tipi di report, come quelli su ritiro e intervento, verranno inviati solo all'endpoint denominato default. Per saperne di più, consulta Configurare l'intestazione Endpoint per i report.

• Cerca problemi nella sintassi delle intestazioni delle norme, ad esempio virgolette mancanti. Visualizza dettagli.

• Verifica che il tuo endpoint sia in grado di gestire le richieste in entrata.

  • Assicurati che l'endpoint supporti le richieste preflight CORS. In caso contrario, non potrà ricevere i report.

  • Testa il comportamento del tuo endpoint. Per farlo, anziché generare manualmente i report, puoi emulare il browser inviando al tuo endpoint richieste che saranno simili a quelle che invierebbe il browser. Esegui questo comando:

  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
  

  L'endpoint dovrebbe rispondere con un codice di operazione riuscita (200 o un altro codice di risposta di operazione riuscita 2xx). In caso contrario, si è verificato un problema con la sua configurazione.

Meccanismi di segnalazione correlati

Solo report

Le intestazioni del criterio -Report-Only e Reporting-Endpoints funzionano insieme.

Gli endpoint configurati in Reporting-Endpoints e specificati nel campo report-to di Content-Security-Policy, Cross-Origin-Embedder-Policy e Cross-Origin-Opener-Policy riceveranno dei report in caso di violazione di questi criteri.

Gli endpoint configurati in Reporting-Endpoints possono essere specificati anche nel campo report-to di Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only e Cross-Origin-Opener-Policy-Report-Only. Riceveranno inoltre dei report nel caso in cui queste norme vengano violate.

Sebbene i report vengano inviati in entrambi i casi, le intestazioni -Report-Only non applicano i criteri: nulla verrà interrotto o effettivamente bloccato, ma riceverai report relativi ai problemi che sarebbero stati bloccati o che potrebbero essere stati bloccati.

ReportingObserver

L'API JavaScript ReportingObserver può aiutarti a osservare gli avvisi lato client.

ReportingObserver e l'intestazione Reporting-Endpoints generano report che hanno lo stesso aspetto, ma consentono casi d'uso leggermente diversi.

Utilizza ReportingObserver se:

• Vuoi solo monitorare le deprecazioni e/o gli interventi del browser. ReportingObserver mostra avvisi lato client come ritiri e interventi sul browser, ma, a differenza di Reporting-Endpoints, non acquisisce altri tipi di segnalazioni, come violazioni CSP o COOP/COEP.
• Devi reagire a queste violazioni in tempo reale. ReportingObserver consente di allegare un callback a un evento di violazione.
• Vuoi allegare ulteriori informazioni a un report per facilitare il debug tramite il callback personalizzato.

Un'altra differenza è che ReportingObserver è configurato solo sul lato client: puoi utilizzarlo anche se non hai controllo sulle intestazioni lato server e non puoi impostare Reporting-Endpoints.

Per approfondire

• Guida alla migrazione dall'API di reporting v0 alla v1
• ReportingObserver
• 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.