CSPViolationReport.documentURL — Eigenschaft · JavaScript-Referenz

Signatur

CSPViolationReport.documentURL

Beschreibung

documentURL ist ein Feld des Wörterbuchs CSPViolationReport. Dieses Wörterbuch bildet den body eines Berichts vom Typ "csp-violation" in der Reporting API. Der Wert gibt an, auf welcher Seite bzw. in welchem Worker die Verletzung auftrat. Das ist nicht dasselbe wie die blockierte Ressource: Deren Adresse steht in blockedURL.

An diesen Bericht kommst du auf zwei Wegen:

Clientseitig mit einem ReportingObserver, der auf types: ["csp-violation"] eingeschränkt ist. Der Wert steht dann in report.body.documentURL.
Serverseitig über die CSP-Direktive report-to zusammen mit dem HTTP-Header Reporting-Endpoints. Der Browser schickt die Berichte als JSON (application/reports+json) per POST. Das Feld heißt dort ebenfalls documentURL.

Du nutzt die Eigenschaft vor allem beim Überwachen und Debuggen einer CSP, zum Beispiel wenn du eine Richtlinie zuerst im Modus Content-Security-Policy-Report-Only ausrollst. Mit documentURL ordnest du Verletzungen einzelnen Seiten oder Routen zu und findest so heraus, welche Seite noch Inline-Skripte oder fremde Ressourcen lädt.

Rückgabewert

Typ

string

Beschreibung

Die URL des Dokuments oder Workers, in dem die Verletzung auftrat. Der Browser bereinigt sie vorher: Fragment (#…) sowie Benutzername und Passwort werden entfernt.

Beispiele

CSP-Verletzungen im Browser mit ReportingObserver erfassen

const observer = new ReportingObserver((reports) => {
  for (const report of reports) {
    const { documentURL, blockedURL, effectiveDirective } = report.body;
    console.log(`Verletzung auf ${documentURL}: ${effectiveDirective} blockiert ${blockedURL}`);
  }
}, { types: ['csp-violation'], buffered: true });

observer.observe();

Verletzung auf https://shop.example/checkout: script-src-elem blockiert https://cdn.fremd.example/track.js

Berichte serverseitig nach Seite gruppieren (Node.js/Express)

// Antwort-Header der Seite:
// Reporting-Endpoints: csp="https://shop.example/csp-reports"
// Content-Security-Policy-Report-Only: script-src 'self'; report-to csp
import express from 'express';

const app = express();
app.use(express.json({ type: 'application/reports+json' }));

const perPage = new Map();

app.post('/csp-reports', (req, res) => {
  for (const report of req.body) {
    if (report.type !== 'csp-violation') continue;
    const page = new URL(report.body.documentURL).pathname;
    perPage.set(page, (perPage.get(page) ?? 0) + 1);
  }
  console.log(Object.fromEntries(perPage));
  res.sendStatus(204);
});

app.listen(3000);

{ '/checkout': 3, '/produkt/42': 1 }

Nur Verletzungen der aktuellen Seite auswerten

const here = location.href.split('#')[0];

new ReportingObserver((reports) => {
  const eigene = reports.filter((r) => r.body.documentURL === here);
  console.log(`${eigene.length} Verletzung(en) auf dieser Seite`);
}, { types: ['csp-violation'] }).observe();

1 Verletzung(en) auf dieser Seite

// Wichtig · Fallstricke

Nicht verwechseln: documentURL ist die Seite, auf der die Verletzung auftrat. Die blockierte Ressource steht in blockedURL, die Seite, von der der Aufruf kam, in referrer.
Ältere Berichte haben andere Feldnamen: Mit der veralteten Direktive report-uri sendet der Browser das Format application/csp-report. Dort heißt das Feld "document-uri" und liegt unter "csp-report". Beim Ereignis securitypolicyviolation heißt es SecurityPolicyViolationEvent.documentURI. Wenn dein Server beide Formate annimmt, musst du beide Varianten auslesen.
Der Browser entfernt das Fragment (#…) und die Zugangsdaten aus der URL. Query-Parameter bleiben dagegen erhalten und können personenbezogene Daten oder Tokens enthalten. Bereinige sie deshalb, bevor du sie speicherst (Datenschutz, DSGVO).
Berichtsdaten kommen vom Client und lassen sich fälschen. Prüfe sie serverseitig, bevor du sie weiterverarbeitest oder in einem Dashboard anzeigst. Gib sie nie ungefiltert als HTML aus, sonst drohen XSS-Lücken.
Kompatibilität: ReportingObserver mit "csp-violation" und report-to funktionieren vor allem in Chromium-Browsern zuverlässig. Setze zusätzlich report-uri als Rückfall für andere Browser.

Siehe auch

CSPViolationReport.blockedURL CSPViolationReport.columnNumber CSPViolationReport.disposition CSPViolationReport.referrer CSPViolationReport.sourceFile