Netbox-Client-Agent-for-Windows/README.md

NetBox Windows Client Agent

Ein schlanker Windows-Agent, der Hardwaredaten per WMI erfasst und einen NetBox-Device-Datensatz sowie das zugehörige Asset im Plugin ArnesSI/netbox-inventory anlegt oder aktualisiert. Das Release ist eine einzelne, selbstenthaltende agent.exe; auf dem Zielsystem muss kein .NET installiert sein.

Was synchronisiert wird

• Rechnername, Hersteller, Modell, BIOS-Seriennummer und Geräte-UUID
• Windows-Version und Architektur, CPU, RAM, Datenträger, MAC- und IP-Adressen
• NetBox Site und Location aus der Konfiguration
• dcim.Device sowie das verknüpfte netbox_inventory.Asset
• Hersteller und Device Type werden bei Bedarf angelegt
• Wiederholbare Updates anhand der BIOS-Seriennummer statt doppelter Datensätze

Der Agent löscht keine NetBox-Objekte. Site, Location und Device Role müssen bereits existieren. Die Region dient zur eindeutigen Auswahl der Site.

Voraussetzungen in NetBox

1. Das Plugin netbox-inventory ist installiert.
2. Eine Device Role mit dem konfigurierten Slug (Standard: windows-client) existiert.
3. Site/Location existieren, falls sie in config.json gesetzt sind.
4. Der API-Token darf Devices, Manufacturers, Device Types und Inventory Assets lesen, anlegen und ändern.

Optionale Custom Fields müssen für dcim.Device existieren. Die linke Seite in custom_fields ist der Agent-Schlüssel, die rechte Seite der NetBox-Custom-Field-Name. Nicht benötigte Einträge können entfernt werden.

Konfiguration

config.example.json als config.json neben die EXE kopieren. Die URL enthält nur die NetBox-Basis-URL, nicht /api.

{
  "netbox_url": "https://netbox.example.com",
  "api_token": "0123456789abcdef",
  "region": "emea",
  "site": "berlin",
  "location": "office-1",
  "device_role": "windows-client",
  "verify_tls": true,
  "timeout_seconds": 30,
  "tags": [],
  "custom_fields": {}
}

site und location sind optional. verify_tls: false ist nur für kurzfristige Tests mit selbstsignierten Zertifikaten gedacht. config.json ist wegen des Tokens in .gitignore enthalten.

Ausführen und bauen

.\agent.exe --dry-run
.\agent.exe
.\agent.exe --config C:\ProgramData\NetBoxAgent\config.json

Der Dry-Run liest NetBox und prüft die Zuordnungen, schreibt aber nichts. Zum lokalen Build wird das .NET 8 SDK benötigt:

.\scripts\build.ps1 -Runtime win-x64

Das Ergebnis liegt in dist\win-x64\agent.exe. GitHub Actions erzeugt zusätzlich ARM64-Artefakte.

Manuelle Installation und Intune

Für eine manuelle Installation agent.exe, config.json, install.ps1 und uninstall.ps1 in dasselbe Paketverzeichnis legen und PowerShell als Administrator starten:

.\install.ps1 -SourceDirectory $PWD

Die Installation kopiert die Dateien nach %ProgramFiles%\NetBox Windows Agent, schränkt die ACL auf Administratoren/SYSTEM ein, erstellt die tägliche geplante Aufgabe NetBox Windows Agent und führt die erste Synchronisation aus.

Für Intune die vier Dateien mit dem Microsoft Win32 Content Prep Tool als .intunewin paketieren:

• Installationsbefehl: powershell.exe -ExecutionPolicy Bypass -File .\install.ps1 -SourceDirectory .
• Deinstallationsbefehl: powershell.exe -ExecutionPolicy Bypass -File .\uninstall.ps1
• Installationskontext: System
• Erkennungsregel: Datei %ProgramFiles%\NetBox Windows Agent\agent.exe vorhanden
• Rückgabecode 0 bedeutet erfolgreiche erste Synchronisation

Sicherheit und Betrieb

• Einen eigenen NetBox-Token mit minimal nötigen Rechten verwenden.
• verify_tls in Produktion immer aktiviert lassen.
• Für größere Umgebungen den Token künftig besser über Windows Credential Manager oder ein Intune-verwaltetes Maschinenzertifikat bereitstellen.
• Logs können in Intune über die Ausgabe der geplanten Aufgabe ergänzt werden; eine Event-Log-Integration ist ein sinnvoller nächster Ausbau.

Vorgeschlagene Commits

feat: add Windows hardware inventory collector and NetBox sync
feat: add self-contained Windows build and Intune deployment scripts
docs: document configuration, permissions, and deployment
ci: build x64 and arm64 agent artifacts