SecurityPolicyViolationEvent.sample — Eigenschaft · JavaScript-Referenz

Signatur

SecurityPolicyViolationEvent.sample

Beschreibung

Die schreibgeschützte Eigenschaft sample eines SecurityPolicyViolationEvent enthält einen kurzen Ausschnitt des Codes, der gegen die Content Security Policy (CSP) verstoßen hat. Laut Spezifikation sind das die ersten 40 Zeichen eines blockierten Inline-Skripts, eines Inline-Event-Handlers (z. B. onclick="…"), eines Inline-Stylesheets oder eines Strings, der an eval() bzw. new Function() übergeben wurde.

Befüllt wird die Eigenschaft nur, wenn die betroffene Direktive das Schlüsselwort 'report-sample' enthält, z. B. script-src 'self' 'report-sample'. Fehlt es, oder wurde eine externe Ressource blockiert (etwa ein Skript von einer fremden Domain), ist sample eine leere Zeichenkette. Die blockierte URL steht dann in blockedURI.

In der Praxis brauchen Sie sample beim CSP-Monitoring: Wenn Sie eine neue Richtlinie mit Content-Security-Policy-Report-Only ausrollen, zeigt der Ausschnitt, welcher Inline-Code betroffen ist. Das hilft beim Unterscheiden zwischen eigenem Legacy-Code, Browser-Erweiterungen und echten Injektionsversuchen. Bei Verletzungen durch Trusted Types enthält sample den Namen der Senke und den Anfang des Werts, z. B. "Element innerHTML|<img src=x onerror=…".

Rückgabewert

Typ

string

Beschreibung

Die ersten bis zu 40 Zeichen des Codes, der die Verletzung ausgelöst hat. Eine leere Zeichenkette "", wenn 'report-sample' fehlt oder eine externe Ressource blockiert wurde.

Beispiele

CSP-Verletzungen mit Codeausschnitt protokollieren

// Das Event wird am Element bzw. Dokument ausgelöst und steigt bis zu document auf
document.addEventListener('securitypolicyviolation', (event) => {
  console.log('Direktive:', event.effectiveDirective);
  console.log('Blockiert:', event.blockedURI);
  console.log('Ausschnitt:', event.sample || '(kein Ausschnitt verfügbar)');
});

Direktive: script-src-elem Blockiert: inline Ausschnitt: console.log('Hallo von Inline-Skript')

Verletzung gezielt auslösen (CSP per meta-Tag mit 'report-sample')

// Im HTML-Head:
// <meta http-equiv="Content-Security-Policy"
//       content="script-src 'self' 'report-sample'">

document.addEventListener('securitypolicyviolation', (e) => {
  console.log(`${e.effectiveDirective}: "${e.sample}"`);
});

// Ein Inline-Event-Handler ist ohne 'unsafe-inline' nicht erlaubt
const button = document.createElement('button');
button.setAttribute('onclick', 'alert("Dieser Handler wird von der CSP blockiert")');
document.body.append(button);
button.click();

script-src-attr: "alert("Dieser Handler wird von der CSP bl"

Ausschnitt an ein Monitoring-Backend senden

const seen = new Set();

document.addEventListener('securitypolicyviolation', (e) => {
  // Doppelte Meldungen pro Seitenaufruf vermeiden
  const key = `${e.effectiveDirective}|${e.blockedURI}|${e.sample}`;
  if (seen.has(key)) return;
  seen.add(key);

  const report = {
    directive: e.effectiveDirective,
    blockedURI: e.blockedURI,
    sample: e.sample.slice(0, 40), // zusätzlich absichern
    source: `${e.sourceFile}:${e.lineNumber}:${e.columnNumber}`,
    disposition: e.disposition // "enforce" oder "report"
  };

  navigator.sendBeacon('/csp-monitor', JSON.stringify(report));
});

// Wichtig · Fallstricke

Ohne 'report-sample' ist der Wert leer: Sie müssen das Schlüsselwort in jede Direktive schreiben, für die Sie Ausschnitte haben wollen (script-src, style-src usw.). Wenn eine Direktive nur über default-src greift, muss es dort stehen.
Bei externen Ressourcen gibt es keinen Ausschnitt: Wird z. B. https://cdn.example.com/x.js blockiert, bleibt sample leer. Werten Sie in diesem Fall blockedURI aus.
Die Länge ist auf 40 Zeichen begrenzt. Das ist Absicht, damit keine größeren Mengen Seiteninhalt in Berichten landen. Rechnen Sie nicht damit, den vollständigen Code zu erhalten.
Sicherheit: Der Ausschnitt kann vom Angreifer kontrollierten Code enthalten, etwa eingeschleustes HTML oder JavaScript. Behandeln Sie ihn deshalb im Monitoring-Dashboard immer als unsicheren Text. Setzen Sie ihn also niemals per innerHTML ein, sondern escapen Sie ihn oder verwenden Sie textContent. Ausschnitte können außerdem personenbezogene Daten oder Tokens enthalten; beachten Sie das beim Speichern (DSGVO).
Browser-Erweiterungen erzeugen oft Verletzungen mit Ausschnitten, die gar nicht von Ihrer Seite stammen. Filtern Sie solche Meldungen z. B. über sourceFile (etwa chrome-extension://).
Die Eigenschaft entspricht dem Feld script-sample in klassischen report-uri-Berichten bzw. sample in Berichten der Reporting API (report-to).
Die Eigenschaft wird von allen aktuellen Browsern unterstützt. Im Internet Explorer gibt es sie nicht.

Siehe auch

SecurityPolicyViolationEvent.referrer SecurityPolicyViolationEvent.sourceFile SecurityPolicyViolationEvent.statusCode SecurityPolicyViolationEvent.blockedURI SecurityPolicyViolationEvent.lineNumber