Vérificateur Reporting API

Ce que le vérificateur examine

Il répond à trois questions sur n'importe quelle URL : où avez-vous dit aux navigateurs d'envoyer leurs rapports, quelles fonctionnalités de sécurité sont réellement câblées vers ces endpoints, et quels rapports sont générés puis jetés. Il ne lit que vos en-têtes de réponse, car c'est aussi tout ce qu'un navigateur lit : pas d'agent, pas de JavaScript, rien à installer.

Reporting-Endpoints ou Report-To ?

Deux en-têtes peuvent faire le travail, et l'un des deux vit en sursis. Reporting-Endpoints est le standard actuel : une ligne de paires nom-URL. Report-To est son prédécesseur déprécié, et la seule raison pour laquelle il refuse de mourir est Network Error Logging, qui l'exige encore. Si vous ajoutez le reporting aujourd'hui, déclarez vos endpoints dans Reporting-Endpoints. Les deux sont couverts en profondeur dans le guide Reporting-Endpoints et le guide Report-To.

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

Report-To: {"group":"default","max_age":86400,"endpoints":[{"url":"https://<Endpoint-ID>.report.centralcsp.com"}]}

Reporting-Endpoints, Report-To, report-to, report-uri

Quatre noms, deux en-têtes et deux directives CSP. Voici le tableau que l'on vient réellement chercher.

Brancher les rapports de violation CSP avec report-to

Le déploiement de CSP le plus sûr commence par des rapports, pas par des règles. Servez la politique en Content-Security-Policy-Report-Only avec une directive report-to qui pointe vers un endpoint déclaré dans Reporting-Endpoints. Les navigateurs vous disent alors exactement ce que la politique aurait cassé, et vous la durcissez avant qu'un seul visiteur ne soit affecté. La directive report-uri, dépréciée, ne vaut plus la peine d'être ajoutée à une nouvelle politique : report-to et Reporting-Endpoints couvrent à eux seuls les rapports de violation CSP. Pour les détails, consultez la Présentation de Content-Security-Policy et le guide du rapport de violation CSP.

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

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

NEL, l'exception qui exige encore Report-To

Certains échecs n'atteignent jamais votre serveur : un DNS qui ne résout pas, un TLS qui n'aboutit pas, des connexions qui meurent en route. Network Error Logging est la façon dont les navigateurs les rapportent, et comme la visite échouée ne livre aucun en-tête, le navigateur doit se souvenir de votre configuration depuis une visite réussie antérieure. C'est pourquoi NEL a encore besoin de l'ancien en-tête Report-To, et pourquoi Reporting-Endpoints ne peut pas le remplacer. Chromium uniquement. Syntaxe complète dans le guide Network Error Logging.

Report-To: {"group":"network-errors","max_age":2592000,"endpoints":[{"url":"https://<Endpoint-ID>.report.centralcsp.com"}]}

NEL: {"report_to":"network-errors","max_age":2592000}

Quand les rapports n'arrivent pas

Six causes couvrent la quasi-totalité des endpoints silencieux.

• Une page servie en http://. La Reporting API ne fonctionne que dans un contexte sécurisé : une page qui n'est pas servie en HTTPS ne génère aucun rapport, quels que soient ses en-têtes.
• Un nom d'endpoint que rien ne déclare. Une directive report-to pointe vers un endpoint qu'aucun en-tête Reporting-Endpoints ou Report-To ne déclare : le navigateur génère le rapport puis l'abandonne.
• Un endpoint en http://. Les navigateurs l'ignorent, sans erreur ni avertissement en console.
• Le mauvais type de contenu. L'endpoint doit accepter les requêtes POST en application/reports+json, ou en application/csp-report pour l'ancien format report-uri.
• Une réponse autre qu'un code 2xx. Tout autre code et le navigateur considère la livraison comme échouée.
• Le délai de regroupement. Celui que l'on prend le plus souvent pour une panne. Les navigateurs mettent les rapports en file et les envoient un peu après le chargement de page qui les a produits : un endpoint qui semble mort trente secondes après un test n'a peut-être simplement pas eu le temps.

Si vous voulez voir les rapports avant même d'avoir branché un endpoint, une page peut lire les siens avec ReportingObserver en JavaScript : c'est un bon moyen de confirmer que le navigateur génère bien ce que vous attendez.

Comment lire vos résultats

Les résultats sont pensés pour être simples : ils vous montrent comment votre reporting est configuré et signalent tout ce qui le casserait. Un endpoint référencé qu'aucun en-tête ne déclare ? Signalé. Un endpoint déclaré vers lequel rien n'envoie ? Signalé. Une politique qui ne rapporte nulle part ? Signalée aussi, avec le correctif juste à côté. Corrigez ce qui est signalé, relancez la vérification, et vos rapports continuent d'arriver.