CSPViolationReport.disposition — Eigenschaft · JavaScript-Referenz

Signatur

CSPViolationReport.disposition

Beschreibung

Die schreibgeschützte Eigenschaft disposition gehört zum Wörterbuch CSPViolationReport. Dieses Objekt steht in der Eigenschaft body eines Report-Objekts vom Typ "csp-violation". Solche Berichte liefert die Reporting API, entweder im Browser über einen ReportingObserver oder als JSON an einen Server-Endpunkt, der mit der CSP-Direktive report-to und dem Header Reporting-Endpoints festgelegt wird.

Der Wert ist immer eine von zwei Zeichenketten:

"enforce": Die Richtlinie kam aus einem Content-Security-Policy-Header (oder einem <meta>-Tag). Die Ressource bzw. Aktion wurde tatsächlich blockiert.
"report": Die Richtlinie kam aus einem Content-Security-Policy-Report-Only-Header. Der Verstoß wurde nur gemeldet, die Ressource wurde trotzdem geladen oder ausgeführt.

Im Alltag brauchen Sie die Eigenschaft vor allem, um eine neue CSP schrittweise einzuführen. Sie betreiben dann eine strengere Richtlinie zunächst im Report-Only-Modus, parallel zur aktiven Richtlinie, und werten beide Berichtsarten getrennt aus. Echte Blockaden ("enforce") können die Funktion der Seite beeinträchtigen und sollten sofort alarmieren. "report"-Einträge zeigen dagegen, was eine künftige Richtlinie kaputt machen würde.

Rückgabewert

Typ

"enforce" | "report"

Beschreibung

"enforce", wenn die verletzte Richtlinie durchgesetzt wurde. "report", wenn sie nur im Report-Only-Modus aktiv war.

Beispiele

Verstöße im Browser mit ReportingObserver nach Disposition trennen

// Voraussetzung: Die Seite wird mit einer CSP ausgeliefert, z. B.
// Content-Security-Policy: img-src 'self'
// Content-Security-Policy-Report-Only: script-src 'self'

const observer = new ReportingObserver((reports) => {
  for (const report of reports) {
    const { disposition, effectiveDirective, blockedURL } = report.body;

    if (disposition === 'enforce') {
      console.error(`Blockiert (${effectiveDirective}): ${blockedURL}`);
    } else {
      console.warn(`Nur gemeldet (${effectiveDirective}): ${blockedURL}`);
    }
  }
}, { types: ['csp-violation'], buffered: true });

observer.observe();

// Löst einen Verstoß gegen img-src aus
const img = new Image();
img.src = 'https://example.org/bild.png';
document.body.append(img);

Blockiert (img-src): https://example.org/bild.png

Berichte serverseitig empfangen (Node.js/Express)

// Antwort-Header der Webseite:
// Reporting-Endpoints: csp-endpoint="https://example.com/csp-reports"
// Content-Security-Policy-Report-Only: script-src 'self'; report-to csp-endpoint

import express from 'express';

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

app.post('/csp-reports', (req, res) => {
  // Der Browser schickt ein Array von Report-Objekten
  for (const report of req.body) {
    if (report.type !== 'csp-violation') continue;

    const { disposition, effectiveDirective, documentURL } = report.body;
    const label = disposition === 'enforce' ? 'AKTIV' : 'TEST';
    console.log(`[${label}] ${effectiveDirective} auf ${documentURL}`);
  }
  res.sendStatus(204);
});

app.listen(3000);

[TEST] script-src-elem auf https://example.com/

Statistik: Report-Only-Verstöße vor dem Umstellen auf enforce zählen

const stats = { enforce: 0, report: 0 };

const observer = new ReportingObserver((reports) => {
  for (const { body } of reports) {
    stats[body.disposition] += 1;
  }
  console.table(stats);
}, { types: ['csp-violation'] });

observer.observe();

┌─────────┬────────┐ │ (index) │ Values │ ├─────────┼────────┤ │ enforce │ 0 │ │ report │ 3 │ └─────────┴────────┘

// Wichtig · Fallstricke

Browser-Kompatibilität: ReportingObserver und Berichte vom Typ "csp-violation" werden vor allem von Chromium-basierten Browsern unterstützt. Firefox und Safari unterstützen sie nur teilweise oder erst in neueren Versionen. Nutzen Sie als Rückfalllösung das Ereignis securitypolicyviolation mit SecurityPolicyViolationEvent.disposition, das in allen aktuellen Browsern verfügbar ist.
Nicht verwechseln: Das veraltete Berichtsformat über report-uri (application/csp-report) verwendet Bindestrich-Schlüssel wie \"disposition\" und \"blocked-uri\" in einem Objekt \"csp-report\". Das neue Format der Reporting API nutzt camelCase (blockedURL, effectiveDirective) in body.
Wenn für dieselbe Seite sowohl ein aktiver als auch ein Report-Only-Header existiert, kann ein und dieselbe Ressource zwei Berichte auslösen, je einen pro Disposition.
Berichte werden gebündelt und zeitversetzt verschickt. Verlassen Sie sich serverseitig nicht auf sofortige Zustellung. Behandeln Sie die Daten außerdem als nicht vertrauenswürdige Eingaben, denn jeder Client kann gefälschte Berichte an Ihren Endpunkt senden.
Die Eigenschaft ist schreibgeschützt. CSPViolationReport ist ein Wörterbuch und kein Konstruktor, Sie können es also nicht selbst instanziieren.

Siehe auch

CSPViolationReport.documentURL CSPViolationReport.lineNumber CSPViolationReport.sample CSPViolationReport.sourceFile CSPViolationReport.statusCode