SecurityPolicyViolationEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface SecurityPolicyViolationEvent extends Event

Beschreibung

Die Schnittstelle SecurityPolicyViolationEvent erbt von Event. Sie beschreibt das Ereignisobjekt des securitypolicyviolation-Ereignisses. Der Browser löst dieses Ereignis an einem Element, am Document oder in einem Worker aus, sobald die Content Security Policy (CSP) eine Aktion blockiert oder (im Modus Content-Security-Policy-Report-Only) nur meldet. Das Ereignis steigt im DOM auf (Bubbling) und ist mit composed markiert, dringt also auch aus Shadow-DOM-Bäumen nach außen.

Mit dem Ereignis kannst du CSP-Verstöße direkt im Client erkennen und auswerten, ohne einen Server-Endpunkt für report-uri bzw. report-to zu betreiben. Typische Einsatzfälle: eine neue Richtlinie im Report-Only-Modus testen, blockierte Drittanbieter-Skripte protokollieren oder Fehler an ein eigenes Monitoring senden.

Wichtige schreibgeschützte Eigenschaften:

blockedURI – URI der blockierten Ressource bzw. Schlüsselwörter wie inline, eval, wasm-eval.
violatedDirective / effectiveDirective – verletzte Direktive (z. B. script-src-elem).
originalPolicy – die vollständige Richtlinie als Zeichenkette.
disposition – "enforce" (blockiert) oder "report" (nur gemeldet).
documentURI, referrer, sourceFile, lineNumber, columnNumber, sample, statusCode.

Der Konstruktor new SecurityPolicyViolationEvent(type, init) wird meist nur in Tests verwendet, um echte Verstöße zu simulieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Regel `"securitypolicyviolation"`.
$options	SecurityPolicyViolationEventInit	{}	Objekt mit den Feldern von `EventInit` (`bubbles`, `cancelable`, `composed`) sowie `blockedURI`, `violatedDirective`, `effectiveDirective`, `originalPolicy`, `disposition`, `documentURI`, `referrer`, `sourceFile`, `sample`, `statusCode`, `lineNumber`, `columnNumber`. In einigen Browsern sind `documentURI`, `effectiveDirective`, `originalPolicy`, `disposition` und `statusCode` Pflichtfelder.

Rückgabewert

Typ

SecurityPolicyViolationEvent

Beschreibung

Eine neue Instanz des Ereignisobjekts (nur beim Konstruktor-Aufruf).

Beispiele

CSP-Verstöße global protokollieren

// Fängt alle Verstöße im Dokument ab (das Ereignis steigt bis zum document auf)
document.addEventListener('securitypolicyviolation', (event) => {
  console.warn('CSP-Verstoß:', {
    blockiert: event.blockedURI,
    direktive: event.effectiveDirective,
    modus: event.disposition,
    quelle: `${event.sourceFile}:${event.lineNumber}:${event.columnNumber}`,
    ausschnitt: event.sample
  });
});

// Test: Bei CSP "script-src 'self'" wird dieses Inline-Skript blockiert
const s = document.createElement('script');
s.textContent = 'console.log("inline")';
document.body.append(s);

CSP-Verstoß: { blockiert: 'inline', direktive: 'script-src-elem', modus: 'enforce', ... }

Verstöße an ein eigenes Monitoring senden

const reportViolation = (event) => {
  const payload = JSON.stringify({
    blockedURI: event.blockedURI,
    directive: event.effectiveDirective,
    disposition: event.disposition,
    page: event.documentURI,
    source: event.sourceFile,
    line: event.lineNumber,
    time: Date.now()
  });
  // sendBeacon funktioniert auch beim Verlassen der Seite zuverlässig
  navigator.sendBeacon('/api/csp-report', payload);
};

document.addEventListener('securitypolicyviolation', reportViolation);

// Später, z. B. nach Abschluss eines Report-Only-Tests:
// document.removeEventListener('securitypolicyviolation', reportViolation);

Ereignis im Test selbst erzeugen

const fakeEvent = new SecurityPolicyViolationEvent('securitypolicyviolation', {
  bubbles: true,
  composed: true,
  blockedURI: 'https://evil.example/tracker.js',
  violatedDirective: 'script-src-elem',
  effectiveDirective: 'script-src-elem',
  originalPolicy: "script-src 'self'",
  disposition: 'enforce',
  documentURI: location.href,
  statusCode: 200
});

document.addEventListener('securitypolicyviolation', (e) => {
  console.log(e instanceof SecurityPolicyViolationEvent, e.blockedURI);
}, { once: true });

document.body.dispatchEvent(fakeEvent);

true https://evil.example/tracker.js

// Wichtig · Fallstricke

Kein Ersatz für serverseitiges Reporting: Wird ein Skript blockiert, bevor dein Listener registriert ist (z. B. ganz oben im <head>), bekommst du den Verstoß nicht mit. Registriere den Listener möglichst früh und nutze zusätzlich report-to.
Nicht abbrechbar: preventDefault() hat keine Wirkung; die Blockade durch die CSP lässt sich nicht aufheben.
Datenschutz/Sicherheit: blockedURI wird bei Weiterleitungen und fremden Ursprüngen oft auf den Ursprung gekürzt. sample enthält höchstens 40 Zeichen und nur dann, wenn die Richtlinie 'report-sample' enthält. Angreifer können über eingeschleusten Code gefälschte Ereignisse auslösen – vertraue Client-Reports daher nicht blind, prüfe ggf. event.isTrusted.
violatedDirective ist ein veralteter Alias für effectiveDirective; nutze bevorzugt Letzteres.
In Workern registrierst du den Listener über self.addEventListener('securitypolicyviolation', …). Alternativ gibt es die Property onsecuritypolicyviolation an Document, Element und WorkerGlobalScope.
Kompatibilität: in allen aktuellen Browsern verfügbar; Firefox erst ab Version 63.

Siehe auch

Event PermissionsPolicyViolationReport SecurePaymentConfirmationRequest DeviceOrientationEvent MerchantValidationEvent