Files
rust-discovery/Rust_RMM_Implementierungsspezifikation.md
2026-11-18 17:21:12 +01:00

42 lines
7.0 KiB
Markdown

# Produktvertrag des Rust-Discovery-MVP
Dieser Vertrag beschreibt den ausgelieferten Funktionsumfang. Die eingesetzten Versionen und die Ergebnisse auf den Zielgeräten stehen in der [MVP-Abnahme](docs/mvp-completion-plan.md).
## Server, Geräte und Kunden
Der Server betreibt die WebUI, den MCP-Endpunkt, den Releasekatalog und das Gerätegateway. PostgreSQL speichert die kundengebundenen Verwaltungsdaten. Der Geräteverkehr geht vom Client aus. Ein aufgenommener Agent authentisiert sich mit seinem Gerätezertifikat, übermittelt Heartbeats und Inventar, holt eventuell vorliegende Aufträge ab und meldet deren Verlauf und Ergebnis. Auch im Leerlauf meldet sich das Gerät regelmäßig.
Jede Installation ist an Kunde, Gerät und Agentenidentität gebunden. Die Standardansicht zeigt bereits authentisierte aktuelle Geräte als online oder offline, mit Hostname, Betriebssystem, freiem und gesamtem Speicherplatz, RAM, CPU und Kunde. Ausgemusterte, ersetzte und unbestätigte Kopplungen sind getrennt in der Historie abrufbar. Fehlende Inventarwerte bleiben als solche erkennbar. Der Zeitpunkt des letzten Kontakts und der Zeitpunkt der Inventarmessung haben unterschiedliche Bedeutung. [Geräteauswahl](crates/server/src/device_list.sql)
Kunden lassen sich in der WebUI anlegen und umbenennen. Beim Kundenwechsel erhält das Gerät eine neue Kopplung. Eine ausgeschiedene Installation kann nach Widerruf und persönlicher Bestätigung endgültig gelöscht werden. Ein noch gültiger offener Genehmigungsantrag oder ein nicht abgeschlossener Job einschließlich `unknown` sperrt die Löschung. Daten weiterhin beteiligter Zielgeräte bleiben erhalten. [Regeln zur Löschung](migrations/0036_delete_device_pairing.sql)
## Vom Skript zum Ergebnis
| Schritt | Verhalten |
| --- | --- |
| Skript veröffentlichen | In der Bibliothek eines Kunden erhält ein Skript einen Namen, einen Interpreter, einen Standard-Ausführungskontext und eine unveränderliche Version. Eine Bearbeitung veröffentlicht eine weitere Version. |
| Auftrag planen | Zielgeräte eines Kunden auswählen und entweder die genaue Bibliotheksversion oder ein eigenes Skript angeben. Der Plan bindet Skriptbytes, Geräteinstallation, Ausführungsrechte, Zeitfenster, Laufzeit, Ausgabegrenze und Versuch. Eine spätere Bibliotheksänderung ändert den Plan nicht. |
| Einreichen und genehmigen | Die Einreichung erzeugt einen Antrag mit Status `pending_approval`. Erst die interaktive WebUI-Genehmigung erzeugt ausführbare Jobs. Im Verlauf stehen Entscheidung, Person und Zeitpunkt. Ein abgelehnter Antrag erzeugt keine Ausführung. |
| Ausführen | Der Client holt den Auftrag ab. Er prüft die signierte, versuchsgebundene Starterlaubnis und führt das Skript im vorgesehenen Konto aus. Vor Ort ist keine Benutzerbestätigung nötig. Doppelte Zustellung darf den Versuch nur einmal starten. |
| Ergebnis lesen | Der Server speichert Zustand, Exitcode und verfügbare Standard- und Fehlerausgabe pro Ziel und Versuch. Die WebUI zeigt Skriptinhalt und Ergebnis im Auftrag. MCP liefert über die Auftrags-ID den Gesamtstand und über die Job-ID das einzelne Ergebnis. |
Linux führt Shellskripte unter dem Dienstkonto oder über den eingerichteten Helper als root aus. Windows führt PowerShell unter LocalService oder über den Helper als SYSTEM aus. Neustart und Installation von Windows-Updates sind Skriptaufträge. Bei einem Neustart kann das Skript bereits vor dem Herunterfahren erfolgreich enden. Der Betriebsnachweis verbindet den neuen Bootbezug mit dem nächsten authentisierten Kontakt und einem Folgeauftrag. [Skriptbibliothek](crates/server/src/script_library.rs) · [Auftragsverarbeitung](crates/server/src/jobs.rs)
Ein Abbruchwunsch wird am Auftrag gespeichert. Bei unterbrochener Rückmeldung gleichen Server, Agent und gegebenenfalls Helper den gespeicherten Versuch ab. Bei `unknown` bleibt die Wirkung ungeklärt. Die WebUI kann einen solchen Fall dokumentiert abschließen. Dieser Abschluss erteilt keine Freigabe für einen weiteren Versuch.
## Öffentliche Verwaltung und Berechtigungen
Die WebUI verwendet HTTPS mit lokalem Passwort und TOTP. MCP verwendet HTTPS mit individuell ausgestellten, befristeten und widerrufbaren Bearer-Tokens. Ein Token gilt für ausgewählte Kunden oder ausdrücklich für alle aktuellen und künftigen Kunden. Der Server prüft die Aktion im Zielkunden und kontrolliert die Rechte der Beteiligten erneut vor Ausführung.
MCP unterstützt Kunden- und Geräteabfragen, Skriptbibliothek, Planung, Einreichung, Auftrags- und Ergebnisabfrage, Abbruchanforderung sowie gespeicherte Status-, Log- und Releaseabfragen. Kundenpflege, Tokenverwaltung und persönliche Entscheidungen erfolgen in der WebUI. Die vom Server angebotenen MCP-Werkzeuge und deren Parameter sind im Toolkatalog definiert. [MCP-Werkzeuge](crates/server/src/mcp.rs) · [Bedienung und Rechte](docs/public-access.md)
Für administrative Skripte gilt zusätzlich das Plattformrecht `root:execute` oder `system:execute`. Bei einem installierten signierten Helper kann der Betreiber die vorhandene zentrale Geräteregel mit `mcp:scoped` für berechtigte Token öffnen. Der Server prüft Kunde, aktuelle Tokenrechte, Installation, Helper und gegebenenfalls die in der Regel festgelegten Skriptbeschränkungen. Eine Tokenrotation erfordert keine Anpassung auf dem Gerät. [Geräteregel](crates/server/src/managed_scripts.rs)
## Geräteaufnahme und Agentupdates
Die WebUI erzeugt einen kundengebundenen Einmalcode und zeigt die HTTPS-Installationsanleitung für die verfügbare Plattform. Zum Erstbezug braucht das Gerät eine vertrauenswürdige TLS-Verbindung. Der Installer prüft Vertrauensmaterial und Release, richtet die lokalen Dienste ein und nimmt das Gerät auf. Anschließend verwendet die Installation ihre eigene Identität. Der lokale Administrator richtet den privilegierten Skript-Helper ein, wenn das Gerät auch Administratoraufträge erhalten soll. [Serverseitiger Bootstrap](crates/server/src/bootstrap)
Der Server stellt je Kunde und Plattform Agent und Helper mit einem gemeinsam signierten Manifest bereit. Das Manifest bindet die Hashes und Größen der Binärdateien. Für die Erstaufnahme liefert der Server auch den passenden Bootstrap-Updater. Linux x64 verwendet den GNU/Linux-Kanal, Windows x64 offiziell `x86_64-pc-windows-gnu`. Der lokale Updater fragt regelmäßig nach einer neueren veröffentlichten Generation, prüft die Bindung an Plattform, Schlüsselring, Releasefolge und Binärhashes und aktiviert das geprüfte Paar unter derselben Geräteidentität. Auf Linux steuert ein systemd-Timer den Abruf, auf Windows ein eigener Updatedienst.
Für Erstinstallation und Update muss das Manifest zum Prüfzeitpunkt gültig sein. Beim bereits installierten Administrator-Helper prüft der Server die Gültigkeit zum gespeicherten Registrierungszeitpunkt des Releases und die Signatur gegen den aktuellen Schlüsselring. Der Ablauf des Manifests allein blockiert daher keinen Adminauftrag auf diesem Client. [Releaseprüfung](crates/server/src/agent_updates.rs) · [Build und Veröffentlichung](docs/development.md)