177 lines
7.5 KiB
Markdown
177 lines
7.5 KiB
Markdown
# 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`](webapp/entwicklung/schema.sql:1) 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`](webapp/entwicklung/architektur.md:1)
|
||
- DB Schema: [`webapp/entwicklung/schema.sql`](webapp/entwicklung/schema.sql:1)
|
||
- Roadmap: [`webapp/entwicklung/roadmap.md`](webapp/entwicklung/roadmap.md:1) |