Document the accepted MVP and retire superseded development plans
Rust development slice / linux (push) Failing after 14s

This commit is contained in:
2026-11-18 17:21:12 +01:00
parent f37b6dc4f7
commit 6963ad332c
188 changed files with 370 additions and 34933 deletions
+43 -70
View File
@@ -1,90 +1,63 @@
# Öffentlicher Zugang ohne OAuth
# WebUI und MCP bedienen
Die WebUI ist unter https://discovery.ease-technologies.de:8443/ erreichbar. Der MCP-Endpunkt lautet https://discovery.ease-technologies.de:8443/mcp. Beide verwenden die öffentliche TLS-Zertifikatskette des bestehenden HTTPS-Ingresses. Der Gerätekanal auf Port 443 verwendet weiterhin seine eigene Geräte-PKI.
Die öffentliche WebUI verwendet ein lokales Benutzerkonto mit Passwort und einem sechsstelligen TOTP-Code. Ein MCP-Client verbindet sich per HTTPS mit seinem eigenen Bearer-Token. Die Anmeldung und die Genehmigung eines konkreten Auftrags sind getrennte Schritte. [WebUI](https://discovery.ease-technologies.de:8443/) · [MCP-Endpunkt](https://discovery.ease-technologies.de:8443/mcp)
## Neustart und Administratorausführung
## Geräte und Kunden
Unter **Aufträge → Neuer Auftrag** das Gerät wählen und **Neustartskript auswählen** verwenden. Bei gemischten Plattformen pro Betriebssystem einen Auftrag anlegen. Die Vorschau zeigt den vollständigen Inhalt und den Ausführungskontext. Nach der Entscheidung unter **Genehmigungen** steht die Ausgabe im Auftrag. „Neustart in einer Minute eingeplant“ bestätigt die Annahme durch das Betriebssystem. Der Wiederanlauf ist nach einem neuen Bootbezug, frischem Agentkontakt und erfolgreichem Folgeauftrag belegt.
**Geräte** zeigt bestätigte Online- und Offline-Geräte der berechtigten Kunden mit Hostname, Betriebssystem, Status, freiem und gesamtem Speicherplatz, RAM, CPU und Kunde. Die Historie enthält unter anderem archivierte und widerrufene Installationen. Ein Klick auf den Hostnamen öffnet das Inventar und die letzten Aufträge. Der Kundenname in der Kopfzeile zeigt, in welchem Kunden die nächste Änderung erfolgt.
Die letzte Meldung im Gerätedetail zeigt, ob der Client Skripte mit dem Dienstkonto und mit Administratorrechten unterstützt. Die tatsächliche Freigabe für einen Nutzer hängt zusätzlich von Kunde, Gerät und den zentralen Ausführungsrechten ab.
Berechtigte Benutzer können Kunden anlegen und umbenennen. Zur Aufnahme den Zielkunden wählen und unter **Verwaltung → Geräteaufnahme** einen Einmalcode erzeugen. Der Code gilt für diesen Kunden und verfällt bei erfolgreicher Aufnahme oder nach 15 Minuten. Die WebUI zeigt für die veröffentlichten Plattformen Download und Installationsbefehl. Auf dem neuen Gerät das HTTPS-Skript mit Administratorrechten aufrufen und den Code am Prompt eingeben. Für lokale Administrator-Skripte die dafür angebotene Installationsoption wählen. Der Windows-Kanal ist `x86_64-pc-windows-gnu`. [Linux-Installer](https://discovery.ease-technologies.de:8443/install/linux.sh) · [Windows-Installer](https://discovery.ease-technologies.de:8443/install/windows.ps1)
## WebUI
### Alte Gerätekopplung endgültig löschen
Die Anmeldung benötigt den lokalen Benutzernamen, das Passwort und einen sechsstelligen TOTP-Code aus einer Authenticator-App. TOTP verwendet SHA-1, 30 Sekunden und sechs Stellen. Für die Ersteinrichtung liegt auf dem Entwicklungs-PC die private Datei `credentials/public-webui-login.json` mit Benutzername, Passwort, Base32-Schlüssel und `otpauth_uri`. Die Datei hat Modus 0600 und ist gitignoriert. Sie dient der Übernahme des Passworts in den Passwortmanager und der Einrichtung der Authenticator-App.
Archivieren und Zurückholen steuern die Sichtbarkeit. Ein Widerruf sperrt die registrierte Identität. Für einen Kundenwechsel das Gerät im Zielkunden neu aufnehmen. Die bisherige Historie gehört zur Installation im ursprünglichen Kunden.
Der Server speichert den Passwortprüfwert als Scrypt mit zufälligem Salt und 128 MiB Arbeitsspeicher. Bereits benutzte TOTP-Zeitschritte werden atomar in PostgreSQL gesperrt. Passwortprüfungen sind parallel begrenzt. Anmeldung und Sitzung nutzen HTTPS, Loginbegrenzung, `Secure`-/`HttpOnly`-/`SameSite=Strict`-Cookies sowie Origin- und CSRF-Prüfungen für Änderungen. Eine Sitzung gilt eine Stunde. Das öffentliche Produktionsprofil bietet den lokalen Login. Die simulierte Entwicklungsanmeldung ist nur am internen API-Dienst verfügbar.
Das Verwalten und Löschen einer Kopplung erfordert `devices:revoke` im betreffenden Kunden. Das Gerät öffnen und unter **Gerät verwalten** widerrufen. Die widerrufene Installation steht unter **Geräte → Historie**. Dort **Kopplung löschen** wählen, Hostname, Kunde und Kopplungs-ID vergleichen und **Endgültig löschen** bestätigen. Noch gültige offene Genehmigungsanträge und nicht abgeschlossene Jobs dieser Installation sperren das Löschen. Das gilt auch für Jobs mit ungeklärter Wirkung (`unknown`). Gelöscht werden diese Installation, ihr Inventar und ihre eigenen Auftragsergebnisse. Gemeinsame signierte Mehrgerätepläne und Auditdaten bleiben nachvollziehbar.
Die Kontokonfiguration liegt auf dem Server unter `/opt/rust-discovery/devstate/public-auth/users.json`, Besitzer 10001, Modus 0600, im Container schreibgeschützt. Änderung von Passwort, TOTP oder `disabled` erfordert den Neustart von öffentlicher API und Gateway. Ein Membership-Widerruf wirkt auch auf bestehende Sitzungen beim nächsten Zugriff. Der vorhandene SSH-Zugang ermöglicht die administrative Wiederherstellung eines verlorenen Authenticator-Zugangs.
## Skript bis zum Ergebnis
1. Unter **Skripte** Shell- oder PowerShell-Code mit einem Namen veröffentlichen. Eine Änderung ergibt eine neue Version. Name und Plattform lassen sich filtern.
2. Unter **Aufträge → Neuer Auftrag** Geräte eines Kunden auswählen. Die Geräteauswahl lässt sich auch aus dem Bestand übernehmen. Eine feste Bibliotheksversion oder **Einmaliges Skript** wählen. Ausführungskonto, Startfrist, Laufzeit und Ausgabelimit prüfen.
3. In der Zusammenfassung **Zur Genehmigung einreichen** wählen. Unter **Genehmigungen** prüft eine berechtigte Person die gebundenen Geräte, Skriptbytes, Rechte und Fristen und entscheidet ausdrücklich. Die Ansicht zeigt offene Anträge und frühere Entscheidungen samt Person und Zeitpunkt.
4. Unter **Aufträge** nach Anlass, Gerät, Status oder Datum filtern. Im Auftrag stehen der gebundene **Skriptinhalt** und je Ausführung Status, Exitcode und Ausgabe. Bei mehreren Geräten führt **Ergebnis anzeigen** zur betreffenden Ausführung. Vom Gerätedetail führt **Ergebnis öffnen** zum selben Job.
Ein Neustart verwendet die passende Bibliotheksversion mit Administratorrechten. Der Exitcode des Skripts belegt die Annahme des Neustartbefehls durch das Betriebssystem. Einen tatsächlich erfolgten Neustart anhand des geänderten Bootbezugs, eines frischen authentisierten Kontakts derselben Installation und eines erfolgreichen Folgeauftrags prüfen.
Unter **Verwaltung → Erweitert** können Berechtigte Paketrezepte, Windows-MSI-Rezepte und öffentliche Artefakte für den gewählten Kunden pflegen. Ein Import mit `catalog:write` hinterlegt die Katalogdaten. Neue Geräteaufträge werden unter **Aufträge** als Skript eingereicht.
## MCP-Tokens
Unter **Verwaltung → MCP-Tokens** Namen, Kundenkreis, Rechte und Ablaufdatum festlegen. Ein Token kann auf ausgewählte Kunden oder ausdrücklich auf alle aktuellen und künftigen Kunden berechtigt werden. Den einmal angezeigten Tokenwert im privaten Zugangsspeicher des MCP-Clients als HTTP-Header hinterlegen.
```http
Authorization: Bearer <MCP-Token>
```
Wirksam sind die erteilten Scopes innerhalb der aktuellen Kundenrechte. Der Widerruf greift bei der nächsten Prüfung auch in einer bestehenden MCP-Sitzung. Die Tokenverwaltung erfordert eine persönliche WebUI-Sitzung mit `tokens:manage`. Folgende Werkzeuge veröffentlicht der Server. [Werkzeugdefinitionen](../crates/server/src/mcp.rs)
| Werkzeug | Funktion und Rechte im Zielkunden |
| --- | --- |
| `tenants.list` | Kunden auflisten, in denen der Token wirksames `inventory:read` besitzt. |
| `inventory.list_devices`, `inventory.get_device`, `monitoring.get_health` | Bestand, Gerätedetail und gespeicherte Statusmeldungen mit `inventory:read`. Die Bestandsliste unterstützt `view=history`. |
| `scripts.list`, `updates.list_releases` | Skriptversionen samt Inhalt bzw. veröffentlichte Agent-Releases mit `operations:read` lesen. |
| `scripts.publish` | Mit `operations:plan` und `scripts:execute` eine unveränderliche Version veröffentlichen. Für einen neuen Namen `expected_version` auf `0` setzen, für eine weitere Version die bisherige Versionsnummer übergeben. |
| `scripts.plan`, `operations.plan` | Eine Bibliotheksrevision bzw. ein einmaliges Skript mit `operations:plan` und `scripts:execute` an konkrete Geräte binden. Für Administratoren gilt zusätzlich das Plattformrecht. |
| `operations.submit` | Den Plan über `plan_id` und einen stabilen `idempotency_key` einreichen. Erfordert `operations:submit`, `operations:read` und die Ausführungsrechte. Der Zustand lautet zunächst `pending_approval`. |
| `jobs.get` | Mit `operations:read` über `operation_id` den Antrag und seine Jobs abfragen. Eine anschließende Abfrage mit genau einer `job_id` liefert das einzelne Ergebnis. |
| `jobs.cancel` | Mit `jobs:cancel` und Begründung einen Abbruch anfordern. Mit `operations:read` die Antwort und den tatsächlichen Endzustand lesen. |
| `logs.query` | Bereits gespeicherte Protokolle mit `logs:read` abfragen. Sensible Protokolle benötigen zusätzlich `logs:read_sensitive`. |
### Administrator-Skripte anfordern
Für einen vollständigen Skriptauftrag braucht ein Token im Zielkunden `operations:plan`, `operations:submit`, `operations:read` und `scripts:execute`. Hinzu kommt für Administratoraufträge je Plattform `root:execute` oder `system:execute`. Zum Veröffentlichen einer Skriptversion benötigt das Token `operations:plan` und `scripts:execute`.
Ein Administratorauftrag braucht auf Linux `root:execute`, auf Windows `system:execute`, zusätzlich zu den Skript- und Auftragsrechten. Für ein einmaliges Administrator-Skript das Profil `full_maintenance_v1` angeben. Bei Auswahl aus der Bibliothek setzt der Server das Profil passend zur gewählten Identität. Für Windows kann die PowerShell-Variante `powershell_51_remote_signed` an den Prozess binden. Die vollständigen MCP-Eingaben liefert `tools/list`.
Auf einem Gerät mit installiertem, signiertem Administrator-Helper kann der Betreiber die vorhandene Geräteregel einmal für diese Tokenrechte öffnen. Der folgende Befehl zeigt den Zustand für genau die gewählte Regel. Die Werte in Großbuchstaben sind durch die Kennungen der Installation und der bestehenden Regel zu ersetzen.
Der installierte signierte Helper muss auf die Geräteidentität gebunden sein. Die zentrale Richtlinie liegt auf dem Server in `/opt/rust-discovery/devstate/managed-scripts/policy.json`. API und Gateway lesen sie über `RMM_MANAGED_SCRIPT_POLICY_FILE`. Für verifizierte Agent-/Helper-Paarwechsel kann `release_anchors` die ursprüngliche Release-ID, Geräteinstallation, Binärhashes und die kanonischen lokalen Richtlinienbytes binden. Der Server vergleicht die daraus für das signierte Folgepaket berechneten Prüfdaten mit den Geräteangaben. [Mounts](../deploy/server.managed-scripts.compose.yaml) · [Serverprüfung](../crates/server/src/managed_scripts.rs)
Der folgende Operator prüft eine vorhandene Geräteregel. Platzhalter durch die tatsächlichen Kennungen der Installation und ihrer bestehenden Regel ersetzen.
```sh
python3 tools/dev_mcp_script_scope.py check --platform linux \
--tenant TENANT_ID --asset ASSET_ID --agent AGENT_ID --evidence ACCEPTANCE_EVIDENCE_ID
```
Mit `enable` wird der Eintrag `mcp:scoped` dieser Regel hinzugefügt, mit `disable` wieder entfernt. Für Windows lautet die Plattform `windows`. Der Server wertet die Regel bei der nächsten Rechteprüfung aus. Bereits separat an einzelne Tokens vergebene Rechte lassen sich durch Widerruf des Tokens entziehen. Ein freies Skript über `operations.plan` oder eine Bibliotheksversion über `scripts.plan` planen und über `operations.submit` einreichen. Die persönliche Entscheidung erfolgt in der WebUI. `jobs.get` liefert über die Auftragskennung den Stand und über die Jobkennung das Ausführungsergebnis.
### Token ausstellen
Nach der WebUI-Anmeldung unter **Verwaltung → MCP-Tokens** einen Namen, den Kundenkreis, die benötigten Rechte und ein Ablaufdatum wählen. Ein einzelner Kunde ist vorausgewählt. Weitere Kunden lassen sich einzeln ergänzen. „Alle aktuellen und zukünftigen Kunden“ ist eine eigene Option für Kundenadministratoren. Standard sind gespeichertes Inventar, Protokolle und Aufträge/Ergebnisse lesen. Der Tokenwert wird einmal angezeigt. Er kann anschließend im MCP-Client als HTTP-Header hinterlegt werden.
```http
Authorization: Bearer <MCP-Token>
```
Ein Token besteht aus einem Präfix und 32 zufälligen Bytes. Der Server speichert ausschließlich dessen SHA-256-Prüfwert. Jedes Token besitzt einen eigenen Principal, einen Ausgabekunden, einen Kundenkreis, feste Scopes, Ablauf und Widerruf. Jede Anfrage wird erneut geprüft. Die wirksamen Rechte sind die Schnittmenge aus Scopes und aktiver Membership. Der Widerruf greift auch bei einer bereits geöffneten MCP-Sitzung. Tokens können mit entsprechenden Rechten Anträge planen und einreichen. Die Jobgenehmigung erfolgt durch die Person in der WebUI. Tokenverwaltung verlangt eine echte interaktive Sitzung mit `tokens:manage` und CSRF-Schutz.
Der verwendete MCP-Client muss einen manuell konfigurierbaren Bearer-Header unterstützen. Die standardisierte automatische MCP-HTTP-Autorisierung beschreibt einen OAuth-Ablauf. Die hier eingerichtete statische Tokenanmeldung verwendet den vorhandenen HTTP-Transport mit selbst verwalteten Zugangsdaten. [MCP-Autorisierung](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
## Geräte und Kunden bedienen
**Geräte → Bestand** zeigt die bestätigten Online- und Offline-Geräte. Über **Historie** sind frühere Installationen erreichbar. Der Hostname öffnet das Inventar mit Laufwerken, Erhebungszeit und den letzten Aufträgen. In der Detailansicht erlaubt **Gerät verwalten** das Archivieren und Zurückholen. Archivieren steuert die Sichtbarkeit, ein Widerruf sperrt die Identität.
**Kunden** erlaubt berechtigten Personen das Anlegen und Umbenennen. Bei **Gerät aufnehmen** zuerst den Kunden im Kopfbereich wählen und anschließend den Einmalcode ausstellen. Für einen Kundenwechsel die bisherige Identität widerrufen und das Gerät beim Zielkunden neu aufnehmen. Frühere Ergebnisse bleiben beim ursprünglichen Kunden.
Der Entwicklungsoperator kann dem bereits eingerichteten lokalen Betreiberkonto über `python3 tools/dev_public_access.py grant-customer-admin` die Kundenadministration zuweisen. Ein signierter Release lässt sich mit `python3 tools/dev_customer_starters.py --tenant UUID --platform PLATTFORM --release RELEASE_UUID` als Installationspaket für leere Kundenkataloge bereitstellen. Das Werkzeug prüft die Objektprüfsummen. Bei der ersten Codeausgabe übernimmt der Server das Paket in den Katalog des Zielkunden. Bereits befüllte Kataloge pflegt der Betreiber je Kunde über den regulären Releaseweg.
## Skriptauftrag bearbeiten
1. Unter **Skripte → Neues Skript** ein Skript veröffentlichen. Spätere Änderungen als neue Version speichern.
2. Unter **Aufträge → Neuer Auftrag** die Geräte eines Kunden wählen. Eine Auswahl aus dem Gerätebestand lässt sich mit **Auftrag erstellen** übernehmen. Bibliotheksskript samt Version auswählen oder **Einmaliges Skript** eingeben.
3. Die Zusammenfassung prüfen und **Zur Genehmigung einreichen** wählen. Nach einer unterbrochenen Einreichung im selben Browsertab den Auftragsdialog erneut öffnen. Er liest den gespeicherten Plan und, falls bereits vorhanden, den zugehörigen Antrag.
4. Unter **Genehmigungen → Offen** den Antrag öffnen, Skript, Zielgeräte, Rechte und Zeitfenster prüfen und genehmigen oder ablehnen. Der Verlauf zeigt die entschiedenen und abgelaufenen Anträge.
5. Unter **Aufträge** den Eintrag öffnen. Der Bereich **Skriptinhalt** zeigt den beim Einreichen gespeicherten Code samt Version oder Kennzeichnung als einmaliges Skript. Bei einem einzelnen Gerät erscheint die Ausgabe sofort. Bei mehreren Geräten öffnet **Ergebnis anzeigen** die Ausgabe direkt beim gewählten Gerät.
Die Standarddiagnosen stehen unter **Skripte** mit getrennten Versionen für Linux und Windows bereit. Die Windows-Updatesuche verwendet `SYSTEM` und benötigt die lokale und zentrale Freigabe für dieses Administratorskript. Auf Linux hängt die Logabfrage von den Journalrechten des Agent-Dienstkontos ab.
Unter **Aufträge** können Name oder Anlass, Hostname oder Geräte-ID, Status und Erstellungsdatum kombiniert werden. Das Enddatum zählt in der Ortszeit des Browsers vollständig mit. Unter **Geräte → Letzte Aufträge** öffnet **Ergebnis öffnen** die zu diesem Gerät gehörende Ausführung. Im Genehmigungsverlauf stehen Person und Zeitpunkt bei der belegten Entscheidung.
## Entwicklung und Deployment
Der öffentliche API-Dienst `public-api` läuft unprivilegiert auf `127.0.0.1:18445`, im Produktionsprofil mit lokalem Passwort/TOTP und ohne Entwicklungszugänge. Der private Entwicklungsdienst bleibt auf `127.0.0.1:18443`. PostgreSQL hat keinen veröffentlichten Port. Der Reverseproxy verifiziert das TLS-Zertifikat des jeweiligen internen Dienstes. Öffentliche Anmeldung und MCP gehen an `public-api`, die vorhandenen Bootstrapdownloads an das Gerätegateway.
Die erstmalig ausgeführten Befehle sind wiederverwendbar.
```sh
python3 tools/dev_public_access.py prepare
python3 tools/dev_public_access.py activate
python3 tools/dev_public_access.py publish
```
`prepare` erzeugt das private Bootstrapkonto und seine echte Human-Membership. `activate` startet die zusätzliche API intern und prüft die angebotenen Anmeldemodi. `publish` validiert die Nginx-Konfiguration und stellt den TLS-Ingress um. Bei einem Aktivierungsfehler wird die vorherige Ingresskonfiguration wiederhergestellt. Wiederholtes `prepare` verwendet die vorhandene private Kontokonfiguration. Abweichende bestehende Daten verlangen einen bewussten administrativen Abgleich.
Weitere Serverupdates verwenden `tools/build.py server-arm64 --ssh --ref REVISION` und `tools/dev_deploy_server.py --ref REVISION`. Der Deploymentrunner übernimmt die aktive Compose-Dateikette des öffentlichen Dienstes und aktiviert auch `public-api`. Reine WebUI-Änderungen verwenden `--web-only`.
## Abnahme am 17. November 2026
76 WebUI-Tests, drei Browser-Bedientests der Tokenverwaltung sowie fünf Backendtests gegen isoliertes PostgreSQL bestanden. Alle 27 Migrationen wurden mit einem eingeschränkten Migrationsbenutzer geprüft. Die öffentliche HTTPS-Abnahme bestätigte 25 Fälle einschließlich Passwort/TOTP, Replay, CSRF, Tenantgrenze, beschränktem Lesetoken und Widerruf in derselben MCP-Sitzung. Alle während der Abnahme erstellten Testtokens sind widerrufen; die Abschlusskontrolle fand null aktive Tokens. [Öffentlicher Nachweis](evidence/public-access-20261117.json)
Die verwendeten Schutzmaßnahmen orientieren sich an den OWASP-Hinweisen zu Anmeldung, Passwortspeicherung und Sitzungen. [Authentifizierung](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) · [Passwortspeicherung](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) · [Sitzungen](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)
### Alte Gerätekopplung endgültig löschen
Unter **Geräte → Historie** die betreffende Installation öffnen. Unter **Gerät verwalten** zuerst die Identität widerrufen und anschließend **Kopplung löschen** wählen. Die Bestätigung nennt Hostname, Kunde und Kopplungs-ID. Offene Genehmigungen oder laufende beziehungsweise ungeklärte Aufträge sperren das Löschen. Nach der Bestätigung entfallen die Geräteidentität, ihr Inventar und ihre eigenen Auftragsergebnisse. Eine weitere Installation desselben Geräts und deren Historie bleiben erhalten. Gemeinsame signierte Mehrgerätepläne und der Auditnachweis bleiben nachvollziehbar.
Mit `enable` lässt der Betreiber für diese Regel entsprechend berechtigte Tokens über den Selektor `mcp:scoped` zu. `disable` entfernt diesen Eintrag. Für Windows lautet die Plattform `windows`. Bereits einzeln vergebene Principal-Berechtigungen und vorhandene Skriptbeschränkungen gelten weiterhin. Der Server prüft die Rechte bei Planung, Freigabe und Start. Ein persönlicher Freigabeklick erfolgt unter **Genehmigungen**. Für einen direkten Freigabelink wird die `plan_id` verwendet, für den Ergebnislink die `operation_id`. [Geräteregel](../tools/dev_mcp_script_scope.py) · [Abnahme auf beiden Plattformen](mvp-completion-plan.md)