ansible-webui/entwicklung/architektur.md

Architektur — Web‑UI für Ansible‑TUI

Kurzer Überblick Dieses Dokument beschreibt die finale Architektur für das MVP Web‑UI gemäß dem gewählten Profil: Minimal — extern gepflegte .htpasswd, direkte ansible‑playbook‑CLI, ZIP/TAR‑Uploads, SSH‑Keys nur abgelegt.

Authentifizierung

• Nur externe .htpasswd zur HTTP‑Basic‑Authentifizierung.
• Die Applikation validiert Anfragen gegen die Webserver‑auth (keine DB‑Sync, keine interne Benutzerverwaltung).
• Betrieb: Ops pflegt .htpasswd; die Applikation nimmt keine Änderungen an .htpasswd vor.

Executor

• Playbooks werden durch Aufruf der systemweiten ansible‑playbook CLI ausgeführt.
• Kein Einsatz von ansible‑runner oder eines persistenten Hintergrund‑Executors im MVP.
• Die Applikation erstellt bei Bedarf temporäre Arbeitsverzeichnisse, schreibt erforderliche Metadaten und ruft ansible‑playbook mit den passenden Parametern.

SSH‑Key‑Handling

• SSH‑Keys werden als Dateien im Dateisystem abgelegt (Uploads oder durch Ops bereitgestellt).
• Die Applikation ändert keine Besitz‑ oder Berechtigungsattribute; Berechtigungsmanagement liegt bei den Betriebsprozessen/Opsteam.
• Keys werden referenziert, aber nicht automatisch verteilt oder in externe Stores synchronisiert.

Netzwerk / Deployment

• Kein integrierter Reverse‑Proxy oder TLS im MVP.
• Container/Service horcht direkt auf Port 8000 (HTTP).
• TLS, Reverse‑Proxy oder Ingress werden von der Ziel‑Betriebsumgebung bereitgestellt und in späteren Releases integriert.

Uploads / Artefakte

• Unterstützte Uploads: ZIP und TAR. Eingangsprüfung auf erlaubte Dateitypen und Größenlimits.
• Entpackung erfolgt in sicheren, temporären Verzeichnissen; keine automatische Ausführung von hochgeladenem Code außer kontrollierten Ansible‑Playbooks.

Persistenz / Datenbank

• Minimales MVP vermeidet eigene Benutzer‑DB. Falls Metadaten nötig sind, begrenzt auf leichtgewichtige lokale Speicherung (z. B. SQLite).
• Keine Speicherung sensitiver Geheimnisse in der Applikations‑DB; Secrets verbleiben unter Ops‑Verwaltung.

Sicherheitshinweise

• Ops ist verantwortlich für sichere Aufbewahrung und Rollout von .htpasswd und SSH‑Keys.
• Applikationslogs vermeiden sensitive Inhalte; Playbook‑Outputs können ggf. redigiert werden.

Offene Fragen

• Keine offenen Fragen — alle Entscheidungen sind gemäß dem Minimal‑Profil finalisiert.

Erweiterung: Automatisches Host‑Onboarding (Feature‑Spec)

Zweck

• Erlaubt automatisches Onboarding neuer Zielhosts mit wählbaren Optionen:
  1. Pro‑Host SSH‑Key: serverseitig erzeugtes Schlüsselpaar (Ed25519, Fallback RSA‑4096).
  2. Login per Username + temporärem Passwort (Sudo‑fähiger Account) für initiale Berechtigungsaufgaben.
  3. Passwort wird nur einmalig verwendet und danach unverzüglich verworfen.

Kontext / Referenzen

• Diese Erweiterung baut auf bestehender Architektur auf; siehe Hauptdokumentation und API‑Liste: webapp/entwicklung/api_endpoints.md, DB‑Schema: webapp/entwicklung/schema.sql und Roadmap: webapp/entwicklung/roadmap.md.

Design‑Prinzipien (Policy: Strict Ops‑First)

• Schlüssel: Ed25519 wird erzeugt. Falls Client/Host Ed25519 nicht unterstützt, Fallback RSA‑4096.
• Host‑Fingerprint: strikt — Fingerprint muss mit Ops' known_hosts übereinstimmen oder vorab durch Ops manuell freigegeben werden. Abweichende Fingerprints erzeugen eine Onboarding‑Sperre (Ops‑Review).
• Privater Schlüssel: niemals persistent auf Datenträger; nur im RAM des Onboarding‑Jobs verfügbar, nur für die Dauer des Jobs.
• Passwort: nur im RAM gehalten; nach erfolgreichem Onboarding sofort unwiederbringlich verworfen. Bei Fehlern sind maximal 3 unmittelbare Retries erlaubt, danach Ops‑Intervention.
• Audit: nur Metadaten (username, host, fingerprint‑SHA256, event=start|success|fail, timestamp, operator_id bei manueller Freigabe). Keine Passwörter oder Private‑Key‑Material in Logs oder DB. Audit‑Retention: 365 Tage.

Komponenten (Erweiterung)

• Onboarding UI (neues Formular, siehe API‑Mapping).
• Onboarding API (neue Endpoints; Auth via HTTP‑Basic/REMOTE_USER).
• Onboarding Service / Job Runner (zuständig für Erzeugung Key, SSH‑Verbindung, sudo‑Aufgaben, Key‑Copy).
• Ops Approval Queue (falls Host‑Fingerprint nicht bekannt).
• DB Erweiterungen (Hosts‑Tabelle, Onboard‑Jobs, Key‑Referenzen, ephemeral markers) — siehe vorgeschlagene Schema‑Änderungen in webapp/entwicklung/schema.sql.
• Audit‑Subsystem: schreibt streng limitierte Events in audit_logs mit Tagging.

Prozessablauf (High‑Level)

• UI: Benutzer öffnet "Host Onboarding" Formular und gibt ein: hostname/ip, ssh_port (optional), username (für initiales Passwort‑Login), temporäres Passwort (nur wenn Option 2 gewählt), gewünschter Ziel‑Benutzername (z. B. ansible user) und evtl. Beschreibung.
• API: POST /onboard/requests erzeugt Onboard‑Request, validiert Felder, erstellt Onboard‑Job und antwortet mit job_id.
• Pre‑Checks: Onboarding Service prüft Erreichbarkeit (TCP), prüft Host‑Fingerprint gegen Ops known_hosts.
  • Falls Fingerprint unbekannt/abweichend: Job wird in Ops‑Approval‑Queue gestellt; API gibt status=awaiting_approval zurück.
  • Falls Fingerprint OK: Fortsetzung.
• Key Generation: Service erzeugt temporäres Schlüsselpaar (Ed25519 oder RSA‑4096); privater Schlüssel bleibt nur in‑memory.
• SSH Login: Service stellt SSH‑Sitzung mit provided username+password auf. Die Login‑Phase verwendet sichere in‑memory Credentials; Zeitüberschreitung/Fehler führen zu Retry (max 3).
• Privilegien: Service führt via sudo (password prompted, one‑time use) die notwendigen Befehle aus (Erstellen Zieluser, setfacl/chown, Erstellen ~/.ssh, Deploy public key).
• Key‑Copy: öffentlicher Schlüssel wird in das target user's authorized_keys geschrieben; Dateirechte gesetzt.
• Verifizieren: Service versucht Login per SSH‑Key (key auth) und optional überprüft sudo‑Ausführung ohne Passwort (wenn operator gewünscht).
• Abschluss: Bei Erfolg markiert Job als completed, privater Schlüssel wird verworfen, Onboard‑Result in DB/Audit geschrieben. Bei Fehlern: bis 3 Retries, danach markiert als failed und Ops benachrichtigt.
• Cleanup: temporäre Verzeichnisse/Handles werden gelöscht, keine sensible Persistenz.

Mermaid: Ablaufdiagramm (vereinfachte Darstellung)

graph TB
  UI[User nutzt Onboarding‑Formular]
  API[POST /onboard/requests]
  JOB[Onboarding Service: Job erstellt]
  PRECHK[Pre‑Checks: TCP + Fingerprint vs Ops known_hosts]
  APPROVE[Ops Approval Queue]
  KEYGEN[Key‑Erzeugung: Ed25519 / RSA‑4096]
  SSHLOGIN[SSH Login mit User+Passwort (RAM)]
  SUDO[Sudo‑Aufgaben: create user, setup ~/.ssh, copy pubkey]
  VERIFY[Verify key auth]
  SUCCESS[Onboarding success -> Audit + DB]
  FAIL[Onboarding failed -> Audit + Ops Benachrichtigung]

  UI --> API --> JOB --> PRECHK
  PRECHK -- match --> KEYGEN --> SSHLOGIN --> SUDO --> VERIFY --> SUCCESS
  PRECHK -- mismatch --> APPROVE --> JOB
  VERIFY -- ok --> SUCCESS
  VERIFY -- nok --> FAIL

Schnittstellen / Integration (Kurz)

• Neue API Endpoints (voll spezifiziert in webapp/entwicklung/api_endpoints.md):
  • POST /onboard/requests — erstellt Onboarding‑Request, Payload enthält host, port, username, password (nur in‑transit), desired_user, options (generate_key: true/false), description.
  • GET /onboard/requests/{id}/status — Jobstatus, ops approval indicator.
  • POST /onboard/requests/{id}/approve — Ops endpoint zum Freigeben eines Fingerprints (Auth: REMOTE_USER muss Ops sein).
  • GET /onboard/keys — listet public keys erzeugt (readonly metadata).
  • GET /onboard/jobs — Liste der Onboarding Jobs (nur Metadaten).
• Sicherheit: Passwords ONLY accepted via HTTPS (Ops deployment requirement). App muss niemals persistieren Passwörter; API akzeptiert Passwort im Request Body, Job Runner liest ihn und löscht danach.

DB‑Änderungen (high level; detail in schema.sql)

• Neue Tabelle hosts:
  • id, hostname/ip, primary_key_id (FK), fingerprint_sha256, onboarded_at, onboarded_by, status (pending/awaiting_approval/onboarded/failed), created_at
• Neue Tabelle onboard_jobs:
  • id, host_id, requested_by, desired_user, options_json, retries, status, started_at, finished_at, error_message
• ssh_keys erweitert / referenziert (public key metadata only; private key never stored)
• audit_logs Nutzung: nur Metadaten (wie oben)

Sicherheits‑ und Audit‑Aspekte (Details)

• Passwort‑Handling:
  • Password im API‑Request wird unmittelbar dem Job übergeben und nur im RAM gehalten.
  • Nach Jobabschluss oder nach Fehlern/Timeouts wird der Speicher unverzüglich ohne Swap/Logging freigegeben.
  • Implementationshinweis: nutze sichere Speicher‑APIs (mmap mit mlock wenn möglich) oder Host‑Mechanismen, um Swapping zu verhindern.
• Private Key Handling:
  • Erzeugung im Job‑Prozess oder in isolierter Secure Enclave; privater Key nie auf Disk.
  • Wenn Ops‑Review/Transfer erforderlich, Key kann kurzfristig (maximal Job‑Dauer) in verschlüsseltem Prozess‑Speicher gehalten werden; standardmäßig verboten.
• Fingerprint Handling:
  • Vergleich gegen Ops known_hosts (Ops liefert Pfad oder API für known_hosts‑Hash).
  • Bei Mismatch: keine automatische Akzeptanz; Ops‑Approval erforderlich.
• Auditing:
  • Erfasste Felder: event_type, job_id, host, fingerprint_sha256, requested_by, operator_id (bei approval), short status message, timestamp.
  • Keine Speicherung sensibler Inhalte (kein Passwort, kein privater Key).
  • Audit‑Retention: 365 Tage; älterer Einträge werden anonymisiert oder gelöscht gemäß Ops‑Policy.
• Log‑Sanitization:
  • Playbook/SSH Outputs werden auf sensitive Patterns geprüft/redigiert bevor sie persistiert oder angezeigt werden.

Betriebsverantwortung / Ops‑Aufgaben

• Ops liefert trusted known_hosts repository oder API‑Endpoint zur Fingerprint‑Prüfung.
• Ops sorgt für Transport‑TLS und sichere Deployment‑Konfiguration (no plaintext HTTP in Prod).
• Ops prüft und genehmigt Host‑Fingerprints in Approval‑Queue.
• Ops führt periodische Reviews/Key‑Rotation durch (nicht automatisch durch App).

Nächste Schritte (Dokumentation)

• API‑Specs aktualisieren: webapp/entwicklung/api_endpoints.md
• Schema‑Änderungen in: webapp/entwicklung/schema.sql
• Roadmap: neue Phase "Onboarding" mit Aufwandsschätzung und Meilensteine: webapp/entwicklung/roadmap.md

(Ende Erweiterung)