Technische Dokumentation
AKTION ERFORDERLICH (nach dem Lesen sofort ausführen)
JETZT: Prüfen, ob die aktuelle Aufgabe in den Anwendungsbereich dieses Skills fälltJETZT:../tool-index.mdlesen, die Verfügbarkeit von Tools und die tatsächlichen Pfade überprüfenNÄCHSTES: Wenn Tools fehlen, Bootstrap aufrufen – Pfade nicht erratenAKTION: Den ersten Schritt des „Workflows“ betreten und ausführen, nicht im Bestätigungsstatus verharren
Hinweise zu Schreibstil, Ton und Stimme finden Sie unter Skill(ce:writer) mit der Persona The Engineer.
Dokumentenausgabe für Sicherheits-/Reverse-Engineering-Aufgaben
Wenn Reverse-Engineering/Pentest/CTF/Sicherheitsanalyse-Aufgaben abgeschlossen sind, ist dieser Skill dafür verantwortlich, formelle technische Dokumentation im Benutzerprojektverzeichnis zu generieren.
Auslöser
- Reverse-Engineering-Aufgabe abgeschlossen, Kernschlussfolgerungen erzielt (Algorithmus-Rekonstruktion, Signatur-Knacken, Umgehungsmethode usw.)
- Pentest abgeschlossen, Schwachstellen gefunden und verifiziert
- CTF-Aufgabe gelöst, Flag erhalten
- Benutzer fordert explizit „Erstelle einen Bericht / eine Dokumentation / ein Writeup“
Vorlagenauswahl
| Aufgabentyp | Verwendete Vorlage |
|---|---|
| APK/Binär/so Reverse-Engineering | references/security-report-templates.md → Reverse-Engineering-Bericht |
| Pentest/Schwachstellensuche | references/security-report-templates.md → Pentest-Bericht |
| CTF-Lösung | references/security-report-templates.md → CTF-Writeup |
| JS/Web-Signatur-Reverse | references/security-report-templates.md → Signatur-Reverse-Bericht |
| Malware / APT / Virenanalyse | references/security-report-templates.md + references/vendor-report-rules.md |
| Allgemeine technische Dokumentation | references/templates.md → README / API-Dokumentation |
Anbieterberichtsstruktur (Issue #65)
Für formelle Sicherheitsberichte MUSS references/vendor-report-rules.md gelesen werden (nur die Struktur, nicht den Originaltext des Anbieters kopieren). Nur bei Aufgabenbeweisen oder expliziter Benutzeranforderung einen Anbieter-Flavor wählen; für normales Reverse-Engineering und andere Aufgaben flavor = null.
| Flavor / Overlay | Wann verwenden | Haupt-Referenzgerüst |
|---|---|---|
malware | Explizite Schadproben, Trojaner, White+Black, Phishing mit Giftködern | Huorong-Stil: Übersicht → Ablauf → Beispielanalyse → Notfallmaßnahmen → IOC |
apt | APT/Kampagnen/Gruppen/mehrstufige Infektionsketten/gezielte Branchenangriffe | Kaspersky-Securelist-Stil: Zusammenfassung → Infektionskette → Untersuchungserzählung → Interessante Funde → Technische Analyse → Erkennung/Minderung → IOC |
flavor = null | Normales APK/ELF/PE/Mach-O Reverse, Algorithmus/Firmware-Analyse, Pentest / CTF / JS-Signatur | Originalaufgaben-Vorlage + Basis-Elemente; keine malware/APT-spezifischen Kapitel |
thin vuln | Benutzer fordert explizit technische Analyse von Schwachstellen/Patches/CVEs | Übersicht → Auswirkung/Reproduktion → Absturz- und Patch-Analyse → Schutzempfehlung (auf null aufgesetzt, nicht als 3. Standard-Text-Flavor) |
Prinzip: Weniger Vorlagen sind mehr – nur 2 Volltext-Flavors von Anbietern; vuln ist nur ein optionales dünnes Overlay, kein drittes Standard-Text-Template.
Gleichzeitig mit §0 Evidence→Finding→Path wirksam; bei Konflikten hat der Evidence-Vertrag Vorrang.
Ausgabespezifikation
- Ausgabeort: Aktuelles Benutzerprojektverzeichnis (nicht das Skill-Paket-Verzeichnis)
- Dateinamenformat:
YYYY-MM-DD_[Typ]-[Zielkurzname]-report.md - Wenn ein
docs/-Verzeichnis im Projekt existiert: Vorzugsweise unterdocs/ablegen - Kodierung: UTF-8
- Sprache: Der Konversationssprache des Benutzers folgen (chinesischer Dialog → chinesischer Bericht, englischer Dialog → englischer Bericht)
Qualitätsanforderungen
- Alle Codeblöcke müssen direkt ausführbar sein oder einen klaren Kontext haben
- Keine Platzhalter/TODOs
- Wichtige Erkenntnisse müssen durch Beweise gestützt werden
- Reproduktionsschritte müssen von Dritten unabhängig reproduzierbar sein
- Vertrauliche Informationen (echte Token, Passwörter, interne URLs) durch Platzhalter ersetzen
- MUSS die Kette Evidence → Finding → Path enthalten (siehe
../ops/evidence-finding-path.mdund Vorlage §0) - MUSS
references/vendor-report-rules.mdlesen:malware/aptoderflavor = nullauswählen (Schwachstellenaufgaben können thinvulnüberlagern); ohne Flavor nur die Aufgaben-Vorlage und die zutreffenden Basis-Elemente ausgeben, kein IOC/ATT&CK erzwingen - SOLLTE auf
scope.md/timeline.mddes Falls verweisen (../scripts/case-init.ps1)
Diagramm-Integration
Beim Generieren des Berichts sollte an geeigneten Stellen der diagram-generator-Skill aufgerufen werden, um visuelle Diagramme zu erstellen:
| Berichtstyp | Empfohlene Diagramme | Diagrammtyp |
|---|---|---|
| Reverse-Engineering-Bericht | Funktionsaufrufgraph, Datenflussdiagramm | Mermaid flowchart / sequenceDiagram |
| Pentest-Bericht | Angriffspfaddiagramm, Netzwerktopologie | Mermaid flowchart / Graphviz |
| CTF-Writeup | Lösungsweg-Flussdiagramm | Mermaid flowchart |
| JS-Signatur-Reverse-Bericht | Anfrageketten-Sequenzdiagramm, Algorithmus-Flussdiagramm | Mermaid sequenceDiagram / flowchart |
Diagramme werden als Mermaid-Codeblöcke in den Bericht-Markdown eingebettet, um eine direkte Darstellung in GitHub/GitLab zu gewährleisten.
Kernprinzipien
1. Progressive Offenlegung
Informationen schichtweise preisgeben:
| Schicht | Inhalt | Benutzerfrage |
|---|---|---|
| 1 | Ein-Satz-Beschreibung | Was ist das? |
| 2 | Quick-Start-Codeblock | Wie verwende ich es? |
| 3 | Vollständige API-Referenz | Welche Optionen habe ich? |
| 4 | Architektur-Tiefgang | Wie funktioniert es? |
Warnungen, Breaking Changes und Voraussetzungen gehören nach OBEN.
2. Aufgabenorientiertes Schreiben
<!-- Schlecht: Funktionsorientiert -->
## AuthService-Klasse
Die AuthService-Klasse stellt Authentifizierungsmethoden bereit...
<!-- Gut: Aufgabenorientiert -->
## Benutzer authentifizieren
Um einen Benutzer zu authentifizieren, rufen Sie login() mit Anmeldeinformationen auf:
3. Zeigen, nicht erzählen
Jedes Konzept benötigt ein konkretes Beispiel.
Formatierungsstandards
- Überschriften im Satzfall: „Getting started“ nicht „Getting Started“
- Maximal 3 Überschriftsebenen: Tiefer bedeutet, das Dokument aufteilen
- Immer die Sprache in Codeblöcken angeben
- Relative Pfade für interne Links
- Tabellen für strukturierte Daten mit 3+ Attributen
Qualitäts-Checkliste
- Codebeispiele getestet und ausführbar
- Kein Platzhaltertext oder TODOs
- Entspricht tatsächlichem Codeverhalten
- Überfliegbar ohne alles zu lesen
- Leser weiß, was als nächstes zu tun ist
Anti-Patterns
| Problem | Lösung |
|---|---|
| Textwand | Aufbrechen mit Überschriften, Aufzählungen, Code, Tabellen |
| Kritische Info vergraben | Warnungen/Breaking Changes nach OBEN |
| Fehlende Fehlerdokumentation | Immer dokumentieren, was schiefgehen kann |
Vorlagen
Für README-, API-Endpunkt- und Dateiorganisationsvorlagen siehe references/templates.md.
Verwandte Skills
Skill(ce:writer)– Schreibstil, Ton und Stimme (The-Engineer-Persona laden)Skill(ce:visualizing-with-mermaid)– Architektur- und Flussdiagramme
On-Demand Bootstrap
Dieser Skill ist nicht auf externe Tools angewiesen, reine Texterzeugung. Kein Bootstrap erforderlich.
Falls Diagramme zur Einbettung in den Bericht gerendert werden müssen, wird der diagram-generator/-Skill aufgerufen.
Routing-Kontext
Upstream-Einstiegspunkte: Alle Sicherheits-/Reverse-Engineering-Skills rufen diesen Skill nach Abschluss der Aufgabe automatisch auf Auslösemodus:
- Automatisch: Nach Aufgabenabschluss als Schritt 9 der Verhaltenskette ausgeführt
- Manuell: Benutzer sagt „Bericht schreiben“, „Dokumentation erstellen“, „Writeup“
Zugehörige Module auf gleicher Ebene:
apk-reverse/– Erstellt Reverse-Engineering-Bericht nach APK-Reverseida-reverse/– Erstellt Reverse-Engineering-Bericht nach Binäranalyseradare2/– Erstellt Reverse-Engineering-Bericht nach CLI-Analysejs-reverse/– Erstellt Signaturbericht nach JS-Signatur-Reversereverse-engineering/– Erstellt Reverse-Engineering-Bericht nach allgemeinem Reversefield-journal/– Berichtsinhalte dienen auch als Datenquelle für das Evolutionstagebuch
Sicherheitsberichtsvorlage: references/security-report-templates.md
Anbieterberichtsregeln: references/vendor-report-rules.md (flavor: malware | apt | null; optionaler overlay: vuln)
Allgemeine Dokumentvorlage: references/templates.md
Selbstkontrolle vor Abschluss (MUSS bestanden sein, bevor der Abschluss erklärt werden kann)
- Habe ich jeden Schritt des Workflows ausgeführt (nicht nur gelesen)?
- Habe ich echte Tool-Pfade basierend auf dem
tool-indexverwendet? - Habe ich reproduzierbare Beweise erzeugt (Befehle/Skripte/Screenshots/Berichte)?
- Enthält der Bericht die Kette Evidence / Finding / Path (Ops-Vertrag)?
- Habe ich die Checklisten-Punkte aus RULES abgeschlossen und zurückgeschrieben?