CSPViolationReport.effectiveDirective — Eigenschaft · JavaScript-Referenz

Signatur

CSPViolationReport.effectiveDirective

Beschreibung

Die schreibgeschützte Eigenschaft effectiveDirective gehört zum Wörterbuch CSPViolationReport. Dieses Wörterbuch ist der body eines Report-Objekts vom Typ "csp-violation". Solche Berichte erzeugt die Reporting API. Sie kommen entweder bei einem ReportingObserver im Dokument an oder werden per HTTP an einen Endpunkt geschickt, den du mit Reporting-Endpoints und der CSP-Direktive report-to festlegst.

Der Wert nennt die tatsächlich durchgesetzte Direktive, nicht unbedingt die, die in der Richtlinie steht. Ein Beispiel: Die Richtlinie enthält nur default-src 'self' und ein fremdes Skript wird blockiert. Dann ist effectiveDirective trotzdem "script-src-elem", weil diese Direktive bei der Prüfung auf default-src zurückgefallen ist. So erfährst du genau, welche Art von Ressource oder Aktion blockiert wurde, etwa ein <script>-Element, ein Inline-Event-Handler (script-src-attr), ein Stylesheet oder ein fetch() (connect-src).

Typische Einsatzzwecke:

CSP-Verstöße nach Direktive gruppieren und auswerten, bevor du eine Richtlinie im Modus Content-Security-Policy-Report-Only scharf schaltest.
Gezielt die Direktive anpassen, die zu streng ist, statt pauschal default-src zu lockern.
Überwachung und Alarme: Verstöße gegen script-src-elem zum Beispiel höher priorisieren, weil sie auf XSS-Versuche hinweisen können.

Rückgabewert

Typ

string

Beschreibung

Name der verletzten, effektiv durchgesetzten Direktive in Kleinbuchstaben, z. B. "script-src-elem", "style-src-attr", "img-src", "connect-src" oder "frame-ancestors".

Beispiele

Verstöße im Browser mit ReportingObserver erfassen

// Seite ausgeliefert mit: Content-Security-Policy: default-src 'self'
const observer = new ReportingObserver((reports) => {
  for (const report of reports) {
    const { effectiveDirective, blockedURL, disposition } = report.body;
    console.log(`[${disposition}] ${effectiveDirective} blockierte ${blockedURL}`);
  }
}, { types: ['csp-violation'], buffered: true });

observer.observe();

// Löst einen Verstoß aus (fremde Quelle)
const img = document.createElement('img');
img.src = 'https://tracker.example.com/pixel.gif';
document.body.append(img);

[enforce] img-src blockierte https://tracker.example.com/pixel.gif

Berichts-Endpunkt in Node.js (Express) nach Direktive auswerten

// Antwort-Header der Seite:
// Reporting-Endpoints: csp="https://example.com/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', 'application/json'] }));

const stats = new Map();

app.post('/csp-reports', (req, res) => {
  const reports = Array.isArray(req.body) ? req.body : [req.body];
  for (const { type, body } of reports) {
    if (type !== 'csp-violation') continue;
    const key = body.effectiveDirective;
    stats.set(key, (stats.get(key) ?? 0) + 1);
  }
  console.log(Object.fromEntries(stats));
  res.sendStatus(204);
});

app.listen(3000);

{ 'script-src-elem': 3, 'script-src-attr': 1 }

Kritische Skript-Verstöße gesondert melden

const SCRIPT_DIRECTIVES = new Set(['script-src', 'script-src-elem', 'script-src-attr']);

const observer = new ReportingObserver((reports) => {
  const critical = reports
    .map((r) => r.body)
    .filter((body) => SCRIPT_DIRECTIVES.has(body.effectiveDirective));

  if (critical.length > 0) {
    navigator.sendBeacon('/security-alerts', JSON.stringify(critical.map((b) => ({
      directive: b.effectiveDirective,
      blocked: b.blockedURL,
      source: `${b.sourceFile}:${b.lineNumber}`
    }))));
  }
}, { types: ['csp-violation'] });

observer.observe();

// Wichtig · Fallstricke

Nicht mit der Richtlinie verwechseln: effectiveDirective kann eine Direktive nennen, die gar nicht in deiner Richtlinie steht, zum Beispiel script-src-elem bei einer Richtlinie mit nur default-src. Wie die vollständige Richtlinie aussah, steht in originalPolicy.
Feinere Direktiven: Moderne Browser melden bei Skripten und Styles meist die Varianten -elem oder -attr statt script-src bzw. style-src. Deine Auswertung sollte alle Varianten berücksichtigen.
Unterschiedliche Feldnamen: Bei der Reporting API heißt das Feld effectiveDirective (camelCase, Content-Type application/reports+json). Beim veralteten report-uri heißt es effective-directive und steht im Objekt csp-report (Content-Type application/csp-report). Ein Endpunkt, der beide Formate annimmt, muss beide Varianten verarbeiten.
Alternative im Dokument: Das DOM-Event securitypolicyviolation liefert denselben Wert über SecurityPolicyViolationEvent.effectiveDirective. Dessen violatedDirective ist ein veralteter Alias.
Kompatibilität: ReportingObserver und report-to werden von Chromium-basierten Browsern und Safari unterstützt. Firefox unterstützt sie nur eingeschränkt. Für breite Abdeckung solltest du zusätzlich report-uri angeben.
Sicherheit: Berichte an einen Endpunkt kann jeder fälschen. Prüfe und begrenze sie deshalb, bevor du sie speicherst. Gib Felder wie sample oder blockedURL nie ungefiltert in einem Admin-Dashboard als HTML aus, sonst entsteht dort eine XSS-Lücke.

Siehe auch

CSPViolationReport.lineNumber CSPViolationReport.blockedURL CSPViolationReport.referrer CSPViolationReport.sourceFile CSPViolationReport.disposition