Signatur
Beschreibung
Das Wörterbuch IntegrityViolationReport beschreibt einen Bericht der Reporting API. Der Browser erzeugt ihn, wenn ein Dokument gegen seine Integritätsrichtlinie verstößt. Die Richtlinie legen Sie mit den HTTP-Headern Integrity-Policy oder Integrity-Policy-Report-Only fest. Damit können Sie z. B. erzwingen, dass jedes geladene Skript ein gültiges integrity-Attribut hat (Subresource Integrity, SRI). Ein <script src="…"> ohne Integritäts-Metadaten ist dann ein Verstoß.
Der Bericht hat den Aufbau aller Reporting-API-Berichte:
type: immer"integrity-violation"url: die URL des Dokuments, in dem der Verstoß aufgetreten istbody: einIntegrityViolationReportBodymit den Einzelheiten
Im body stehen documentURL (URL des Dokuments), blockedURL (URL der betroffenen Ressource), destination (Ressourcentyp, derzeit "script") und reportOnly. reportOnly ist true, wenn der Verstoß nur gemeldet und nicht blockiert wurde.
Auf zwei Wegen kommen Sie an die Berichte: Im Browser lesen Sie sie mit einem ReportingObserver und dem Typfilter "integrity-violation". Oder Sie lassen sie an einen Server-Endpunkt schicken, den Sie mit Reporting-Endpoints festlegen und in der Richtlinie mit endpoints=(…) angeben. Ein sinnvoller Ablauf für die Einführung: Starten Sie mit Integrity-Policy-Report-Only, sammeln Sie alle Skripte ohne SRI und stellen Sie danach auf erzwingenden Betrieb um.
Rückgabewert
ReportingObserver, über observer.takeRecords() oder als JSON am Reporting-Endpunkt.Beispiele
Integritätsrichtlinie per HTTP-Header aktivieren (Node.js/Express)
import express from 'express';
const app = express();
app.use((req, res, next) => {
// Endpunkt für Berichte festlegen
res.setHeader('Reporting-Endpoints', 'integrity-endpoint="https://example.com/reports"');
// Nur melden, nicht blockieren: Skripte ohne SRI werden gemeldet
res.setHeader(
'Integrity-Policy-Report-Only',
'blocked-destinations=(script), endpoints=(integrity-endpoint)'
);
next();
});
app.use(express.static('public'));
app.listen(3000, () => console.log('Server läuft auf Port 3000'));Verstöße im Browser mit ReportingObserver auslesen
const observer = new ReportingObserver((reports) => {
for (const report of reports) {
const { documentURL, blockedURL, destination, reportOnly } = report.body;
console.log(`[${report.type}] ${destination} ${blockedURL}`);
console.log(`Dokument: ${documentURL}, nur melden: ${reportOnly}`);
}
}, { types: ['integrity-violation'], buffered: true });
observer.observe();
// Ein Skript ohne integrity-Attribut erzeugt einen Verstoß
const script = document.createElement('script');
script.src = 'https://cdn.example.com/lib.js';
document.head.append(script);Berichte am Server-Endpunkt empfangen
import express from 'express';
const app = express();
app.use(express.json({ type: 'application/reports+json' }));
app.post('/reports', (req, res) => {
const violations = req.body.filter((r) => r.type === 'integrity-violation');
for (const { url, body } of violations) {
console.warn('SRI fehlt:', body.blockedURL, 'auf', url);
}
res.sendStatus(204);
});
app.listen(3000);Browser-Unterstützung prüfen und Richtlinie erzwingen
// Vorher per Header gesetzt:
// Integrity-Policy: blocked-destinations=(script), endpoints=(integrity-endpoint)
if (!('ReportingObserver' in globalThis)) {
console.log('ReportingObserver wird nicht unterstützt');
} else {
const observer = new ReportingObserver((reports) => {
const blocked = reports.filter((r) => !r.body.reportOnly);
console.log(`${blocked.length} Skript(e) blockiert`);
}, { types: ['integrity-violation'] });
observer.observe();
}// Wichtig · Fallstricke
- Experimentell:
Integrity-Policyund der Berichtstyp"integrity-violation"gibt es derzeit nur in Chromium-Browsern (ab Version 138). Firefox und Safari erzeugen keine solchen Berichte. Verlassen Sie sich deshalb nicht allein darauf. - Es gibt keinen Konstruktor. Berichte erzeugt nur der Browser. Sie können sie nur lesen.
- Derzeit ist nur
destination = "script"spezifiziert. Stylesheets und andere Ressourcentypen werden (noch) nicht geprüft. - Geprüft wird nur, ob Integritäts-Metadaten vorhanden sind. Ob ein Hash falsch ist, meldet die normale SRI-Prüfung: Das Laden schlägt dann fehl und es gibt einen Konsolenfehler.
- Ohne Reporting-Endpunkt (
Reporting-Endpointsundendpoints=(…)) werden Berichte nur lokal anReportingObserverübergeben. Der Browser verschickt sie gebündelt und verzögert, also nicht in Echtzeit. - Sicherheit:
blockedURLkann URLs mit Query-Parametern enthalten, z. B. Tokens. Speichern Sie Berichte daher datenschutzgerecht. Behandeln Sie außerdem eingehende Berichte am Endpunkt als nicht vertrauenswürdige Eingaben, denn sie lassen sich fälschen. - Die Richtlinie gilt zusätzlich zur Content Security Policy und ersetzt sie nicht. Am besten kombinieren Sie beide.