ansible-webui/entwicklung/api_endpoints.md

API Endpoints — Web‑UI für Ansible‑TUI

Hinweis zur Authentifizierung

• HTTP‑Basic wird extern via .htpasswd gepflegt; Webserver setzt Auth und ggf. REMOTE_USER.
• Die Applikation verifiziert keine internen Benutzer, erwartet ggf. REMOTE_USER zur Audit‑Zuordnung.

Endpunkte (MVP)

GET /health

• Beschreibung: Simple Health‑Check
• Antwort: 200 OK

GET /playbooks

• Beschreibung: Liste aller hochgeladenen Playbooks (Metadaten)
• Query: ?limit=&offset=
• Antwort: JSON Array [{id,name,filename,uploaded_by,uploaded_at}]

POST /uploads

• Beschreibung: Upload eines ZIP/TAR mit Playbook(s)
• Konsumiert: multipart/form-data file=...
• Validierung: MIME und Dateiendung (zip,tar,tgz), Größenlimit
• Antwort: 201 Created + Metadaten

GET /playbooks/{id}

• Beschreibung: Metadaten zu einem Playbook
• Antwort: JSON

POST /playbooks/{id}/run

• Beschreibung: Startet einen Run via systemweiter ansible-playbook CLI. Keine Nutzung von ansible-runner.
• Body: optional JSON {inventory: string, extra_vars: object, tags: [string], become: bool}
• Behaviour: Prozess wird vom Service gestartet; stdout/stderr werden in temporäre Dateien geschrieben.
• Antwort: 202 Accepted {run_id}

GET /runs/{run_id}/status

• Beschreibung: Statusabfrage (queued,running,success,failed)
• Antwort: JSON {run_id,status,exit_code,started_at,finished_at}

GET /runs/{run_id}/output

• Beschreibung: Holt vollständiges stdout/stderr des Runs (Text/stream)
• Antwort: text/plain (oder chunked)

GET /keys

• Beschreibung: Listet referenzierbare SSH‑Keys (nur lesend)
• Antwort: JSON [{key_id,filename,description}]

GET /logs?limit=&offset=

• Beschreibung: Zugriff auf Run‑Logs / Audit‑Einträge (keine sensiblen Daten)
• Antwort: JSON

Sicherheits‑Hinweis

• Die Applikation führt keine Änderung an SSH‑Keys oder .htpasswd durch.
• Alle schreibenden Betriebsaufgaben (Permissions, Key‑Rollout, TLS) sind außerhalb des MVP‑Scopes.

Erweiterung: Onboarding API — Endpoints für automatisches Host‑Onboarding

Authentifizierung / Autorisierung

• Auth via vorhandene HTTP‑Basic/.htpasswd‑Integration; Webserver stellt REMOTE_USER zur Verfügung.
• Ops‑spezifische Endpoints (z. B. Approve) erfordern REMOTE_USER ∈ Ops‑Gruppe (Ops‑Policy).
• Transport: Produktion erfordert TLS (Ops‑Deployment‑Voraussetzung).

Zusätzliche Endpoints (Übersicht)

• POST /onboard/requests
• GET /onboard/requests
• GET /onboard/requests/{id}/status
• POST /onboard/requests/{id}/approve
• POST /onboard/requests/{id}/cancel
• GET /onboard/jobs
• GET /onboard/keys
• GET /onboard/requests/{id}/logs

POST /onboard/requests

• Zweck: Erstellt eine Onboarding‑Anfrage / startet ein Onboarding‑Job (sofern Pre‑Checks erfolgreich sind).
• Auth: REMOTE_USER (any authenticated user)
• Konsumiert: application/json
• Payload: { "host": "192.0.2.10", // host oder IP "port": 22, // optional, default 22 "login_user": "ubuntu", // Account zur initialen Login‑Phase (sudo‑fähig) "login_password": "secret", // nur in‑transit; wird nicht persistiert "desired_user": "ansible", // Benutzer, der angelegt/wenn nötig benutzt wird "generate_key": true, // true => Server erzeugt Schlüsselpaar (Ed25519/RSA‑4096 fallback) "public_key": null, // optional, wenn false und Nutzer eigenen Schlüssel liefert "description": "Kurzinfo", "options": { // optional: z. B. {"force_approve":false} "force_approve": false } }
• Verhalten:
  • Validierung von Pflichtfeldern.
  • Erzeugt Onboard‑Request und Onboard‑Job, reply enthält { "job_id": "...", "status": "created" }.
  • Wenn Fingerprint nicht mit Ops known_hosts übereinstimmt, wird status = "awaiting_approval".
• Antwort: 201 Created { "job_id": "uuid", "status": "created" | "awaiting_approval" | "queued" }
• Fehlercodes:
  • 400 Bad Request (Validierungsfehler)
  • 401 Unauthorized
  • 429 Too Many Requests (Rate‑Limit pro User/Host)

GET /onboard/requests

• Zweck: Listet Onboarding‑Requests (nur Metadaten)
• Query: ?limit=&offset=&status=
• Antwort: JSON Array [{job_id, host, requested_by, status, created_at, fingerprint_sha256?}]

GET /onboard/requests/{id}/status

• Zweck: Statusabfrage für einen Request
• Antwort: { "job_id": "...", "host": "...", "status": "created|queued|running|awaiting_approval|approved|onboarded|failed|cancelled", "retries": 0, "started_at": "...", "finished_at": "...", "error_message": "kurze Fehlerdiagnose (sensitivitäts‑gefiltert)" }

POST /onboard/requests/{id}/approve

• Zweck: Ops‑Endpoint zur Freigabe eines abweichenden Host‑Fingerprints
• Auth: REMOTE_USER muss Ops sein (Server‑Side check)
• Payload: { "approve": true, "operator_note": "Fingerprint validiert via call", "operator_id": "ops-username" }
• Verhalten: Wenn genehmigt, Job wird zur Fortsetzung freigegeben; Audit‑Eintrag mit operator_id erzeugt.
• Antwort: 200 OK { "job_id": "...", "status": "approved" }
• Fehler: 403 Forbidden (wenn nicht Ops), 404 Not Found

POST /onboard/requests/{id}/cancel

• Zweck: Bricht laufenden/queued Onboarding‑Job ab (z. B. User Abbruch)
• Auth: Requester oder Ops
• Antwort: 200 OK { "job_id": "...", "status": "cancelled" }

GET /onboard/jobs

• Zweck: Admin/Operator Sicht auf Onboard‑Jobs (Metadaten)
• Filters: status, requested_by, host
• Antwort: Array von job‑Metadaten (keine sensitiven Inhalte)

GET /onboard/keys

• Zweck: Listet erzeugte Public‑Keys (Metadaten only)
• Antwort: [{ "key_id": "...", "host_id": "...", "public_key_fingerprint": "...", "created_at": "..." }]

GET /onboard/requests/{id}/logs

• Zweck: Liefert redigierte Logs des Onboarding‑Jobs (Ausgaben, Schritte)
• Sicherheits‑Hinweis: Logs sind gesäubert; keine Passwörter oder private Key‑Material enthalten.
• Antwort: text/plain oder JSON { "lines":[ ... ] }

Sicherheits‑Hinweise für API‑Design

• Login‑Password darf niemals geloggt werden; im API‑Server mittelbar nur in‑memory übergeben.
• API darf niemals privaten Schlüssel in Responses zurückliefern.
• Alle Endpoints, die sensible Ablaufsteuerung erlauben (approve, cancel), müssen REMOTE_USER‑Checks durchführen.
• Rate‑Limits: Schutz gegen bruteforce / DOS.
• Input‑Sanitization: host/username dürfen keine Shell‑Injection ermöglichen; SSH‑Interaktionen erfolgen kontrolliert.
• Audit: Jeder state‑wechsel (created, awaiting_approval, approved, onboarded, failed, cancelled) schreibt ein Metadaten‑Audit (siehe webapp/entwicklung/schema.sql Anpassungen).

Mapping UI ↔ API

• UI‑Form "Host Onboarding" ↟ POST /onboard/requests
• UI‑Ops Dashboard ↟ GET /onboard/requests?status=awaiting_approval
• UI‑Ops Approve Button ↟ POST /onboard/requests/{id}/approve
• UI‑User Status Polling ↟ GET /onboard/requests/{id}/status
• UI‑Logs ↟ GET /onboard/requests/{id}/logs

Beispiel‑Flow (Kurz)

1. User sendet POST /onboard/requests mit login_password.
2. API antwortet job_id.
3. Onboarding Service führt Pre‑Check aus; bei Fingerprint‑Mismatch → awaiting_approval.
4. Ops Approver ruft POST /onboard/requests/{id}/approve → Service fährt fort.
5. Job schreibt audit_logs und setzt Host Status auf onboarded oder failed.

Referenzen zur weiteren Anpassung

• Architektur: webapp/entwicklung/architektur.md
• DB Schema: webapp/entwicklung/schema.sql
• Roadmap: webapp/entwicklung/roadmap.md