Rolling Documentation: Opportunistisches Host-Scanning hinzugefügt

2026-01-28 16:26:29 +01:00
parent 3660683a73
commit 6826e36386
5 changed files with 524 additions and 0 deletions
--- a/plans/partitioned-enchanting-mango.md
+++ b/plans/partitioned-enchanting-mango.md
@@ -0,0 +1,189 @@
+# Plan: CLAUDE.md erweitern - Opportunistisches Host-Scanning
+
+## Ziel
+
+Neue Anweisung in `~/dotfiles/claude_settings/CLAUDE.md` aufnehmen: **Rolling Documentation durch opportunistisches Host-Scanning**
+
+## Kontext
+
+Bei der Arbeit an n8n/flow.wvits.de hatte ich SSH-Zugriff auf gw-nu-dmz02, habe aber nur die für die aktuelle Aufgabe relevanten Firewall-Regeln dokumentiert. Der User möchte, dass bei jedem Host-Zugriff ein vollständiger Scan erfolgt.
+
+---
+
+## Änderung
+
+### Datei
+
+`~/dotfiles/claude_settings/CLAUDE.md`
+
+### Platzierung
+
+Nach Zeile 467 (nach "Dokumentations-Verifikation (PFLICHT)" und vor "Skills-Referenz")
+
+### Neuer Abschnitt
+
+```markdown
+### Rolling Documentation: Opportunistisches Host-Scanning
+
+**Prinzip:** Wenn du während deiner Arbeit Zugriff auf einen Host bekommst, führe einen VOLLSTÄNDIGEN Scan durch - nicht nur für die aktuelle Aufgabe.
+
+#### Auslöser
+
+- SSH-Zugriff auf einen Host
+- Web-UI Zugriff (pfsense, NPM, etc.)
+- API-Zugriff
+
+#### Workflow bei Host-Zugriff
+
+1. **Prüfe:** Existiert `infrastructure/hosts/[hostname].md`?
+2. **Falls nein oder unvollständig:** Vollständigen Scan durchführen
+3. **Dann erst:** Ursprüngliche Aufgabe erledigen
+
+#### Scan-Checkliste nach Host-Typ
+
+**Netzwerk-Geräte (pfsense, Router):**
+- [ ] Interfaces (Name, IP, Netz)
+- [ ] ALLE Firewall-Regeln (nicht nur relevante!)
+- [ ] ALLE Aliases
+- [ ] NAT-Regeln (Port-Forwards, Outbound)
+- [ ] DHCP/DNS-Konfiguration
+- [ ] System-Version
+- [ ] **ABHÄNGIGKEITEN:** Welche Hosts/Dienste hängen von diesem Gerät ab?
+
+**Linux-Server:**
+- [ ] OS/Version
+- [ ] Interfaces und IPs
+- [ ] Laufende Dienste
+- [ ] Docker-Container
+- [ ] Offene Ports
+- [ ] Wichtige Configs
+- [ ] **ABHÄNGIGKEITEN:** Welche anderen Hosts braucht dieser Server? Wer braucht ihn?
+
+**Windows-Server:**
+- [ ] OS/Version
+- [ ] Interfaces und IPs
+- [ ] Dienste und geplante Tasks
+- [ ] Installierte Rollen
+- [ ] **ABHÄNGIGKEITEN:** Verbindungen zu anderen Systemen
+
+#### PFLICHT: Abhängigkeiten dokumentieren
+
+**Bei JEDEM Host-Scan müssen die Abhängigkeiten erfasst werden:**
+
+| Frage | Dokumentieren in |
+|-------|------------------|
+| Welche Hosts/Dienste braucht dieser Host? | `hosts/[host].md` → Abschnitt "Abhängigkeiten" |
+| Welche Hosts/Dienste hängen von diesem Host ab? | `hosts/[host].md` → Abschnitt "Abhängig von diesem Host" |
+| Gibt es Abhängigkeitsketten? | `dependencies.md` → Mermaid-Diagramm |
+
+**Ziel:** Anhand der Dokumentation muss erkennbar sein:
+- Was passiert wenn Host X ausfällt?
+- Welche Dienste sind von Änderungen an Host X betroffen?
+- Welche Hosts müssen vor Host X gestartet werden?
+
+**Beispiel Abhängigkeits-Dokumentation:**
+
+```markdown
+## Abhängigkeiten
+
+Dieser Host benötigt:
+- **srv-docker02** (10.10.10.81) - n8n Backend
+- **srv-nu-dc01** (10.10.10.111) - DNS-Auflösung
+
+## Abhängig von diesem Host
+
+Folgende Dienste/Hosts sind von diesem Host abhängig:
+- **flow.wvits.de** - Webhook-Zugang fällt aus wenn dieser Host down ist
+- **n8n.vinos.de** - Interner Zugang über diesen NPM
+
+## Impact bei Ausfall
+
+| Ausfall-Szenario | Betroffene Dienste |
+|------------------|-------------------|
+| Komplett-Ausfall | flow.wvits.de, n8n.vinos.de, ... |
+| Nur Port 443 | HTTPS-Zugriff auf alle proxied Dienste |
+```
+
+**dependencies.md aktualisieren:**
+
+Nach jedem Host-Scan prüfen ob `infrastructure/dependencies.md` aktualisiert werden muss:
+- Neue Abhängigkeitskette entdeckt? → Mermaid-Diagramm ergänzen
+- Impact-Analyse hinzufügen
+- Repo-Links aktualisieren
+
+#### Beispiel
+
+**Aufgabe:** Firewall-Regel für srv-revproxy01 prüfen
+
+| Falsch | Richtig |
+|--------|---------|
+| Nur die eine Regel prüfen | Erst: Existiert hosts/gw-nu-dmz02.md? |
+| Session beenden | Nein → Vollständigen Scan aller Regeln, Aliases, Interfaces |
+| | Host-Datei erstellen |
+| | Dann: Ursprüngliche Aufgabe |
+
+#### Rekursive Host-Entdeckung (WICHTIG!)
+
+**Wenn du bei einem Scan Referenzen zu anderen Hosts siehst, gehe AUTOMATISCH weiter:**
+
+Entdeckungsquellen:
+- Firewall-Regeln (Ziel-IPs, Aliases)
+- NAT-Regeln (Forward-Ziele)
+- DNS-Einträge
+- Docker-Compose (externe Hosts)
+- Konfigurationsdateien
+- Log-Einträge
+- Netzwerk-Verbindungen
+
+**Workflow:**
+
+```
+Host A scannen
+  ↓
+Entdecke Referenz zu Host B (z.B. in Firewall-Regel)
+  ↓
+Kann ich Host B erreichen?
+  ├─ JA → Host B scannen (rekursiv)
+  └─ NEIN → Host B in Entdeckungsliste aufnehmen
+```
+
+**Entdeckungsliste führen:**
+
+Wenn ein Host nicht gescannt werden kann (kein Zugriff, keine Credentials, etc.):
+
+```markdown
+## Entdeckte aber nicht gescannte Hosts
+
+| Host | IP | Entdeckt in | Grund für fehlenden Scan |
+|------|----|-------------|-------------------------|
+| srv-xyz01 | 10.10.10.99 | gw-nu-dmz02 Firewall-Regel | Kein SSH-Zugriff |
+| db-server | 10.10.20.5 | docker-compose.yml | Credentials unbekannt |
+```
+
+**Der User muss dich NICHT auf jeden Host einzeln hinweisen!**
+
+Du sollst selbstständig:
+1. Referenzen zu anderen Hosts erkennen
+2. Versuchen diese zu scannen
+3. Falls nicht möglich: Dokumentieren was du entdeckt hast
+4. Beim nächsten Mal nachfragen ob Zugriff jetzt möglich ist
+
+#### Effizienz
+
+Nutze parallele Agenten für umfangreiche Scans und rekursive Entdeckung.
+
+#### Ausnahmen
+
+- Zeitkritische Notfälle (erst fixen, dann dokumentieren)
+- Explizite User-Anweisung nur aktuelle Aufgabe zu erledigen
+- User sagt explizit "nicht weiter scannen"
+```
+
+---
+
+## Verifikation
+
+1. CLAUDE.md editieren
+2. Abschnitt an korrekter Stelle eingefügt prüfen
+3. `cd ~/dotfiles/claude_settings && git add -A && git commit -m "Rolling Documentation: Opportunistisches Host-Scanning hinzugefügt" && git push origin main`
+4. `git status` zeigt clean