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 localmente o durante dello sviluppo perché utenti reali, reti reali e dispositivi reali cambia le regole del gioco. L'API di reporting consente di individuare alcuni di questi errori, ad esempio come violazioni della sicurezza o API deprecate e presto deprecate chiamate in tutto il sito e le trasmette a un endpoint specificato.

Ti permette di dichiarare ciò che vuoi monitorare tramite intestazioni HTTP. gestiti dal browser.

La configurazione dell'API di reporting garantisce che, quando gli utenti di questi tipi di errori, sarai in grado di 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 criteri per la sicurezza dei contenuti e criteri per i documenti. Non sai cosa fanno? Va bene, continuerai a essere in grado di comprendere questo esempio.

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 che il tuo codebase potrebbe utilizzare.

Per farlo, devi configurare un'intestazione Reporting-Endpoints e mappare questo 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 qualcosa di 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 di violazione CSP, un report di violazione delle norme relative ai documenti e un report report che individuano questi problemi.

Con un breve ritardo, fino a un minuto, il browser invia i report al configurato per questo tipo di violazione. I report vengono inviati fuori banda dal browser stesso (non dal tuo server né dal tuo sito).

Gli endpoint ricevono questi report.

Ora puoi accedere ai report su questi endpoint e monitorare cosa non ha funzionato. Sei pronto per 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 configurato. Invia richieste con le seguenti caratteristiche:

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

Ecco i dati che puoi trovare in ciascuno di questi report:

Report con credenziali

Gli endpoint di reporting 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 in merito alla segnalazione. della ad esempio se l'account di un determinato utente causa errori in modo coerente o se una determinata sequenza di azioni intraprese su altre pagine attiva un report su questa pagina.

Quando e in che modo il browser invia i report?

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

Ciò significa che quando utilizzi l'API di reporting, il rendimento è minimo o nullo.

I report vengono inviati con un ritardo (fino a un minuto) per aumentare le probabilità di inviarli in batch. In questo modo si risparmia larghezza di banda rispetto alla connessione di rete dell'utente, soprattutto importanti sui dispositivi mobili. Il browser può anche ritardare la pubblicazione se è impegnato a elaborare una priorità più alta al lavoro o se l'utente si trova su una rete lenta e/o congestionata in quel momento.

Problemi relativi a terze parti e proprietari

Verranno inviati i report generati a causa di violazioni o ritiri che si verificano sulla tua pagina agli endpoint che hai configurato. Sono incluse le violazioni commesse da script di terze parti. in esecuzione sulla tua pagina.

Eventuali violazioni o ritiri che si sono verificati in un iframe multiorigine incorporato nella tua pagina non essere segnalati ai tuoi endpoint (almeno non per impostazione predefinita). Un iframe potrebbe configurare il proprio generazione di report e persino report sul servizio di reporting proprietario del proprio sito; ma così è. al sito nel frame. Inoltre, tieni presente che la maggior parte dei report viene generata solo se la norma di una pagina viene violata, e che le norme della tua pagina e quelle dell'iframe sono diverse.

Esempio con ritiri

Supporto browser

La tabella riportata di seguito riassume il supporto dei browser per la versione 1 dell'API di reporting, ovvero Reporting-Endpoints. Il supporto del browser per l'API di reporting v0 (intestazione Report-To) è uguale, tranne che per un tipo di report: Logging degli errori di rete non è supportato nella nuova API di reporting. Per maggiori dettagli, leggi la guida alla migrazione.

Questa tabella riassume solo il supporto per report-to con la nuova intestazione Reporting-Endpoints. Leggi i suggerimenti per la migrazione dei report CSP se vuoi eseguire la migrazione a Reporting-Endpoints.

Utilizzo dell'API di reporting

Decidi dove inviare i report

Avete due opzioni:

• Inviare report a un servizio di raccolta report esistente.
• Invia report a un raccoglitore di report creato e gestito da te.

Opzione 1: utilizza un servizio di raccoglitore di report esistente

Ecco alcuni esempi di servizi di raccolta di report:

• uri del report
• uriport

Se sei a conoscenza di altre soluzioni, segnalaci un problema e aggiorneremo questo post.

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

• Questo raccoglitore supporta tutti i tipi di report? Ad esempio, non tutte le soluzioni endpoint di reporting supportare i report COOP/COEP.
• Ti senti a tuo agio nel condividere gli URL della tua applicazione con un raccoglitore di report di terze parti? Anche se il browser rimuove informazioni sensibili da questi URL, le informazioni sensibili potrebbero trapelare in questo modo. Se sembra troppo rischioso per gestire il tuo endpoint di reporting.

Opzione 2: crea e utilizza il tuo raccoglitore di report

Creare un server che riceva i report non è così semplice. Per iniziare, puoi creare un fork boilerplate leggero. È realizzato con Express e può ricevere e visualizzare report.

1. Vai al raccoglitore del report boilerplate.

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

3. Ora hai il tuo clone! Puoi personalizzarlo in base alle tue esigenze.

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

• Controlla se ci sono richieste POST con un valore Content-Type di application/reports+json per riconoscere i report richieste 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 le opzioni 1 e 2

Potresti voler lasciare che un determinato fornitore si occupi di alcuni tipi di report, ma disporre di un servizio interno soluzione 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 uno o una serie di valori separati da virgole coppie chiave-valore:

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 imposta sia Reporting-Endpoints sia Report-To. Consulta i dettagli nella guida alla migrazione. In particolare, se utilizzi i report per Content-Security-Policy violazioni 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 endpoint)

Ogni chiave può essere un nome a tua scelta, ad esempio main-endpoint o endpoint-1. Puoi decidere di impostare endpoint con nomi diversi per un report diverso di tipo, ad esempio my-coop-endpoint e my-csp-endpoint. In questo modo può indirizzare le segnalazioni a endpoint diversi a seconda del loro tipo.

Se vuoi ricevere intervento, ritiro 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 (anche se verranno generati).

Valori (URL)

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

L'URL di un 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 usarne uno un unico endpoint per tutti i criteri.

Dove impostare l'intestazione?

Nella nuova API di reporting, che verrà trattata in questo post: i report hanno come ambito i documenti. Ciò significa che per un dato di origine, diversi documenti, come site.example/page1 site.example/page2, possono inviare report a endpoint diversi.

Per ricevere segnalazioni su violazioni o ritiri, devi imposta l'intestazione come middleware in tutte le risposte.

Ecco un esempio in 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 criteri

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

Puoi utilizzare più endpoint per più criteri o usare diversi più endpoint in tutti i criteri.

report-to non è necessario per il ritiro, l'intervento e l'arresto anomalo report. Questi report non sono legati a nessun criterio. Vengono generate a condizione che è stato configurato un endpoint default e viene inviato 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

Esempio di codice

Per vedere tutte queste funzionalità nel contesto, di seguito è riportato un esempio di server Node che utilizza Express e raggruppa tutti gli argomenti trattati in questo articolo. Mostra come configurare i report per diversi tipi di report e visualizzare i risultati.

Eseguire il debug della configurazione dei report

Generare deliberatamente report

Quando configuri l'API di reporting, è probabile che tu debba violare intenzionalmente i tuoi criteri per verificare se i report vengono generati e inviati come previsto. Per vedere un codice di esempio che viola le norme e fa altre cose dannose che generare report di tutti i tipi, consulta la demo.

Risparmia tempo

I report possono essere inviati con un ritardo, circa un minuto, un tempo lungo durante il debug. ↓ Per fortuna, quando esegui il debug in Chrome, puoi usare il flag --short-reporting-delay per ricevere i report non appena vengono generati.

Esegui questo comando nel terminale per attivare questo flag:

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

Utilizza DevTools

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

A partire da ottobre 2021, questa funzionalità è sperimentale. Per utilizzarlo, segui questi passaggi:

1. Utilizza Chrome versione 96 o successive (controlla digitando chrome://version nel browser).
2. Digita o incolla chrome://flags/#enable-experimental-web-platform-features nella barra dell'URL di Chrome.
3. Fai clic su Attivato.
4. Riavvia il browser.
5. Apri Chrome DevTools.
6. In Chrome DevTools, apri Impostazioni. In Esperimenti, fai clic su Attiva il riquadro dell'API di reporting in nel riquadro Applicazione.
7. Ricarica DevTools.
8. Ricarica la pagina. I report generati dalla pagina in cui è aperto DevTools saranno elencato in Chrome DevTools Riquadro Applicazione, in 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 correttamente o meno.

Risoluzione dei problemi

I report non vengono generati o non vengono inviati come previsto all'endpoint? Di seguito sono riportati alcuni suggerimenti per la risoluzione dei problemi.

I report non vengono generati

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

• Controlla report-to nelle norme. Se questa configurazione non è corretta, non verrà generato. Vai a Modificare le norme per per risolvere il problema. Un altro modo per risolvere il problema è controllare la console DevTools in Chrome: nella console per la violazione prevista, significa che probabilmente il criterio configurato correttamente.
• Tieni presente che saranno aperti solo i report generati per il documento DevTools verranno visualizzate in questo elenco. Un esempio: se il tuo sito site1.example incorpora un iframe site2.example che viola un criterio e, di conseguenza, genera un report. Questo report verrà visualizzato in DevTools solo se apri in una finestra separata e apri DevTools per quella finestra.

I report vengono generati, ma non inviati o non ricevuti

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

• Assicurati di utilizzare ritardi brevi. Forse il report non viene visualizzato perché non è stato ancora inviato.

• Controlla la configurazione dell'intestazione Reporting-Endpoints. Se c'è un problema, invia una segnalazione è stato generato correttamente non verrà inviato. In DevTools, lo stato del report rimarrà invariato Queued (potrebbe passare a Pending e poi tornare rapidamente a Queued quando un tentativo di consegna è in questo caso. Ecco alcuni errori comuni che possono causare questo problema:

• L'endpoint è 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 il ritiro e l'intervento verranno inviati solo all'endpoint denominato default. Per saperne di più, consulta Configurare l'intestazione Reporting-Endpoint.

• Cerca eventuali problemi di sintassi delle intestazioni dei criteri, ad esempio le virgolette mancanti. Visualizza dettagli.

• Verifica che l'endpoint possa gestire le richieste in entrata.

  • Assicurati che il tuo 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 simili i dati inviati dal 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 deve rispondere con un codice di operazione riuscita (200 o un altro codice di risposta di operazione riuscita 2xx). In caso contrario, c'è un problema con la sua configurazione.

Meccanismi di segnalazione correlati

Solo report

Le intestazioni dei criteri -Report-Only e Reporting-Endpoints funzionano insieme.

Endpoint configurati in Reporting-Endpoints e specificati nel campo report-to di Content-Security-Policy, Cross-Origin-Embedder-Policy e Cross-Origin-Opener-Policy riceverà segnalazioni in caso di violazione di queste norme.

Gli endpoint configurati in Reporting-Endpoints possono essere specificati anche in report-to campo di Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only e Cross-Origin-Opener-Policy-Report-Only Inoltre, riceveranno segnalazioni in caso di violazione di queste norme.

Anche se i report vengono inviati in entrambi i casi, le intestazioni -Report-Only non applicano criteri: niente è infranto o bloccato, ma riceverai report su ciò che sarebbe non funzionante o bloccato.

ReportingObserver

L'API JavaScript di ReportingObserver può aiutarti 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.

Usa ReportingObserver se:

• Vuoi monitorare solo i ritiri e/o gli interventi del browser. ReportingObserver mostra avvisi lato client, ad esempio ritiri e gli interventi del browser, ma a differenza di Reporting-Endpoints, acquisire altri tipi di segnalazioni, come violazioni di CSP o COOP/COEP.
• Devi reagire a queste violazioni in tempo reale. ReportingObserver marche puoi allegare un callback a un evento di violazione.
• Vuoi collegare a un report informazioni aggiuntive per facilitare il debug, mediante il callback personalizzato.

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

Per approfondire

• Guida alla migrazione dall'API di reporting da v0 a v1
• ReportingObserver
• Specifica: API di reporting precedente (v0)
• Specifica: nuova API di reporting (v1)

Immagine hero di Nine Koepfer / @enka80 su Annulla schermata, modificato. Ringraziamo Ian Clelland, Eiji Kitamura e Milica Mihajlija per le loro recensioni e i loro suggerimenti su questo articolo.