CSPViolationReport.referrer — Eigenschaft · JavaScript-Referenz

Signatur

CSPViolationReport.referrer

Beschreibung

Die Eigenschaft referrer gehört zum Wörterbuch CSPViolationReport. Dieses Objekt ist der body eines Berichts vom Typ "csp-violation" aus der Reporting API. Sie enthält die URL der Seite, von der aus der Nutzer auf das Dokument mit der CSP-Verletzung gekommen ist, also den Referrer dieses Dokuments.

Nützlich ist der Wert vor allem bei der Auswertung von CSP-Berichten. Er zeigt, über welche Einstiegsseiten oder externen Links Nutzer auf betroffene Seiten kommen. So lassen sich zum Beispiel Verletzungen, die durch eingeschleuste Parameter aus einer bestimmten Quelle ausgelöst werden, von Problemen in der eigenen Seite unterscheiden.

Der Bericht erreicht Sie auf zwei Wegen:

clientseitig über einen ReportingObserver mit types: ["csp-violation"], als report.body.referrer;
serverseitig als JSON an den Endpunkt, der über den HTTP-Header Reporting-Endpoints und die CSP-Direktive report-to festgelegt ist.

Der Wert ist schreibgeschützt. Er ist ein leerer String oder null, wenn es keinen Referrer gibt, etwa bei direkter Eingabe der Adresse oder wegen einer strengen Referrer-Policy.

Rückgabewert

Typ

string | null

Beschreibung

Die URL der verweisenden Seite des betroffenen Dokuments. Je nach Referrer-Policy kann sie gekürzt sein (nur Origin). Ist kein Referrer vorhanden, ist der Wert leer bzw. null.

Beispiele

Referrer im Browser mit ReportingObserver auslesen

// Voraussetzung: Die Seite liefert eine CSP aus, z. B.
// Content-Security-Policy: script-src 'self'
const observer = new ReportingObserver((reports) => {
  for (const report of reports) {
    const { referrer, blockedURL, effectiveDirective } = report.body;
    console.log(`Verletzung: ${effectiveDirective} blockierte ${blockedURL}`);
    console.log(`Referrer: ${referrer || '(keiner)'}`);
  }
}, { types: ['csp-violation'], buffered: true });

observer.observe();

// Verletzung provozieren: externes Skript laden
const s = document.createElement('script');
s.src = 'https://cdn.example.org/lib.js';
document.head.append(s);

Verletzung: script-src-elem blockierte https://cdn.example.org/lib.js Referrer: https://www.google.com/

CSP-Berichte serverseitig nach Referrer gruppieren (Node.js/Express)

import express from 'express';

const app = express();
const stats = new Map();

// Header für alle Antworten setzen
app.use((req, res, next) => {
  res.set('Reporting-Endpoints', 'csp="/csp-reports"');
  res.set('Content-Security-Policy', "script-src 'self'; report-to csp");
  next();
});

app.post('/csp-reports', express.json({ type: 'application/reports+json' }), (req, res) => {
  for (const report of req.body) {
    if (report.type !== 'csp-violation') continue;
    const ref = report.body.referrer || '(direkt)';
    stats.set(ref, (stats.get(ref) ?? 0) + 1);
  }
  console.log(Object.fromEntries(stats));
  res.sendStatus(204);
});

app.listen(3000);

{ 'https://www.google.com/': 3, '(direkt)': 1 }

Nur Verletzungen mit externem Referrer melden

const isExternal = (url) => {
  if (!url) return false;
  try {
    return new URL(url).origin !== location.origin;
  } catch {
    return false;
  }
};

new ReportingObserver((reports) => {
  const extern = reports.filter((r) => isExternal(r.body.referrer));
  if (extern.length) {
    navigator.sendBeacon('/analytics/csp', JSON.stringify(
      extern.map((r) => ({ referrer: r.body.referrer, blocked: r.body.blockedURL }))
    ));
  }
}, { types: ['csp-violation'] }).observe();

// Wichtig · Fallstricke

Kompatibilität: ReportingObserver und der Berichtstyp "csp-violation" werden vor allem von Chromium-Browsern unterstützt. Für breitere Unterstützung eignet sich zusätzlich das Event securitypolicyviolation (SecurityPolicyViolationEvent.referrer).
Altes Format: Bei der veralteten Direktive report-uri sendet der Browser ein anderes JSON ({"csp-report": {...}}) mit Schlüsseln wie "document-uri". Das Feld heißt dort ebenfalls "referrer", der Rest der Struktur unterscheidet sich aber. Ein Server-Endpunkt sollte beide Formate verarbeiten können.
Referrer-Policy: Der Wert richtet sich nach der gültigen Referrer-Policy. Bei no-referrer ist er leer. Bei strict-origin-when-cross-origin (Standard) enthält er bei fremden Ursprüngen nur den Origin, keinen Pfad.
Datenschutz und Sicherheit: Referrer-URLs können personenbezogene Daten oder Token in Query-Parametern enthalten. Speichern Sie sie nur gekürzt oder anonymisiert. Behandeln Sie empfangene Berichte als nicht vertrauenswürdige Eingaben, denn jeder kann gefälschte Berichte an den Endpunkt senden. Werte vor der Anzeige in einem Dashboard daher immer escapen (XSS).
Die Eigenschaft ist schreibgeschützt. Sie ist nur über report.body zugänglich, nicht als globales Objekt.

Siehe auch

Document.referrer CSPViolationReport.effectiveDirective CSPViolationReport.lineNumber CSPViolationReport.sample CSPViolationReport.sourceFile