SecurityPolicyViolationEvent.violatedDirective — Eigenschaft · JavaScript-Referenz

Signatur

SecurityPolicyViolationEvent.violatedDirective

Beschreibung

Die schreibgeschützte Eigenschaft violatedDirective eines SecurityPolicyViolationEvent enthält als String den Namen der Content-Security-Policy-Direktive (CSP), gegen die verstoßen wurde, etwa script-src, img-src oder style-src-attr. Das Ereignis securitypolicyviolation wird an document, an betroffene Elemente oder im Worker-Kontext an den Global Scope ausgelöst, sobald der Browser eine Ressource oder Aktion wegen der CSP blockiert oder im Modus Content-Security-Policy-Report-Only meldet.

Die Eigenschaft hilft vor allem beim Überwachen und Auswerten von CSP-Verstößen im Client: Man kann Verstöße nach Direktive gruppieren, gezielt an einen eigenen Logging-Endpunkt senden oder während der Entwicklung herausfinden, welche Regel eine Ressource blockiert.

Laut aktueller Spezifikation ist violatedDirective ein historischer Alias von effectiveDirective. Beide geben die Direktive zurück, die tatsächlich angewendet wurde. Fehlt also script-src und greift ersatzweise default-src, wird trotzdem die „wirksame“ Direktive wie script-src-elem gemeldet und nicht default-src. Die vollständige Richtlinie steht in originalPolicy.

Rückgabewert

Typ

string

Beschreibung

Name der verletzten CSP-Direktive, z. B. "script-src-elem", "img-src" oder "connect-src".

Beispiele

Verstöße per addEventListener protokollieren

// CSP z. B.: Content-Security-Policy: img-src 'self'
document.addEventListener('securitypolicyviolation', (event) => {
  console.log(`Verletzt: ${event.violatedDirective}`);
  console.log(`Blockiert: ${event.blockedURI}`);
});

// Löst einen Verstoß aus, weil das Bild von einer fremden Quelle kommt
const img = new Image();
img.src = 'https://example.com/bild.png';
document.body.append(img);

Verletzt: img-src Blockiert: https://example.com/bild.png

Verstöße an eigenen Logging-Endpunkt senden

const reportViolation = (event) => {
  const payload = {
    directive: event.violatedDirective,
    effective: event.effectiveDirective,
    blocked: event.blockedURI,
    source: `${event.sourceFile}:${event.lineNumber}`,
    disposition: event.disposition // 'enforce' oder 'report'
  };
  navigator.sendBeacon('/csp-log', JSON.stringify(payload));
};

document.addEventListener('securitypolicyviolation', reportViolation);

Verstöße nach Direktive zählen (on-Property)

const counter = new Map();

document.onsecuritypolicyviolation = ({ violatedDirective }) => {
  counter.set(violatedDirective, (counter.get(violatedDirective) ?? 0) + 1);
};

// Später, z. B. im Debug-Panel
setTimeout(() => {
  console.table(Object.fromEntries(counter));
}, 5000);

┌─────────────────┬────────┐ │ (index) │ Values │ ├─────────────────┼────────┤ │ script-src-elem │ 2 │ │ img-src │ 1 │ └─────────────────┴────────┘

Ereignis manuell erzeugen (z. B. für Tests)

const evt = new SecurityPolicyViolationEvent('securitypolicyviolation', {
  violatedDirective: 'script-src',
  effectiveDirective: 'script-src',
  originalPolicy: "script-src 'self'",
  blockedURI: 'inline',
  disposition: 'enforce',
  statusCode: 200
});

console.log(evt.violatedDirective);

script-src

// Wichtig · Fallstricke

Alias von effectiveDirective: Moderne Browser liefern die wirksame Direktive, z. B. script-src-elem statt script-src oder default-src. Ältere Browserversionen gaben teilweise die Direktive samt Quellenliste zurück (z. B. "img-src 'self'"). Wer robust auswerten will, sollte mit split(' ')[0] nur den Namen abtrennen oder direkt effectiveDirective verwenden.
Das Ereignis wird auch im Report-Only-Modus ausgelöst. Ob wirklich blockiert wurde, steht in disposition ("enforce" oder "report").
Ein Listener kann den Verstoß nicht verhindern oder rückgängig machen. Er dient nur der Beobachtung.
Sicherheit: Werte wie blockedURI oder sample können von Angreifern gesteuert sein. Vor der Anzeige im DOM immer escapen, also nie per innerHTML einsetzen.
Verstöße, die entstehen, bevor das Skript den Listener registriert, werden nicht erfasst. Für eine vollständige Erfassung eignen sich serverseitige Berichte über report-to bzw. report-uri.

Siehe auch

SecurityPolicyViolationEvent.statusCode SecurityPolicyViolationEvent.effectiveDirective SecurityPolicyViolationEvent.blockedURI SecurityPolicyViolationEvent.disposition SecurityPolicyViolationEvent.documentURI