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
Maud Nalpas

Einige Fehler treten nur in der Produktion auf. Sie werden weder lokal noch während der Entwicklung angezeigt, da echte Nutzer, echte Netzwerke und echte Geräte das Spiel beeinflussen. Mit der Reporting API lassen sich einige dieser Fehler leichter auf Ihrer Website erkennen, z. B. Sicherheitsverstöße oder eingestellte und demnächst eingestellte API-Aufrufe, und an einen von Ihnen angegebenen Endpunkt übertragen.

Sie können damit über HTTP-Header deklarieren, was überwacht werden soll, und sie wird vom Browser ausgeführt.

Wenn Sie die Reporting API einrichten, können Sie sich darauf verlassen, dass Nutzer solche Fehler sofort erfahren und beheben können.

In diesem Beitrag erfahren Sie, was diese API kann und wie Sie sie verwenden. Los gehts!

Demo und Code

Ab Chrome 96 (Chrome Beta oder Canary, seit Oktober 2021) die Reporting API in Aktion sehen

Überblick

Diagramm mit einer Zusammenfassung der Schritte unten – von der Berichterstellung bis zum Zugriff auf Berichte durch den Entwickler
Wie Berichte erstellt und gesendet werden.

Angenommen, deine Website site.example hat eine Content Security Policy und eine Dokumentrichtlinie. Sie wissen nicht, was diese bewirken? Kein Problem, Sie werden dieses Beispiel immer noch verstehen.

Sie beschließen, Ihre Website zu überwachen, um Verstöße gegen diese Richtlinien zu erkennen. Außerdem möchten Sie veraltete oder demnächst eingestellte APIs im Auge behalten, die Ihre Codebasis möglicherweise verwendet.

Dazu konfigurieren Sie einen Reporting-Endpoints-Header und ordnen diese Endpunktnamen bei Bedarf über die 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, durch das einige Nutzer gegen diese Richtlinien verstoßen.

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 Bericht über den CSP-Verstoß, einen Bericht über den Verstoß gegen die Dokumentrichtlinien und einen Einstellungsbericht, in dem 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 diese Art von Verstoß konfiguriert wurde. Die Berichte werden vom Browser selbst als Out-of-Band gesendet, nicht von Ihrem Server oder Ihrer Website.

Die Endpunkte erhalten diese Berichte.

Sie können jetzt an diesen Endpunkten auf die Berichte zugreifen und sehen, was schiefgelaufen ist. Sie können nun mit der Fehlerbehebung für das Problem 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 überwachen können, die auf Ihrer Website auftreten:

Berichtstyp Beispiel für eine Situation, in der ein Bericht generiert wird
Verstoß gegen die CSP (nur Ebene 3) Sie haben auf einer Ihrer Seiten eine Content-Security-Policy (CSP) festgelegt. Es wird jedoch versucht, auf der Seite ein Script zu laden, das von der CSP nicht zugelassen wird.
COOP-Verstoß Du hast ein Cross-Origin-Opener-Policy-Objekt auf einer Seite festgelegt, aber ein ursprungsübergreifendes Fenster versucht, direkt mit dem Dokument zu interagieren.
COEP-Verstoß Sie haben auf einer Seite ein Cross-Origin-Embedder-Policy festgelegt, aber das Dokument enthält einen ursprungsübergreifenden iFrame, der nicht für das Laden durch ursprungsübergreifende Dokumente aktiviert wurde.
Verstoß gegen die Dokumentrichtlinie Die Seite enthält eine Dokumentrichtlinie, die die Nutzung von document.write verhindert, aber ein Skript versucht, document.write aufzurufen.
Warnung zur Einstellung Auf der Seite wird eine API verwendet, die eingestellt wird oder eingestellt wird. Sie ruft sie direkt oder über ein Drittanbieterskript der obersten Ebene auf.
Intervention Auf der Seite wird eine Aktion ausgeführt, die der Browser aus Gründen der Sicherheit, Leistung oder Nutzererfahrung nicht anerkennt. 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 sendet Anfragen, 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"
  }
]

Im Folgenden sind die Daten aufgeführt, die in diesen Berichten enthalten sind:

Field Beschreibung
age Die Anzahl der Millisekunden zwischen dem Zeitstempel des Berichts und der aktuellen Zeit.
body Die tatsächlichen Berichtsdaten, serialisiert in einem JSON-String Die im body eines Berichts enthaltenen Felder werden durch type des Berichts bestimmt. ⚠️ Berichte verschiedener Typen haben einen unterschiedlichen Text. Den genauen Text der einzelnen Berichtstypen finden Sie im Demo-Endpunkt für die Berichterstellung . Folgen Sie dann der Anleitung, um Beispielberichte zu erstellen.
type Ein Berichtstyp, z. B. csp-violation oder coep.
url Die Adresse des Dokuments oder des Workers, von dem/dem der Bericht generiert wurde. Sensible Daten wie Nutzername, Passwort und Fragment werden aus dieser URL entfernt.
user_agent Der User-Agent-Header der Anfrage, über die der Bericht erstellt wurde.

Berichte mit Anmeldedaten

Endpunkte für Berichte, die denselben Ursprung haben wie die Seite, auf der der Bericht erstellt wird, erhalten die Anmeldedaten (Cookies) in den Anfragen, die die Berichte enthalten.

Anmeldedaten können nützliche 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 Out-of-Band von Ihrer Website bereitgestellt: 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, stellt die Berichte in die Warteschlange und sendet sie zu einem geeigneten Zeitpunkt automatisch.

Das bedeutet, dass bei Verwendung der Reporting API wenig bis gar keine Leistungsbeeinträchtigungen auftreten.

Berichte werden mit einer Verzögerung von bis zu einer Minute gesendet. Dadurch steigt die Wahrscheinlichkeit, dass Berichte stapelweise gesendet werden. Dies spart Bandbreite, um die Netzwerkverbindung des Nutzers zu berücksichtigen, was auf Mobilgeräten besonders wichtig ist. Der Browser kann die Zustellung auch verzögern, wenn er gerade mit der Verarbeitung höherer Priorität beschäftigt ist oder sich der Nutzer in einem langsamen und/oder überlasteten Netzwerk befindet.

Probleme von Drittanbietern und von selbst erhobenen Daten

Berichte, die aufgrund von Verstößen oder Einstellungen auf Ihrer Seite generiert werden, werden an die von Ihnen konfigurierten Endpunkte gesendet. Dazu zählen auch Verstöße, die durch Drittanbieter-Skripts auf Ihrer Seite begehen.

Verstöße oder Einstellungen, die in einem ursprungsübergreifenden iFrame, der in Ihre Seite eingebettet ist, vorgenommen wurden, werden nicht an Ihre Endpunkte gemeldet. Das gilt zumindest nicht standardmäßig. Ein iFrame könnte seine eigenen Berichte einrichten und sogar Berichte an den Berichtsdienst Ihrer Website – also den Ihres Erstanbieters – senden. Aber das ist die Aufgabe der Website mit Frames. Beachte außerdem, dass die meisten Berichte nur erstellt werden, wenn die Richtlinien einer Seite verletzt werden und die Richtlinien deiner Seite von denen des iFrames abweichen.

Beispiel mit Einstellungen

Wenn der Header „Reporting-Endpunkte“ auf Ihrer Seite eingerichtet ist, wird an Ihren Endpunkt gemeldet, dass eingestellte APIs, die von Drittanbieter-Skripts auf Ihrer Seite aufgerufen werden, gemeldet werden. Ein veraltetes API, das von einem in Ihre Seite eingebetteten iFrame aufgerufen wird, wird nicht an Ihren Endpunkt gemeldet. Ein Einstellungsbericht wird nur generiert, wenn der iFrame-Server Reporting-Endpunkte eingerichtet hat. Dieser Bericht wird an den Endpunkt gesendet, den der iFrame-Server eingerichtet hat.
Wenn der Header „Reporting-Endpunkte“ auf Ihrer Seite eingerichtet ist, wird Ihrem Endpunkt eine Meldung der eingestellten API gesendet, die von Drittanbieter-Skripts aufgerufen wird, die auf Ihrer Seite ausgeführt werden. Ein veraltetes API, das von einem in Ihre Seite eingebetteten iFrame aufgerufen wird, wird nicht an Ihren Endpunkt gemeldet. Ein Einstellungsbericht wird nur generiert, wenn der iFrame-Server Reporting-Endpunkte eingerichtet hat. Dieser Bericht wird an den Endpunkt gesendet, den der iFrame-Server eingerichtet hat.

Unterstützte Browser

In der folgenden Tabelle ist die Browserunterstützung für die Reporting API Version 1 für den Reporting-Endpoints-Header zusammengefasst. Die Browserunterstützung für Version 0 der Reporting API (Report-To-Header) ist bis auf einen Berichtstyp identisch: Netzwerkfehler-Logging wird in der neuen Reporting API nicht unterstützt. Weitere Informationen finden Sie im Migrationsleitfaden.

Berichtstyp Chrome Chrome für iOS Safari Firefox Edge
CSP-Verstoß (nur Level 3)* ✔ Ja ✔ Ja ✔ Ja ✘ Nein ✔ Ja
Logging von Netzwerkfehlern ✘ Nein ✘ Nein ✘ Nein ✘ Nein ✘ Nein
Alle anderen Arten: COOP-/COEP-Verstoß, Verstoß gegen Dokumentrichtlinien, Einstellung, Eingriff, Absturz ✔ Ja ✘ Nein ✘ Nein ✘ Nein ✔ Ja

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](/blog/reporting-api-migration/#csp_reporting_migration).

Reporting API verwenden

Empfänger für Berichte festlegen

Es stehen zwei Optionen zur Verfügung:

  • Senden Sie Berichte an einen vorhandenen Report-Collector-Dienst.
  • Senden Sie Berichte an einen Reporting-Collector, den Sie selbst erstellen und betreiben.

Option 1: Vorhandenen Dienst für das Erfassen von Berichten verwenden

Beispiele für Dienste zum Erfassen von Berichten:

Wenn du andere Lösungen kennst, eröffne ein Problem und informiere uns darüber. Wir aktualisieren dann diesen Beitrag.

Berücksichtigen Sie bei der Auswahl des Collectors für Berichte die folgenden Punkte: 🧐

  • Unterstützt dieses Collector alle Berichtstypen? Beispielsweise unterstützen nicht alle Lösungen für Endpunkte zur Berichterstellung COOP-/COEP-Berichte.
  • Möchten Sie eine der URLs Ihrer Anwendung an einen externen Report-Collector weitergeben? Selbst wenn der Browser vertrauliche Informationen aus diesen URLs entfernt, können vertrauliche Informationen auf diese Weise offengelegt werden. Wenn dies für Ihre Anwendung zu riskant erscheint, betreiben Sie einen eigenen Endpunkt für die Berichterstellung.

Option 2: Eigenes Berichts-Collector-Tool erstellen und betreiben

Es ist gar nicht so einfach, Ihren eigenen Server aufzubauen, der Berichte empfängt. Zunächst können Sie unseren leichten Standardcode abspalten. Sie wurde mit Express erstellt. Damit können Berichte empfangen und angezeigt werden.

  1. Gehen Sie zum Boilerplate Report Collector.

  2. Klicke auf Zum Bearbeiten Remix, damit das Projekt bearbeitet werden kann.

  3. Sie haben jetzt Ihren Klon! Sie können es für Ihre eigenen Zwecke anpassen.

Wenn Sie keinen Standardcode verwenden und Ihren eigenen Server von Grund auf neu erstellen:

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

Option 3: Option 1 und 2 kombinieren

Möglicherweise möchten Sie einen bestimmten Anbieter die Bearbeitung einiger Arten von Berichten überlassen, andere jedoch eine interne Lösung anbieten.

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 eine Reihe von durch Kommas getrennten Schlüssel/Wert-Paaren 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, sowohl Reporting-Endpoints als auch Report-To festzulegen. Weitere Informationen finden Sie in der Migrationsanleitung. Wenn Sie die Berichterstellung für Content-Security-Policy-Verstöße nur über die Anweisung report-uri verwenden, lesen Sie die Migrationsschritte für CSP-Berichte.

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 verschiedene benannte Endpunkte für verschiedene Berichtstypen festlegen, z. B. my-coop-endpoint, my-csp-endpoint. Damit können Sie Berichte je nach Typ an verschiedene Endpunkte weiterleiten.

Wenn Sie Berichte zu Eingriffen, Einstellungen und/oder Abstürzen erhalten möchten, legen Sie einen Endpunkt mit dem Namen default fest.

Wenn der Header Reporting-Endpoints keinen default-Endpunkt angibt, werden Berichte dieses Typs nicht gesendet, aber generiert.

Werte (URLs)

Jeder Wert ist eine URL Ihrer Wahl, an die die Berichte gesendet werden. Welche URL Sie hier festlegen müssen, hängt davon ab, was Sie in Schritt 1 festgelegt haben.

Eine Endpunkt-URL:

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 lege ich die Kopfzeile fest?

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 unterschiedliche Dokumente wie site.example/page1 und site.example/page2 Berichte an verschiedene Endpunkte senden können.

Wenn Sie Berichte über Verstöße oder Einstellungen erhalten möchten, die auf einer beliebigen Seite Ihrer Website auftreten, 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();
});

Richtlinien bearbeiten

Nachdem Sie den Header Reporting-Endpoints konfiguriert haben, 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 mehrere Endpunkte für mehrere Richtlinien oder unterschiedliche Endpunkte für alle Richtlinien verwenden.

Für jede Richtlinie sollte der Wert von „report-to“ einer der benannten Endpunkte sein, die Sie konfiguriert haben.

report-to ist für Berichte zu Einstellung, Eingriffen und Abstürzen nicht erforderlich. Diese Berichte sind an keine Richtlinien gebunden. Sie werden generiert, solange ein default-Endpunkt eingerichtet ist und an diesen default-Endpunkt gesendet wird.

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

Beispielcode

Im Folgenden finden Sie ein Beispiel für einen Knotenserver, der Express verwendet und alle in diesem Artikel behandelten Teile kombiniert. Sie erfahren, wie Sie die Berichterstellung für verschiedene Berichtstypen konfigurieren und die Ergebnisse anzeigen lassen.

Fehler bei der Berichtseinrichtung beheben

Berichte bewusst erstellen

Beim Einrichten der Reporting API müssen Sie wahrscheinlich vorsätzlich gegen Ihre Richtlinien verstoßen, damit Sie prüfen können, ob Berichte wie erwartet generiert und gesendet werden. In der Demo sehen Sie Beispielcode, der gegen Richtlinien verstößt und sonstige schädliche Aktionen verursacht, durch die Berichte aller Typen generiert werden.

Zeit sparen

Berichte können mit einer Verzögerung von etwa einer Minute gesendet werden, was eine lange Zeit für die Fehlerbehebung ist. 😴 Glücklicherweise kannst du bei der Fehlerbehebung in Chrome das Flag --short-reporting-delay verwenden, um Berichte sofort nach ihrer Erstellung zu erhalten.

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

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

Entwicklertools verwenden

In Chrome können Sie sich mit den Entwicklertools die gesendeten oder gesendeten Berichte ansehen.

Diese Funktion ist seit Oktober 2021 experimentell. Gehen Sie dazu folgendermaßen vor:

  1. Sie verwenden Chrome-Version 96 oder höher. Geben Sie dazu chrome://version in Ihren Browser ein.
  2. Geben oder fügen Sie chrome://flags/#enable-experimental-web-platform-features in die URL-Leiste von Chrome ein.
  3. Klicken Sie auf Aktiviert.
  4. Starten Sie den Browser neu.
  5. Öffnen Sie die Chrome-Entwicklertools.
  6. Öffnen Sie in den Chrome-Entwicklertools die Einstellungen. Klicken Sie unter „Tests“ auf Bereich „Reporting API“ im Bereich „Anwendung“ aktivieren.
  7. Laden Sie die Entwicklertools neu.
  8. Aktualisieren Sie die Seite. Berichte, die über die Seite generiert werden, auf der die Entwicklertools geöffnet sind, werden im Bereich Anwendung der Chrome-Entwicklertools unter Reporting API aufgeführt.
Screenshot der Entwicklertools mit Liste der Berichte
In den Chrome-Entwicklertools werden die auf Ihrer Seite erstellten Berichte und ihr Status angezeigt.

Berichtsstatus

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

Status Beschreibung
Success Der Browser hat den Bericht gesendet und der Endpunkt hat einen Erfolgscode (200 oder einen anderen Erfolgsantwortcode 2xx) zurückgegeben.
Pending Der Browser versucht gerade, den Bericht zu senden.
Queued Der Bericht wurde erstellt und der Browser versucht derzeit nicht, ihn zu senden. Ein Bericht wird in einem der folgenden Fälle als Queued angezeigt:
  • Der Bericht ist neu und der Browser wartet auf den Versand weiterer Berichte.
  • Der Bericht ist nicht neu. Der Browser hat bereits versucht, diesen Bericht zu senden, und der Bericht ist fehlgeschlagen. Er wartet, bevor er es erneut versucht.
MarkedForRemoval Nach längerem Versuch (Queued) wird der Bericht nicht mehr vom Browser gesendet. Er wird demnächst aus der Liste der zu sendenden Berichte entfernt.

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

Fehlerbehebung

Werden Berichte nicht erstellt oder nicht wie erwartet an Ihren Endpunkt gesendet? Hier sind ein paar Tipps zur Fehlerbehebung.

Berichte werden nicht erstellt

Die Berichte, die in den Entwicklertools angezeigt werden, wurden korrekt generiert. Wenn der erwartete Bericht nicht in dieser Liste angezeigt wird, gehen Sie so vor:

  • Prüfen Sie report-to in Ihren Richtlinien. Ist dies falsch konfiguriert, wird kein Bericht generiert. Informationen zur Behebung dieses Problems finden Sie unter Richtlinien bearbeiten. Eine weitere Möglichkeit zur Fehlerbehebung besteht in der Entwicklertools-Konsole in Chrome: Wenn in der Konsole ein Fehler für den erwarteten Verstoß angezeigt wird, bedeutet dies, dass deine Richtlinie wahrscheinlich richtig konfiguriert ist.
  • Beachte, dass in dieser Liste nur die Berichte angezeigt werden, die für das Dokument generiert wurden, in dem die Entwicklertools geöffnet sind. Ein Beispiel: Wenn deine Website site1.example einen iFrame site2.example einbettet, der gegen eine Richtlinie verstößt, und damit ein Bericht erstellt wird, wird dieser Bericht nur dann in den Entwicklertools angezeigt, wenn du den iFrame in einem eigenen Fenster öffnest und die Entwicklertools für dieses Fenster öffnest.

Berichte werden erstellt, aber nicht gesendet oder nicht empfangen

Was ist, wenn du einen Bericht in den Entwicklertools sehen kannst, ihn aber nicht an deinen Endpunkt senden?

  • Achten Sie auf kurze Verspätungen. Möglicherweise sehen Sie einen Bericht nicht, weil er noch nicht gesendet wurde.
  • Prüfen Sie die Konfiguration des Reporting-Endpoints-Headers. Wenn ein Problem vorliegt, wird kein Bericht gesendet, der korrekt erstellt wurde. In den Entwicklertools bleibt der Status des Berichts Queued. Er kann zu Pending und dann schnell wieder zu Queued zurückkehren, wenn ein Zustellversuch unternommen wird. Häufige Fehler, die dieses Problem verursachen können:

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

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

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

  • Der Endpunkt default fehlt. Einige Berichtstypen, z. B. Einstellungs- und Interventionsberichte, werden nur an den Endpunkt default gesendet. Weitere Informationen finden Sie unter Berichterstellungs-Endpunkte-Header konfigurieren.

  • Suchen Sie nach Problemen in der Syntax der Richtlinienüberschriften, z. B. nach fehlenden Anführungszeichen. Details anzeigen

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

    • Achten Sie darauf, dass Ihr Endpunkt CORS-Preflight-Anfragen unterstützt. Ist dies nicht der Fall, können keine Berichte an sie gesendet werden.

    • Testen Sie das Verhalten des Endpunkts. Statt Berichte manuell zu generieren, können Sie dazu den Browser emulieren. Senden Sie dazu Anfragen an Ihren Endpunkt, die dem ähneln, die der Browser senden würde. 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 antworten (200 oder einem anderen Erfolgsantwortcode 2xx). Andernfalls liegt ein Problem mit der Konfiguration vor.

Nur Bericht

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

Endpunkte, die in Reporting-Endpoints konfiguriert und im Feld report-to von Content-Security-Policy, Cross-Origin-Embedder-Policy und Cross-Origin-Opener-Policy angegeben sind, erhalten Berichte, 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. Außerdem erhalten sie Meldungen, wenn gegen diese Richtlinien verstoßen wird.

Während Berichte in beiden Fällen gesendet werden, werden die Richtlinien durch -Report-Only-Header nicht erzwungen: Nichts funktioniert oder wird tatsächlich blockiert. Sie erhalten jedoch Berichte darüber, was gefallen wäre oder was blockiert worden wäre.

ReportingObserver

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

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

Verwenden Sie ReportingObserver, wenn:

  • Sie möchten nur Einstellungen und/oder Browserinterventionen beobachten. ReportingObserver zeigt clientseitige Warnungen wie Einstellungen und Browsereingriffe an, erfasst jedoch 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. ReportingObserver ermöglicht das Anhängen eines Callbacks an ein Verstoßereignis.
  • Sie möchten einem Bericht über den benutzerdefinierten Callback zusätzliche Informationen hinzufügen, um die Fehlerbehebung zu erleichtern.

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

Weitere Informationen

Hero-Image von Nine Koepfer / @enka80 auf Unsplash, bearbeitet. Vielen Dank an Ian Clelland, Eiji Kitamura und Milica Mihajlija für die Rezensionen und Vorschläge in diesem Artikel.