Les headers Content Security Policy, appliquer et signaler

Les headers HTTP qui transportent une CSP, enforce ou report-only, report-to ou report-uri, les limites du meta et la combinaison des politiques.

Une politique de sécurité du contenu (CSP) parvient au navigateur dans un header de réponse HTTP. Vous envoyez la politique dans la réponse, le navigateur la lit, puis il applique les règles à la page. Cette page couvre les deux headers qui la transportent, la façon dont la politique signale les violations, les limites de la balise <meta>, et ce qui se passe quand une réponse transporte plus d'une politique.

Pour le contenu de la politique lui-même, voir les directives et les valeurs qu'elles acceptent.

Le header d'application dans sa forme la plus simple :

Content-Security-Policy: default-src 'self'

Enforce ou report-only

Deux headers transportent une politique. Ils prennent exactement la même syntaxe ; seul change ce que le navigateur fait d'une violation.

Header	Statut	Ce que fait le navigateur
`Content-Security-Policy`	✅ Bon	Applique la politique : bloque la violation et la signale.
Content-Security-Policy-Report-Only	✅ Bon	Signale la violation mais ne la bloque pas.

Le mode report-only vous laisse voir ce qu'une politique casserait avant de l'activer. Vous déployez la politique dans le header report-only, collectez les rapports, corrigez ce que la politique aurait bloqué, puis basculez la même chaîne dans le header d'application. Une politique report-only n'a d'intérêt qu'avec un endpoint de reporting, puisqu'elle ne fait rien d'autre que signaler.

Content-Security-Policy-Report-Only:
  default-src 'self';
  report-to csp-endpoint

Une réponse peut transporter à la fois une politique appliquée et une politique report-only, ce qui vous permet d'appliquer une base éprouvée tout en testant une politique plus stricte en parallèle.

Comment la politique signale

Une politique indique au navigateur où envoyer ses rapports avec l'une des deux directives suivantes.

report-to nomme un groupe de reporting. L'URL du groupe est déclarée dans un header à part, Reporting-Endpoints, qui fait partie de la Reporting API. C'est le mécanisme actuel. Voir la page CSP report-to.
report-uri envoie les rapports directement à une URL. C'est le mécanisme historique, ignoré là où report-to est pris en charge, c'est-à-dire désormais tous les navigateurs actuels (Chrome, Edge, Safari et Firefox).

report-to est le mécanisme principal ; ne gardez report-uri en complément que pour les navigateurs anciens qui n'ont pas été mis à jour. Le header moderne Reporting-Endpoints va de pair avec report-to ; l'ancien header Report-To est un mécanisme distinct et déprécié dont la CSP n'a plus besoin (il ne reste requis que pour NEL).

Reporting-Endpoints: csp-endpoint="https://<Endpoint-ID>.report.centralcsp.com"

Content-Security-Policy:
  default-src 'self';
  report-uri https://<Endpoint-ID>.report.centralcsp.com;
  report-to csp-endpoint

Les deux chemins produisent des formes de rapport différentes : des noms de champs avec tirets pour report-uri, du camelCase pour report-to. Dans les deux cas vous recevez un rapport de violation CSP, que CentralCSP collecte et normalise. Pour vérifier que votre endpoint est bien branché, lancez le vérificateur Reporting API.

Livraison via une balise meta

Vous pouvez aussi transmettre une politique en HTML avec une balise <meta> dans le <head> du document, pratique quand vous n'avez pas la main sur les headers de réponse.

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; object-src 'none'">

Une politique <meta> est plus limitée qu'un header. Elle ne peut pas faire de report-only. Elle ne peut pas utiliser report-uri, report-to, frame-ancestors ni sandbox. Elle doit apparaître dans le <head> et ne régit que le contenu qui vient après elle dans le document. Préférez le header HTTP partout où vous pouvez en définir un.

Comment plusieurs politiques se combinent

Quand une réponse transporte plus d'une politique appliquée, le navigateur les applique toutes, et une ressource doit satisfaire chacune pour se charger. Les politiques se combinent par intersection, donc la règle effective est la plus restrictive de l'ensemble.

Ajouter une politique ne peut donc que resserrer le résultat, jamais le relâcher. Une seconde politique script-src 'self' ne réautorisera pas un hôte qu'une première politique script-src 'none' a déjà bloqué. Chaque politique est aussi évaluée indépendamment pour le reporting, donc une violation peut produire des rapports vers plusieurs endpoints.

Recommandation

Utilisez les deux headers ensemble : appliquez la politique dont vous êtes sûr aujourd'hui, et testez chaque resserrement dans une politique report-only avant de le promouvoir. Branchez le reporting sur report-to et Reporting-Endpoints, que tous les navigateurs actuels prennent désormais en charge.

Reporting-Endpoints: csp-endpoint="https://<Endpoint-ID>.report.centralcsp.com"

Content-Security-Policy:
    script-src 'nonce-{RANDOM}' 'strict-dynamic';
    object-src 'none';
    base-uri 'none';
    report-to csp-endpoint

Content-Security-Policy-Report-Only:
    script-src 'nonce-{RANDOM}' 'strict-dynamic';
    connect-src 'self';
    report-to csp-endpoint

Resserrer par étapes avec une politique report-only en miroir, c'est le déploiement que recommande le guide de CSP stricte de web.dev, et ça vous évite un incident de production à chaque changement.

FAQ

Quelle est la différence entre une CSP enforce et report-only ?

Content-Security-Policy bloque une violation et la signale ; Content-Security-Policy-Report-Only la signale seulement, ce qui vous permet de tester une politique avant de l'appliquer. Voyez enforce vs report-only pour le workflow de déploiement complet.

Puis-je définir une CSP dans une balise meta ?

Oui pour la plupart des directives, mais une balise <meta http-equiv="Content-Security-Policy"> ne peut pas faire de report-only et ignore report-uri, report-to, frame-ancestors et sandbox. Voyez balises meta vs headers pour savoir quand utiliser chacun.

Headers