Comment utiliser le CSP Builder

Écrire une politique de sécurité du contenu (CSP) à la main prend du temps et se rate facilement. Vous listez chaque source de script, de style, de police et d'image que la page charge, vous en oubliez quelques-unes, et soit vous cassez le site, soit vous laissez un trou. Le CSP Builder prend une autre voie : il lit les reports de violation que votre site envoie déjà et les transforme en une politique qui couvre ce que vos pages chargent réellement.

Cet article déroule le Builder de bout en bout : choisir une politique de départ, définir la quantité de reports à analyser, générer la politique, revoir chaque source, déployer. Vous repartez avec un header prêt à poser, au lieu d'un fichier vide et d'un long après-midi.

Si vous découvrez la CSP, lisez d'abord démarrer avec la Content Security Policy, puis revenez ici pour générer votre première vraie politique.

Ce que fait le CSP Builder

Le CSP Builder est un outil du dashboard CentralCSP : vous le lancez sur les données de reports de votre compte, sans rien installer.

Une Content Security Policy est un header de réponse HTTP qui indique au navigateur depuis quelles sources une page peut charger scripts, styles, images et autres ressources. Le navigateur l'applique ; tout ce qui n'est pas autorisé est bloqué et signalé.

Le Builder travaille à partir de ces reports. Quand votre site envoie des reports de violation à un endpoint de reporting, chaque ressource bloquée ou qui aurait été bloquée est enregistrée avec sa directive et sa source. Le Builder lit cet historique et assemble une politique qui autorise les sources que votre application utilise légitimement, et applique des valeurs par défaut sûres au reste. Vous relisez le résultat avant tout déploiement.

Il n'impose rien et ne sert pas de proxy au trafic. Il produit un header ; c'est vous qui le déployez sur votre serveur, et le navigateur qui l'applique.

Avant de commencer

Le Builder a besoin de données de reports pour apprendre. Deux choses doivent être en place :

Un endpoint de reporting. Votre site envoie les reports CSP à un endpoint CentralCSP de la forme https://<Endpoint-ID>.report.centralcsp.com. Voyez démarrer avec le reporting CSP pour la configuration.
Un peu d'historique de reports. Plus les reports couvrent de trafic, plus la politique générée est complète. Une fenêtre plus longue capte les ressources qui ne se chargent que sur des pages rarement visitées : laissez donc les reports s'accumuler sur un cycle de trafic complet avant de générer.

Lancez votre première politique en mode Report-Only pour rassembler des reports sans rien bloquer. Report-Only envoie les mêmes reports de violation qu'une politique imposée : le Builder récupère donc de vraies données pendant que votre site continue de tourner.

Étape 1. Choisissez une politique de départ

Le Builder part d'une politique de base et l'affine. Vous pouvez le laisser détecter la politique que votre site sert déjà, partir d'un modèle de départ CSP strict, ou coller une politique personnalisée.

Un point de départ courant est une base stricte qui refuse tout par défaut et n'ouvre que ce que les reports prouvent nécessaire :

Content-Security-Policy-Report-Only:
  default-src 'self';
  script-src 'self' 'report-sample';
  style-src 'self';
  img-src 'self';
  font-src 'self';
  object-src 'none';
  base-uri 'none';
  form-action 'self';
  frame-ancestors 'none';
  report-uri https://<Endpoint-ID>.report.centralcsp.com

Ici default-src fixe le repli, object-src et base-uri verrouillent une surface d'attaque héritée, et frame-ancestors bloque le clickjacking. Le mot-clé 'report-sample' demande au navigateur d'inclure un extrait du contenu bloqué dans chaque report, ce qui aide à distinguer le code légitime du code injecté.

Étape 2. Choisissez une fenêtre de reporting

Choisissez ensuite la plage temporelle des reports que le Builder doit analyser. Une fenêtre plus longue couvre une plus grande partie du comportement de votre site, y compris les pages et les parcours qui ne s'exécutent qu'occasionnellement. Une fenêtre plus courte ne reflète que le trafic récent.

Le Builder lit les reports de violation de cette fenêtre, les regroupe par directive et détermine quelles sources vos pages ont réellement demandées. C'est là qu'il découvre que vos scripts viennent de votre propre origine et d'un host d'analytics précis, vos polices d'un CDN, etc.

Étape 3. Générez et revoyez la politique

Le Builder assemble une politique à partir des reports analysés. Il ajoute les sources dont votre application a besoin par directive et applique des valeurs par défaut sûres aux directives qui n'ont eu aucun trafic légitime.

Une politique générée pour un site typique ressemble à ceci, une directive par ligne :

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'strict-dynamic' 'nonce-r4nd0m' https://cdn.example.com;
  style-src 'self' https://fonts.googleapis.com;
  img-src 'self' data: https://*.example.com;
  font-src 'self' https://fonts.gstatic.com;
  connect-src 'self' https://api.example.com;
  object-src 'none';
  base-uri 'none';
  form-action 'self';
  frame-ancestors 'none';
  upgrade-insecure-requests;
  report-uri https://<Endpoint-ID>.report.centralcsp.com

Quelques points à remarquer dans un header généré :

script-src suit l'approche moderne : un nonce par requête, avec 'strict-dynamic', pour que les scripts de confiance chargent ce dont ils ont besoin sans que vous listiez chaque host. Voyez comment fonctionne 'strict-dynamic' pour le mot-clé, et les nonces CSP dans Next.js pour câbler les nonces dans le code applicatif.
connect-src, font-src et img-src listent les vrais hosts vus dans vos reports, rien de plus.
upgrade-insecure-requests pousse toute sous-ressource en HTTP simple vers HTTPS.

Si vos reports montrent des styles ou des scripts inline, le Builder les fait remonter et vous laisse trancher entre un nonce, un hash ou une réécriture du code inline. Ne vous rabattez pas sur 'unsafe-inline' ; pourquoi unsafe-inline affaiblit votre CSP explique le coût.

Étape 4. Revoyez chaque source

La génération n'a pas le dernier mot. Le Builder vous fait parcourir la politique directive par directive, pour que vous approuviez ce qui y entre. C'est l'étape qui empêche un host égaré de se glisser dans votre script-src.

Pour chaque source, vérifiez qu'elle a sa place. Un host que vous reconnaissez (votre CDN, votre fournisseur d'analytics) reste. Un host que vous ne reconnaissez pas mérite un examen avant d'être autorisé : le report peut correspondre à une ressource injectée, ou à un tiers dont vous ne voulez pas. Passer les tags tiers en revue est un travail à part entière ; CSP pour Google Analytics et Tag Manager couvre les plus courants.

Gardez la politique en Report-Only pendant cette revue. Le navigateur signale les violations de la nouvelle politique sans l'imposer : vous confirmez qu'elle couvre le trafic réel avant qu'elle ne puisse casser quoi que ce soit.

Étape 5. Déployez la politique

Quand la politique vous convient, copiez le header et posez-le sur votre serveur. La syntaxe exacte dépend de votre stack, et comment définir le header CSP dans chaque framework les passe en revue ; voici nginx en exemple :

add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'strict-dynamic' 'nonce-r4nd0m' https://cdn.example.com; style-src 'self' https://fonts.googleapis.com; img-src 'self' data: https://*.example.com; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://api.example.com; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests; report-uri https://<Endpoint-ID>.report.centralcsp.com" always;

Ne basculez de Content-Security-Policy-Report-Only vers Content-Security-Policy que quand vous êtes sûr de vous. Les deux headers peuvent tourner côte à côte : imposez celle en qui vous avez confiance sur Content-Security-Policy pendant que vous testez l'itération suivante sur le header Report-Only.

Une fois la politique imposée, gardez l'endpoint de reporting actif. Le nouveau code et les nouveaux tiers apparaîtront sous forme de nouveaux reports, et vous relancerez le Builder pour les intégrer.

Validez avant et après le déploiement

Deux outils gratuits permettent de vérifier la politique sans avoir à la déployer :

L'évaluateur CSP note une politique et signale les points faibles, comme un script-src trop large ou un object-src manquant.
Le scanner CSP lit le header en direct sur une URL pour que vous confirmiez ce que la production sert réellement.

Passez la politique dans l'évaluateur avant de l'imposer, puis scannez le site en direct, pour vérifier que le header déployé correspond bien à ce que vous avez approuvé.

De la politique générée à la surveillance continue

Une politique n'est pas une tâche ponctuelle. Les sites changent, les dépendances se mettent à jour, de nouveaux scripts tiers apparaissent. Les reports qui ont alimenté le Builder continuent d'arriver : vous voyez les violations au fil de l'eau et vous régénérez la politique quand votre stack évolue.

Pour les pages de paiement, cette visibilité continue est aussi une preuve. La surveillance continue des scripts et des headers vous aide à répondre aux exigences 6.4.3 et 11.6.1 de PCI DSS v4, qui demandent de gérer et de détecter les changements de scripts sur les pages de paiement. CentralCSP conserve cet historique ; c'est un QSA qui valide la conformité, pas nous.

Prêt à générer une politique à partir de vos propres reports ? Commencez gratuitement, pointez votre site vers un endpoint de reporting, puis lancez le Builder sur du trafic réel.