Assetmanager/SOFTWARE-CLIENT-ARCHITECTURE.md

Vorschlag: Client-Kommunikation und spätere Softwareverteilung

Zielbild

Ein kleiner Windows-Client („AssetManager Agent“) läuft auf jedem verwalteten Rechner. Das Netlogon-/GPO-Startskript installiert oder aktualisiert nur diesen Agenten. Die eigentlichen Inventur- und Softwareaufträge werden anschließend über eine abgesicherte HTTPS-API gesteuert.

Warum nicht jeden Befehl direkt im Netlogon-Skript ausführen?

Ein Startskript ist gut für Bootstrap und Reparatur, aber ungeeignet für eine dauerhafte Auftragssteuerung:

• Benutzer- und Computerstart verzögern sich.
• Rückmeldungen und Wiederholungen sind schwer nachzuvollziehen.
• Ein Netzlaufwerk oder DC kann beim Start noch nicht erreichbar sein.
• Softwareinstallationen benötigen Status, Timeout, Exitcode und Neustartlogik.
• Passwörter oder globale API-Schlüssel dürfen nicht im Skript stehen.

Empfohlene Komponenten

1. Bootstrap per GPO/Netlogon

Das bestehende Startskript:

1. legt C:\ProgramData\AssetManager\agent an,
2. lädt eine signierte Agent-Version von einer internen HTTPS-Adresse,
3. installiert einen Windows-Dienst,
4. schreibt nur Server-URL und eine einmalige Registrierungskennung,
5. startet den Dienst.

2. Geräteidentität

Beim ersten Start registriert sich der Agent mit:

• Computername,
• AD-Domäne,
• BIOS-Seriennummer,
• Windows MachineGuid,
• optional MeshCentral Node-ID.

Der Server erstellt danach ein gerätespezifisches Token. Dieses Token wird lokal mit Windows-DPAPI geschützt. Kein gemeinsamer API-Schlüssel für alle Clients.

3. Agent-Polling

Der Client fragt beispielsweise alle 5 Minuten per HTTPS ab:

GET /api/agent/v1/jobs/next

Antwort bei keinem Auftrag:

{"job": null, "next_poll_seconds": 300}

Antwort bei einem Auftrag:

{
  "job": {
    "id": 4711,
    "type": "software_inventory",
    "expires_at": "2026-07-22T23:00:00Z",
    "payload": {}
  }
}

Der Client bestätigt zuerst die Übernahme und meldet später Ergebnis, Exitcode, Logauszug und Zeitstempel zurück.

4. Softwareinventur

Erste Funktion des Agenten:

• installierte MSI-Programme aus 32- und 64-Bit-Registry auslesen,
• optional AppX-Pakete,
• Name, Version, Hersteller, Installationsdatum und UninstallString erfassen,
• Ergebnis komprimiert an AssetManager senden,
• serverseitig pro Asset versioniert speichern.

Nicht Win32_Product verwenden, da diese WMI-Klasse MSI-Reparaturen auslösen und sehr langsam sein kann.

5. Softwarekatalog für spätere Verteilung

Serverseitige Tabellen:

• software_packages
• software_package_versions
• software_jobs
• software_job_results
• agent_devices
• agent_tokens
• agent_inventory_runs

Ein Softwarepaket enthält:

• Name und Version,
• Installationsquelle,
• SHA-256-Hash,
• Installationsbefehl,
• Deinstallationsbefehl,
• Erkennungsregel,
• erlaubte Exitcodes,
• Neustartverhalten,
• Timeout,
• Zielarchitektur.

6. Installationsquelle

Pakete können zunächst weiter auf dem DC liegen, zum Beispiel:

\\fileserver\software\packages\ExampleApp\1.0\

Der Auftrag enthält aber nicht beliebigen PowerShell-Code, sondern verweist auf eine freigegebene Paketdefinition. Der Agent prüft:

1. Paket ist serverseitig freigegeben,
2. Quelle liegt in einem erlaubten UNC-Basispfad,
3. Datei-Hash stimmt,
4. Installationsbefehl entspricht der Paketdefinition.

Langfristig ist ein interner HTTPS-Paketdownload robuster als UNC, weil er ohne Maschinenzugriff auf die Freigabe funktioniert und leichter protokolliert werden kann.

7. Sicherheitsregeln

• ausschließlich HTTPS mit intern vertrauenswürdigem Zertifikat,
• pro Gerät eigenes widerrufbares Token,
• Jobs serverseitig signieren oder über authentisierte TLS-Verbindung liefern,
• keine freie Shell-/PowerShell-Eingabe über die Weboberfläche,
• Befehle nur aus fest definierten Jobtypen,
• Paketdateien mit SHA-256 prüfen,
• vollständiges Auditlog,
• Rollen/Berechtigungen für Freigabe und Ausführung,
• maximale Joblaufzeit und Wiederholungsgrenze,
• Agent nur als SYSTEM, wenn der konkrete Job dies benötigt.

Sinnvolle Ausbaustufen

Phase 1 – Inventur

• Agent registrieren
• Heartbeat und letzter Kontakt
• Betriebssystem- und Softwareinventur
• Anzeige im Assetdetail
• manueller Inventurauftrag

Phase 2 – Auftragsmodell

• generische Jobwarteschlange
• Status: pending, claimed, running, success, failed, expired
• Exitcodes, Logs, Timeout und Wiederholung
• Live-Anzeige im AssetManager

Phase 3 – Softwarekatalog

• Paketdefinitionen
• Erkennungsregeln
• Installation und Deinstallation
• Einzelgerät und Gerätegruppe
• Wartungsfenster

Phase 4 – Rollout-Sicherheit

• Pilotgruppen
• Genehmigungsworkflow
• gestaffelte Verteilung
• Abbruch bei Fehlerquote
• Neustartkoordination

Empfehlung für den nächsten Entwicklungsschritt

Zuerst nur Phase 1 umsetzen. Der Agent sollte noch keine beliebigen Befehle ausführen. Wenn Registrierung, Heartbeat und Softwareinventur stabil laufen, kann dieselbe gesicherte Kommunikation für die Jobwarteschlange und später die Softwareverteilung verwendet werden.