ITSM/docs/adr/ADR-011-fleet-agent-und-ssh.md

ADR-011: Fleet-Anbindung — Pull-Agent mit SSH-Fallback

Datum: 2026-07-28 · Status: Akzeptiert Vorgabe: "Systemverwaltung aller Groundwork-OS Systeme, aber auch Windows und Linux System via Agent" (Anbindung: Agent + SSH-Fallback)

Kontext

Zu verwaltende Systeme: Groundwork-OS-Instanzen, Linux-Server, Windows- Clients/Server. Sie stehen teils hinter NAT/Firewalls, teils ohne Möglichkeit zur Softwareinstallation. Reine Push-Steuerung (Server → Host) verlangt erreichbare Ports und hinterlegte Zugangsdaten für jedes System.

Entscheidung

Primär: Pull-Agent. Der Agent wird mit einem mandantengebundenen Enrollment-Token einmalig registriert und erhält ein eigenes Host-Token (in der DB nur als SHA-256-Hash — gleiches Prinzip wie Sessions, ADR-002). Danach ausschließlich ausgehende HTTPS-Verbindungen:

POST /api/fleet/enroll     einmalig, mit Enrollment-Token
POST /api/fleet/heartbeat  zyklisch: Status + Inventar, Antwort = offene Jobs
POST /api/fleet/jobs/:id/result   Ergebnis (exit code, stdout/stderr gekürzt)

Kein offener Port auf dem verwalteten System, NAT-tauglich, Token pro Host einzeln widerrufbar (Host sperren ⇒ Agent verliert sofort Zugriff).

Sekundär: SSH/WinRM-Fallback für agentenlose Hosts — als Host-Typ ssh gepflegt, ausgeführt vom Server aus. Zugangsdaten werden nicht in Groundcontrol gespeichert (kein Passwort-Tresor im Produkt); genutzt wird der SSH-Key des Servers. Reichweite bewusst kleiner als beim Agenten.

Job-Sicherheit: Jobs sind Kommandos auf fremden Systemen — daher

• nur Rolle fleet_operator/admin darf Jobs anlegen (Rolle fleet_viewer sieht nur Inventar),
• jeder Job wird im Audit-Log mit Kommando, Ziel und Auslöser protokolliert,
• Jobs sind an einen Host gebunden und laufen genau einmal (Status Offen → Zugestellt → Erledigt/Fehler),
• Agent führt Jobs unter seiner eigenen Kennung aus; Rechteausweitung ist Sache des Systems, nicht der Plattform.

Konsequenzen

• Funktioniert über NAT/Firewall hinweg, ohne eingehende Ports.
• Host-Token einzeln widerrufbar; Kompromittierung bleibt lokal begrenzt.
• Ein Agent-Binary für Linux und Windows (Rust, statisch gelinkt). − Latenz durch Polling (Heartbeat-Intervall statt Echtzeit) — für Verwaltungsaufgaben akzeptabel; WebSocket wäre eine spätere Option. − SSH-Fallback ist bewusst eingeschränkt (Server-Key statt Credential-Store); ein Passwort-Tresor wäre ein eigener ADR mit deutlich höherem Schutzbedarf.