← Tous les articles

Démarrer avec le reporting CSP

CentralCSP Team ·

Dernière mise à jour:

Une politique de sécurité du contenu (CSP) ne vaut que ce que vous en apprenez. C'est par le reporting que le navigateur vous dit quelles ressources votre politique bloquerait, sur de vraies pages, dans des navigateurs qui ne sont pas les vôtres. Ce guide met en place le reporting de façon moderne, démêle la confusion entre report-uri, report-to et les headers de reporting, et vous montre à quoi ressemble vraiment 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 le temps de prendre vos marques.

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 navigateur peut quand même bloquer un script légitime chez quelqu'un d'autre, 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é que report-to désigne :

  • 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, elle, est actuelle. Ce n'est 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'historique côté 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. Vous choisissez librement le nom de l'endpoint (csp-endpoint ici), il doit seulement être identique 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. Il n'a pas non plus besoin d'être sur votre propre origine : le faire pointer vers <Endpoint-ID>.report.centralcsp.com correspond exactement à l'usage 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. report-uri ne vous apporte que la couverture des clients plus anciens, ceux qui ne prennent pas en charge la directive récente. Si vous voulez ce repli 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

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

À quoi ressemble un rapport de violation

Le contenu prend deux formes, avec 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 objet unique enveloppé dans csp-report, avec des noms de champs à traits d'union, posté en application/csp-report :

{
  "csp-report": {
    "document-uri": "https://example.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://example.com/signup",
    "user_agent": "Mozilla/5.0 ...",
    "body": {
      "documentURL": "https://example.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. Le même endpoint ingère désormais 12 types de rapports navigateur via le même header, les rapports CSP ne sont donc que le début.

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 rassemble les rapports au même endroit : quelles origines sont bloquées, à quelle fréquence, et sur quelles pages. Vous distinguez alors un vrai problème d'un blocage sans conséquence, et vous resserrez la politique sereinement. Une fois le bruit disparu, vous passez du report-only à l'application. 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

Articles liés

Sources