Surveiller votre application Web avec l'API Reporting

Utilisez l'API Reporting pour surveiller les failles de sécurité, les appels d'API obsolètes et plus encore.

Maud Nalpas

Certaines erreurs ne se produisent qu'en production. Vous ne les verrez pas en local ni pendant le développement, car les vrais utilisateurs, les vrais réseaux et les vrais appareils changent la donne. L'API Reporting vous aide à détecter certaines de ces erreurs, comme les failles de sécurité ou les appels d'API obsolètes et bientôt obsolètes sur votre site, et les transmet à un point de terminaison que vous avez spécifié.

Il vous permet de déclarer ce que vous souhaitez surveiller à l'aide d'en-têtes HTTP et est géré par le navigateur.

La configuration de l'API Reporting vous permet d'être averti lorsque les utilisateurs rencontrent ces types d'erreurs, afin que vous puissiez les corriger.

Cet article explique ce que cette API peut faire et comment l'utiliser. C'est parti !

Présentation

Supposons que votre site, site.example, dispose d'une Content-Security-Policy et d'une Document-Policy. Vous ne savez pas à quoi servent ces fonctionnalités ? Pas de problème, vous pourrez quand même comprendre cet exemple.

Vous décidez de surveiller votre site pour savoir quand ces règles sont enfreintes, mais aussi parce que vous souhaitez garder un œil sur les API obsolètes ou bientôt obsolètes que votre codebase peut utiliser.

Pour ce faire, configurez un en-tête Reporting-Endpoints et mappez ces noms de points de terminaison à l'aide de la directive report-to dans vos règles, si nécessaire.

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint

Un événement imprévu se produit et ces règles sont enfreintes pour certains de vos utilisateurs.

Exemples de cas de non-respect

index.html

<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>

script.js, chargé par index.html

// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
  document.write('<h1>hi</h1>');
} catch (e) {
  console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;

Le navigateur génère un rapport sur les violations CSP, un rapport sur les violations de la règle Document-Policy et un rapport sur les obsolescences qui capturent ces problèmes.

Après un court délai (jusqu'à une minute), le navigateur envoie ensuite les rapports au point de terminaison configuré pour ce type d'infraction. Les rapports sont envoyés hors bande par le navigateur lui-même (et non par votre serveur ni par votre site).

Le ou les points de terminaison reçoivent ces rapports.

Vous pouvez désormais accéder aux rapports sur ces points de terminaison et identifier les problèmes. Vous êtes prêt à résoudre le problème qui affecte vos utilisateurs.

Exemple de rapport

{
  "age": 2,
  "body": {
    "blockedURL": "https://site2.example/script.js",
    "disposition": "enforce",
    "documentURL": "https://site.example",
    "effectiveDirective": "script-src-elem",
    "originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
    "referrer": "https://site.example",
    "sample": "",
    "statusCode": 200
  },
  "type": "csp-violation",
  "url": "https://site.example",
  "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}

Cas d'utilisation et types de rapports

L'API Reporting peut être configurée pour vous aider à surveiller de nombreux types d'avertissements ou de problèmes intéressants qui se produisent sur votre site :

Rapports

À quoi ressemblent les rapports ?

Le navigateur envoie les rapports au point de terminaison que vous avez configuré. Il envoie des requêtes qui se présentent comme suit :

POST
Content-Type: application/reports+json

La charge utile de ces requêtes est une liste de rapports.

Exemple de liste de rapports

[
  {
    "age": 420,
    "body": {
      "columnNumber": 12,
      "disposition": "enforce",
      "lineNumber": 11,
      "message": "Document policy violation: document-write is not allowed in this document.",
      "policyId": "document-write",
      "sourceFile": "https://site.example/script.js"
    },
    "type": "document-policy-violation",
    "url": "https://site.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  },
  {
    "age": 510,
    "body": {
      "blockedURL": "https://site.example/img.jpg",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://dummy.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  }
]

Voici les données que vous pouvez trouver dans chacun de ces rapports :

Rapports avec identifiants

Les points de terminaison de création de rapports qui ont la même origine que la page qui génère le rapport reçoivent les identifiants (cookies) dans les requêtes contenant les rapports.

Les identifiants peuvent fournir un contexte supplémentaire utile sur le rapport. Par exemple, ils peuvent indiquer si le compte d'un utilisateur donné déclenche des erreurs de manière cohérente ou si une certaine séquence d'actions effectuées sur d'autres pages déclenche un rapport sur cette page.

Quand et comment le navigateur envoie-t-il des rapports ?

Les rapports sont envoyés hors bande depuis votre site : le navigateur contrôle le moment où ils sont envoyés aux points de terminaison configurés. Il n'existe pas non plus de moyen de contrôler le moment où le navigateur envoie les rapports. Il les capture, les met en file d'attente et les envoie automatiquement au moment opportun.

Cela signifie que les performances ne sont pas ou peu affectées lorsque vous utilisez l'API Reporting.

Les rapports sont envoyés avec un délai (jusqu'à une minute) pour augmenter les chances de les envoyer par lots. Cela permet d'économiser de la bande passante pour respecter la connexion réseau de l'utilisateur, ce qui est particulièrement important sur mobile. Le navigateur peut également retarder la diffusion s'il est occupé à traiter des tâches de priorité plus élevée ou si l'utilisateur se trouve sur un réseau lent ou encombré au moment de la diffusion.

Problèmes liés à des tiers et à des propriétaires

Les rapports générés en raison de cas de non-respect ou d'obsolescence sur votre page seront envoyés aux points de terminaison que vous avez configurés. Cela inclut les cas de non-respect commis par des scripts tiers exécutés sur votre page.

Les cas de non-respect ou d'obsolescence qui se sont produits dans un iFrame cross-origin intégré à votre page ne seront pas signalés à vos points de terminaison (du moins pas par défaut). Une iframe peut configurer son propre service de création de rapports et même envoyer des rapports à celui de votre site (c'est-à-dire le service de création de rapports first party), mais cela dépend du site encadré. Notez également que la plupart des rapports ne sont générés que si le règlement d'une page est enfreint, et que les règles de votre page et celles de l'iframe sont différentes.

Exemple avec des obsolescences

Prise en charge des navigateurs

Le tableau suivant récapitule la compatibilité des navigateurs avec l'API Reporting v1, c'est-à-dire avec l'en-tête Reporting-Endpoints. La compatibilité des navigateurs avec l'API Reporting v0 (en-tête Report-To) est la même, à l'exception d'un type de rapport : la journalisation des erreurs réseau n'est pas compatible avec la nouvelle API Reporting. Pour en savoir plus, consultez le guide de migration.

Ce tableau ne récapitule que la compatibilité de report-to avec le nouvel en-tête Reporting-Endpoints. Consultez les conseils sur la migration des rapports CSP si vous souhaitez migrer vers Reporting-Endpoints.

Utiliser l'API Reporting

Choisir où envoyer les rapports

Vous avez deux options :

• Envoyez des rapports à un service de collecte de rapports existant.
• Envoyez des rapports à un collecteur de rapports que vous créez et gérez vous-même.

Option 1 : Utiliser un service de collecte de rapports existant

Voici quelques exemples de services de collecte de rapports :

• report-uri
• uriports

Si vous connaissez d'autres solutions, ouvrez un problème pour nous en informer. Nous mettrons à jour cet article.

En plus du prix, tenez compte des points suivants lorsque vous sélectionnez un collecteur de rapports : 🧐

• Ce collecteur est-il compatible avec tous les types de rapports ? Par exemple, toutes les solutions de points de terminaison de création de rapports ne sont pas compatibles avec les rapports COOP/COEP.
• Acceptez-vous de partager les URL de votre application avec un collecteur de rapports tiers ? Même si le navigateur supprime les informations sensibles de ces URL, des informations sensibles peuvent être divulguées de cette manière. Si cela vous semble trop risqué pour votre application, utilisez votre propre point de terminaison de signalement.

Option 2 : Créer et gérer votre propre collecteur de rapports

Créer votre propre serveur pour recevoir des rapports n'est pas une tâche simple. Pour commencer, vous pouvez forker notre boilerplate léger. Il est conçu avec Express et peut recevoir et afficher des rapports.

Lorsque vous créez votre propre collecteur de rapports :

• Recherchez les requêtes POST avec un Content-Type de application/reports+json pour identifier les demandes de rapports envoyées par le navigateur à votre point de terminaison.
• Si votre point de terminaison se trouve sur une origine différente de celle de votre site, assurez-vous qu'il est compatible avec les requêtes de vérification préliminaire CORS.

Option 3 : Combiner les options 1 et 2

Vous pouvez choisir de confier certains types de rapports à un fournisseur spécifique, mais de gérer d'autres types de rapports en interne.

Dans ce cas, définissez plusieurs points de terminaison comme suit :

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

Configurer l'en-tête Reporting-Endpoints

Définissez un en-tête de réponse Reporting-Endpoints. Sa valeur doit être une ou plusieurs paires clé-valeur séparées par une virgule :

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Si vous migrez de l'ancienne API Reporting vers la nouvelle, il peut être judicieux de définir Reporting-Endpoints et Report-To. Pour en savoir plus, consultez le guide de migration. En particulier, si vous utilisez les rapports pour les cas de non-respect de Content-Security-Policy en utilisant uniquement la directive report-uri, consultez les étapes de migration pour les rapports CSP.

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: ...

Clés (noms de points de terminaison)

Chaque clé peut être un nom de votre choix, tel que main-endpoint ou endpoint-1. Vous pouvez choisir de définir différents points de terminaison nommés pour différents types de rapports (par exemple, my-coop-endpoint, my-csp-endpoint). Vous pouvez ainsi acheminer les rapports vers différents points de terminaison en fonction de leur type.

Si vous souhaitez recevoir des rapports d'intervention, d'abandon, d'erreur ou une combinaison de ces rapports, définissez un point de terminaison nommé default.

Si l'en-tête Reporting-Endpoints ne définit aucun point de terminaison default, les rapports de ce type ne seront pas envoyés (bien qu'ils seront générés).

Valeurs (URL)

Chaque valeur correspond à l'URL de votre choix, à laquelle les rapports seront envoyés. L'URL à définir ici dépend de ce que vous avez décidé à l'étape 1.

URL d'un point de terminaison :

• Doit commencer par une barre oblique (/). Les chemins relatifs ne sont pas acceptés.
• Peut être cross-origin, mais dans ce cas, les identifiants ne sont pas envoyés avec les rapports.

Exemples

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

Vous pouvez ensuite utiliser chaque point de terminaison nommé dans la stratégie appropriée ou utiliser un seul point de terminaison dans toutes les stratégies.

Où définir l'en-tête ?

Dans la nouvelle API Reporting, celle qui est abordée dans cet article, les rapports sont limités aux documents. Cela signifie que pour une origine donnée, différents documents, tels que site.example/page1 et site.example/page2, peuvent envoyer des rapports à différents points de terminaison.

Pour recevoir un rapport sur les cas de non-respect ou les obsolescences survenus sur une page de votre site, définissez l'en-tête en tant que middleware sur toutes les réponses.

Voici un exemple dans Express :

const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;

app.use(function (request, response, next) {
  // Set up the Reporting API
  response.set(
    'Reporting-Endpoints',
    `main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
  );
  next();
});

Modifier vos règles

Maintenant que l'en-tête Reporting-Endpoints est configuré, ajoutez une directive report-to à chaque en-tête de règle pour lequel vous souhaitez recevoir des rapports sur les cas de non-respect. La valeur de report-to doit correspondre à l'un des points de terminaison nommés que vous avez configurés.

Vous pouvez utiliser le point de terminaison multiple pour plusieurs règles ou utiliser différents points de terminaison pour différentes règles.

report-to n'est pas nécessaire pour les rapports obsolescence, intervention et plantage. Ces rapports ne sont liés à aucune règle. Ils sont générés tant qu'un point de terminaison default est configuré et sont envoyés à ce point de terminaison default.

Exemple

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint

Déboguer la configuration de vos rapports

Générer intentionnellement des rapports

Lorsque vous configurez l'API Reporting, vous devrez probablement enfreindre intentionnellement vos règles afin de vérifier si les rapports sont générés et envoyés comme prévu.

Gagnez du temps

Les rapports peuvent être envoyés avec un délai d'environ une minute, ce qui est long lors du débogage. 😴 Heureusement, lorsque vous déboguez dans Chrome, vous pouvez utiliser l'indicateur --short-reporting-delay pour recevoir les rapports dès qu'ils sont générés.

Exécutez la commande suivante dans votre terminal pour activer ce flag :

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

Utiliser les outils de développement

Dans Chrome, utilisez les outils de développement pour afficher les rapports qui ont été envoyés ou qui le seront.

Depuis octobre 2021, cette fonctionnalité est expérimentale. Pour l'utiliser, procédez comme suit :

1. Utilisez la version 96 ou une version ultérieure de Chrome (pour vérifier, saisissez chrome://version dans votre navigateur).
2. Saisissez ou collez chrome://flags/#enable-experimental-web-platform-features dans la barre d'adresse de Chrome.
3. Cliquez sur Activé.
4. Redémarrez le navigateur.
5. Accédez aux Outils pour les développeurs Chrome.
6. Dans les outils pour les développeurs Chrome, ouvrez les paramètres. Sous "Tests", cliquez sur Activer le panneau de l'API Reporting dans le panneau "Application".
7. Actualisez les outils de développement.
8. Actualisez la page. Les rapports générés par la page dans laquelle les outils pour les développeurs sont ouverts seront listés dans le panneau Application des outils pour les développeurs Chrome, sous API Reporting.

État du rapport

La colonne État indique si un rapport a bien été envoyé.

Les rapports sont supprimés au bout d'un certain temps, qu'ils aient été envoyés ou non.

Dépannage

Les rapports ne sont-ils pas générés ou envoyés comme prévu à votre point de terminaison ? Voici quelques conseils pour résoudre ce problème.

Les rapports ne sont pas générés

Les rapports qui s'affichent dans les outils de développement ont été générés correctement. Si le rapport que vous attendez n'apparaît pas dans cette liste :

• Consultez report-to dans vos règles. Si cette option est mal configurée, aucun rapport ne sera généré. Pour résoudre ce problème, accédez à Modifier vos règles. Pour résoudre ce problème, vous pouvez également consulter la console DevTools dans Chrome. Si une erreur s'affiche dans la console pour le non-respect que vous attendiez, cela signifie que votre règle est probablement correctement configurée.
• N'oubliez pas que seuls les rapports générés pour le document dans lequel les outils de développement sont ouverts s'affichent dans cette liste. Par exemple, si votre site site1.example intègre un iFrame site2.example qui ne respecte pas une règle et génère donc un rapport, ce rapport ne s'affichera dans les outils de développement que si vous ouvrez l'iFrame dans sa propre fenêtre et ouvrez les outils de développement pour cette fenêtre.

Les rapports sont générés, mais ne sont pas envoyés ni reçus

Que faire si vous voyez un rapport dans les outils de développement, mais que votre point de terminaison ne le reçoit pas ?

• Veillez à utiliser des délais courts. Il est possible que vous ne puissiez pas voir un rapport, car il n'a pas encore été envoyé.

• Vérifiez la configuration de votre en-tête Reporting-Endpoints. En cas de problème, un rapport généré correctement ne sera pas envoyé. Dans les outils de développement, l'état du rapport restera Queued (il peut passer à Pending, puis revenir rapidement à Queued lorsqu'une tentative d'envoi est effectuée) dans ce cas. Voici quelques erreurs courantes qui peuvent être à l'origine de ce problème :

• Le point de terminaison est utilisé, mais pas configuré. Exemple :

 Document-Policy: document-write=?0;report-to=endpoint-1;
 Reporting-Endpoints: default="https://reports.example/default"

• Le point de terminaison default est manquant. Certains types de rapports, tels que les rapports d'obsolescence et d'intervention, ne seront envoyés qu'au point de terminaison nommé default. Pour en savoir plus, consultez Configurer l'en-tête Reporting-Endpoints.

• Recherchez les problèmes de syntaxe dans vos en-têtes de règles, comme les guillemets manquants. Afficher les détails

• Vérifiez que votre point de terminaison peut gérer les requêtes entrantes.

  • Assurez-vous que votre point de terminaison est compatible avec les requêtes CORS préliminaires. Si ce n'est pas le cas, il ne pourra pas recevoir de rapports.

  • Testez le comportement de votre point de terminaison. Pour ce faire, au lieu de générer des rapports manuellement, vous pouvez émuler le navigateur en envoyant à votre point de terminaison des requêtes qui ressemblent à celles que le navigateur enverrait. Exécutez la commande suivante :

  curl --header "Content-Type: application/reports+json" \
    --request POST \
    --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \
    YOUR_ENDPOINT
  

  Votre point de terminaison doit répondre avec un code de réussite (200 ou un autre code de réponse de réussite 2xx). Si ce n'est pas le cas, cela signifie qu'il y a un problème avec sa configuration.

Mécanismes de signalement associés

Rapport uniquement

Les en-têtes de règles -Report-Only et Reporting-Endpoints fonctionnent ensemble.

Les points de terminaison configurés dans Reporting-Endpoints et spécifiés dans le champ report-to de Content-Security-Policy, Cross-Origin-Embedder-Policy et Cross-Origin-Opener-Policy recevront des rapports en cas de non-respect de ces règles.

Les points de terminaison configurés dans Reporting-Endpoints peuvent également être spécifiés dans le champ report-to de Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only et Cross-Origin-Opener-Policy-Report-Only. Ils recevront également des rapports en cas de non-respect de ces règles.

Bien que des rapports soient envoyés dans les deux cas, les en-têtes -Report-Only n'appliquent pas les règles : rien ne sera cassé ni réellement bloqué, mais vous recevrez des rapports sur ce qui aurait été cassé ou bloqué.

ReportingObserver

L'API JavaScript ReportingObserver peut vous aider à observer les avertissements côté client.

ReportingObserver et l'en-tête Reporting-Endpoints génèrent des rapports qui se ressemblent, mais qui permettent des cas d'utilisation légèrement différents.

Utilisez ReportingObserver si :

• Vous ne souhaitez surveiller que les abandons ou les interventions du navigateur. ReportingObserver affiche les avertissements côté client tels que les obsolescences et les interventions du navigateur, mais contrairement à Reporting-Endpoints, il ne capture aucun autre type de rapport, comme les cas de non-respect des CSP ou des COOP/COEP.
• Vous devez réagir à ces cas de non-respect en temps réel. ReportingObserver permet d'associer un rappel à un événement d'infraction.
• Vous souhaitez joindre des informations supplémentaires à un rapport pour faciliter le débogage à l'aide du rappel personnalisé.

Une autre différence est que ReportingObserver n'est configuré que côté client : vous pouvez l'utiliser même si vous n'avez aucun contrôle sur les en-têtes côté serveur et que vous ne pouvez pas définir Reporting-Endpoints.

Documentation complémentaire

• Guide de migration de l'API Reporting v0 vers v1
• ReportingObserver
• Spécification : ancienne API Reporting (v0)
• Spécification : nouvelle API Reporting (v1)

Image principale de Nine Koepfer / @enka80 sur Unsplash, modifiée. Merci beaucoup à Ian Clelland, Eiji Kitamura et Milica Mihajlija pour leurs commentaires et suggestions sur ce document.