Content-Security-Policy-Beispiele: So bauen Sie eine strikte CSP für Ihre Website

1. Was eine Content-Security-Policy leistet und was nicht

Eine Policy ist eine Liste von Direktiven, getrennt durch Semikolons. Jede Direktive nennt einen Ressourcentyp und die dafür erlaubten Quellen: script-src für JavaScript, style-src für CSS, img-src, font-src, connect-src für Fetch-, XHR- und WebSocket-Verbindungen sowie frame-src für Frames, die die Seite einbettet. default-src dient als Rückfallwert für diese Fetch-Direktiven, wenn eine bestimmte fehlt (W3C CSP Level 3).

Drei wichtige Direktiven greifen nicht auf default-src zurück: frame-ancestors (welche Websites Ihre Seite in einen Frame laden dürfen), base-uri (was ein <base>-Element setzen darf) und form-action (wohin Formulare senden dürfen). Eine Policy, die nur default-src 'self' enthält, lässt also weiterhin zu, dass jede Website Ihre Seite einbettet und ein eingeschleustes <base>-Tag relative URLs umleitet.

Quellangaben gibt es in drei Formen:

• Schlüsselwörter in einfachen Anführungszeichen: 'self' (der eigene Origin der Seite), 'none' (nichts), 'unsafe-inline', 'unsafe-eval' und 'strict-dynamic'.
• Hosts und Schemata: https://cdn.example.com, https://*.example.com, https: oder data:.
• Nonces und Hashes: 'nonce-…' und 'sha256-…', die einzelne Script- oder Style-Elemente freigeben statt ganzer Hosts.

Senden Sie die Policy als HTTP-Header. Ein <meta http-equiv="Content-Security-Policy">-Tag funktioniert für die meisten Direktiven, doch die Spezifikation schließt dort frame-ancestors, report-uri und sandbox aus, und eine Report-Only-Policy lässt sich per Meta-Tag überhaupt nicht ausliefern (MDN-Leitfaden zur CSP). Bleiben Sie realistisch: Eine CSP begrenzt, was eingeschleuster Code anrichten kann. Sie ersetzt weder das Escaping von Ausgaben noch die Validierung von Eingaben, die die Einschleusung von vornherein verhindern.

2. Drei Content-Security-Policy-Beispiele als Ausgangspunkt

Beispiel A: eine Website ohne Skripte von Drittanbietern. Eine Allowlist-Policy funktioniert, wenn jedes Skript und jedes Stylesheet als Datei auf Ihrem eigenen Origin liegt:

Content-Security-Policy: default-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'; upgrade-insecure-requests

Sie blockiert jedes Inline-<script>, jedes style-Attribut und alles, was von anderen Hosts kommt. Damit passt sie zu handgebauten oder statisch generierten Websites ohne Einbettungen.

Beispiel B: eine serverseitig gerenderte Website mit Nonce. Das ist die strikte Policy, die web.dev für Seiten empfiehlt, die der Server pro Anfrage erzeugt, ergänzt um Frame-Schutz:

Content-Security-Policy: script-src 'nonce-R4nd0mBase64Value' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'

Die Nonce ändert sich mit jeder Antwort (Abschnitt 3). Beachten Sie, was fehlt: Ohne default-src bleiben Styles, Bilder, Fonts und Verbindungen unbeschränkt. Das ist ein bewusster Kompromiss: Die Policy konzentriert sich auf die Ausführung von Skripten, wo Cross-Site-Scripting den größten Schaden anrichtet, und vermeidet Hostlisten, die bei jedem Domainwechsel eines Anbieters brechen.

Beispiel C: statische oder gecachte Seiten mit Hashes. Wenn alle Besucher dasselbe HTML erhalten, geben Sie Inline-Skripte über ihren Hash frei:

Content-Security-Policy: script-src 'sha256-BASE64_HASH_OF_INLINE_LOADER' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'

Ganz gleich, welche Variante Sie wählen: Ergänzen Sie die Berichtsdirektiven aus Abschnitt 6 und senden Sie die Policy zunächst als Content-Security-Policy-Report-Only.

3. Nonces und Hashes statt 'unsafe-inline'

'unsafe-inline' erlaubt jedes Inline-Skript, auch eines, das ein Angreifer eingeschleust hat, und hebt damit den größten Teil dessen auf, was eine CSP gegen Cross-Site-Scripting leistet. Nonces und Hashes geben nur den Inline-Code frei, den Sie tatsächlich ausliefern wollen. Browser ignorieren 'unsafe-inline' in einer Direktive, die zusätzlich eine Nonce oder einen Hash enthält (MDN). Deshalb kann es in einer strikten Policy als Rückfall für sehr alte Browser stehen bleiben.

Nonces

Eine Nonce ist ein Zufallswert, den der Server für jede Antwort erzeugt, in den Header schreibt und in das nonce-Attribut jedes Skripts kopiert, das ausgeführt werden soll. Sie muss unvorhersehbar und bei jeder Antwort neu sein; web.dev empfiehlt mindestens 128 Bit aus einem kryptografisch sicheren Zufallsgenerator. In einer Node.js-Anwendung:

import crypto from 'node:crypto';

app.use((req, res, next) => {
  const nonce = crypto.randomBytes(16).toString('base64');
  res.locals.nonce = nonce;
  res.setHeader('Content-Security-Policy',
    `script-src 'nonce-${nonce}' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'`);
  next();
});

Das Template schreibt dann <script nonce="…" src="/app.js"></script> mit demselben Wert. Setzen Sie die Nonce dort, wo Ihre Templates Ihre eigenen Script-Tags erzeugen, und niemals, indem Sie alle <script>-Tags im fertigen HTML umschreiben: Eine pauschale Ersetzung würde auch ein eingeschleustes Skript freigeben. Zwei Fallen sind häufig: Ein CDN oder Seiten-Cache, der das HTML speichert, liefert allen Besuchern dieselbe Nonce aus, und ein Wert, der beim Build in eine statische Datei geschrieben wird, ist keine Nonce.

Hashes

Ein Hash gibt genau ein Inline-Skript frei: den base64-kodierten SHA-256-, SHA-384- oder SHA-512-Hash des Textes zwischen den Script-Tags. Jedes Zeichen zählt, auch Leerzeichen und Zeilenumbrüche, sodass eine Änderung am Minifier oder Template einen neuen Hash ergibt. Darum eignen sich Hashes besser für statische und gecachte Seiten, deren Inhalt für alle gleich ist. Chrome zeigt in der Konsole den erwarteten Hash an, wenn es ein Inline-Skript blockiert; Sie können ihn auch selbst berechnen:

printf '%s' 'console.log("hello")' | openssl dgst -sha256 -binary | openssl base64

Was beide nicht erlauben

Inline-Event-Handler wie onclick="…" und javascript:-URLs blockiert eine Nonce- oder Hash-basierte Policy. Verlagern Sie diesen Code in Skriptdateien und binden Sie ihn mit addEventListener an. 'unsafe-hashes' kann einen bestimmten Handler über seinen Hash erlauben, sollte aber nur eine Übergangslösung sein. Code, der Zeichenketten als Code ausführt, etwa eval(), new Function() oder setTimeout mit einem String, braucht 'unsafe-eval'. Ersetzen Sie ihn, wo es geht, und nutzen Sie das engere 'wasm-unsafe-eval', wenn nur WebAssembly kompiliert werden muss (MDN script-src).

4. strict-dynamic: vertrauenswürdige Skripte laden lassen, was sie brauchen

Auf den meisten Websites laufen Skripte, die weitere Skripte nachladen: Ein Tag-Manager fügt Analytics hinzu, ein Consent-Banner seine Anbieter, ein Chat-Widget sein eigenes Bundle. Jeden Host aufzulisten, den sie verwenden könnten, ist fehleranfällig. 'strict-dynamic' geht einen anderen Weg: Ein per Nonce oder Hash erlaubtes Skript darf weitere Skripte hinzufügen, und auch diese gelten als vertrauenswürdig.

In Browsern, die es unterstützen, sorgt 'strict-dynamic' außerdem dafür, dass Host-Allowlists, 'self' und 'unsafe-inline' in script-src ignoriert werden (MDN). Daraus folgen drei Dinge:

• Jedes <script>-Tag in Ihrem HTML braucht die Nonce oder einen passenden Hash, auch Skripte vom eigenen Origin, denn 'self' gibt sie nicht mehr frei.
• Skripte, die ein vertrauenswürdiges Skript mit document.createElement('script') erzeugt, sind erlaubt. Skripte, die mit document.write in die Seite geschrieben werden (vom Parser eingefügte Skripte), sind es nicht; alte Einbettungs-Snippets, die darauf setzen, funktionieren dann nicht mehr.
• Vertrauen wird weitergegeben. Alles, was Ihr Tag-Manager lädt, wird ausgeführt. Wer dort veröffentlichen darf, kann also faktisch Code auf Ihrer Website ausführen. Behandeln Sie diesen Zugang wie einen Deployment-Zugang.

Für ältere Browser ergänzen Sie Rückfallwerte, die neuere Browser ignorieren:

script-src 'nonce-R4nd0mBase64Value' 'strict-dynamic' https: 'unsafe-inline'; object-src 'none'; base-uri 'none'

Ein Browser mit Unterstützung für CSP Level 3 wendet nur die Nonce und 'strict-dynamic' an. Ein Browser, der Nonces kennt, aber 'strict-dynamic' nicht, nutzt die Nonce und https:, und ein sehr alter Browser fällt auf 'unsafe-inline' https: zurück. Google dokumentiert ein Nonce-fähiges Tag-Manager-Snippet, das die Nonce an die hinzugefügten Skripte weitergibt, und weist darauf hin, dass benutzerdefinierte JavaScript-Variablen im Tag Manager weiterhin 'unsafe-eval' benötigen (CSP-Leitfaden zum Tag Manager).

5. frame-ancestors, object-src 'none' und base-uri: Direktiven, die Sie ausdrücklich setzen sollten

• frame-ancestors legt fest, welche Websites Ihre Seite in einem Frame einbetten dürfen, und schützt so vor Clickjacking. Verwenden Sie 'none', wenn niemand die Seite einbetten muss, 'self', wenn nur Ihre eigenen Seiten das tun, oder nennen Sie exakte Origins wie https://app.example.com. Die Direktive wirkt nur im HTTP-Header. X-Frame-Options (DENY oder SAMEORIGIN) bleibt ein Rückfall für ältere Browser; beide sollten dieselbe Einbettung erlauben (MDN frame-ancestors).
• object-src 'none' blockiert <object> und <embed>. Plugins gibt es in modernen Browsern nicht mehr, doch diese Elemente können weiterhin Inhalte laden, und eine strikte Policy ohne default-src lässt sie unbeschränkt, wenn Sie nichts anderes angeben.
• base-uri 'none', oder 'self', falls Ihre Seiten ein <base>-Element nutzen, verhindert, dass ein eingeschleustes <base href> alle relativen Skript-URLs auf einen fremden Host umleitet.
• form-action 'self' begrenzt, wohin Formulare senden dürfen. Ergänzen Sie den Origin Ihres Zahlungs- oder Login-Anbieters, falls ein Formular dorthin sendet, und testen Sie diese Abläufe nach der Änderung.
• upgrade-insecure-requests lässt den Browser http://-Unterressourcen über HTTPS laden. Das hilft gegen Mixed Content, ersetzt aber kein HSTS.

Schreiben Sie diese Direktiven ausdrücklich in jede Policy, auch in die Beispiele B und C. Sie erfordern kaum Pflege und schließen Lücken, die die Skriptregeln offenlassen.

6. Verstöße melden mit report-to und report-uri

Verstoßberichte zeigen, was eine Policy in den Browsern echter Besucher blockiert hat oder im Report-Only-Modus blockieren würde. CSP Level 3 definiert report-to, das einen im Header Reporting-Endpoints deklarierten Endpunkt benennt, und erklärt das ältere report-uri, das direkt eine URL erhält, für veraltet. Laut MDN ist report-to seit 2026 in aktuellen Browsern verfügbar, ältere Browserversionen verstehen nur report-uri. Browser mit report-to-Unterstützung ignorieren report-uri, senden Sie also vorerst beides (MDN report-to):

Reporting-Endpoints: csp="https://example.com/csp-reports"
Content-Security-Policy-Report-Only: script-src 'nonce-R4nd0mBase64Value' 'strict-dynamic' 'report-sample'; object-src 'none'; base-uri 'none'; report-uri https://example.com/csp-reports; report-to csp

Die beiden Mechanismen senden unterschiedliche Formate. report-uri schickt ein JSON-Objekt mit dem Schlüssel csp-report und dem Content-Type application/csp-report. report-to schickt application/reports+json: eine Liste von Berichten mit dem type csp-violation, deren Body Felder wie documentURL, blockedURL, effectiveDirective und disposition (enforce oder report) enthält. Mit 'report-sample' enthält der Bericht zu blockiertem Inline-Code dessen erste 40 Zeichen. Nehmen Sie beide Formate am selben Endpunkt an.

• Rechnen Sie mit Rauschen. Browsererweiterungen schleusen Skripte ein und lösen Verstöße mit Quelldateien wie chrome-extension:// oder moz-extension:// aus. Gruppieren Sie die Berichte nach Direktive und blockiertem Host und achten Sie auf Muster statt auf Einzelfälle.
• Behandeln Sie Berichte als personenbezogene Daten. Dokument-URLs und Referrer können Query-Strings mit E-Mail-Adressen oder Tokens enthalten. Entfernen oder kürzen Sie diese, bewahren Sie Berichte nur kurz auf und geben Sie sie nicht ohne Grund weiter.
• Schützen Sie den Endpunkt. Jeder kann gefälschte Berichte senden. Setzen Sie Größen- und Ratenlimits und zeigen Sie Berichtsinhalte in einer Admin-Oberfläche nie unescaped an.

7. Was typischerweise bricht: Analytics, Fonts, Inline-Skripte und Einbettungen

Die meisten Verstöße der ersten Tage stammen aus wenigen Quellen. Das Feld effectiveDirective im Bericht zeigt, welche Regel Sie prüfen sollten:

Inline-Styles sind ein geringeres Risiko als Inline-Skripte, aber nicht harmlos: Eingeschleustes CSS kann verändern, was Besucher sehen, und über Attributselektoren einzelne Seitendaten nach außen geben. Viele Frameworks und CSS-in-JS-Bibliotheken fügen Style-Elemente zur Laufzeit ein. Prüfen Sie daher, ob Ihres Nonces unterstützt, bevor Sie 'unsafe-inline' aus style-src entfernen. Wer Fonts und Bibliotheken selbst hostet, erledigt mehrere dieser Zeilen auf einmal und hält die Policy kurz.

8. Eine CSP stufenweise einführen

1. Bestandsaufnahme. Erfassen Sie Skripte, Styles, Fonts, Frames und Verbindungsziele Ihrer wichtigsten Seiten: Startseite, Login, Kundenkonto, Checkout und Seiten mit eingebetteten Widgets. Das Network-Panel der DevTools und die Konfiguration Ihres Tag-Managers sind die schnellsten Quellen.
2. Report-Only. Senden Sie den Entwurf als Content-Security-Policy-Report-Only mit aktivierten Berichten. Nichts wird blockiert; Verstöße erscheinen in der Konsole und an Ihrem Endpunkt. Lassen Sie den Modus lange genug laufen, damit auch selten besuchte Seiten und Kampagnen auftauchen, meist eine Woche oder länger.
3. Die Quellen korrigieren, nicht die Policy. Nonces ergänzen, Inline-Handler in Dateien verschieben, Fonts selbst hosten. Einen Host oder 'unsafe-eval' fügen Sie nur als dokumentierte Ausnahme mit verantwortlicher Person und Begründung hinzu.
4. Durchsetzen. Ändern Sie den Header-Namen in Content-Security-Policy. Lassen Sie daneben eine strengere Report-Only-Policy laufen, um die nächste Verschärfung zu testen: Kommen beide Header an, setzt der Browser den einen durch und meldet zum anderen nur.
5. Dranbleiben. Ein neues Marketing-Tag, ein Plugin-Update oder ein Framework-Upgrade kann neuen Inline-Code mitbringen. Lassen Sie den Berichtsendpunkt aktiv und prüfen Sie den Header nach jeder Änderung an Server, CDN oder Framework erneut.

Zwei Infrastrukturdetails sorgen oft für Überraschungen. Fügt ein CDN oder Framework einen eigenen CSP-Header hinzu, setzt der Browser jede empfangene Policy durch und eine Ressource muss alle bestehen; ein zusätzlicher Header kann also nur verschärfen, nie lockern (MDN). Und wird HTML am Edge gecacht, muss die Nonce dort erzeugt werden, wo die Seite zusammengesetzt wird, oder Sie wechseln zu Hashes. So sehen Sie, was eine Seite wirklich sendet:

curl -sS -D - -o /dev/null https://example.com/ | grep -i content-security-policy

Der Leitfaden zum Security Headers Check behandelt die Header, die neben die CSP gehören, und die Sicherheits-Checkliste für den Website-Launch ordnet sie in eine vollständige Prüfung vor dem Livegang ein.

9. Den ausgelieferten Header mit dem kostenlosen Checker prüfen

Sobald die Policy durchgesetzt wird, zeigt der kostenlose Security Headers Checker, was ein Browser von Ihrer Startseite erhält. Er führt den kostenlosen Launch-Readiness-Snapshot von Sitelemetry aus, acht passive Prüfungen an einer öffentlichen Domain ohne Anmeldung, und zeigt die Header-Prüfung geöffnet über den anderen sieben.

• Er ruft die Startseite des eingegebenen Origins ab, folgt bis zu fünf Weiterleitungen und liest die letzte Antwort. Andere Seiten wie Login oder Checkout tragen oft eigene Policies; prüfen Sie diese mit DevTools oder curl.
• Er liest nur den durchgesetzten Content-Security-Policy-Header. In der Report-Only-Phase meldet er die CSP daher weiterhin als fehlend, mit mittlerem Risiko, denn eine reine Berichts-Policy blockiert nichts. Bis zur Durchsetzung ist dieses Ergebnis zu erwarten.
• Eine frame-ancestors-Direktive in der durchgesetzten Policy zählt als Frame-Schutz, ebenso wie X-Frame-Options.
• In der separaten Härtungsnote (A bis F) erhält eine CSP weniger Punkte, wenn default-src oder eine script-src- bzw. style-src-Direktive (einschließlich der Varianten -elem und -attr) 'unsafe-inline' enthält oder wenn default-src oder eine Skript-Direktive 'unsafe-eval' enthält. Die Note liest die Policy so, wie sie geschrieben ist; ein 'unsafe-inline' als Rückfall neben einer Nonce kostet also ebenfalls Punkte, obwohl aktuelle Browser es ignorieren.
• Nonces, Hashes, 'strict-dynamic', object-src, base-uri und Berichte bewertet er nicht. Dafür nutzen Sie die Browserkonsole und Ihre Verstoßberichte.

Das Ergebnis zeigt einen Score und das Ergebnis jeder der acht Prüfungen, sodass Sie das CSP-Signal neben HSTS, TLS und den übrigen öffentlichen Prüfungen sehen.