Documentation Technique
ACTION REQUIRED (à exécuter immédiatement après lecture)
NOW: Confirmer si la tâche actuelle correspond au champ d'application de ce skillNOW: Lire../tool-index.mdpour vérifier la disponibilité des outils et les chemins réelsNEXT: Si des outils manquent, appeler bootstrap sans deviner les cheminsACT: Entrer dans la première étape du "workflow" et l'exécuter, ne pas rester en attente de confirmation
Pour les consignes de style d'écriture, ton et voix, utilisez Skill(ce:writer) avec le personnage The Engineer.
Sortie de documentation pour les tâches de sécurité / rétro-ingénierie
Lorsqu'une tâche de rétro-ingénierie, de test d'intrusion, de CTF ou d'analyse de sécurité est terminée, ce skill est chargé de générer une documentation technique formelle dans le répertoire du projet utilisateur.
Déclencheurs
- Tâche de rétro-ingénierie terminée avec des conclusions clés (algorithme reconstitué, signature déchiffrée, contournement trouvé, etc.)
- Test d'intrusion terminé avec des vulnérabilités découvertes et validées
- Problème CTF résolu avec flag obtenu
- L'utilisateur demande explicitement "un rapport / une documentation / un writeup"
Sélection du modèle
| Type de tâche | Modèle à utiliser |
|---|---|
| Rétro-ingénierie APK/binaire/so | references/security-report-templates.md → Rapport de rétro-ingénierie |
| Test d'intrusion / Découverte de vulnérabilités | references/security-report-templates.md → Rapport de test d'intrusion |
| Résolution CTF | references/security-report-templates.md → Writeup CTF |
| Rétro-ingénierie de signature JS/Web | references/security-report-templates.md → Rapport de rétro-ingénierie de signature |
| Logiciel malveillant / APT / Analyse de virus | references/security-report-templates.md + references/vendor-report-rules.md |
| Documentation technique générique | references/templates.md → README / Documentation API |
Structure du rapport fournisseur (Issue #65)
Les rapports de sécurité formels DOIVENT lire references/vendor-report-rules.md (structure uniquement, ne pas recopier le texte original du fournisseur). Choisir un flavor fournisseur uniquement lorsque les preuves de la tâche ou l'utilisateur le demandent explicitement ; pour les tâches de rétro-ingénierie ordinaires et autres, utiliser flavor = null.
| Flavor / Surcharge | Quand l'utiliser | Modèle principal |
|---|---|---|
malware | Échantillon malveillant clair, cheval de Troie, blanc+noir, phishing / empoisonnement | Style Huorong : Résumé → Flux → Analyse d'échantillon → Réponse d'urgence → IOC |
apt | APT / campagne / groupe / chaîne d'infection multi-étapes / ciblage sectoriel | Style Securelist Kaspersky : Résumé → Chaîne d'infection → Récit d'enquête → Résultats intéressants → Analyse technique → Détection et atténuation → IOC |
flavor = null | Rétro-ingénierie APK/ELF/PE/Mach-O ordinaire, analyse de firmware / fonctionnalité / signature JS | Modèle original de la tâche + éléments génériques de base ; ne pas ajouter les chapitres spécifiques malware/APT |
Surcharge fine vuln | L'utilisateur demande explicitement une analyse technique de vulnérabilité / correctif / CVE | Résumé → Impact / Reproduction → Analyse de crash et correctif → Recommandations de protection (superposé à null, pas un 3e flavor par défaut) |
Principe : Les modèles en petit nombre mais de bonne qualité — seulement 2 flavors fournisseurs complets ; vuln est une surcharge fine optionnelle, pas un troisième modèle complet par défaut.
À appliquer simultanément avec §0 Evidence → Finding → Path ; en cas de conflit, le contrat Evidence prévaut.
Spécifications de sortie
- Emplacement de sortie : Répertoire actuel du projet utilisateur (pas le répertoire du skill)
- Format du nom de fichier :
YYYY-MM-DD_[type]-[abrégé_de_cible]-report.md - Si le projet a un répertoire
docs/: Prioriser le placement sousdocs/ - Encodage : UTF-8
- Langue : Suivre la langue de la conversation utilisateur (conversation en français → rapport en français, conversation en anglais → rapport en anglais)
Exigences de qualité
- Tous les blocs de code doivent être exécutables directement ou avoir un contexte clair
- Aucun texte de placeholder / TODO
- Les découvertes clés doivent être étayées par des preuves
- Les étapes de reproduction doivent permettre à un tiers de reproduire de manière indépendante
- Les informations sensibles (jetons réels, mots de passe, URL internes) doivent être remplacées par des placeholders
- DOIT inclure la chaîne Evidence → Finding → Path (voir
../ops/evidence-finding-path.mdet le modèle §0) - DOIT lire
references/vendor-report-rules.md: choisirmalware/aptouflavor = null(les tâches de vulnérabilité peuvent superposer la surcharge finevuln) ; sans flavor, n'utiliser que le modèle de tâche original et les éléments de base applicables, ne pas forcer IOC/ATT&CK - DEVRAIT référencer les fichiers
scope.md/timeline.mddu cas (../scripts/case-init.ps1)
Intégration de diagrammes
Lors de la génération du rapport, le skill diagram-generator doit être appelé aux emplacements appropriés pour produire des diagrammes visuels :
| Type de rapport | Diagramme suggéré | Type de diagramme |
|---|---|---|
| Rapport de rétro-ingénierie | Graphe d'appels de fonctions, diagramme de flux de données | Mermaid flowchart / sequenceDiagram |
| Rapport de test d'intrusion | Diagramme du chemin d'attaque, topologie réseau | Mermaid flowchart / Graphviz |
| Writeup CTF | Diagramme de flux de raisonnement de résolution | Mermaid flowchart |
| Rapport de rétro-ingénierie de signature JS | Diagramme de séquence temporelle de la chaîne de requêtes, diagramme de flux d'algorithme | Mermaid sequenceDiagram / flowchart |
Les diagrammes sont intégrés dans le markdown du rapport sous forme de blocs de code Mermaid, garantissant un rendu direct sur GitHub/GitLab.
Principes Fondamentaux
1. Divulgation Progressive
Révéler l'information par couches :
| Couche | Contenu | Question Utilisateur |
|---|---|---|
| 1 | Une phrase de description | Qu'est-ce que c'est ? |
| 2 | Bloc de code de démarrage rapide | Comment l'utiliser ? |
| 3 | Référence API complète | Quelles sont mes options ? |
| 4 | Plongée dans l'architecture | Comment ça fonctionne ? |
Les avertissements, changements cassants et prérequis sont placés EN HAUT.
2. Rédaction Orientée Tâche
<!-- Mauvais : Orienté fonctionnalité -->
## Classe AuthService
La classe AuthService fournit des méthodes d'authentification...
<!-- Bon : Orienté tâche -->
## Authentification des utilisateurs
Pour authentifier un utilisateur, appelez login() avec les identifiants :
3. Montrer, ne pas Dire
Chaque concept nécessite un exemple concret.
Standards de Formatage
- Titres en phrase case : "Getting started" et non "Getting Started"
- Maximum 3 niveaux de titres : Plus profond signifie diviser le document
- Toujours spécifier le langage dans les blocs de code
- Chemins relatifs pour les liens internes
- Tableaux pour les données structurées avec 3+ attributs
Liste de Vérification Qualité
- Exemples de code testés et exécutables
- Aucun texte de placeholder ou TODO
- Correspond au comportement réel du code
- Consultable sans tout lire
- Le lecteur sait quoi faire ensuite
Anti-Patterns
| Problème | Correction |
|---|---|
| Mur de texte | Découper avec titres, puces, code, tableaux |
| Info critique enterrée | Avertissements/changements cassants en HAUT |
| Documentation d'erreurs manquante | Toujours documenter ce qui peut mal tourner |
Modèles
Pour les modèles README, endpoint API et organisation de fichiers, voir references/templates.md.
Compétences Connexes
Skill(ce:writer)— Style d'écriture, ton et voix (charger le personnage The Engineer)Skill(ce:visualizing-with-mermaid)— Diagrammes d'architecture et de flux
Bootstrap à la Demande (On-Demand Bootstrap)
Ce skill ne dépend d'aucun outil externe, génération purement textuelle. Aucun bootstrap nécessaire.
Si des diagrammes doivent être rendus pour un rapport, le skill diagram-generator/ sera appelé.
Contexte de Routage
Entrée amont : Tous les skills de sécurité / rétro-ingénierie appellent automatiquement ce skill après la tâche. Mode de déclenchement :
- Automatique : exécuté comme l'étape 9 de la chaîne de comportement après la tâche.
- Manuel : l'utilisateur dit "écris un rapport", "génère un writeup".
Modules associés au même niveau :
apk-reverse/— Génère un rapport de rétro-ingénierie après analyse APKida-reverse/— Génère un rapport de rétro-ingénierie après analyse binaireradare2/— Génère un rapport de rétro-ingénierie après analyse CLIjs-reverse/— Génère un rapport de signature après rétro-ingénierie JSreverse-engineering/— Génère un rapport de rétro-ingénierie généralfield-journal/— Le contenu du rapport sert également de source de données pour le journal d'évolution
Modèle de rapport de sécurité : references/security-report-templates.md
Règles de rapport fournisseur : references/vendor-report-rules.md (flavor : malware | apt | null ; surcharge optionnelle : vuln)
Modèle de documentation générique : references/templates.md
Auto-Vérification d'Achèvement de Tâche (DOIT être validé avant de déclarer terminé)
- Ai-je exécuté chaque étape du workflow (pas seulement lu) ?
- Ai-je utilisé des chemins d'outils réels basés sur
tool-index? - Ai-je produit des preuves reproductibles (commandes / scripts / captures / rapports) ?
- Le rapport contient-il Evidence / Finding / Path (contrat ops) ?
- Les éléments de la liste de vérification RULES sont-ils complétés et reportés ?