Webanwendung mit der Reporting API überwachen

Mit der Reporting API können Sie Sicherheitsverstöße, eingestellte API-Aufrufe und mehr im Blick behalten.

Maud Nalpas

Einige Fehler treten nur in der Produktion auf. Lokal oder während der Entwicklung werden sie nicht angezeigt, da echte Nutzer, echte Netzwerke und echte Geräte das Spiel verändern. Die Reporting API hilft dabei, einige dieser Fehler zu erkennen, z. B. Sicherheitsverstöße oder eingestellte und bald eingestellte API-Aufrufe auf Ihrer Website, und überträgt sie an einen von Ihnen angegebenen Endpunkt.

Damit können Sie mithilfe von HTTP-Headern deklarieren, was Sie beobachten möchten. Die API wird vom Browser ausgeführt.

Wenn Sie die Reporting API einrichten, können Sie sicher sein, dass Sie über diese Art von Fehlern informiert werden, wenn sie bei Nutzern auftreten, und sie beheben können.

In diesem Beitrag wird beschrieben, was diese API kann und wie sie verwendet wird. Los gehts!

Übersicht

Angenommen, Ihre Website site.example hat eine Content-Security-Policy und eine Document-Policy. Sie wissen nicht, was diese Funktionen bewirken? Das ist kein Problem, Sie werden das Beispiel trotzdem verstehen.

Sie entscheiden sich, Ihre Website zu überwachen, um zu wissen, wann gegen diese Richtlinien verstoßen wird, aber auch, um ein Auge auf nicht mehr unterstützte oder bald nicht mehr unterstützte APIs zu haben, die in Ihrer Codebasis verwendet werden.

Dazu konfigurieren Sie einen Reporting-Endpoints-Header und ordnen diese Endpunktnamen bei Bedarf mit der Anweisung report-to in Ihren Richtlinien zu.

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

Es passiert etwas Unvorhergesehenes und diese Richtlinien werden für einige Ihrer Nutzer verletzt.

Beispiele für Verstöße

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 von 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;

Der Browser generiert einen CSP-Verstoßbericht, einen Bericht zu Verstößen gegen die Dokumentrichtlinie und einen Bericht zu veralteten Funktionen, in denen diese Probleme erfasst werden.

Mit einer kurzen Verzögerung von bis zu einer Minute sendet der Browser die Berichte dann an den Endpunkt, der für diesen Verstoßtyp konfiguriert wurde. Die Berichte werden vom Browser selbst (nicht von Ihrem Server oder Ihrer Website) Out-of-Band gesendet.

Die Endpunkte erhalten diese Berichte.

Sie können jetzt auf die Berichte zu diesen Endpunkten zugreifen und nachvollziehen, was schiefgelaufen ist. Sie können jetzt mit der Fehlerbehebung beginnen.

Beispielbericht

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

Anwendungsfälle und Berichtstypen

Die Reporting API kann so konfiguriert werden, dass Sie viele Arten von interessanten Warnungen oder Problemen auf Ihrer Website im Blick behalten können:

Berichte

Der Browser sendet Berichte an den von Ihnen konfigurierten Endpunkt. Es werden Anfragen gesendet, die so aussehen:

POST
Content-Type: application/reports+json

Die Nutzlast dieser Anfragen ist eine Liste von Berichten.

Beispielliste mit Berichten

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

Hier finden Sie die Daten, die in den einzelnen Berichten enthalten sind:

Berichte mit Anmeldedaten

Berichtsendpunkte, die denselben Ursprung haben wie die Seite, die den Bericht generiert, erhalten die Anmeldedaten (Cookies) in den Anfragen, die die Berichte enthalten.

Anmeldedaten können nützlichen zusätzlichen Kontext zum Bericht liefern, z. B. ob das Konto eines bestimmten Nutzers regelmäßig Fehler auslöst oder ob eine bestimmte Abfolge von Aktionen auf anderen Seiten einen Bericht auf dieser Seite auslöst.

Wann und wie sendet der Browser Berichte?

Berichte werden außerhalb des Bandes von Ihrer Website gesendet: Der Browser steuert, wann sie an die konfigurierten Endpunkte gesendet werden. Es gibt auch keine Möglichkeit, zu steuern, wann der Browser Berichte sendet. Er erfasst, stellt sie in die Warteschlange und sendet sie automatisch zu einem geeigneten Zeitpunkt.

Das bedeutet, dass es bei der Verwendung der Reporting API kaum oder gar keine Leistungsprobleme gibt.

Berichte werden mit einer Verzögerung von bis zu einer Minute gesendet, um die Wahrscheinlichkeit zu erhöhen, dass Berichte in Batches gesendet werden. Dadurch wird Bandbreite gespart, um die Netzwerkverbindung des Nutzers zu schonen, was besonders auf Mobilgeräten wichtig ist. Der Browser kann die Übermittlung auch verzögern, wenn er mit der Verarbeitung von Aufgaben mit höherer Priorität beschäftigt ist oder wenn der Nutzer zu diesem Zeitpunkt ein langsames oder überlastetes Netzwerk verwendet.

Probleme mit Drittanbieter- und Erstanbieter-Cookies

Berichte, die aufgrund von Verstößen oder Einstellungen, die auf Ihrer Seite stattfinden, generiert werden, werden an die von Ihnen konfigurierten Endpunkte gesendet. Dazu gehören auch Verstöße, die durch Drittanbieter-Scripts auf Ihrer Seite begangen werden.

Verstöße oder Einstellungen, die in einem ursprungsübergreifenden iFrame auf Ihrer Seite aufgetreten sind, werden nicht an Ihre Endpunkte gemeldet (zumindest nicht standardmäßig). Ein iFrame kann eigene Berichte einrichten und sogar Berichte an den Berichtsdienst deiner Website, also des Erstanbieters, senden. Das hängt jedoch von der Website ab, die im iFrame eingebettet ist. Beachten Sie außerdem, dass die meisten Berichte nur generiert werden, wenn gegen eine Richtlinie einer Seite verstoßen wird, und dass sich die Richtlinien Ihrer Seite von den Richtlinien des iFrames unterscheiden.

Beispiel mit Einstellungen

Unterstützte Browser

In der folgenden Tabelle wird die Browserunterstützung für die Reporting API v1 mit dem Header Reporting-Endpoints zusammengefasst. Die Browserunterstützung für die Reporting API v0 (Report-To-Header) ist identisch, mit Ausnahme eines Berichtstyps: Network Error Logging wird in der neuen Reporting API nicht unterstützt. Weitere Informationen finden Sie in der Migrationsanleitung.

In dieser Tabelle wird nur die Unterstützung für report-to mit dem neuen Reporting-Endpoints-Header zusammengefasst. Lesen Sie die Migrationstipps für CSP-Berichte, wenn Sie zu Reporting-Endpoints migrieren möchten.

Reporting API verwenden

Festlegen, wohin Berichte gesendet werden sollen

Es stehen zwei Optionen zur Verfügung:

• Berichte an einen vorhandenen Dienst zum Erfassen von Berichten senden
• Berichte an einen von Ihnen selbst erstellten und betriebenen Berichtscollector senden

Option 1: Vorhandenen Dienst zum Erfassen von Berichten verwenden

Beispiele für Berichtserfassungsdienste:

• report-uri
• uriports
• HeaderHawk
• Sentry

Wenn Sie andere Lösungen kennen, öffnen Sie ein Problem, um uns darüber zu informieren. Wir aktualisieren dann diesen Beitrag.

Berücksichtigen Sie bei der Auswahl eines Berichtskollektors neben dem Preis die folgenden Punkte: 🧐

• Unterstützt dieser Collector alle Berichtstypen? Beispielsweise unterstützen nicht alle Lösungen für Berichterstellungsendpunkte COOP-/COEP-Berichte.
• Sind Sie damit einverstanden, dass URLs Ihrer Anwendung an einen Drittanbieter für die Erfassung von Berichten weitergegeben werden? Selbst wenn der Browser vertrauliche Informationen aus diesen URLs entfernt, können vertrauliche Informationen auf diese Weise preisgegeben werden. Wenn Ihnen das für Ihre Anwendung zu riskant erscheint, sollten Sie einen eigenen Berichterstellungsendpunkt betreiben.

Option 2: Eigenen Berichtssammler erstellen und betreiben

Einen eigenen Server zu erstellen, der Berichte empfängt, ist nicht ganz einfach. Als Einstieg können Sie unser einfaches Boilerplate forken. Sie wurde mit Express erstellt und kann Berichte empfangen und anzeigen.

Wenn Sie einen eigenen Berichtscollector erstellen, gilt Folgendes:

• Suchen Sie nach POST-Anfragen mit einem Content-Type von application/reports+json, um Berichts-Anfragen zu erkennen, die vom Browser an Ihren Endpunkt gesendet wurden.
• Wenn sich Ihr Endpunkt auf einem anderen Ursprung als Ihre Website befindet, muss er CORS-Preflight-Anfragen unterstützen.

Option 3: Option 1 und 2 kombinieren

Möglicherweise möchten Sie bestimmte Arten von Berichten von einem bestimmten Anbieter erstellen lassen, für andere jedoch eine interne Lösung nutzen.

Legen Sie in diesem Fall mehrere Endpunkte so fest:

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

Reporting-Endpoints-Header konfigurieren

Legen Sie einen Reporting-Endpoints-Antwortheader fest. Der Wert muss ein oder mehrere kommagetrennte Schlüssel/Wert-Paare sein:

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

Wenn Sie von der alten Reporting API zur neuen Reporting API migrieren, kann es sinnvoll sein, beide Reporting-Endpoints und Report-To festzulegen. Weitere Informationen finden Sie in der Migrationsanleitung. Wenn Sie insbesondere die Berichterstellung für Content-Security-Policy-Verstöße nur mit der report-uri-Anweisung verwenden, lesen Sie die Migrationsschritte für die CSP-Berichterstellung.

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

Schlüssel (Endpunktnamen)

Jeder Schlüssel kann ein Name Ihrer Wahl sein, z. B. main-endpoint oder endpoint-1. Sie können für verschiedene Berichtstypen unterschiedliche benannte Endpunkte festlegen, z. B. my-coop-endpoint und my-csp-endpoint. Damit können Sie Berichte je nach Typ an verschiedene Endpunkte weiterleiten.

Wenn du Berichte zu Interventionen, eingestellten Funktionen, Abstürzen oder eine Kombination davon erhalten möchtest, richte einen Endpunkt mit dem Namen default ein.

Wenn im Reporting-Endpoints-Header kein default-Endpunkt definiert ist, werden Berichte dieses Typs nicht gesendet (obwohl sie generiert werden).

Werte (URLs)

Jeder Wert ist eine URL Ihrer Wahl, an die die Berichte gesendet werden. Die URL, die Sie hier festlegen, hängt davon ab, was Sie in Schritt 1 entschieden haben.

Eine Endpunkt-URL:

• Muss mit einem Schrägstrich (/) beginnen. Relative Pfade werden nicht unterstützt.
• Kann ursprungsübergreifend sein. In diesem Fall werden jedoch keine Anmeldedaten mit den Berichten gesendet.

Beispiele

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

Sie können dann jeden benannten Endpunkt in der entsprechenden Richtlinie oder einen einzelnen Endpunkt für alle Richtlinien verwenden.

Wo wird der Header festgelegt?

In der neuen Reporting API, um die es in diesem Beitrag geht, sind Berichte auf Dokumente beschränkt. Das bedeutet, dass für einen bestimmten Ursprung verschiedene Dokumente wie site.example/page1 und site.example/page2 Berichte an unterschiedliche Endpunkte senden können.

Wenn du Berichte zu Verstößen oder Einstellungen auf einer beliebigen Seite deiner Website erhalten möchtest, lege den Header als Middleware für alle Antworten fest.

Hier ein Beispiel 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();
});

Richtlinien bearbeiten

Nachdem der Header Reporting-Endpoints konfiguriert wurde, fügen Sie jedem Richtlinienheader, für den Sie Berichte zu Verstößen erhalten möchten, eine report-to-Anweisung hinzu. Der Wert von report-to sollte einer der benannten Endpunkte sein, die Sie konfiguriert haben.

Sie können den Endpunkt „multiple“ für mehrere Richtlinien oder verschiedene Endpunkte für verschiedene Richtlinien verwenden.

report-to ist für Berichte zu eingestellten Funktionen, Interventionen und Abstürzen nicht erforderlich. Diese Berichte sind an keine Richtlinie gebunden. Sie werden generiert, solange ein default-Endpunkt eingerichtet ist, und an diesen default-Endpunkt gesendet.

Beispiel

# 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

Fehlerbehebung bei der Berichtseinrichtung

Berichte absichtlich erstellen

Wenn Sie die Reporting API einrichten, müssen Sie wahrscheinlich absichtlich gegen Ihre Richtlinien verstoßen, um zu prüfen, ob Berichte wie erwartet erstellt und gesendet werden.

Zeit sparen

Berichte werden möglicherweise mit einer Verzögerung von etwa einer Minute gesendet. Das ist beim Debuggen eine lange Zeit. 😴 Glücklicherweise können Sie beim Debuggen in Chrome das Flag --short-reporting-delay verwenden, um Berichte zu erhalten, sobald sie generiert wurden.

Führen Sie diesen Befehl im Terminal aus, um das Flag zu aktivieren:

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

Entwicklertools verwenden

In Chrome können Sie mit den Entwicklertools die Berichte aufrufen, die gesendet wurden oder gesendet werden.

Seit Oktober 2021 ist diese Funktion experimentell. So verwenden Sie die Funktion:

1. Verwenden Sie Chrome-Version 96 oder höher (geben Sie chrome://version in Ihren Browser ein, um die Version zu prüfen).
2. Geben Sie chrome://flags/#enable-experimental-web-platform-features in die Adressleiste von Chrome ein oder fügen Sie es ein.
3. Klicken Sie auf Aktiviert.
4. Starten Sie den Browser neu.
5. Öffnen Sie die Chrome-Entwicklertools.
6. Öffne die Einstellungen in den Chrome-Entwicklertools. Klicken Sie unter „Tests“ auf Reporting API-Bereich im Anwendungsbereich aktivieren.
7. Laden Sie die Entwicklertools neu.
8. Laden Sie die Seite neu. Berichte, die von der Seite generiert werden, auf der die Entwicklertools geöffnet sind, werden in den Chrome-Entwicklertools im Bereich Anwendung unter Reporting API aufgeführt.

Berichtsstatus

In der Spalte Status sehen Sie, ob ein Bericht erfolgreich gesendet wurde.

Berichte werden nach einer Weile entfernt, unabhängig davon, ob sie gesendet wurden oder nicht.

Fehlerbehebung

Werden Berichte nicht generiert oder nicht wie erwartet an Ihren Endpunkt gesendet? Hier sind einige Tipps zur Fehlerbehebung.

Berichte werden nicht erstellt

Berichte, die in den Entwicklertools angezeigt werden, wurden korrekt erstellt. Wenn der erwartete Bericht nicht in dieser Liste angezeigt wird:

• Sehen Sie in Ihren Richtlinien nach, ob report-to erwähnt wird. Wenn dies falsch konfiguriert ist, wird kein Bericht generiert. Bearbeite deine Richtlinien, um das Problem zu beheben. Eine weitere Möglichkeit zur Fehlerbehebung besteht darin, die DevTools-Konsole in Chrome zu prüfen: Wenn in der Konsole ein Fehler für den erwarteten Verstoß angezeigt wird, ist Ihre Richtlinie wahrscheinlich richtig konfiguriert.
• In dieser Liste werden nur die Berichte angezeigt, die für das Dokument generiert wurden, in dem die Entwicklertools geöffnet sind. Beispiel: Wenn auf Ihrer Website site1.example ein iFrame site2.example eingebettet ist, der gegen eine Richtlinie verstößt und daher einen Bericht generiert, wird dieser Bericht in den DevTools nur angezeigt, wenn Sie den iFrame in einem eigenen Fenster öffnen und die DevTools für dieses Fenster öffnen.

Berichte werden generiert, aber nicht gesendet oder empfangen

Was passiert, wenn Sie einen Bericht in DevTools sehen, Ihr Endpunkt ihn aber nicht empfängt?

• Verwenden Sie kurze Verzögerungen. Vielleicht können Sie einen Bericht nicht sehen, weil er noch nicht gesendet wurde.

• Prüfen Sie die Konfiguration des Reporting-Endpoints-Headers. Wenn ein Problem auftritt, wird ein korrekt generierter Bericht nicht gesendet. In den DevTools bleibt der Status des Berichts in diesem Fall Queued (er kann zu Pending wechseln und dann schnell wieder zu Queued zurückkehren, wenn ein Zustellversuch unternommen wird). Häufige Fehler, die diesen Fehler verursachen können:

• Der Endpunkt wird verwendet, ist aber nicht konfiguriert. Beispiel:

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

• Der Endpunkt default fehlt. Einige Berichtstypen, z. B. Berichte zu Einstellungen und Interventionen, werden nur an den Endpunkt mit dem Namen default gesendet. Weitere Informationen finden Sie unter Header „Reporting-Endpoints“ konfigurieren.

• Suchen Sie nach Fehlern in der Syntax der Richtlinien-Header, z. B. nach fehlenden Anführungszeichen. Details ansehen

• Prüfen Sie, ob Ihr Endpunkt eingehende Anfragen verarbeiten kann.

  • Achten Sie darauf, dass Ihr Endpunkt CORS-Preflight-Anfragen unterstützt. Andernfalls können keine Berichte empfangen werden.

  • Testen Sie das Verhalten des Endpunkts. Anstatt Berichte manuell zu generieren, können Sie den Browser emulieren, indem Sie Anfragen an Ihren Endpunkt senden, die so aussehen, wie sie vom Browser gesendet werden würden. Führen Sie den folgenden Befehl aus:

  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
  

  Der Endpunkt sollte mit einem Erfolgscode (200 oder einem anderen Antwortcode für eine erfolgreiche Ausführung 2xx) antworten. Wenn dies nicht der Fall ist, liegt ein Problem mit der Konfiguration vor.

Zugehörige Meldemechanismen

Nur Berichterstellung

-Report-Only-Richtlinienheader und Reporting-Endpoints arbeiten zusammen.

In Reporting-Endpoints konfigurierte und im Feld report-to von Content-Security-Policy, Cross-Origin-Embedder-Policy und Cross-Origin-Opener-Policy angegebene Endpunkte erhalten Berichte, wenn diese Richtlinien verletzt werden.

In Reporting-Endpoints konfigurierte Endpunkte können auch im Feld report-to von Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only und Cross-Origin-Opener-Policy-Report-Only angegeben werden. Sie erhalten auch Berichte, wenn gegen diese Richtlinien verstoßen wird.

In beiden Fällen werden Berichte gesendet, aber mit -Report-Only-Headern werden die Richtlinien nicht erzwungen. Es wird nichts beschädigt oder blockiert, aber Sie erhalten Berichte darüber, was beschädigt oder blockiert worden wäre.

ReportingObserver

Mit der ReportingObserver-JavaScript API können Sie clientseitige Warnungen beobachten.

ReportingObserver und der Header Reporting-Endpoints generieren Berichte, die gleich aussehen, aber leicht unterschiedliche Anwendungsfälle ermöglichen.

Verwenden Sie ReportingObserver, wenn:

• Sie möchten nur Einstellungen oder Browser-Interventionen überwachen. ReportingObserver zeigt clientseitige Warnungen wie Einstellungen und Browsereingriffe an, erfasst aber im Gegensatz zu Reporting-Endpoints keine anderen Arten von Berichten wie CSP- oder COOP/COEP-Verstöße.
• Sie müssen in Echtzeit auf diese Verstöße reagieren. Mit ReportingObserver können Sie einen Callback an ein Ereignis für einen Verstoß anhängen.
• Sie möchten einem Bericht zusätzliche Informationen anhängen, um die Fehlersuche zu erleichtern, und verwenden dazu den benutzerdefinierten Callback.

Ein weiterer Unterschied besteht darin, dass ReportingObserver nur clientseitig konfiguriert wird. Sie können es also auch verwenden, wenn Sie keine Kontrolle über serverseitige Header haben und Reporting-Endpoints nicht festlegen können.

Weitere Informationen

• Migrationsanleitung von der Reporting API v0 zur v1
• ReportingObserver
• Spezifikation: Legacy Reporting API (v0)
• Spezifikation: Neue Reporting API (v1)

Vielen Dank an Ian Clelland, Eiji Kitamura und Milica Mihajlija für ihre Rezensionen und Vorschläge zu diesem Dokument.