SecurityPolicyViolationEvent.documentURI — Eigenschaft · JavaScript-Referenz

Signatur

SecurityPolicyViolationEvent.documentURI

Beschreibung

Die Eigenschaft documentURI gehört zum Interface SecurityPolicyViolationEvent und kann nur gelesen werden. Sie enthält den URI des Dokuments oder Workers, in dem eine Content Security Policy verletzt wurde. Der Wert entspricht dem Feld document-uri in klassischen CSP-Berichten, die über report-uri verschickt werden.

Gebraucht wird die Eigenschaft vor allem beim clientseitigen Überwachen von CSP-Verstößen. Wenn auf einer Website mehrere Seiten, iframes oder Worker laufen, sieht man daran, wo der Verstoß passiert ist. Zusammen mit blockedURI, violatedDirective bzw. effectiveDirective und sourceFile ergibt sich ein vollständiges Bild für eigene Logging- oder Telemetrie-Endpunkte.

Der Browser entfernt aus dem URI das Fragment (#...) sowie Benutzername und Passwort. Die Query-Parameter bleiben dagegen erhalten. Der Wert kann deshalb sensible Daten wie Tokens in der URL enthalten. Das sollte man beachten, bevor man ihn weitergibt.

Rückgabewert

Typ

string

Beschreibung

Der URI des Dokuments oder Workers, in dem der Verstoß aufgetreten ist, ohne Fragment und ohne Zugangsdaten.

Beispiele

CSP-Verstöße im Dokument protokollieren

document.addEventListener('securitypolicyviolation', (event) => {
  console.log('Dokument:', event.documentURI);
  console.log('Blockiert:', event.blockedURI);
  console.log('Direktive:', event.effectiveDirective);
});

Dokument: https://example.com/shop?id=42 Blockiert: https://evil.example/tracker.js Direktive: script-src-elem

Verstöße an einen eigenen Logging-Endpunkt senden

const reportViolation = (event) => {
  const payload = {
    // Query-Parameter entfernen, damit keine Tokens mitgeschickt werden
    documentURI: event.documentURI.split('?')[0],
    blockedURI: event.blockedURI,
    directive: event.effectiveDirective,
    disposition: event.disposition,
    source: `${event.sourceFile}:${event.lineNumber}`
  };
  navigator.sendBeacon('/csp-log', JSON.stringify(payload));
};

window.addEventListener('securitypolicyviolation', reportViolation);

Verstöße in einem Worker erkennen

// worker.js
self.addEventListener('securitypolicyviolation', (event) => {
  self.postMessage({
    type: 'csp-violation',
    where: event.documentURI, // URI des Worker-Skripts
    blocked: event.blockedURI
  });
});

Event zu Testzwecken selbst erzeugen

const testEvent = new SecurityPolicyViolationEvent('securitypolicyviolation', {
  documentURI: 'https://example.com/test',
  violatedDirective: 'img-src',
  effectiveDirective: 'img-src',
  originalPolicy: "img-src 'self'",
  disposition: 'enforce',
  statusCode: 200,
  blockedURI: 'https://cdn.example/bild.png'
});

console.log(testEvent.documentURI);

https://example.com/test

// Wichtig · Fallstricke

Schreibgeschützt: Wenn man event.documentURI einen neuen Wert zuweist, passiert nichts (im Strict Mode gibt es einen TypeError). Einen eigenen Wert setzt man nur über das Init-Objekt im Konstruktor.
Datenschutz: Das Fragment und die Zugangsdaten werden entfernt, die Query-Parameter aber nicht. Vor dem Versand an Dritte oder in Logs sollte man die URL daher bereinigen.
Nicht verwechseln mit blockedURI: documentURI ist der Ort, an dem der Verstoß passiert ist. blockedURI ist die blockierte Ressource.
Nur-Bericht-Modus: Das Event wird auch bei Content-Security-Policy-Report-Only ausgelöst. In diesem Fall hat disposition den Wert "report".
Verstöße in iframes: Ein Verstoß in einem iframe landet im Kontext des iframes und nicht beim übergeordneten Dokument.
Kompatibilität: Wird in allen modernen Browsern unterstützt. Ältere Browser liefern den Wert unter Umständen nur über das Berichtsformat von report-uri.

Siehe auch

SecurityPolicyViolationEvent SecurityPolicyViolationEvent.blockedURI SecurityPolicyViolationEvent.effectiveDirective SecurityPolicyViolationEvent.sourceFile SecurityPolicyViolationEvent.referrer SecurityPolicyViolationEvent.columnNumber