Rédiger et réviser une documentation de sécurité pour les développeurs

## Écrire des conseils applicables par les développeurs, sans sortir de la sécurité Écrivez pour les développeurs plutôt que pour les spécialistes de la sécurité. Les recommandations doivent être exactes, pratiques, concises et prendre clairement position. Préférez de bons conseils qu’un développeur peut appliquer à des conseils théoriquement optimaux, mais trop complexes à suivre. Maintenez chaque recommandation dans le modèle de menaces de sécurité du document. Les conseils généraux sur la qualité du code, les performances et l’architecture doivent être traités ailleurs, sauf s’ils limitent directement un risque de sécurité. Considérez les règles de contribution comme obligatoires pour chaque outil de rédaction. Préservez le processus humain faisant autorité et les guides rédactionnels du dépôt, et n’utilisez le guide abrégé destiné aux agents que comme résumé opérationnel. ## Lire chaque source citée et vérifier qu’elle appuie l’affirmation Récupérez et lisez chaque source citée, puis confirmez qu’elle étaye précisément l’affirmation concernée. N’inventez ni ne devinez jamais une URL, ne citez pas une page qui redirige vers une page de destination sans rapport et ne vous fiez pas à la mémoire d’entraînement ni à un résumé. Créez un lien vers la page ou la section précise qui contient les éléments justificatifs. Vérifiez les renvois internes avant de les utiliser. Ne pointez pas vers un document ou une ancre qui n’existe pas. Lorsque des contrôles de densité des citations s’appliquent, incluez au moins une citation HTTPS intégrée dans chaque nouvelle section H2. Étayez séparément les affirmations nouvelles, surprenantes, propres à certains paramètres ou susceptibles d’être contestées ; les pratiques courantes établies n’exigent pas une citation dans chaque phrase. Les sources peuvent être intégrées au texte ou regroupées dans une section Références. Privilégiez les normes, les recommandations de sécurité gouvernementales ou sectorielles, la documentation officielle des projets et des fournisseurs, les références de plateformes bien entretenues, les dépôts sources de référence et les travaux de recherche évalués par les pairs. Évitez les fermes de contenu commercial optimisées pour les moteurs de recherche. Les contrôles de citations fixent un minimum ; ils ne prouvent pas que le contenu est correct. ## Donner une mesure pour chaque menace et dire ce qu’elle n’empêche pas Les citations sont nécessaires, mais ne suffisent pas. Associez chaque menace à une contre-mesure concrète et indiquez explicitement ce contre quoi la mesure protège et ne protège pas. N’introduisez pas d’attaques hors du modèle de menaces déclaré sans réserve claire. Une mesure destinée à une couche ne doit pas être présentée comme une protection contre la compromission d’une autre couche. N’ajoutez que des recommandations qui constituent réellement une mesure de sécurité ou concernent un risque de sécurité. Examinez séparément l’exactitude, l’utilité pratique pour les développeurs et la pertinence thématique ; une recommandation erronée doit être rejetée même si elle est bien citée. ## Garder chaque changement petit et mettre un lien au lieu de copier Limitez chaque modification à un seul document de recommandations ou à un petit ensemble clairement coordonné. Lorsque le dépôt fixe ces limites, ne dépassez pas trois documents de contenu ni 1 500 lignes nettes ajoutées sans ticket de suivi approuvé. Soumettez les changements de dépendances, d’automatisation et les corrections limitées aux fautes de frappe à leurs propres règles de périmètre. Partez d’une branche propre fondée sur la branche par défaut et conservez un seul sujet par branche. N’ouvrez jamais deux demandes de modification depuis la même branche, car des changements sans rapport pourraient passer de l’une à l’autre. Exigez un ticket approuvé avant de proposer un document de recommandations nouveau ou substantiellement réécrit. Ne regroupez pas des changements opportunistes de mise en forme, des modifications en masse ou des corrections sans rapport. Avant d’ajouter une section, recherchez dans le document actuel, les documents connexes et l’index du dépôt. Créez un lien vers les recommandations existantes au lieu de les reproduire. Préservez les familles documentaires volontairement organisées en étoile. Les renvois coordonnés sont valables ; la copie des recommandations d’un autre document ne l’est pas. Si un contenu relève d’un autre sujet, déplacez-le vers le document existant ou nouveau approprié au lieu d’étendre artificiellement le périmètre actuel. ## Expliquer d’abord la conception et n’utiliser du code que si le sujet l’exige Pour les sujets généraux, privilégiez les modèles d’architecture, les principes de conception et les décisions de sécurité au code propre à un langage. Le code vieillit vite, et des extraits isolés peuvent devenir dangereux s’ils sont copiés sans leur contexte d’origine. Utilisez librement du code lorsque le sujet est intrinsèquement propre à un langage, axé sur les injections ou la paramétrisation, ou consacré à un durcissement concret. Une forte densité de code convient lorsque les détails exécutables constituent eux-mêmes les recommandations de sécurité et non du code standard accessoire. Gardez le code d’illustration bref, indiquez le langage des blocs délimités lorsque cela est pratique et ne présentez pas les exemples comme prêts pour la production, sauf s’ils ont été conçus et révisés selon cette exigence. ## Supprimer le remplissage et recommander une approche claire Éliminez les préambules génériques, les rappels répétés, les listes exhaustives d’options et les introductions à la mode mais creuses. Recommandez une approche précise et n’expliquez que le contexte nécessaire à un développeur pour l’appliquer en toute sécurité. Utilisez l’anglais américain, effectuez des vérifications orthographiques et terminologiques, et gardez les phrases accessibles aux lecteurs non natifs. Définissez les acronymes non évidents à leur première utilisation, tout en laissant sans explication les abréviations de protocoles et de localisateurs universellement connues lorsque le guide de style l’autorise. Réécrivez ou écartez les passages qui ressemblent à un texte automatisé générique. La concision ne doit pas faire disparaître les contraintes, les exceptions, les limites des menaces ni la raison pour laquelle une recommandation est plus sûre. ## Suivre les règles du dépôt pour Markdown et les images Utilisez Markdown et évitez le HTML brut, à l’exception des éléments explicitement autorisés tels que `details` et `summary`. Utilisez de manière cohérente des tirets pour les listes, le gras Markdown et les citations en bloc. Laissez une ligne vide après chaque titre. Un document type commence par un H1 et une Introduction, se poursuit par des sections H2 ciblées et peut se terminer par des Références. Trois à six sections H2 constituent une valeur par défaut utile, et non une limite stricte. N’ajoutez pas de table des matières manuelle lorsque l’outil de publication la génère. Respectez les règles de nommage des fichiers du dépôt. N’utilisez que des lettres, des chiffres, des traits d’union et des traits de soulignement, et conservez tout suffixe obligatoire tel que `_Cheat_Sheet.md`. Créez les nouveaux documents à partir du modèle approuvé. Stockez les ressources dans le répertoire prévu à cet effet. Utilisez le format d’image approuvé, fournissez un texte de remplacement pertinent et référencez les ressources avec le chemin relatif correct. Intégrez les liens avec des libellés descriptifs et utilisez HTTPS dès que possible. ## Lancer le lint et la vérification des liens avant de demander une révision Avant de proposer des changements, exécutez l’analyse Markdown, le contrôle terminologique et le vérificateur de liens définis par le dépôt. Exécutez également les contrôles de périmètre, de densité des citations et les autres règles applicables au contenu modifié. Traitez l’échec d’un contrôle local ou d’intégration continue comme un défaut à examiner, et non comme une raison de contourner le contrôle. Examinez l’écart final afin que les modifications générées ou automatisées ne masquent pas des changements sans rapport. Comprenez les limites de l’automatisation. Les contrôles mécaniques peuvent détecter un Markdown mal formé, une terminologie interdite, des liens inactifs, un périmètre excessif et des modèles de citations manquants, mais ils ne peuvent pas déterminer si une source étaye une affirmation, si un conseil est correct, si le sujet appartient au document ou si le contenu duplique des recommandations existantes. ## Déclarer l’aide de l’IA et réviser sous plusieurs angles Déclarez toute assistance substantielle de l’IA dans la description de la demande de modification. Consignez le nom de l’outil, sa version connue et l’instruction fournie dans la section de déclaration prévue par le dépôt. Cette exigence s’applique à tous les outils d’IA ; une omission peut invalider la contribution. Révisez les recommandations de sécurité selon des dimensions distinctes : exactitude en matière de sécurité, utilité pratique pour les développeurs, qualité des sources et des liens, doublons et emplacement, et qualité linguistique. Des réviseurs spécialisés peuvent travailler indépendamment, mais leurs conclusions doivent être regroupées en un seul verdict fondé sur des éléments probants. Utilisez des résultats explicites tels qu’accepter, demander des modifications ou fermer. Citez des éléments précis pour les constats bloquants, distinguez les échecs mécaniques des erreurs de jugement et n’approuvez pas uniquement parce que des citations ou des contrôles automatisés existent.