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

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

Antwort bei einem Auftrag:

```json
{
  "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.