Monitorare l'applicazione web con l'API di reporting

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

Maud Nalpas

Alcuni errori si verificano solo in produzione. Non li vedrai localmente o durante lo sviluppo perché utenti reali, reali reti e reali dispositivi fanno la differenza. L'API Reporting consente di rilevare alcuni di questi errori, come violazioni della sicurezza o chiamate API ritirate e in procinto di essere ritirate nel tuo sito, e di trasmetterli a un endpoint specificato.

Ti consente di dichiarare cosa vuoi monitorare tramite le intestazioni HTTP ed è gestito dal browser.

La configurazione dell'API Reporting ti consente di sapere quando gli utenti riscontrano questi tipi di errori, in modo da poterli correggere.

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

Demo e codice

Prova l'API Reporting 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 Content-Security-Policy e un Document-Policy. Non sai cosa fanno? Non preoccuparti, riuscirai comunque a comprendere questo esempio.

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

A tale scopo, configura un'intestazione Reporting-Endpoints e mappa questi nomi di endpoint tramite la direttiva 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, caricata 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 del CSP, un report di violazione delle norme relative ai documenti e un report di ritiro che rilevano questi problemi.

Dopo 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 tuo server né dal tuo sito).

Gli endpoint ricevono questi report.

Ora puoi accedere ai report su questi endpoint e monitorare cosa non va. Ora 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 Reporting può essere configurata per aiutarti a monitorare molti tipi di avvisi o problemi interessanti che si verificano nel 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 report di esempio

[
  {
    "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 ciascuno 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 genera errori in modo coerente o se una determinata sequenza di azioni intraprese in altre pagine attiva un report in questa pagina.

Quando e come il browser invia i report?

I report vengono pubblicati al di fuori del tuo sito: il browser controlla quando vengono inviati agli endpoint configurati. Inoltre, non è possibile controllare quando il browser invia i report: li acquisisce, li mette in coda e li invia automaticamente al momento opportuno.

Ciò significa che non ci sono problemi di rendimento quando utilizzi l'API Reporting.

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 per rispettare la connessione di rete dell'utente, aspetto particolarmente importante su dispositivi mobili. Il browser può anche ritardare l'invio se è impegnato a elaborare attività di priorità più elevata o se l'utente si trova su una rete lenta e/o congestionata.

Problemi relativi a dati proprietari e di terze parti

I report generati a causa di violazioni o ritiri nella 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 i ritiri avvenuti in un iframe cross-origin incorporato nella tua pagina non verranno segnalati ai tuoi endpoint (almeno non per impostazione predefinita). Un iframe potrebbe configurare i propri report e persino inviare report al servizio di generazione di report del tuo sito, ovvero proprietario, ma dipende dal sito incorniciato. Tieni inoltre presente che la maggior parte dei report viene generata solo se vengono violate le norme di una pagina e che le norme della tua pagina e quelle dell'iframe sono diverse.

Esempio con ritiri

Supporto browser

La tabella seguente riassume il supporto del browser per l'API di reporting v1, ovvero con l'intestazioneReporting-Endpoints. Il supporto del browser per la versione 0 dell'API Reporting (intestazione Report-To) è lo stesso, tranne per un tipo di report: la registrazione degli errori di rete non è supportata nella nuova API Reporting. Per maggiori dettagli, leggi la guida alla migrazione.

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

Utilizzo dell'API Reporting

Decidi dove inviare i report

Avete due opzioni:

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

Opzione 1: utilizza un servizio di raccolta dei report esistente

Ecco alcuni esempi di servizi di raccolta dei report:

• report-uri
• uriports

Se conosci altre soluzioni, apri un problema per comunicarcelo e aggiorneremo questo post.

Oltre al prezzo, prendi in considerazione i seguenti punti quando selezioni un collettore di report: 🧐

• Questo raccoglitore supporta tutti i tipi di report? Ad esempio, non tutte le soluzioni di endpoint per i report supportano 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 le informazioni sensibili da questi URL, queste potrebbero essere divulgate in questo modo. Se ti sembra troppo rischioso per la tua applicazione, utilizza il tuo endpoint di generazione di report.

Opzione 2: crea e gestisci il tuo raccoglitore di report

Creare un server che riceva i report non è così banale. Per iniziare, puoi eseguire il fork del nostro boilerplate leggero. È stato creato con Express e può ricevere e visualizzare i report.

1. Vai al collettore di report boilerplate.

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

3. Ora hai il tuo clone. Puoi personalizzarlo per le tue esigenze.

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

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

Opzione 3: combina le opzioni 1 e 2

Potresti voler lasciare che un fornitore specifico si occupi di alcuni tipi di report, 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 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 esegui la migrazione dall'API di reporting precedente alla nuova API di reporting, potrebbe essere opportuno impostare entrambi Reporting-Endpoints e Report-To. Consulta la guida alla migrazione per ulteriori dettagli. In particolare, se utilizzi i report per le violazioniContent-Security-Policy solo tramite la direttiva report-uri, consulta i passaggi per la migrazione ai 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 tipi di report diversi, ad esempio my-coop-endpoint, my-csp-endpoint. In questo modo, puoi indirizzare i report a diversi endpoint a seconda del tipo.

Se vuoi ricevere report su interventi, ritiro e/o arresti anomali, imposta un endpoint denominato default.

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

Valori (URL)

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

Un URL endpoint:

• Deve iniziare con una barra (/). I percorsi relativi non sono supportati.
• Può essere cross-origin, 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 o un singolo endpoint in tutti i criteri.

Dove impostare l'intestazione?

Nella nuova API di reporting, quella descritta in questo post, i report sono limitati ai 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 su violazioni o ritiri in qualsiasi pagina del tuo sito, imposta l'intestazione come middleware su 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();
});

Modificare i criteri

Ora che l'intestazione Reporting-Endpoints è configurata, aggiungi una direttiva 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 per i vari criteri.

report-to non è necessario per i report di ritiro, intervento e arresto anomalo. Questi report non sono vincolati a nessun criterio. Vengono generati se è configurato un endpoint default 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

Esempio di codice

Per vedere tutto questo nel contesto, di seguito è riportato un esempio di server Node che utilizza Express e riunisce tutti gli elementi discussi in questo articolo. Mostra come configurare i report per diversi tipi di report e ne mostra i risultati.

Eseguire il debug della configurazione dei report

Generare intenzionalmente report

Quando configuri l'API Reporting, probabilmente dovrai 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 compie altre azioni dannose che generano report di tutti i tipi, dai un'occhiata alla demo.

Risparmia tempo

I report potrebbero essere inviati con un ritardo di circa un minuto, un tempo lungo per il debug. 😴 Fortunatamente, durante il debug in Chrome puoi utilizzare 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

Utilizzare 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 e 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 Abilita il riquadro API Reporting nel riquadro Applicazione.
7. Ricarica DevTools.
8. Ricarica la pagina. I report generati dalla pagina in cui è aperto DevTools verranno elencati nel riquadro Applicazione di Chrome DevTools, in API 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 inviati come previsto al tuo endpoint? Ecco alcuni suggerimenti per risolvere il problema.

I report non vengono generati

I report visualizzati in DevTools sono stati generati correttamente. Se il report che ti aspetti non compare in questo elenco:

• Seleziona report-to nelle tue norme. Se questa impostazione non è configurata correttamente, non verrà generato un report. Per risolvere il problema, vai a Modificare le norme. Un altro modo per risolvere il problema è controllare la console DevTools in Chrome: se nella console viene visualizzato un errore relativo alla 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. Un esempio: se il tuo sito site1.example incorpora un iframe site2.example che viola una norma e genera un report, questo report verrà visualizzato in DevTools solo se apri l'iframe nella relativa finestra e apri DevTools per quella finestra.

I report vengono generati, ma non vengono inviati o ricevuti

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

• Assicurati di utilizzare tempi di attesa brevi. Forse non riesci a vedere un report perché non è stato ancora inviato.

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

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

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

• L'endpoint default non è presente. Alcuni tipi di report, come i report di ritiro e intervento, verranno inviati solo all'endpoint denominato default. Scopri di più in Configurare l'intestazione Reporting-Endpoints.

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

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

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

  • Testa il comportamento dell'endpoint. Per farlo, anziché generare manualmente i report, puoi emulare il browser inviando all'endpoint richieste che assomigliano a quelle che invierà 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 deve rispondere con un codice di successo (200 o un altro codice di risposta di successo 2xx). In caso contrario, esiste un problema con la configurazione.

Meccanismi di generazione di report correlati

Solo report

Le intestazioni dei criteri -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 report in caso di violazione di questi criteri.

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

Sebbene i report vengano inviati in entrambi i casi, le intestazioni -Report-Only non applicano le norme: non si verificheranno errori o blocchi, ma riceverai report su ciò che avrebbe causato errori o blocchi.

ReportingObserver

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

L'intestazione ReportingObserver e Reporting-Endpoints generano report apparentemente uguali, ma consentono casi d'uso leggermente diversi.

Utilizza ReportingObserver se:

• Vuoi monitorare solo i ritiri e/o gli interventi del browser. ReportingObserver mostra avvisi lato client come ritiri e interventi del browser, ma a differenza di Reporting-Endpoints, non registra altri tipi di segnalazioni, come violazioni di 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 viene configurato solo lato client: puoi utilizzarlo anche se non hai alcun controllo sulle intestazioni lato server e non puoi impostare Reporting-Endpoints.

Per approfondire

• Guida alla migrazione dall'API Reporting v0 alla v1
• ReportingObserver
• Specifiche: API Reports precedente (v0)
• Specifiche: nuova API Reporting (v1)

Immagine hero di Nine Koepfer / @enka80 su Unsplash, modificata. Un grande ringraziamento a Ian Clelland, Eiji Kitamura e Milica Mihajlija per le loro recensioni e i loro suggerimenti su questo articolo.