Document BizTalk monitoring permissions

Dokumentation.md

@@ -136,6 +136,63 @@ Der Check liest standardmaessig das lokale Application Log fuer die letzten 60 M
 
 Die Liste ist ueber `EventLogSources` konfigurierbar.
 
+## Berechtigungsmodell
+
+### LocalSystem und lokaler WMI-Zugriff
+
+Der Checkmk Windows Agent und der Agent Controller laufen standardmaessig als `LocalSystem` (`NT AUTHORITY\SYSTEM`). Der Wrapper und die EXE erben diesen Kontext. Das Plugin verbindet sich lokal mit `\\<eigener-server>\root\MicrosoftBizTalkServer`, setzt keine eigenen Anmeldedaten, nutzt kein Remote-WMI und fuehrt keine veraendernden WMI-Methoden aus. Das lokale Windows Application Event Log wird ebenfalls nur gelesen.
+
+Die lokalen Rechte von `LocalSystem` reichen fuer diese Zugriffe normalerweise aus. Im regulaeren lokalen Betrieb werden deshalb keine zusaetzlichen DCOM-, Firewall- oder pauschalen WMI-Namespace-Freigaben benoetigt.
+
+### Netzwerkidentitaet zum SQL Server
+
+BizTalk-WMI-Klassen koennen ihre Daten aus der BizTalk Management- oder MessageBox-Datenbank beziehen. Liegt SQL Server auf einer anderen Maschine, authentifiziert sich `LocalSystem` dort mit dem Active-Directory-Computerkonto des BizTalk-Servers:
+
+```text
+DOMAIN\BIZTALKSERVER$
+```
+
+Dieses Konto besitzt nicht automatisch BizTalk- oder SQL-Berechtigungen. Daraus kann die Situation entstehen, dass die Verbindung zum lokalen WMI-Namespace erfolgreich ist, einzelne SQL-gestuetzte WMI-Klassen aber `Access denied`, `UnauthorizedAccessException` oder `UNKNOWN` liefern.
+
+### Pruefung und Freigabe
+
+Der direkte Programmstart in einer administrativen Shell laeuft unter dem angemeldeten Benutzer und ist deshalb kein ausreichender Berechtigungstest. Verbindlich ist die Ausfuehrung durch den Checkmk Agent Controller als `LocalSystem`:
+
+```powershell
+& "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump |
+    Select-String -Pattern "BizTalk|Access denied|Unauthorized|UNKNOWN" -Context 0,1
+```
+
+Bei Zugriffsfehlern gilt folgendes Least-Privilege-Vorgehen:
+
+1. Computerkonto des BizTalk-Servers ermitteln, normalerweise `DOMAIN\BIZTALKSERVER$`.
+2. Die bei der BizTalk-Konfiguration verwendete Operator-Gruppe feststellen.
+3. Das Computerkonto in `BizTalk Server Operators` beziehungsweise die kundenspezifisch benannte Operator-Gruppe aufnehmen.
+4. Kerberos-Tickets des Systemkontos erneuern oder den Server im Wartungsfenster neu starten.
+5. Den Agent-Dump wiederholen.
+6. Nur fuer weiterhin abgelehnte, konkret identifizierte WMI-Klassen mit BizTalk- und SQL-Administration pruefen, ob Administratorrechte erforderlich sind.
+
+Die Operator-Rolle ist fuer grundlegendes Monitoring und Zustandsabfragen vorgesehen. Direkte manuelle Aenderungen an den Rollen der BizTalk-SQL-Datenbanken sind zu vermeiden; die durch BizTalk konfigurierte Windows-Gruppe ist die vorgesehene Berechtigungsgrenze.
+
+| Agent-Dump-Ergebnis | Massnahme |
+| --- | --- |
+| Plausible Werte fuer alle BizTalk-Services | Keine Berechtigungsaenderung. |
+| WMI-Namespace nicht erreichbar | BizTalk-WMI-Provider, WMI-Dienst, Namespace und ACL gezielt pruefen. |
+| Nur SQL-gestuetzte Klassen scheitern | Computerkonto in die BizTalk-Operator-Gruppe aufnehmen. |
+| Nur Event-Log-Service ist `UNKNOWN` | Lokalen Application-Log-Zugriff pruefen. |
+| Fehler bleibt mit Operator-Rolle bestehen | Betroffene Klasse und konkrete BizTalk-/SQL-Rollenanforderung untersuchen. |
+
+Die Operator-Mitgliedschaft des Computerkontos steht allen auf diesem Server als `LocalSystem` laufenden Diensten fuer Netzwerkzugriffe zur Verfuegung. Falls diese Sicherheitsauswirkung nicht akzeptabel ist, kann ein separater Collector unter einem dedizierten gMSA- oder Dienstkonto mit Operator-Rechten Checkmk-Spooldaten erzeugen. Diese Variante ist noch nicht Bestandteil der aktuellen Implementierung. Der komplette Checkmk-Agent sollte nicht allein fuer dieses Plugin auf eine andere Identitaet umgestellt werden, weil dies alle Agent-Sektionen und Local Checks betrifft.
+
+Quellen:
+
+- https://docs.checkmk.com/latest/en/agent_windows.html
+- https://docs.checkmk.com/latest/en/localchecks.html
+- https://learn.microsoft.com/en-us/biztalk/core/minimum-security-user-rights
+- https://learn.microsoft.com/en-us/biztalk/core/access-control-and-data-security
+- https://learn.microsoft.com/en-us/entra/architecture/service-accounts-computer
+- https://learn.microsoft.com/en-us/windows/win32/wmisdk/access-to-wmi-namespaces
+
 ## Resilienz
 
 Das Plugin ist bewusst defensiv gebaut:
@@ -262,4 +319,3 @@ Sinnvolle naechste Ausbaustufen:
 - Optionales serverseitiges Check-Plugin nach Checkmk Check API V2.
 - Custom Dashboard/View als Checkmk GUI Extension.
 - Ergaenzung um MessageBox-Spool/Tracking-Daten, falls operativ benoetigt.
-