nixos-config/docs/research-intent/full-system-aufit.md

Intent: Full-System Audit

Ziel

Führe einen umfassenden, rein lesenden Audit der gesamten Plattform durch.

Der Audit soll nicht nur einzelne Komponenten isoliert prüfen, sondern das System als Ganzes betrachten und insbesondere den deklarativen Soll-Zustand aus dem NixOS-Repository mit dem tatsächlich laufenden Ist-Zustand auf dem VPS vergleichen.

Ziel ist es, technische Risiken, Inkonsistenzen, Fehlkonfigurationen, wiederkehrende Fehler, Architekturprobleme und sinnvolle Verbesserungsmöglichkeiten zu identifizieren.

Der Audit soll ausdrücklich keine Änderungen am System vornehmen.

Scope

Untersuche die Plattform end-to-end.

Dazu gehören insbesondere:

• das gesamte relevante Git-Repository
• NixOS- und Service-Konfigurationen
• deklarierter Soll-Zustand versus tatsächlicher Runtime-Zustand
• laufende systemd-Services
• fehlgeschlagene oder ungewöhnlich häufig neu gestartete Units
• systemd-Journals und wiederkehrende Warnungen oder Fehler
• Netzwerkdienste und deren Erreichbarkeit
• Reverse-Proxy-Konfiguration und Routing
• intern und extern exponierte Services
• Tailnet-bezogene Dienste und Abhängigkeiten
• gehostete Anwendungen und deren Backends
• APIs und HTTP-Endpunkte
• Web-Oberflächen aus Sicht eines tatsächlichen Benutzers
• offensichtliche Inkonsistenzen zwischen Code, Dokumentation und Runtime
• veraltete, ungenutzte oder widersprüchliche Konfiguration
• Sicherheits- und Zuverlässigkeitsrisiken
• Observability-Lücken
• technische Schulden und unnötige Komplexität

Diese Liste ist kein vollständiger Prüfplan.

Der Researcher soll ausdrücklich über diese Punkte hinaus untersuchen, wenn während des Audits relevante Spuren, Auffälligkeiten oder Zusammenhänge sichtbar werden.

Arbeitsweise

Arbeite explorativ und korreliere Informationen aus unterschiedlichen Quellen miteinander.

Beispiele:

• Wenn ein Service Fehler im Journal zeigt, prüfe die dazugehörige Nix-Konfiguration.
• Wenn die deklarative Konfiguration einen Dienst vorsieht, prüfe, ob und wie dieser tatsächlich läuft.
• Wenn ein Web-Frontend erreichbar ist, prüfe auch die zugrunde liegenden Requests, APIs und Backend-Services.
• Wenn Runtime-Zustand und Repository voneinander abweichen, dokumentiere die Abweichung.
• Wenn mehrere scheinbar unabhängige Symptome dieselbe Ursache haben könnten, behandle sie gemeinsam.

Der Fokus liegt nicht auf einer mechanischen Checkliste, sondern auf dem Verständnis des Systems als zusammenhängende Plattform.

Berechtigungen

Der Researcher darf zur Untersuchung alle verfügbaren Read-only-Werkzeuge verwenden, insbesondere:

• Repository und Dateien lesen
• Git-Historie untersuchen
• Shell-Kommandos zur Diagnose ausführen
• Prozess- und Servicezustände abfragen
• systemd und Journals untersuchen
• Netzwerkzustände und offene Ports prüfen
• lokale und erreichbare HTTP-/API-Endpunkte aufrufen
• Web-Oberflächen aufrufen und funktional untersuchen
• Konfigurationen miteinander vergleichen

Harte Grenze: Read-only

Während dieses Intents dürfen keine Änderungen vorgenommen werden.

Insbesondere nicht:

• Dateien verändern
• Commits erstellen
• Änderungen pushen
• NixOS rebuilden oder aktivieren
• Services starten, stoppen oder neu starten
• Konfigurationen reloaden
• Pakete installieren oder entfernen
• Datenbanken oder persistente Daten verändern
• produktive Requests mit verändernder Wirkung ausführen
• neue Folge-Intents automatisch anlegen oder ausführen

Wenn eine mögliche Verbesserung gefunden wird, soll sie ausschließlich dokumentiert werden.

Erwartetes Ergebnis

Erstelle einen ausführlichen Audit-Report.

Executive Summary

Beginne mit einer kurzen Zusammenfassung der wichtigsten 3–5 Erkenntnisse.

Diese Begrenzung gilt ausschließlich für die Executive Summary.

Die vollständige Anzahl der Findings ist nicht begrenzt.

Audit Coverage

Dokumentiere, welche Bereiche tatsächlich untersucht wurden und welche nicht untersucht werden konnten.

Nenne relevante Einschränkungen, fehlende Zugriffe oder Unsicherheiten ausdrücklich.

Findings

Dokumentiere jedes relevante Finding separat.

Für jedes Finding möglichst angeben:

• ID
• Titel
• Schweregrad
• betroffene Komponenten
• Beobachtung
• konkrete Evidenz
• erwarteter Zustand
• tatsächlicher Zustand
• vermutete Ursache
• mögliche Auswirkungen
• empfohlene nächste Schritte
• Konfidenz der Einschätzung

Geeignete Schweregrade können beispielsweise sein:

• Critical
• High
• Medium
• Low
• Informational

Findings sollen durch konkrete Evidenz gestützt sein und nicht ausschließlich auf Vermutungen beruhen.

Positive Findings

Dokumentiere auch Dinge, die besonders sauber, robust oder sinnvoll umgesetzt sind.

Der Audit soll nicht ausschließlich eine Fehlerliste sein.

Cross-System Observations

Führe Erkenntnisse auf, die sich erst aus der Verbindung mehrerer Komponenten ergeben, beispielsweise:

• Repository und Runtime widersprechen sich
• mehrere Services zeigen Symptome derselben Ursache
• Architektur und tatsächlicher Traffic-Flow unterscheiden sich
• Dokumentation beschreibt einen Zustand, der nicht mehr existiert

Empfohlene Folge-Intents

Erstelle am Ende eine priorisierte Liste möglicher Folge-Intents.

Diese sollen ausreichend konkret sein, damit aus ihnen später eigenständige Intents erstellt werden können.

Folge-Intents dürfen in diesem Audit jedoch weder automatisch erzeugt noch ausgeführt werden.

Wenn sinnvoll, unterscheide zwischen:

• Bugfix
• Reliability
• Security
• Cleanup
• Refactoring
• Documentation
• Observability
• Architecture

Priorisierung

Priorisiere Findings nicht nur nach theoretischem Schweregrad, sondern auch nach realem Nutzen.

Berücksichtige dabei unter anderem:

• Wahrscheinlichkeit eines tatsächlichen Problems
• mögliche Auswirkungen
• Nutzerrelevanz
• Betriebsrisiko
• Sicherheitsrelevanz
• Aufwand einer späteren Behebung
• Wahrscheinlichkeit, dass sich das Problem verschärft

Grundprinzipien

• Read-only.
• Evidenz vor Spekulation.
• Systemisch statt komponentenweise denken.
• Soll-Zustand und Ist-Zustand miteinander vergleichen.
• Auffälligkeiten über mehrere Schichten hinweg korrelieren.
• Nicht an der vorgegebenen Checkliste stehen bleiben.
• Keine Änderungen durchführen.
• Keine Probleme erfinden, nur um Findings zu produzieren.
• Wenn etwas gut funktioniert, das ebenfalls dokumentieren.