Webanwendung mit der Reporting API überwachen

Mit der Reporting API können Sie Sicherheitsverstöße, eingestellte API-Aufrufe und mehr überwachen.

Maud Nalpas

Achtung:

Dies ist eine API-Anleitung mit detaillierten Nutzungsbeispielen für die Reporting API (v1), in der der Reporting-Endpoints-Header verwendet wird.

Wenn Sie die alte Reporting API (Report-To-Header) verwenden, lesen Sie stattdessen den Abschnitt zur API-Migration.

Suchen Sie nach der Dokumentation zu Network Error Logging? Weitere Informationen finden Sie unter „Netzwerkfehler protokollieren“.

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. Mit der Reporting API lassen sich einige dieser Fehler erkennen, z. B. Sicherheitsverstöße oder eingestellte und bald eingestellte API-Aufrufe auf Ihrer Website. Die API überträgt diese Fehler an einen von Ihnen angegebenen Endpunkt.

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

Wenn Sie die Reporting API einrichten, können Sie sicher sein, dass Sie informiert werden, wenn Nutzer diese Arten von Fehlern haben, damit Sie sie beheben können.

In diesem Beitrag wird beschrieben, was mit dieser API möglich ist und wie sie verwendet wird. Los gehts!

Übersicht

Wie Berichte generiert und gesendet werden.

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 erfahren, wann diese Richtlinien verletzt werden, aber auch, um ein Auge auf veraltete oder bald veraltete APIs zu haben, die in Ihrer Codebasis verwendet werden.

Dazu konfigurieren Sie einen Reporting-Endpoints-Header und ordnen diese Endpunktnamen bei Bedarf mit der report-to-Anweisung 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 einige Ihrer Nutzer verstoßen gegen diese Richtlinien.

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 Document-Policy-Verstoßbericht und einen Deprecation-Bericht, in denen diese Probleme erfasst werden.

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

Der/die Endpunkt(e) empfängt/empfangen 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 des Problems beginnen, das Ihre Nutzer betrifft.

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:

Achtung:Network Error Logging (Protokollierung von Netzwerkfehlern) ist nicht aufgeführt, da es in der neuen Version der API nicht unterstützt wird. Weitere Informationen finden Sie im Migrationsleitfaden.

Berichtstyp	Beispiel für eine Situation, in der ein Bericht generiert wird
CSP-Verstoß (nur Stufe 3)	Sie haben auf einer Ihrer Seiten eine Content-Security-Policy (CSP) festgelegt, aber auf der Seite wird versucht, ein Skript zu laden, das von Ihrer CSP nicht zugelassen wird.
Verstoß gegen die COOP	Sie haben ein Cross-Origin-Opener-Policy auf einer Seite festgelegt, aber ein fensterübergreifendes Fenster versucht, direkt mit dem Dokument zu interagieren.
Verstoß gegen die Richtlinien zur sexuellen Ausbeutung von Kindern	Sie haben ein Cross-Origin-Embedder-Policy auf einer Seite festgelegt, das Dokument enthält aber ein Cross-Origin-iFrame, das nicht für das Laden durch Cross-Origin-Dokumente aktiviert wurde.
Richtlinienverstoß bei Dokumenten	Die Seite hat eine Dokumentrichtlinie, die die Verwendung von document.write verhindert, aber ein Skript versucht, document.write aufzurufen.
Verstoß gegen die Richtlinie für Berechtigungen	Die Seite hat eine Berechtigungsrichtlinie, die die Verwendung des Mikrofons verhindert, und ein Skript, das Audioeingabe anfordert.
Warnung zur Einstellung	Auf der Seite wird eine API verwendet, die nicht mehr unterstützt wird oder deren Unterstützung eingestellt wird. Sie wird direkt oder über ein Drittanbieter-Script auf oberster Ebene aufgerufen.
Intervention	Die Seite versucht, etwas zu tun, das der Browser aus Sicherheits-, Leistungs- oder Nutzerfreundlichkeitsgründen nicht zulässt. Beispiel in Chrome: Die Seite verwendet document.write in langsamen Netzwerken oder ruft navigator.vibrate in einem ursprungsübergreifenden Frame auf, mit dem der Nutzer noch nicht interagiert hat.
Unfall	Der Browser stürzt ab, während Ihre Website geöffnet ist.

Berichte

Wie sehen Berichte aus?

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

Folgende Daten sind in den einzelnen Berichten enthalten:

Feld	Beschreibung
age	Die Anzahl der Millisekunden zwischen dem Zeitstempel des Berichts und der aktuellen Zeit.
body	Die tatsächlichen Berichtsdaten, serialisiert in einen JSON-String. Die Felder, die in einem body eines Berichts enthalten sind, werden durch das type des Berichts bestimmt. ⚠️ Berichte unterschiedlicher Typen haben unterschiedliche Inhalte.
type	Ein Berichtstyp, z. B. csp-violation oder coep.
url	Die Adresse des Dokuments oder Workers, aus dem der Bericht generiert wurde. Vertrauliche Daten wie Nutzername, Passwort und Fragment werden aus dieser URL entfernt.
user_agent	Der User-Agent-Header der Anfrage, aus der der Bericht generiert wurde.

Berichte mit Anmeldedaten

Berichtsendpunkte mit demselben Ursprung wie die Seite, auf der der Bericht generiert wird, erhalten die Anmeldedaten (Cookies) in den Anfragen, die die Berichte enthalten.

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

Hinweis:Ursprungsübergreifende Endpunkte erhalten keine Anmeldedaten. Dies ist eine Sicherheitsmaßnahme, die nicht geändert werden kann.

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. Außerdem lässt sich nicht steuern, wann der Browser Berichte sendet. Er erfasst, reiht sie in die Warteschlange ein und sendet sie automatisch zu einem geeigneten Zeitpunkt.

Daher gibt es bei der Verwendung der Reporting API kaum oder gar keine Leistungsprobleme.

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, was insbesondere bei Mobilgeräten wichtig ist. Der Browser kann die Auslieferung 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.

Hinweis:Wenn Sie lokal debuggen, können Sie diese Verzögerung deaktivieren. Weitere Informationen

Probleme mit Drittanbietern und mit selbst erhobenen Daten

Berichte, die aufgrund von Verstößen oder Einstellungen, die auf Ihrer Seite erfolgen, generiert werden, werden an die von Ihnen konfigurierten Endpunkte gesendet. Dazu gehören auch Verstöße, die durch Drittanbieter-Scripts auf Ihrer Seite verursacht 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 erstellen und sogar an den Berichterstellungsdienst Ihrer Website (also des Erstanbieters) senden. Das liegt jedoch an der eingebetteten Website. Die meisten Berichte werden nur generiert, wenn gegen die Richtlinie einer Seite verstoßen wird. Die Richtlinien Ihrer Seite und die Richtlinien des iFrames sind unterschiedlich.

Wichtiger Hinweis:In den Chrome-Entwicklertools wird ein Konsolenfehler oder eine Konsolenwarnung für Verstöße angezeigt, die von Drittanbieter-Scripts und ursprungsübergreifenden iFrames verursacht werden. Nicht alle führen dazu, dass Berichte an Ihren Endpunkt gesendet werden. Das ist nur bei den ersten der Fall.

Beispiel mit Einstellungen, die eingestellt werden

Wenn der Header „Reporting-Endpoints“ auf Ihrer Seite eingerichtet ist: Veraltete APIs, die von Drittanbieter-Scripts auf Ihrer Seite aufgerufen werden, werden an Ihren Endpunkt gemeldet. Wenn eine eingestellte API von einem in Ihre Seite eingebetteten iFrame aufgerufen wird, wird dies nicht an Ihren Endpunkt gemeldet. Ein Bericht zur Einstellung wird nur generiert, wenn der Iframe-Server Reporting-Endpunkte eingerichtet hat. Dieser Bericht wird an den Endpunkt gesendet, den der Server des Iframes eingerichtet hat.

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 dieselbe, mit Ausnahme eines Berichtstyps: Die Protokollierung von Netzwerkfehlern wird in der neuen Reporting API nicht unterstützt. Weitere Informationen finden Sie im Migrationsleitfaden.

Berichtstyp	Chrome	Chrome iOS	Safari	Firefox	Edge
CSP-Verstoß (nur Stufe 3)*	✔ Ja	✔ Ja	✔ Ja	✘ Nein	✔ Ja
Protokollierung von Netzwerkfehlern	✘ Nein	✘ Nein	✘ Nein	✘ Nein	✘ Nein
Verstoß gegen COOP/COEP	✔ Ja	✘ Nein	✔ Ja	✘ Nein	✔ Ja
Alle anderen Typen: Dokumentrichtlinienverstoß, Einstellung, Intervention, Absturz	✔ Ja	✘ Nein	✘ Nein	✘ Nein	✔ Ja

Achtung:

Die Browserunterstützung für CSP-Berichte unterscheidet sich von anderen Berichtstypen, da CSP schon seit einiger Zeit verfügbar ist. CSP-Berichte können mit folgenden Tools generiert werden:

• Die alte report-uri-Anweisung, die nicht auf der Reporting API basiert.
• Die neuere report-to-Anweisung, die auf der Reporting API und den Headern Reporting-To oder Reporting-Endpoints basiert.

In dieser Tabelle wird nur die Unterstützung für report-to mit dem neuen Reporting-Endpoints-Header zusammengefasst. Wenn Sie zu Reporting-Endpoints migrieren möchten, lesen Sie die Tipps zur Migration von CSP-Berichten.

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 Collector senden

Option 1: Vorhandenen Dienst zum Erfassen von Berichten verwenden

Beispiele für Dienste zum Erfassen von Berichten:

• report-uri
• uriports

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

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

• Werden alle Berichtstypen von diesem Collector unterstützt? Beispielsweise unterstützen nicht alle Lösungen für Reporting-Endpunkte COOP-/COEP-Berichte.
• Sind Sie damit einverstanden, URLs Ihrer Anwendung an einen Drittanbieter weiterzugeben, der Berichte erstellt? Auch wenn der Browser vertrauliche Informationen aus diesen URLs entfernt, können auf diese Weise vertrauliche Informationen preisgegeben werden. Wenn das für Ihre Anwendung zu riskant ist, können Sie einen eigenen Berichterstellungs-Endpunkt betreiben.

Option 2: Eigenen Berichtssammler erstellen und betreiben

Das Erstellen eines eigenen Servers, der Berichte empfängt, ist nicht ganz einfach. Als Einstieg können Sie unser einfaches Boilerplate forken. Sie basiert auf Express und kann Berichte empfangen und anzeigen.

Wenn Sie einen eigenen Berichtskollektor erstellen, gilt Folgendes:

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

Wichtig:Achten Sie darauf, dass Ihr Endpunkt CORS-Preflight-Anfragen unterstützt.

Option 3: Option 1 und Option 2 kombinieren

Möglicherweise möchten Sie, dass ein bestimmter Anbieter sich um einige Arten von Berichten kümmert, während Sie für andere eine interne Lösung haben.

In diesem Fall legen Sie 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 durch Kommas getrennte 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 Berichte zu Content-Security-Policy-Verstößen nur mit der report-uri-Anweisung verwenden, sollten Sie sich die Migrationsschritte für CSP-Berichte ansehen.

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. So können Sie Berichte je nach Typ an verschiedene Endpunkte weiterleiten.

Wenn Sie Interventions-, Einstellungs- oder Absturzberichte oder eine Kombination aus diesen erhalten möchten, legen Sie einen Endpunkt mit dem Namen default fest.

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

Wichtiger Hinweis:Trotz des Namens ist default kein Fallback-Endpunkt. Wenn Sie beispielsweise report-to my-endpoint für Document-Policy einrichten und my-endpoint in Reporting-Endpoints nicht definieren, werden Berichte zu Document-Policy-Verstößen generiert, aber nicht gesendet, da der Browser nicht weiß, wohin sie gesendet werden sollen.

Werte (URLs)

Jeder Wert ist eine URL Ihrer Wahl, an die die Berichte gesendet werden. Die hier festzulegende URL 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 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 in allen Richtlinien verwenden.

Wo kann ich den Header festlegen?

In der neuen Reporting API, die in diesem Beitrag behandelt wird, 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 verschiedene Endpunkte senden können.

Wenn Sie Berichte zu Verstößen oder Einstellungen auf einer Seite Ihrer Website erhalten möchten, legen Sie 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();
});

Hinweis:Dies unterscheidet sich von der alten Reporting API (Report-To-Header), bei der Sie einen „Ambient“-Endpunkt für eine Seite festlegen und automatisch Berichte für jede Seite mit demselben Ursprung erhalten konnten. Wenn Sie von der alten Reporting API zur neuen Reporting API migrieren, finden Sie hier eine Migrationsanleitung.

Richtlinien bearbeiten

Nachdem der Reporting-Endpoints-Header 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 Multi-Endpoint für mehrere Richtlinien oder verschiedene Endpunkte für verschiedene Richtlinien verwenden.

report-to ist für Einstellungs-, Interventions- und Absturzberichte 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

Achtung:Die richtige report-to-Syntax zu finden, kann schwierig sein, da nicht alle Richtlinien dieselbe Headerstruktur verwenden. Je nach Richtlinie kann die richtige Syntax report-to=main-endpoint oder report-to main-endpoint sein.

Berichterstellung einrichten und Fehler beheben

Berichte bewusst erstellen

Beim Einrichten der Reporting API müssen Sie wahrscheinlich absichtlich gegen Ihre Richtlinien verstoßen, um zu prüfen, ob Berichte wie erwartet generiert 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 werden.

Führen Sie diesen Befehl in Ihrem Terminal aus, um dieses Flag zu aktivieren:

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

Wichtiger Hinweis:Dieses Flag ist nicht über die Chrome-Benutzeroberfläche verfügbar, sondern nur als Befehlszeilenflag. Informationen zum Ausführen von Chromium mit Flags

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 das Tool:

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 sie dort ein.
3. Klicken Sie auf Aktiviert.
4. Starten Sie den Browser neu.
5. Öffnen Sie die Chrome-Entwicklertools.
6. Öffnen Sie die Einstellungen in den Chrome-Entwicklertools. Klicken Sie unter „Tests“ auf Reporting API-Bereich im Anwendungsbereich aktivieren.
7. Laden Sie die Entwicklertools neu.
8. Aktualisieren Sie die Seite. 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.

In den Chrome-Entwicklertools werden die auf Ihrer Seite generierten Berichte und ihr Status angezeigt.

Berichtsstatus

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

Status	Beschreibung
Success	Der Browser hat den Bericht gesendet und der Endpunkt hat mit einem Erfolgscode (200 oder einem anderen Erfolgscode 2xx) geantwortet.
Pending	Der Browser versucht, den Bericht zu senden.
Queued	Der Bericht wurde generiert und der Browser versucht nicht, ihn zu senden. Ein Bericht wird in einem der folgenden beiden Fälle als Queued angezeigt: Der Bericht ist neu und der Browser wartet ab, ob weitere Berichte eingehen, bevor er versucht, ihn zu senden. Der Bericht ist nicht neu. Der Browser hat bereits versucht, ihn zu senden, was fehlgeschlagen ist. Er wartet, bevor er es noch einmal versucht.
MarkedForRemoval	Nachdem der Browser eine Weile versucht hat, den Bericht zu senden (Queued), wird er bald aus der Liste der zu sendenden Berichte entfernt.

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

Wichtiger Hinweis:Der Status Queued ist nicht immer aussagekräftig, da er nicht genau angibt, ob der Versand fehlgeschlagen ist oder noch nicht versucht wurde. Wenn Sie kurze Meldeverzögerungen verwenden, können Sie Folgendes erreichen: Ein Bericht, der in diesem Fall Queued bleibt, deutet wahrscheinlich darauf hin, dass der Versand fehlschlägt.

Fehlerbehebung

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

Berichte werden nicht generiert

Berichte, die in DevTools angezeigt werden, wurden korrekt generiert. Wenn der erwartete Bericht nicht in dieser Liste angezeigt wird:

• Sehen Sie in Ihren Richtlinien nach, ob report-to zulässig ist. Wenn dies falsch konfiguriert ist, wird kein Bericht generiert. Gehen Sie zu Richtlinien bearbeiten, 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 DevTools geöffnet ist. Ein 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?

Wichtiger Hinweis:Da der Bericht vom Browser selbst und nicht von einer bestimmten Website gesendet wird, werden die POST-Anfragen, die die Berichte enthalten, nicht im Bereich Netzwerk Ihrer Entwicklertools angezeigt.

• 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 es ein Problem gibt, wird ein korrekt generierter Bericht nicht gesendet. In 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). Einige häufige Fehler, die dies verursachen können:

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

Code mit einem Fehler

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

Berichte zu Verstößen gegen die Dokumentrichtlinie sollten an endpoint-1 gesendet werden. Dieser Endpunktname ist jedoch nicht in Reporting-Endpoints konfiguriert.

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

• Suchen Sie in der Syntax Ihrer Richtlinienheadern nach Problemen, 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. Wenn nicht, kann sie keine Berichte empfangen.

  • Testen Sie das Verhalten Ihres Endpunkts. Dazu können Sie den Browser emulieren, indem Sie Anfragen an Ihren Endpunkt senden, die so aussehen, als würden sie vom Browser gesendet. Führen Sie Folgendes 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
  

  Ihr Endpunkt sollte mit einem Erfolgscode (200 oder einem anderen Erfolgscode 2xx) antworten. Andernfalls liegt ein Problem mit der Konfiguration vor.

Zugehörige Meldeverfahren

Nur Berichterstellung

Die -Report-Only-Richtlinienüberschriften und die Reporting-Endpoints arbeiten zusammen.

An die in Reporting-Endpoints konfigurierten und im Feld report-to von Content-Security-Policy, Cross-Origin-Embedder-Policy und Cross-Origin-Opener-Policy angegebenen Endpunkte werden Berichte gesendet, wenn gegen diese Richtlinien verstoßen wird.

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 -Report-Only-Headern wird nicht durchgesetzt, dass die Richtlinien eingehalten werden. Es wird also nichts unterbrochen oder tatsächlich blockiert. Sie erhalten jedoch Berichte darüber, was unterbrochen oder blockiert worden wäre.

Hinweis:Wenn Sie einen -Report-Only-Header verwenden und Ihre Reporting-Endpunkte mit dem alten Header Report-To konfiguriert haben, sollten Sie nach Möglichkeit zu Reporting-Endpoints migrieren. Weitere Informationen

ReportingObserver

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

Mit ReportingObserver und der Kopfzeile Reporting-Endpoints werden Berichte generiert, 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. Im Gegensatz zu Reporting-Endpoints werden jedoch keine anderen Arten von Berichten wie CSP- oder COOP-/COEP-Verstöße erfasst.
• Sie müssen in Echtzeit auf diese Verstöße reagieren. ReportingObserver ermöglicht es, einen Callback an ein Ereignis für einen Verstoß anzuhängen.
• Sie möchten einem Bericht zusätzliche Informationen anhängen, um das Debugging 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 Reporting API v0 zu v1
• ReportingObserver
• Spezifikation: alte Reporting API (Version 0)
• Spezifikation: Neue Reporting API (v1)

Hero-Bild von Nine Koepfer / @enka80 auf Unsplash, bearbeitet. Vielen Dank an Ian Clelland, Eiji Kitamura und Milica Mihajlija für ihre Rezensionen und Vorschläge zu diesem Dokument.