Émet des champs structurés autorisés, masque les secrets et les données personnelles (PII), utilise des noms d'événements stables et des identifiants de corrélation, et ne journalise jamais les corps de requête bruts.
Statut du package : contexte de référence prêt pour revue humaine. Le contrat et les scénarios de test sont complets, mais aucune garantie n'est donnée qu'une implémentation adoptante les ait validés.
Décision
Les journaux d'application sont des événements structurés avec une liste blanche de noms de champs. Les secrets, identifiants et données personnelles sont masqués ou hachés avant émission. Les noms d'événements sont des chaînes stables, non des phrases interpolées. Chaque événement lié à une requête porte un identifiant de corrélation correspondant à la trace. Les corps de requête et de réponse bruts ne sont pas journalisés.
Portée
- Liste blanche des champs, masquage, nommage des événements, identifiant de corrélation, interdiction des corps, accès aux journaux et alignement de la rétention pour les journaux d'application des services backend.
- Journaux de débogage dans des environnements proches de la production.
- Transmission aux workflows d'effacement lorsqu'un magasin de journaux est un système de données personnelles.
Hors de ce bloc
- Politique d'attributs de span pour les traces distribuées, sauf que les identifiants de corrélation doivent correspondre.
- Cardinalité des labels de métriques.
Contrat
- Les émetteurs ne peuvent inclure que des clés autorisées ; les clés inconnues sont supprimées ou provoquent l'échec des vérifications de schéma CI.
- Les mots de passe, jetons, en-têtes d'autorisation, cookies et champs PII listés sont masqués ou remplacés par un hachage clé avant le stockage du journal.
- Le nom d'événement est une constante pointée issue d'un registre ; les messages en texte libre ne doivent pas inclure de chaînes fournies par l'utilisateur qui dupliquent des PII.
- L'identifiant de corrélation est présent sur les événements liés à une requête et égale l'identifiant de trace utilisé pour les appels sortants.
- Les corps de requête et de réponse, fichiers multipart, et chaînes de requête contenant des PII ne sont pas journalisés, même en mode débogage.
- Les magasins de journaux utilisés pour les opérations respectent les tickets d'effacement pour les champs restant directement identifiants ; les identifiants de sujet hachés sont documentés comme réversibles ou non.
Guide d'implémentation
- Suivre la cheat sheet OWASP sur la journalisation pour ne pas enregistrer de secrets, puis ajouter une liste blanche de projet pour que les nouveaux champs nécessitent une revue.
- Fournir un logger typé ;
log.info(obj)d'une entité ORM est interdit.
Gestion des erreurs
- En cas d'échec de masquage (le sérialiseur ajoute des clés supplémentaires), l'événement est supprimé ou un stub d'erreur de masquage est envoyé, jamais l'objet brut.
- L'absence d'identifiant de corrélation à une frontière de worker crée un nouvel identifiant et enregistre un parent manquant, plutôt que de journaliser la charge complète du job pour compenser.
- Le niveau debug en production applique toujours la même liste blanche.
Vérification et opérations
- Mesurer le taux de clés inconnues supprimées, les stubs d'erreur de masquage, les événements sans identifiant de corrélation, et les revues d'accès aux magasins de journaux.
- Injecter un secret canari dans une requête de test et prouver qu'il n'apparaît jamais dans le stockage.
- Prouver par des tests qu'un événement de réinitialisation de mot de passe n'inclut pas le jeton brut.
Les exemples exécutables dans ce package sont des fixtures et contrats d'acceptation. Exécutez
python tools/validate.py depuis la racine de la collection pour vérifier la structure et les métadonnées du package ; puis
implémentez et exécutez les scénarios dans le dépôt cible.
Hypothèses d'adoption
- Les noms et valeurs numériques dans
example.yamlsont un profil d'adoption, pas des valeurs par défaut universelles. - L'équipe adoptante doit mapper les acteurs, classes de données, vocabulaire d'erreur et propriété à son système.