# 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.