Webanwendung mit der Reporting API überwachen

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

Maud Nalpas
Maud Nalpas

Einige Fehler treten nur in der Produktionsumgebung auf. Sie sehen sie weder lokal noch während da echte Nutzer, echte Netzwerke und echte Geräte um das Spiel zu verändern. Mit der Reporting API lassen sich einige dieser Fehler abfangen, z. B. als Sicherheitsverstöße oder eingestellte und bald eingestellte API auf Ihrer Website und leitet sie an einen von Ihnen angegeben ist.

Sie können damit per HTTP-Header angeben, was Sie beobachten möchten. vom Browser ausgeführt werden.

Wenn Sie die Reporting API einrichten, wissen Sie, damit Sie sie beheben können.

In diesem Beitrag wird erläutert, welche Möglichkeiten diese API bietet und wie sie verwendet wird. Legen wir los!

Demo und Code

Die Reporting API in Aktion ab Chrome 96 und höher (Chrome Beta oder Canary, seit Oktober 2021).

Übersicht

<ph type="x-smartling-placeholder">
</ph> Diagramm mit einer Zusammenfassung der Schritte unten – von der Berichterstellung bis zum Berichtzugriff durch den Entwickler <ph type="x-smartling-placeholder">
</ph> Wie Berichte erstellt und gesendet werden

Angenommen, Ihre Website site.example verfügt über eine Content-Sicherheits- und eine Dokumentrichtlinie. Sie wissen nicht, was diese Funktionen bewirken? Das ist aber nicht schlimm. um dieses Beispiel zu verstehen.

Sie beschließen, Ihre Website zu überwachen, um zu erfahren, wann ein Verstoß gegen diese Richtlinien vorliegt. sollten Sie veraltete oder bald nicht mehr unterstützte APIs im Auge behalten, die Ihre Codebasis möglicherweise verwendet.

Dazu konfigurieren Sie einen Reporting-Endpoints-Header und ordnen diesen Endpunkt zu über die report-to-Anweisung in Ihren Richtlinien.

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 ein Verstoß gegen diese Richtlinien Nutzenden.

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 zu CSP-Verstößen, einen Bericht zu Dokumentrichtlinien und eine Einstellung zur Einstellung von Produkten und Diensten. die diese Probleme erfassen.

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 gesendet Out-of-Band durch den dem Browser selbst (weder von Ihrem Server noch von Ihrer Website).

Die Endpunkte erhalten diese Berichte.

Sie können jetzt auf die Berichte zu diesen Endpunkten zugreifen und den Fehler im Blick behalten. Sie sind bereit, mit der Fehlerbehebung für das Problem zu beginnen, von dem Ihre Nutzer betroffen sind.

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 interessanter Warnungen oder Probleme im Blick behalten können. die auf Ihrer Website auftreten:

Berichtstyp Beispiel für eine Situation, in der ein Bericht generiert wird
CSP-Verstoß (nur Level 3) Sie haben auf einer Ihrer Seiten eine Content-Security-Policy (CSP) festgelegt, aber die Seite versucht, ein Script zu laden, das von Ihrer CSP nicht zulässig ist.
COOP-Verstoß Sie haben eine Cross-Origin-Opener-Policy auf einer Seite festgelegt, aber ein ursprungsübergreifendes Fenster versucht, direkt mit dem Dokument zu interagieren.
COEP-Verstoß Sie haben einen Cross-Origin-Embedder-Policy auf einer Seite festgelegt, aber das Dokument enthält einen ursprungsübergreifenden iFrame, der nicht aktiviert wurde, dass er von ursprungsübergreifenden Dokumenten geladen wird.
Verstoß gegen die Dokumentrichtlinie Die Seite hat eine Dokumentrichtlinie, die die Verwendung von document.write verhindert, aber ein Script versucht, document.write aufzurufen.
Verstoß gegen die Berechtigungsrichtlinie Auf der Seite gibt es eine Berechtigungsrichtlinie, die die Nutzung des Mikrofons verhindert, sowie ein Script, das eine Audioeingabe anfordert.
Einstellungswarnung Die Seite verwendet eine API, die veraltet ist oder eingestellt wird. direkt oder über ein Drittanbieter-Skript auf oberster Ebene aufgerufen.
Intervention Auf der Seite wird versucht, eine Aktion auszuführen, die vom Browser aus Gründen der Sicherheit, Leistung oder Nutzerfreundlichkeit nicht berücksichtigt wird. 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 die Website geöffnet ist.

Berichte

Wie sehen Berichte aus?

Der Browser sendet Berichte an den von Ihnen konfigurierten Endpunkt. Er 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"
  }
]

Die folgenden Daten enthalten die einzelnen Berichte:

Feld Beschreibung
age Die Anzahl der Millisekunden zwischen dem Zeitstempel des Berichts und der aktuellen Zeit.
body Die eigentlichen Berichtsdaten, serialisiert in einen JSON-String. Die Felder in der body eines Berichts werden durch die type des Berichts bestimmt. ⚠️ Berichte verschiedener Typen haben einen anderen Text. Den genauen Text der einzelnen Berichtstypen finden Sie im Demo-Berichtsendpunkt . Folgen Sie der Anleitung zum Generieren von Beispielberichten.
type Einen Berichtstyp, z. B. csp-violation oder coep.
url Die Adresse des Dokuments oder Mitarbeiters, von dem/der der Bericht erstellt wurde. Sensible 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, die denselben Ursprung haben wie die Seite, auf der der Bericht erstellt wird, erhalten die Anmeldedaten (Cookies) nicht in die Anfragen aufnehmen, die die Berichte enthalten.

Die Anmeldedaten können nützlichen zusätzlichen Kontext zum Bericht liefern. für z. B. ob das Konto eines bestimmten Nutzers immer wieder Fehler auslöst oder ob eine bestimmte Sequenz der auf anderen Seiten ausgeführten Aktionen lösen auf dieser Seite einen Bericht aus.

Wann und wie sendet der Browser Berichte?

Die Berichte werden Out-of-Band von Ihrer Website gesendet: Der Browser steuert, werden sie an die konfigurierten Endpunkte gesendet. Außerdem lässt sich nicht steuern, wann sendet der Browser Berichte. erfasst, in die Warteschlange gestellt und automatisch an zu einem geeigneten Zeitpunkt.

Das bedeutet, dass es bei der Verwendung der Reporting API kaum bis keine Leistungseinbußen 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. Das spart Bandbreite, was vor allem auf Mobilgeräten wichtig. Der Browser kann die Auslieferung auch verzögern, wenn er gerade mit der Verarbeitung höherer Priorität beschäftigt ist. oder der Nutzer gerade ein langsames und/oder überlastetes Netzwerk hat.

Drittanbieter- und eigene Probleme

Berichte, die aufgrund von Verstößen oder Einstellungen auf Ihrer Seite generiert werden, werden gesendet mit den von Ihnen konfigurierten Endpunkten verbunden. Dazu gehören auch Verstöße durch Drittanbieter-Skripts. auf Ihrer Seite ausgeführt wird.

Verstöße oder Einstellungen zu Einstellungen, die in einem ursprungsübergreifenden iFrame, der in Ihre Seite eingebettet ist, erfolgen nicht an Ihre Endpunkte gemeldet werden (zumindest nicht standardmäßig). Ein iFrame könnte eine eigene Berichterstellung und sogar Berichte an den Erstanbieter-Berichtsdienst Ihrer Website; aber das ist oben Website in einem Frame. Beachten Sie außerdem, dass die meisten Berichte nur bei Verstößen gegen die Richtlinien einer Seite erstellt werden. und dass sich die Richtlinien Ihrer Seite von denen des iFrame unterscheiden.

Beispiel mit eingestellten Funktionen

<ph type="x-smartling-placeholder">
</ph> Wenn der Header „Reporting-Endpunkte“ auf Ihrer Seite eingerichtet ist, wird eine nicht mehr unterstützte API, die von auf Ihrer Seite ausgeführten Skripts von Drittanbietern aufgerufen wird, an Ihren Endpunkt gemeldet. Eine eingestellte API, die von einem in Ihre Seite eingebetteten iFrame aufgerufen wird, wird nicht an Ihren Endpunkt gemeldet. Ein Einstellungsbericht wird nur erstellt, wenn auf dem iFrame-Server Berichterstellungs-Endpunkte eingerichtet sind. Dieser Bericht wird an den vom iFrame-Server eingerichteten Endpunkt gesendet. <ph type="x-smartling-placeholder">
</ph> Wenn der Header „Reporting-Endpunkte“ auf Ihrer Seite eingerichtet ist, wird eine nicht mehr unterstützte API, die von auf Ihrer Seite ausgeführten Skripts von Drittanbietern aufgerufen wird, an Ihren Endpunkt gemeldet. Eine eingestellte API, die von einem in Ihre Seite eingebetteten iFrame aufgerufen wird, wird nicht an Ihren Endpunkt gemeldet. Ein Einstellungsbericht wird nur erstellt, wenn auf dem iFrame-Server Berichterstellungs-Endpunkte eingerichtet sind. Dieser Bericht wird an den vom iFrame-Server eingerichteten Endpunkt gesendet.

Unterstützte Browser

Die folgende Tabelle fasst die Browserunterstützung für Version 1 der Reporting API zusammen, also für Reporting-Endpoints-Header. Die Browserunterstützung für die Reporting API Version 0 (Report-To-Header) ist die Gleich, mit Ausnahme eines Berichtstyps: Das Logging von Netzwerkfehlern wird in der neuen Reporting API nicht unterstützt. Weitere Informationen finden Sie in der Migrationsanleitung.

Berichtstyp Chrome Chrome für iOS Safari Firefox Edge
CSP-Verstoß (nur Level 3)* ✔ Ja ✔ Ja ✔ Ja ✘ Nein ✔ Ja
Netzwerkfehler-Logging ✘ Nein ✘ Nein ✘ Nein ✘ Nein ✘ Nein
COOP/COEP-Verstoß ✔ Ja ✘ Nein ✔ Ja ✘ Nein ✔ Ja
Alle anderen Arten: Verstoß gegen Dokumentrichtlinien, Einstellung, Intervention, 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 der CSP-Berichte.

Reporting API verwenden

Entscheiden, wohin Berichte gesendet werden sollen

Es stehen zwei Optionen zur Verfügung:

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

Option 1: Vorhandenen Report Collector-Dienst verwenden

Beispiele für Report-Collector-Dienste:

Wenn Sie andere Lösungen kennen, melden Sie uns bitte ein Problem. Wir werden diesen Beitrag dann aktualisieren.

Neben den Preisen sollten Sie bei der Auswahl eines Report Collectors die folgenden Punkte berücksichtigen: 🧐

  • Unterstützt dieser Collector alle Berichtstypen? Beispielsweise sind nicht alle Lösungen für COOP/COEP-Berichte unterstützen.
  • Sind Sie damit einverstanden, einige der URLs Ihrer Anwendung an einen Report Collector eines Drittanbieters weiterzugeben? Selbst wenn der Browser vertrauliche Informationen aus diesen URLs entfernt, können vertrauliche Informationen auf diese Weise offengelegt werden. Wenn das zu riskant für und Ihren eigenen Berichtsendpunkt betreiben.

Option 2: Einen eigenen Report Collector erstellen und betreiben

Das Erstellen eines eigenen Servers, auf dem Berichte empfangen werden, ist gar nicht so einfach. Zum Einstieg können Sie unseren aus Textbausteinen. Das Tool wurde mit Express erstellt und kann Berichte empfangen und anzeigen.

  1. Rufen Sie die Collector-Funktion für Standardberichte auf.

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

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

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

  • Suchen Sie nach POST-Anfragen mit einer Content-Type von application/reports+json, um Berichte zu erkennen Anfragen, die vom Browser an Ihren Endpunkt gesendet werden.
  • Wenn sich der Endpunkt an einem anderen Ursprung als Ihre Website befindet, prüfen Sie, ob er CORS-Preflight-Anfragen unterstützt.

Option 3: Option 1 und 2 kombinieren

Möglicherweise möchten Sie einen bestimmten Anbieter überlassen, um einige Berichtstypen zu bearbeiten, aber Sie haben einen internen Anbieter. eine Lösung für andere.

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 Wert oder eine Reihe von durch Kommas getrennten Werten sein. Schlüssel/Wert-Paare:

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, ist es unter Umständen sinnvoll, Legen Sie sowohl Reporting-Endpoints als auch Report-To fest. Weitere Informationen finden Sie in der Migrationsanleitung. Wenn Sie die Berichterstellung für Nur Content-Security-Policy Verstöße gemäß der Richtlinie „report-uri“ – 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 Berichte unterschiedliche benannte Endpunkte festlegen Typen, z. B. my-coop-endpoint, my-csp-endpoint. Damit können Sie können Berichte je nach Typ an verschiedene Endpunkte weiterleiten.

Wenn Sie Unterstützung, Einstellung und/oder Absturz 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.

Werte (URLs)

Jeder Wert ist eine URL Ihrer Wahl, an die die Berichte gesendet werden. URL 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"

Anschließend können Sie jeden benannten Endpunkt in der entsprechenden Richtlinie oder einen einzelnen Endpunkt verwenden. für alle Richtlinien einen einzelnen Endpunkt benötigt.

Wo soll die Kopfzeile festgelegt werden?

In der neuen Reporting API, also der, die in diesem Post: Berichte werden auf Dokumente beschränkt. Das bedeutet, dass für eine bestimmte Ursprung, verschiedene Dokumente wie site.example/page1 und site.example/page2, kann Berichte an verschiedene Endpunkte senden.

Um Berichte über Verstöße oder Einstellungen auf einer beliebigen Seite Ihres -Website ist, legen Sie den Header als Middleware für alle Antworten fest.

Hier ist 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 Reporting-Endpoints-Header nun konfiguriert ist, fügen Sie einen report-to hinzu an jeden Richtlinienheader an, für den Sie einen Verstoß erhalten möchten. Berichte. Der Wert von report-to sollte einer der benannten Endpunkte sein, die Sie festgelegt haben konfiguriert.

Sie können mehrere Endpunkte für mehrere Richtlinien oder verschiedene Richtlinienübergreifend.

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

report-to wird für Einstellung, Eingriff und Absturz nicht benötigt Berichte. Diese Berichte sind an keine Richtlinien gebunden. Sie werden generiert, ist ein default-Endpunkt eingerichtet und werden 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

Beispielcode

Im Folgenden finden Sie ein Beispiel für einen Node-Server, der Express verwendet. und bringt alle in diesem Artikel behandelten Elemente zusammen. Es zeigt, wie Sie Konfigurieren der Berichterstellung für verschiedene Berichttypen und zeigt die Ergebnisse an.

Fehler bei der Berichtseinrichtung beheben

Berichte bewusst erstellen

Wenn Sie die Reporting API einrichten, müssen Sie wahrscheinlich absichtlich um zu überprüfen, ob Berichte wie erwartet erstellt und gesendet werden. Beispielcode zu sehen, der gegen Richtlinien verstößt und andere schädliche Dinge anstellt, die Berichte aller Art erstellen, sehen Sie sich die Demo an.

Zeit sparen

Berichte werden möglicherweise mit Verzögerung gesendet. Das kann etwa eine Minute dauern, was sehr lang ist. bei der Fehlerbehebung. Џ Zum Glück kannst du bei der Fehlerbehebung in Chrome die Kennzeichnung --short-reporting-delay, um Berichte zu erhalten, sobald sie erstellt wurden.

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

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

Entwicklertools verwenden

Verwende in Chrome die Entwicklertools, um zu sehen, welche Berichte bereits gesendet wurden oder gesendet werden.

Diese Funktion befindet sich seit Oktober 2021 in der Testphase. Gehen Sie dazu folgendermaßen vor:

  1. Sie verwenden Chrome-Version 96 und höher (durch Eingabe von chrome://version in Ihren Browser).
  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 Berichts-API-Bereich aktivieren App-Bereich.
  7. Aktualisiere die Entwicklertools.
  8. Aktualisieren Sie die Seite. Berichte, die von der Seite generiert werden, auf der die Entwicklertools geöffnet sind, werden die in den Chrome-Entwicklertools aufgeführt sind, Anwendung unter Reporting API.
<ph type="x-smartling-placeholder">
</ph> Screenshot der Entwicklertools mit der Liste der Berichte <ph type="x-smartling-placeholder">
</ph> 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 gesendet wurde.

Status Beschreibung
Success Der Browser hat den Bericht gesendet und der Endpunkt hat mit einem Erfolgscode (200 oder einem anderen Erfolgsantwortcode 2xx) geantwortet.
Pending Der Browser versucht derzeit, 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 beiden Fälle als Queued angezeigt: <ph type="x-smartling-placeholder">
    </ph>
  • Der Bericht ist neu und der Browser wartet auf weitere Berichte, bevor er gesendet wird.
  • Der Bericht ist nicht neu, Der Browser hat bereits versucht, diesen Bericht zu senden, ist jedoch fehlgeschlagen und wartet, bevor er es erneut versucht.
MarkedForRemoval Nach einigem Versuch (Queued) hat der Browser den Versuch gestoppt, den Bericht zu senden. Der Browser wird daher demnächst aus der Liste der zu sendenden Berichte entfernt.

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

Fehlerbehebung

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

Berichte werden nicht generiert

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

  • Sieh dir die report-to in deinen Richtlinien an. Ist dies falsch konfiguriert, wird ein wird der Bericht nicht generiert. Rufe den Abschnitt Richtlinien bearbeiten auf, um beheben Sie dieses Problem. Eine weitere Möglichkeit zur Fehlerbehebung ist die Entwicklertools-Konsole in Chrome: für den erwarteten Verstoß angezeigt wird, bedeutet dies, dass Ihre Richtlinie richtig konfiguriert ist.
  • Nur die Berichte, die für das Dokument generiert wurden, in dem DevTools geöffnet ist, in dieser Liste angezeigt werden. Beispiel: Auf Ihrer Website site1.example ist ein iFrame site2.example eingebettet. der gegen eine Richtlinie verstößt und daher einen Bericht erstellt. Dieser Bericht wird nur dann in den Entwicklertools angezeigt, wenn Sie die iFrame in einem eigenen Fenster öffnen und die Entwicklertools für dieses Fenster öffnen.

Berichte werden generiert, aber nicht gesendet oder nicht empfangen

Was ist, wenn Sie einen Bericht in den Entwicklertools aufrufen können, ihn aber nicht an Ihren Endpunkt erhalten?

  • Achten Sie auf kurze Verzögerungen. Wenn Sie einen Bericht nicht sehen, wurden noch nicht gesendet.
  • Prüfen Sie die Konfiguration des Reporting-Endpoints-Headers. Wenn es ein Problem gibt, kann eine Meldung korrekt generiert wurde, werden nicht gesendet. In den Entwicklertools bleibt der Status des Berichts Queued (möglicherweise zu Pending und dann schnell zurück zu Queued, wenn ein Zustellversuch gemacht). Hier einige häufige Fehler, die dazu führen können:

  • Der Endpunkt wird verwendet, 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 über Verstöße gegen Dokumentrichtlinien sollten an endpoint-1 gesendet werden, aber dieser Endpunktname ist nicht konfiguriert in Reporting-Endpoints.

  • Der Endpunkt default fehlt. Einige Berichtstypen, z. B. Einstellung und Bearbeitung werden nur an den Endpunkt default gesendet. Weitere Informationen finden Sie unter Header für Reporting-Endpunkte konfigurieren.

  • Achten Sie auf Probleme in der Syntax der Richtlinienüberschriften, z. B. fehlende Anführungszeichen. Details ansehen

  • Prüfen Sie, ob der 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 empfangen werden.

    • Testen Sie das Verhalten des Endpunkts. Anstatt zu generieren, Berichte manuell erstellen, können Sie den Browser emulieren, indem Sie Anfragen an Ihren Endpunkt senden, die wie was 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 (200 oder einem anderen Erfolgsantwortcode 2xx) antworten. Ist dies nicht der Fall, gibt es ein Problem mit der Konfiguration.

Nur Bericht

Die Richtlinienheader „-Report-Only“ 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 erhält Berichte, wenn gegen diese Richtlinien verstoßen wird.

In Reporting-Endpoints konfigurierte Endpunkte können auch in der Feld report-to von Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only und Cross-Origin-Opener-Policy-Report-Only Bei Verstößen gegen diese Richtlinien erhalten sie ebenfalls Berichte.

Obwohl Berichte in beiden Fällen gesendet werden, erzwingen -Report-Only-Header nicht die Richtlinien: Nichts wird funktionsunfähig oder blockiert, ihr erhaltet aber Meldungen darüber, was beschädigt oder blockiert worden wäre.

ReportingObserver

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

Mit ReportingObserver und dem Header Reporting-Endpoints werden Berichte generiert, die sehen gleich aus, ermöglichen jedoch etwas unterschiedliche Anwendungsfälle.

Verwenden Sie ReportingObserver in folgenden Fällen:

  • Sie möchten nur Einstellungen und/oder Browsereingriffe im Blick behalten. ReportingObserver zeigt clientseitige Warnungen wie Einstellungen an und Browser-Interventionen, aber im Gegensatz zu Reporting-Endpoints alle anderen Arten von Meldungen wie CSP- oder COOP/COEP-Verstöße erfassen.
  • Sie müssen in Echtzeit auf diese Verstöße reagieren. ReportingObserver Marke können Sie einen Callback an ein Verstoßereignis anhängen.
  • Sie möchten einem Bericht zusätzliche Informationen zur Fehlerbehebung hinzufügen, benutzerdefinierten Callback des Nutzers an.

Ein weiterer Unterschied ist, dass ReportingObserver nur clientseitig konfiguriert wird: auch dann verwenden, wenn Sie keine Kontrolle über serverseitige Header haben und Reporting-Endpoints festlegen.

Weitere Informationen

Hero-Image 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 Artikel.