Je web-app monitoren met de Reporting API

Gebruik de Reporting API om onder andere beveiligingsschendingen en beëindigde API-aanroepen te controleren.

Maud Nalpas

Sommige fouten treden alleen op in de productieomgeving. Je ziet ze niet lokaal of tijdens de ontwikkeling, omdat echte gebruikers, echte netwerken en echte apparaten de game veranderen. Met de Reporting API kun je sommige van deze fouten opsporen, zoals beveiligingsschendingen of beëindigde en binnenkort beëindigde API-aanroepen op je site, en deze doorsturen naar een eindpunt dat je hebt opgegeven.

Hiermee kun je aangeven wat je wilt bijhouden met HTTP-headers. De functie wordt uitgevoerd door de browser.

Als je de Reporting API instelt, weet je zeker dat je op de hoogte wordt gesteld als gebruikers dit soort fouten tegenkomen, zodat je ze kunt oplossen.

In deze post leggen we uit wat deze API kan doen en hoe je deze gebruikt. Laten we beginnen.

Overzicht

Stel dat uw site, site.example, een Content-Security-Policy en een Document-Policy heeft. Weet je niet wat deze doen? Dat is geen probleem, je kunt dit voorbeeld nog steeds begrijpen.

Je besluit je site te monitoren om te weten wanneer dit beleid wordt geschonden, maar ook omdat je beëindigde of binnenkort beëindigde API's die je codebase misschien gebruikt, in de gaten wilt houden.

Hiervoor stelt u een Reporting-Endpoints-header in en wijst u deze eindpuntnamen toe met de richtlijn report-to in uw beleid waar nodig.

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

Er gebeurt iets onvoorziens en deze beleidsregels worden geschonden voor sommige van je gebruikers.

Voorbeelden van schendingen

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, geladen door 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;

De browser genereert een CSP-schendingsrapport, een Document-Policy-schendingsrapport en een beëindigingsrapport waarin deze problemen worden vastgelegd.

Met een korte vertraging (maximaal een minuut) stuurt de browser de rapporten naar het eindpunt dat is ingesteld voor dit schendingstype. De rapporten worden out-of-band door de browser zelf gestuurd (niet door je server of je site).

De eindpunten krijgen deze rapporten.

Je hebt nu toegang tot de rapporten over deze eindpunten en kunt nagaan wat er is misgegaan. Je kunt nu beginnen met het oplossen van het probleem dat van invloed is op je gebruikers.

Voorbeeldrapport

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

Use cases en rapporttypen

Je kunt de Reporting API instellen om veel soorten interessante waarschuwingen of problemen op je site te volgen:

Rapporten

De browser stuurt rapporten naar het eindpunt dat je hebt ingesteld. Het stuurt verzoeken die er zo uitzien:

POST
Content-Type: application/reports+json

De payload van deze verzoeken is een lijst met rapporten.

Voorbeeldlijst met rapporten

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

In elk van deze rapporten vindt u de volgende gegevens:

Rapporten met inloggegevens

Rapportage-eindpunten met dezelfde oorsprong als de pagina die het rapport genereert, krijgen de inloggegevens (cookies) in de verzoeken die de rapporten bevatten.

Inloggegevens kunnen nuttige aanvullende context bieden over het rapport, bijvoorbeeld of het account van een bepaalde gebruiker consequent fouten activeert of dat een bepaalde reeks acties op andere pagina's een rapport op deze pagina activeert.

Wanneer en hoe stuurt de browser rapporten?

Rapporten worden out-of-band geleverd vanaf je site: de browser bepaalt wanneer ze naar de ingestelde eindpunten worden gestuurd. Je kunt ook niet bepalen wanneer de browser rapporten stuurt. De browser legt ze vast, zet ze in de wachtrij en stuurt ze automatisch op een geschikt moment.

Dit betekent dat er weinig tot geen prestatieproblemen zijn bij het gebruik van de Reporting API.

Rapporten worden met een vertraging verstuurd (maximaal een minuut) om de kans te vergroten dat rapporten in batches worden verstuurd. Dit bespaart bandbreedte om de netwerkverbinding van de gebruiker niet te veel te belasten. Dit is vooral belangrijk op mobiele apparaten. De browser kan de bezorging ook vertragen als deze bezig is met werk met een hogere prioriteit of als de gebruiker op dat moment een traag of overbelast netwerk gebruikt.

Problemen met derden en first-party problemen

Rapporten die worden gegenereerd vanwege schendingen of beëindigingen op je pagina, worden naar de eindpunten gestuurd die je hebt ingesteld. Dit omvat ook schendingen die worden begaan door scripts van derden die op uw pagina worden uitgevoerd.

Schendingen of beëindigingen die in een cross-origin iframe zijn gebeurd dat op uw pagina is ingesloten, worden niet aan uw eindpunt(en) gerapporteerd (in ieder geval niet standaard). Een iframe kan een eigen rapportage instellen en zelfs rapporteren aan de rapportageservice van uw site, dat wil zeggen de rapportageservice van de first-party. Dit is echter aan de ingelijste site. De meeste rapporten worden alleen gegenereerd als het beleid van een pagina wordt geschonden. Het beleid van je pagina en het beleid van het iframe verschillen.

Voorbeeld met beëindigingen

Browserondersteuning

In de volgende tabel staat de browserondersteuning voor de Reporting API v1, die de Reporting-Endpoints-header gebruikt. De browserondersteuning voor de Reporting API v0 (Report-To-header) is hetzelfde, behalve voor één rapporttype: Network Error Logging wordt niet ondersteund in de nieuwe Reporting API. Lees de migratiehandleiding voor meer informatie.

Deze tabel bevat alleen een overzicht van de ondersteuning voor report-to met de nieuwe kop Reporting-Endpoints. Lees de migratietips voor CSP-rapportage als u wilt migreren naar Reporting-Endpoints.

De Reporting API gebruiken

Bepalen waar rapporten naartoe moeten worden gestuurd

U heeft 2 mogelijkheden:

• Rapporten sturen naar een bestaande service voor rapportverzameling.
• Rapporten sturen naar een rapportverzamelaar die je zelf maakt en beheert.

Optie 1: Gebruik een bestaande service voor rapportverzameling

Dit zijn enkele voorbeelden van services voor rapportverzameling:

• report-uri
• uriports
• HeaderHawk
• Sentry

Als je andere oplossingen weet, open je een probleem om ons dit te laten weten. We updaten deze post dan.

Houd naast de prijs ook rekening met de volgende punten als je een rapportverzamelaar selecteert: 🧐

• Ondersteunt deze verzamelaar alle rapporttypen? Niet alle oplossingen voor rapportage-eindpunten ondersteunen bijvoorbeeld COOP-/COEP-rapporten.
• Vind je het goed om de URL's van je app te delen met een externe rapportverzamelaar? Zelfs als de browser gevoelige informatie uit deze URL's verwijdert, kan gevoelige informatie op deze manier worden gelekt. Als dit te riskant is voor je app, kun je je eigen rapportage-eindpunt gebruiken.

Optie 2: Je eigen rapportverzamelaar maken en gebruiken

Het is niet eenvoudig om een eigen server te bouwen die rapporten ontvangt. Je kunt aan de slag door onze lichtgewicht boilerplate te forken. Deze is gemaakt met Express en kan rapporten ontvangen en weergeven.

Als je je eigen rapportverzamelaar maakt, gebeurt het volgende:

• Controleer op POST-verzoeken met een Content-Type van application/reports+json om rapportverzoeken te herkennen die door de browser naar je eindpunt zijn gestuurd.
• Als je eindpunt zich op een andere bron bevindt dan je site, zorg je dat het CORS-preflightverzoeken ondersteunt.

Optie 3: Combineer optie 1 en 2

Misschien wilt u dat een specifieke provider bepaalde typen rapporten afhandelt, maar heeft u een interne oplossing voor andere typen.

Stel in dit geval meerdere eindpunten in:

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

De Reporting-Endpoints-kop instellen

Stel een reactieheader Reporting-Endpoints in. De waarde moet een of een reeks door komma's gescheiden sleutel-waardeparen zijn:

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

Als u migreert van de verouderde Reporting API naar de nieuwe Reporting API, is het misschien handig om zowel Reporting-Endpoints als Report-To in te stellen. Ga naar de migratiehandleiding voor meer informatie. Als u rapportage voor Content-Security-Policy schendingen gebruikt met alleen de report-uri-richtlijn, neemt u de migratiestappen voor CSP-rapportage door.

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

Sleutels (eindpuntnamen)

Elke sleutel kan een naam naar keuze zijn, zoals main-endpoint of endpoint-1. U kunt verschillende benoemde eindpunten instellen voor verschillende rapporttypen, bijvoorbeeld my-coop-endpoint, my-csp-endpoint. Hiermee kun je rapporten naar verschillende eindpunten routeren, afhankelijk van het type.

Als je rapporten over interventie, beëindiging, crash of een combinatie hiervan wilt krijgen, stel je een eindpunt met de naam default in.

Als de kop Reporting-Endpoints geen default-eindpunt definieert, worden rapporten van dit type niet gestuurd (hoewel ze wel worden gegenereerd).

Waarden (URL's)

Elke waarde is een URL van uw keuze waarnaar de rapporten worden gestuurd. De URL die u hier instelt, hangt af van wat u in stap 1 heeft besloten.

Een eindpunt-URL:

• Moet beginnen met een slash (/). Relatieve paden worden niet ondersteund.
• Kan cross-origin zijn, maar in dat geval worden de inloggegevens niet met de rapporten meegestuurd.

Voorbeelden

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

U kunt elk benoemd eindpunt dan in het juiste beleid gebruiken of één eindpunt voor alle beleidsregels gebruiken.

Waar stel je de koptekst in?

In de nieuwe Reporting API (die in dit bericht wordt behandeld) vallen rapporten onder documenten. Dit betekent dat voor één bepaalde oorsprong verschillende documenten, zoals site.example/page1 en site.example/page2, rapporten naar verschillende eindpunten kunnen sturen.

Als je een rapport wilt krijgen over schendingen of beëindigingen op een pagina van je site, stel je de header in als middleware voor alle reacties.

Hier is een voorbeeld 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();
});

Uw beleid bewerken

Nu de Reporting-Endpoints-header is ingesteld, voeg je een report-to-instructie toe aan elke beleidsheader waarvoor je schendingsrapporten wilt krijgen. De waarde van report-to moet een van de benoemde eindpunten zijn die u heeft ingesteld.

Je kunt het eindpunt voor meerdere beleidsregels gebruiken of verschillende eindpunten gebruiken voor verschillende beleidsregels.

report-to is niet nodig voor rapporten over beëindiging, interventie en crash. Deze rapporten zijn niet gebonden aan een beleid. Ze worden gegenereerd zolang er een default eindpunt is ingesteld en worden naar dit default eindpunt gestuurd.

Voorbeeld

# 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

Fouten in uw rapportage-instellingen opsporen

Rapporten genereren

Als je de Reporting API instelt, moet je waarschijnlijk opzettelijk je beleid schenden om te controleren of rapporten worden gegenereerd en verstuurd zoals verwacht.

Tijd besparen

Rapporten kunnen met een vertraging worden gestuurd, ongeveer een minuut, wat een lange tijd is bij het debuggen. 😴 Gelukkig kun je bij het debuggen in Chrome de flag --short-reporting-delay gebruiken om rapporten te krijgen zodra ze zijn gemaakt.

Voer deze opdracht uit in je terminal om deze vlag aan te zetten:

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

DevTools gebruiken

Gebruik DevTools in Chrome om de rapporten te bekijken die zijn gestuurd of worden gestuurd.

Sinds oktober 2021 is deze functie experimenteel. Volg deze stappen om de functie te gebruiken:

1. Gebruik Chrome-versie 96 en hoger (check dit door chrome://version in je browser te typen).
2. Typ of plak chrome://flags/#enable-experimental-web-platform-features in de adresbalk van Chrome.
3. Klik op Aangezet.
4. Start uw browser opnieuw.
5. Open Chrome DevTools.
6. Open Instellingen in Chrome DevTools. Klik onder Experimenten op Het deelvenster Reporting API aanzetten in het deelvenster Applicatie.
7. Laad DevTools opnieuw.
8. Laad de pagina opnieuw. Rapporten die worden gegenereerd door de pagina waarop DevTools is geopend, worden vermeld in het deelvenster Applicatie van Chrome DevTools, onder Reporting API.

Rapportstatus

In de kolom Status staat of een rapport is verstuurd.

Meldingen worden na een tijdje verwijderd, of ze nu wel of niet zijn verstuurd.

Problemen oplossen

Worden rapporten niet gegenereerd of niet naar verwachting naar je eindpunt gestuurd? Hier zijn een paar tips om dit probleem op te lossen.

Er worden geen rapporten gemaakt

Rapporten die in DevTools worden getoond, zijn correct gegenereerd. Als het rapport dat u verwacht niet in deze lijst staat:

• Controleer report-to in je beleid. Als dit verkeerd is ingesteld, wordt er geen rapport gemaakt. Ga naar Uw beleid bewerken om dit op te lossen. Je kunt dit ook oplossen door de DevTools-console in Chrome te checken. Als er een fout in de console verschijnt voor de schending die je verwachtte, betekent dit waarschijnlijk dat je beleid correct is ingesteld.
• Alleen de rapporten die zijn gegenereerd voor het document waarin DevTools is geopend, worden in deze lijst getoond. Een voorbeeld: Als je site site1.example een iframe insluit site2.example dat een beleid schendt en daarom een rapport genereert, wordt dit rapport alleen in DevTools getoond als je het iframe in een eigen venster opent en DevTools voor dat venster opent.

Rapporten worden gegenereerd, maar niet gestuurd of niet ontvangen

Wat als je een rapport kunt zien in DevTools, maar je eindpunt het niet krijgt?

• Gebruik korte vertragingen. Misschien is de reden dat je een rapport niet kunt zien, dat het nog niet is verstuurd.

• Controleer de Reporting-Endpoints-headerconfiguratie. Als er een probleem is, wordt een correct gegenereerd rapport niet gestuurd. In DevTools blijft de status van het rapport Queued (de status kan verspringen naar Pending en dan snel terug naar Queued als er een bezorgpoging wordt gedaan). Enkele veelvoorkomende fouten die dit kunnen veroorzaken:

• Het eindpunt wordt gebruikt, maar is niet ingesteld. Voorbeeld:

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

• Het eindpunt default ontbreekt. Sommige rapporttypen, zoals beëindigings- en interventierapporten, worden alleen naar het eindpunt met de naam default gestuurd. Lees meer in De header Reporting-Endpoints configureren.

• Zoek naar problemen in de syntaxis van je beleidskoppen, zoals ontbrekende aanhalingstekens. Details bekijken.

• Controleer of uw eindpunt inkomende verzoeken kan verwerken.

  • Zorg dat je eindpunt CORS-pre-flightverzoeken ondersteunt. Als dat niet het geval is, kan het geen rapporten krijgen.

  • Test het gedrag van je eindpunt. In plaats van handmatig rapporten te genereren, kun je de browser nabootsen door verzoeken naar je eindpunt te sturen die lijken op wat de browser zou sturen. Voer het volgende uit:

  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
  

  Je eindpunt moet reageren met een succescode (200 of een andere succesreactiecode 2xx). Als dit niet gebeurt, is er een probleem met de configuratie.

Gerelateerde rapportagemechanismen

Alleen rapportage

-Report-Only beleidsheaders en de Reporting-Endpoints werken samen.

Eindpunten die zijn ingesteld in Reporting-Endpoints en zijn ingevoerd in het veld report-to van Content-Security-Policy, Cross-Origin-Embedder-Policy en Cross-Origin-Opener-Policy, krijgen rapporten als deze beleidsregels worden geschonden.

Eindpunten die zijn ingesteld in Reporting-Endpoints kunnen ook worden ingevoerd in het veld report-to van Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only en Cross-Origin-Opener-Policy-Report-Only. Ze krijgen ook rapporten als dit beleid wordt geschonden.

In beide gevallen worden rapporten gestuurd, maar met -Report-Only-headers wordt het beleid niet afgedwongen. Er gaat niets stuk en er wordt niets geblokkeerd, maar je krijgt wel rapporten over wat er stuk zou zijn gegaan of zou zijn geblokkeerd.

ReportingObserver

Met de ReportingObserver JavaScript API kunt u waarschuwingen aan de clientzijde waarnemen.

De kop ReportingObserver en de kop Reporting-Endpoints genereren rapporten die er hetzelfde uitzien, maar ze maken net iets andere use cases mogelijk.

Gebruik ReportingObserver in de volgende gevallen:

• Je wilt alleen beëindigingen of browserinterventies bijhouden. ReportingObserver geeft waarschuwingen aan de clientzijde, zoals beëindigingen en browserinterventies, maar in tegenstelling tot Reporting-Endpoints worden er geen andere typen rapporten vastgelegd, zoals CSP- of COOP/COEP-schendingen.
• Je moet in realtime op deze schendingen reageren. ReportingObserver maakt het mogelijk om een callback aan een schendingsgebeurtenis te koppelen.
• Je wilt aanvullende informatie aan een rapport toevoegen om te helpen bij het debuggen, met behulp van de aangepaste callback.

Een ander verschil is dat ReportingObserver alleen aan de clientzijde is ingesteld: je kunt het zelfs gebruiken als je geen controle hebt over headers aan de serverzijde en Reporting-Endpoints niet kunt instellen.

Aanvullende informatie

• Migratiehandleiding van Reporting API v0 naar v1
• ReportingObserver
• Specificatie: verouderde Reporting API (v0)
• Specificatie: nieuwe Reporting API (v1)

Met dank aan Ian Clelland, Eiji Kitamura en Milica Mihajlija voor hun beoordelingen en suggesties voor dit document.