[Docgen] Guest-Doku unvollständig: Updates (0/78) und HTTP-Services (0/78) werden nie gerendert, Ports aus nur einer von zwei Quellen #213
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Folgeissue zu #212. Waehrend der Fehleranalyse an den Agent-Daten ist aufgefallen, dass die Guest-Dokumentation mehrere vorhandene Datenquellen gar nicht rendert. Kein Bug im engeren Sinn — die Doku ist schlicht unvollstaendig, und zwar an den Stellen, die den Betrieb am meisten interessieren.
Bestandsaufnahme (78 generierte VM-Dateien,
_BEISPIELausgenommen)vm_scans[vmid].diskvm_scans[vmid].dockerVMPortSnapshotVMNotevm_scans[vmid].updates— wird nie gerendertvm_scans[vmid].http_services— wird nie gerendertZum Vergleich: die 7 Node-Dateien sind vollstaendig (PVE-Version, CPU, RAM, Kernel, Temp, Uptime, IP, Updates, Storage, Netzwerk — durchgaengig gefuellt). Das Problem sitzt ausschliesslich auf Guest-Ebene.
1. Updates fehlen vollstaendig
_vm_md()hat keine Update-Sektion.gscan["updates"]mitavailable/security/checkedliegt vor und wird vonadmin_router.py:226undupdate_router.pyausgewertet. Die Doku zeigt damit "Host: 90 Updates verfuegbar (Security: 3)" auf Node-Ebene und schweigt zu allen Gaesten darunter. Bei VM-Updates als Kernfeature (#123) ist das die groesste Luecke.Fallstrick — Display-Gating fuer gestoppte Guests.
admin_router.py:221dokumentiert die verbindliche Regel (#30):Docgen muss dasselbe tun, sonst stehen in der Doku dauerhaft Phantom-Updates fuer gestoppte VMs. Nicht die Daten filtern — die Darstellung gaten, und den Zustand benennen:
Genau diese Regel ist ein Musterbeispiel dafuer, warum die Anreicherung nach
services/guest_view.pygehoert (#212): sie steht heute als Kommentar in einem Router und wird beim Nachbauen zuverlaessig uebersehen.2. HTTP-Services werden nicht genutzt
vm_scans[vmid].http_serviceswird vom Agent gemeldet und vom Dashboard zu Service-Links verarbeitet (deploy_router.py:336). In der Doku taucht es nicht auf.Das ist die direkteste verfuegbare Quelle fuer die Funktion eines Guests — relevant fuer die
role-Ableitung in #209, die bisher nur Docker-Images und Ports auswertet. Ein Guest ohne Docker, aber mit erkanntem HTTP-Service auf 8080, ist heute "unbekannt".Neue Sektion
## Dienstemit Port, erkanntem Dienst/Titel und Pfad. Keine Links in die Live-Umgebung erzeugen — die Doku ist ein Snapshot, kein Dashboard.3. Ports kommen aus zwei Quellen
Docgen liest ausschliesslich die Tabelle
VMPortSnapshot(10 von 78 Dateien). Parallel liefert der Agentvm_scans[vmid].ports, dasdeploy_router.py:337verwendet. Dieselbe Quellen-Spaltung wie beim Agent-Feld in #212.Zusammenfuehren in
guest_view.build_guest_view(), mit klarer Herkunftskennzeichnung in der Ausgabe — ein Port aus dem aktiven Port-Scan (mitexposure-Bewertung) ist eine andere Aussage als ein vom Agent gemeldeter Listener.4. Belegter Speicher: Node-Storage vs. Guest-Disk
_vm_mdrendertgscan["disk"](Gast-df, also tatsaechliche Belegung im Dateisystem). Die Kopftabelle zeigt danebenmaxdiskaus Proxmox (zugewiesene Groesse). Beides ist richtig, steht aber unkommentiert nebeneinander und laedt zu Fehlschluessen ein. Spaltenueberschriften eindeutig benennen ("zugewiesen" vs. "belegt im Gast").Prompt fuer Claude Code
Definition of Done
## Dienste-Sektion aushttp_serviceszugewiesenvs.belegt im Gastnicht mehr verwechselbarrole-Ableitung nutzt HTTP-ServicesNachtrag: Updates entfallen — Doku ist strukturell, nicht zustandsbezogen
Der Update-Teil dieses Issues wird ersatzlos gestrichen. Punkt 1 ("Updates fehlen vollstaendig") und alle davon abhaengigen Anteile im CC-Prompt (Update-Kopfzeile,
updates_*-Frontmatter, Matrix-Spalte "Updates", MOC-Arbeitslisten zu Security-Updates und fehlender Pruefung) sind hinfaellig.Begruendung: derselbe Massstab, mit dem CVEs aus #209 geflogen sind. Updates sind Zustand, kein Strukturmerkmal — hochfrequent, beim Lesen bereits veraltet, und in einer taeglich committeten Snapshot-Doku erzeugen sie Diff-Rauschen, das echte Infrastruktur-Aenderungen ueberdeckt. Updates gehoeren ins Dashboard (#123) und ins Task-Center, nicht ins Vault. Die ganze Diskussion um Display-Gating fuer gestoppte Guests (#30) entfaellt damit ebenfalls — sie war nur noetig, weil die Zahlen ueberhaupt in die Doku sollten.
Was von diesem Issue bleibt:
## Diensteaushttp_services(Punkt 2)zugewiesenvs.belegt im Gasteindeutig benennen (Punkt 4)Was hinzukommt: Die Docker-Erfassung ist jetzt der wichtigste Baustein, weil sie zusammen mit dem Dienste-Inventar (#215) die Funktionserkennung traegt. Docker-Sektionen erscheinen aktuell in 37 von 78 Dateien; nach #212 ist zu pruefen, ob diese Zahl zur Realitaet passt oder ob dort dieselbe Fehlerklasse steckt wie beim Agent-Feld.
Die Funktions-/Rollenerkennung selbst wandert vollstaendig nach #216.
Updates raus — gleiche Begruendung wie bei den CVEs: vergaenglicher Zustand, gehoert nicht in eine strukturelle Doku. Nachtrag am Issue-Ende, Punkt 1 des CC-Prompts ist hinfaellig.
Schwerpunkt verschiebt sich damit auf Docker + Dienste als Grundlage der Funktionserkennung. Die Ableitung selbst liegt jetzt in #216.