Monitor uw webapplicatie met de Reporting API

Gebruik de rapportage-API om beveiligingsschendingen, verouderde API-aanroepen en meer te monitoren.

Maud Nalpas

Sommige fouten doen zich alleen voor in de productieomgeving. Je ziet ze niet lokaal of tijdens de ontwikkeling, omdat echte gebruikers , echte netwerken en echte apparaten de situatie veranderen. De Reporting API helpt bij het opsporen van een aantal van deze fouten, zoals beveiligingsschendingen of verouderde en binnenkort te vervallen API-aanroepen op je site, en stuurt ze door naar een door jou opgegeven eindpunt.

Hiermee kun je via HTTP-headers aangeven wat je wilt monitoren, en het wordt door de browser uitgevoerd.

Door de rapportage-API in te stellen, weet u zeker dat u op de hoogte bent wanneer gebruikers dit soort fouten tegenkomen, zodat u ze kunt verhelpen.

In dit artikel wordt uitgelegd wat deze API kan doen en hoe je hem kunt gebruiken. Laten we beginnen!

Overzicht

Laten we ervan uitgaan dat uw site, site.example , een Content-Security-Policy en een Document-Policy heeft. Weet u niet wat deze doen? Geen probleem, u zult dit voorbeeld nog steeds begrijpen.

Je besluit je site te monitoren om te weten wanneer deze beleidsregels worden overtreden, maar ook omdat je wilt controleren of je codebase verouderde of binnenkort verouderde API's gebruikt.

Om dit te doen, configureert u een Reporting-Endpoints header en koppelt u deze eindpuntnamen waar nodig met behulp van de report-to richtlijn in uw beleid.

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, waardoor sommige gebruikers deze regels overtreden.

Voorbeelden van overtredingen

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 rapport over schendingen van het CSP, een rapport over schendingen van het documentbeleid en een rapport over verouderde functionaliteit, waarin deze problemen worden vastgelegd.

Met een korte vertraging – tot maximaal een minuut – stuurt de browser de rapporten vervolgens naar het eindpunt dat is geconfigureerd voor dit type overtreding. De rapporten worden door de browser zelf verzonden (niet door uw server of uw website).

Het/de eindpunt(en) ontvangt/ontvangen deze rapporten.

Je hebt nu toegang tot de rapporten over deze eindpunten en kunt zien wat er mis is gegaan. Je bent klaar om het probleem op te lossen dat je gebruikers treft.

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

Gebruiksscenario's en rapporttypen

De rapportage-API kan worden geconfigureerd om u te helpen bij het monitoren van allerlei interessante waarschuwingen of problemen die zich op uw site voordoen:

Rapporten

De browser stuurt rapporten naar het door u geconfigureerde eindpunt. De verzonden verzoeken zien er als volgt uit:

POST
Content-Type: application/reports+json

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

Hieronder vindt u de gegevens die in elk van deze rapporten te vinden zijn:

Gecertificeerde rapporten

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

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

Wanneer en hoe verzendt de browser rapporten?

Rapporten worden buiten de normale communicatiekanalen van uw website verzonden : de browser bepaalt wanneer ze naar de geconfigureerde eindpunten worden gestuurd. Er is ook geen manier om te bepalen wanneer de browser rapporten verzendt; deze verzamelt, plaatst in een wachtrij en verzendt ze automatisch op een geschikt moment.

Dit betekent dat er bij gebruik van de rapportage-API nauwelijks tot geen prestatieproblemen zijn.

Rapporten worden met een vertraging van maximaal een minuut verzonden om de kans te vergroten dat rapporten in batches worden verzonden. Dit bespaart bandbreedte en ontziet de netwerkverbinding van de gebruiker, wat vooral belangrijk is op mobiele apparaten. De browser kan de verzending ook vertragen als deze bezig is met het verwerken van taken met een hogere prioriteit, of als de gebruiker op dat moment een trage of overbelaste netwerkverbinding heeft.

Derden- en eerste-partijkwesties

Rapporten die worden gegenereerd vanwege overtredingen of verouderde functionaliteit op uw pagina, worden verzonden naar de door u geconfigureerde eindpunten. Dit omvat ook overtredingen begaan door scripts van derden die op uw pagina worden uitgevoerd.

Schendingen of verouderde functionaliteit die plaatsvinden in een cross-origin iframe dat in uw pagina is ingesloten, worden niet aan uw endpoint(s) gerapporteerd (althans niet standaard). Een iframe kan zijn eigen rapportage instellen en zelfs rapporteren aan de rapportageservice van uw site – dat wil zeggen, de first-party service; maar dat is de verantwoordelijkheid van de site waarin het iframe is ingesloten. Houd er ook rekening mee dat de meeste rapporten alleen worden gegenereerd als het beleid van een pagina wordt geschonden, en dat het beleid van uw pagina en het beleid van het iframe verschillen.

Voorbeeld met verouderde functies

Browserondersteuning

De volgende tabel geeft een overzicht van de browserondersteuning voor de Reporting API v1 , oftewel met de Reporting-Endpoints header. De browserondersteuning voor de Reporting API v0 ( Report-To header) is hetzelfde, met uitzondering van één rapporttype: het loggen van netwerkfouten wordt niet ondersteund in de nieuwe Reporting API. Raadpleeg de migratiehandleiding voor meer informatie.

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

De rapportage-API gebruiken

Bepaal waar de rapporten naartoe moeten worden gestuurd.

Je hebt twee opties:

• Rapporten verzenden naar een bestaande rapportageservice.
• Stuur rapporten naar een rapportagesysteem dat u zelf bouwt en beheert.

Optie 1: Gebruik een bestaande rapportverzamelservice

Enkele voorbeelden van diensten voor het verzamelen van rapporten zijn:

• rapport-uri
• uriports

Als je andere oplossingen kent, open dan een issue om ons dit te laten weten, dan werken we dit bericht bij!

Naast de prijs zijn de volgende punten belangrijk bij het kiezen van een rapportverzamelaar: 🧐

• Ondersteunt deze collector alle rapporttypen? Niet alle oplossingen voor rapportage-endpoints ondersteunen bijvoorbeeld COOP/COEP-rapporten.
• Vindt u het verantwoord om URL's van uw applicatie te delen met een externe partij die rapporten verzamelt? Zelfs als de browser gevoelige informatie uit deze URL's verwijdert, kan gevoelige informatie op deze manier alsnog uitlekken . Als dit te riskant lijkt voor uw applicatie, kunt u beter uw eigen rapportage-eindpunt beheren.

Optie 2: Bouw en beheer uw eigen rapportverzamelaar.

Het bouwen van een eigen server die rapporten ontvangt, is niet zo eenvoudig. Om te beginnen kun je onze lichte boilerplate forken. Deze is gebouwd met Express en kan rapporten ontvangen en weergeven.

Wanneer u uw eigen rapportverzamelaar bouwt:

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

Optie 3: Combineer optie 1 en 2.

U kunt ervoor kiezen om bepaalde soorten rapporten door een specifieke leverancier te laten genereren, terwijl u voor andere rapporten een interne oplossing hebt.

Stel in dit geval meerdere eindpunten als volgt in:

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

Configureer de Reporting-Endpoints header

Stel een Reporting-Endpoints -antwoordheader in. De waarde ervan moet bestaan ​​uit één of meerdere door komma's gescheiden sleutel-waardeparen:

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

Als u migreert van de oude Reporting API naar de nieuwe Reporting API, is het wellicht verstandig om zowel Reporting-Endpoints als Report-To in te stellen. Zie de migratiehandleiding voor meer informatie. Als u met name rapportage gebruikt voor schendingen van Content-Security-Policy met alleen de report-uri richtlijn, raadpleeg dan de migratiestappen voor CSP-rapportage .

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 ervoor kiezen om verschillende benoemde eindpunten in te stellen voor verschillende rapporttypen, bijvoorbeeld my-coop-endpoint , my-csp-endpoint . Hiermee kunt u rapporten naar verschillende eindpunten routeren, afhankelijk van hun type.

Als u meldingen wilt ontvangen over interventies , afschrijvingen , crashes of een combinatie hiervan, stelt u een eindpunt in met de naam default .

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

Waarden (URL's)

Elke waarde is een URL naar keuze, waarnaar de rapporten worden verzonden. De URL die u hier instelt, is afhankelijk van uw keuze in stap 1.

Een eindpunt-URL:

• Moet beginnen met een schuine streep ( / ). Relatieve paden worden niet ondersteund.
• Het kan om een ​​verbinding tussen verschillende bronnen gaan; in dat geval worden de inloggegevens echter 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"

Je kunt vervolgens elk benoemd eindpunt in het juiste beleid gebruiken, of één enkel eindpunt in alle beleidsregels gebruiken.

Waar moet de koptekst worden geplaatst?

In de nieuwe Reporting API – die in dit artikel wordt besproken – zijn rapporten gekoppeld aan documenten . Dit betekent dat voor één bepaalde oorsprong verschillende documenten, zoals site.example/page1 en site.example/page2 , rapporten naar verschillende eindpunten kunnen sturen.

Om meldingen te ontvangen over overtredingen of verouderde functionaliteiten op een willekeurige pagina van uw site, stelt u 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}