Démarrer avec le reporting CSP

Une politique de sécurité du contenu (CSP) ne vaut que ce que vous en apprenez. Le reporting est la façon dont le navigateur vous dit quelles ressources votre politique bloquerait, sur de vraies pages, dans de vrais navigateurs que vous ne possédez pas. Ce guide met en place le reporting de façon moderne, démêle l'enchevêtrement déroutant de report-uri, report-to et des headers de reporting, et vous montre à quoi ressemble réellement un rapport de violation.

En bref : envoyez le header Reporting-Endpoints, pointez la directive report-to vers lui, et démarrez en report-only pour que rien ne casse pendant que vous apprenez.

Pourquoi activer le reporting

Vous ne pouvez pas reproduire tous les navigateurs, extensions et appareils que vos visiteurs utilisent. Une politique qui paraît propre dans votre propre navigateur peut tout de même bloquer un script légitime pour quelqu'un sur une autre configuration. Le reporting est votre système d'alerte précoce : le navigateur envoie un petit rapport JSON chaque fois que la politique bloque quelque chose, vous voyez donc les vraies violations avant qu'elles ne deviennent des tickets de support.

Deux directives, deux headers (la partie qui déroute tout le monde)

Il y a deux directives CSP (elles vont à l'intérieur de la politique) et deux headers de reporting (des headers de réponse distincts qui nomment un endpoint). Les directives disent « rapporte ici » ; les headers définissent ce que « ici » veut dire.

Les directives, à l'intérieur de Content-Security-Policy ou de Content-Security-Policy-Report-Only :

report-uri <url> : prend une URL directement. Dépréciée, mais toujours utile comme repli.
report-to <name> : prend un simple nom, pas une URL. Le nom est défini par un header de reporting. C'est la directive actuelle.

Les headers de reporting, qui définissent l'endpoint nommé vers lequel report-to pointe :

Reporting-Endpoints : le standard actuel (Reporting API v1). La syntaxe est name="https://...".
Report-To : le header v0 déprécié. Vous n'en avez pas besoin pour une nouvelle mise en place.

C'est là que les vieux conseils se trompent. Le header Report-To est ce qui est déprécié ; la directive report-to est actuelle. Ce ne sont pas la même chose. Pour tout ce qui est nouveau, définissez votre endpoint avec Reporting-Endpoints et référencez-le depuis la directive report-to. Pour l'histoire au niveau des headers, voir Report-To vs Reporting-Endpoints ; pour les deux directives, voir report-uri vs report-to.

La mise en place moderne, en report-only

Envoyez deux headers de réponse. Le nom de l'endpoint (csp-endpoint ici) est le vôtre à choisir ; il doit simplement correspondre aux deux endroits. Pointez-le vers votre endpoint CentralCSP et gardez d'abord la politique en report-only, pour que le navigateur rapporte les violations sans rien bloquer :

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

Content-Security-Policy-Report-Only:
  default-src 'self';
  script-src 'self';
  style-src 'self';
  img-src 'self';
  object-src 'none';
  base-uri 'none';
  report-to csp-endpoint

L'endpoint doit être servi via HTTPS. Le Reporting API ignore les endpoints non sécurisés, et l'endpoint n'a pas besoin d'être sur votre propre origine, donc le pointer vers <Endpoint-ID>.report.centralcsp.com est exactement le modèle prévu.

Gardez report-uri comme repli (optionnel)

Les navigateurs qui prennent en charge report-to ignorent report-uri, donc ajouter les deux ne produit pas de rapports en double. La seule chose que report-uri vous apporte est la couverture des clients plus anciens qui ne prennent pas en charge la directive plus récente. Si vous voulez ce repli de ceinture et bretelles, listez les deux dans la même politique :

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

Notez que report-uri ne fonctionne que dans un vrai header de réponse, jamais dans une balise <meta>.

À quoi ressemble un rapport de violation

Il y a deux formes de contenu, et elles utilisent des noms de champs différents. Ne les confondez pas. Pour une lecture champ par champ, voir la référence des champs du rapport de violation CSP.

La forme héritée report-uri est un unique objet enveloppant csp-report, avec des noms de champs à traits d'union, posté en application/csp-report :

{
  "csp-report": {
    "document-uri": "https://api-next.centralcsp.com/signup",
    "violated-directive": "script-src-elem",
    "effective-directive": "script-src-elem",
    "blocked-uri": "https://apis.google.com/js/platform.js",
    "disposition": "report",
    "status-code": 200,
    "script-sample": ""
  }
}

La forme du Reporting API (report-to) est un tableau JSON de rapports, posté en application/reports+json, avec des champs de corps en camelCase :

[
  {
    "type": "csp-violation",
    "age": 53531,
    "url": "https://api-next.centralcsp.com/signup",
    "user_agent": "Mozilla/5.0 ...",
    "body": {
      "documentURL": "https://api-next.centralcsp.com/signup",
      "blockedURL": "https://apis.google.com/js/platform.js",
      "effectiveDirective": "script-src-elem",
      "originalPolicy": "default-src 'self'; report-to csp-endpoint",
      "disposition": "report",
      "statusCode": 200,
      "sample": ""
    }
  }
]

Le champ disposition vaut report tant que vous êtes en report-only et enforce une fois la politique appliquée. Le champ sample (un court extrait du code fautif) n'apparaît que lorsque vous ajoutez le mot-clé 'report-sample' à la directive. CentralCSP ingère les deux formes, vous n'avez donc pas à les normaliser vous-même.

Voir vos rapports et agir dessus

L'endpoint est la partie qui fait le travail, il est donc utile de comprendre où vont les rapports du navigateur et comment les recevoir. Pointer l'endpoint vers CentralCSP vous donne les rapports en un seul endroit : quelles origines sont bloquées, à quelle fréquence, et sur quelles pages, pour que vous distinguiez un vrai problème d'un inoffensif et resserriez la politique en confiance. De là, vous passez du report-only à l'application une fois le bruit disparu. La suite CSP gère la collecte et l'analyse, et le scanner CSP gratuit vérifie ce que vous avez déployé.

La page Violations CSP, avec les rapports regroupés par directive et origine bloquée

Étapes suivantes

Débutant complet en politiques ? Commencez par démarrer avec la politique de sécurité du contenu.
Vous construisez une politique complète ? Voir comment construire une CSP robuste.
Prêt à collecter les rapports ? Créez un compte gratuit et obtenez votre endpoint.