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 imprévu se produit et ces règles sont enfreintes par 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 de non-respect de la CSP, un rapport de non-respect de la Document-Policy et un rapport de dépréciation 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 :