149 lines
11 KiB
Markdown
149 lines
11 KiB
Markdown
# 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`](webapp/entwicklung/api_endpoints.md:1), DB‑Schema: [`webapp/entwicklung/schema.sql`](webapp/entwicklung/schema.sql:1) und Roadmap: [`webapp/entwicklung/roadmap.md`](webapp/entwicklung/roadmap.md:1).
|
||
|
||
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`](webapp/entwicklung/schema.sql:1).
|
||
- 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`](webapp/entwicklung/api_endpoints.md:1)):
|
||
- 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`](webapp/entwicklung/api_endpoints.md:1)
|
||
- Schema‑Änderungen in: [`webapp/entwicklung/schema.sql`](webapp/entwicklung/schema.sql:1)
|
||
- Roadmap: neue Phase "Onboarding" mit Aufwandsschätzung und Meilensteine: [`webapp/entwicklung/roadmap.md`](webapp/entwicklung/roadmap.md:1)
|
||
|
||
(Ende Erweiterung) |