Add WMI and SQL permission diagnostics

Dokumentation.md

@@ -91,15 +91,16 @@ biztalk_checkmk_pulse.cmd
   v
 BizTalkCheckmkPulse.exe
   |
-  | liest lokal
+  | liest lokal und prueft im gleichen Sicherheitskontext
   +-- WMI root\MicrosoftBizTalkServer
   +-- Windows Application Event Log
+  +-- SQL-Verbindung zu BizTalkMgmtDb/BizTalkMsgBoxDb
   |
   v
 Checkmk Local Check Zeilen nach STDOUT
 ```
 
-Der `.cmd`-Wrapper liefert auch dann eine gueltige `UNKNOWN`-Zeile, wenn die EXE fehlt. Die EXE selbst faengt Laufzeitfehler ab und schreibt fuer alle stabilen Services `UNKNOWN`, damit unvollstaendige Deployments oder WMI-Probleme in Checkmk sichtbar bleiben.
+Der `.cmd`-Wrapper liefert auch dann eine gueltige `UNKNOWN`-Zeile mit Massnahme, wenn die EXE fehlt oder bereits der Prozessstart mit einem Exitcode fehlschlaegt. Die EXE selbst faengt Laufzeitfehler ab und schreibt fuer alle stabilen Services `UNKNOWN`, damit unvollstaendige Deployments oder WMI-Probleme in Checkmk sichtbar bleiben.
 
 ## Datenquellen
 
@@ -136,6 +137,14 @@ Der Check liest standardmaessig das lokale Application Log fuer die letzten 60 M
 
 Die Liste ist ueber `EventLogSources` konfigurierbar.
 
+### SQL-Zugriffsprobe
+
+Nach erfolgreicher oder teilweise erfolgreicher Plattformabfrage uebernimmt der SQL-Probe die per WMI ermittelten Management- und MessageBox-Ziele. Fuer jedes eindeutige Ziel wird mit `System.Data.SqlClient` eine Verbindung mit integrierter Windows-Authentifizierung geoeffnet und `SELECT 1` ausgefuehrt. Die Verbindung wird unmittelbar danach geschlossen; es werden keine BizTalk-Tabellen gelesen oder veraendert.
+
+Der Test laeuft unter derselben Identitaet wie der Checkmk Local Check. Damit wird sichtbar, ob `LocalSystem` beziehungsweise das Maschinenkonto des BizTalk-Servers das SQL-Ziel tatsaechlich erreichen und die Datenbank oeffnen kann. Die Probe ist mit `ProbeSqlConnectivity=false` deaktivierbar und verwendet `SqlConnectionTimeoutSeconds` mit dem Default 5 Sekunden je Ziel als Timeout.
+
+Im produktiven Betrieb sollte der komplette Local Check asynchron mit 300 Sekunden Cache ausgefuehrt werden. So fuehren fehlende SQL-Rechte nicht bei jedem Checkmk-Abruf zu weiteren fehlgeschlagenen Login-Ereignissen. Der Trade-off ist eine Zustandsverzoegerung von maximal fuenf Minuten.
+
 ## Berechtigungsmodell
 
 ### LocalSystem und lokaler WMI-Zugriff
@@ -182,6 +191,23 @@ Die Operator-Rolle ist fuer grundlegendes Monitoring und Zustandsabfragen vorges
 | 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. |
 
+### Automatische Diagnose im Programm
+
+WMI-Verbindungsaufbau und jede erforderliche WMI-Klasse werden separat bewertet. Erwartbare Exceptions werden in folgende Kategorien eingeordnet:
+
+| Diagnose | Bedeutung | Ausgegebene Massnahme |
+| --- | --- | --- |
+| `Wmi/Permission` | Namespace oder BizTalk-WMI-Klasse verweigert den Zugriff. | Namespace-ACL bei Verbindungsfehlern beziehungsweise BizTalk-Operator-Gruppe bei Klassenfehlern pruefen. |
+| `Wmi/Connectivity` | WMI-/RPC-Ziel nicht erreichbar. | WMI-Dienst, Provider und bei Remote-WMI zusaetzlich DNS/RPC/Firewall pruefen. |
+| `Wmi/Timeout` | WMI-Abfrage ueberschreitet `QueryTimeoutSeconds`. | WMI-, BizTalk- und SQL-Auslastung untersuchen, bevor der Timeout erhoeht wird. |
+| `Wmi/Configuration` | Namespace oder Klasse fehlt. | BizTalk-WMI-Provider und BizTalk-Installation pruefen beziehungsweise reparieren. |
+| `Sql/Permission` | Login oder Datenbankzugriff wird abgelehnt. | Maschinenkonto der BizTalk-Operator-Gruppe zuordnen, Kerberos erneuern, keine direkten DB-Rollen vergeben. |
+| `Sql/Connectivity` | SQL-Server oder Instanz nicht erreichbar. | Servername, DNS, SQL-Dienst, TCP-Protokoll, Port und Firewall pruefen. |
+| `Sql/Timeout` | SQL-Verbindung oder Testabfrage laeuft in den Timeout. | Netzwerk und SQL-Auslastung pruefen; Timeout nur begruendet anheben. |
+| `Sql/Configuration` | WMI-Ziele unvollstaendig oder TLS-, Zertifikats-, SPN-/SSPI-Konfiguration fehlerhaft. | Plattformabfragen beziehungsweise Zertifikatskette, Verschluesselung, SPN und Kerberos gezielt pruefen. |
+
+Jede Diagnose enthaelt Bereich/Kategorie, betroffene Komponente, eine kurze Ursache, `Massnahme:` und `Technik:` mit Exception-Typ, HRESULT oder SQL-Fehlernummer. Erforderliche Datenquellen besitzen eigene Verfuegbarkeitsflags. Schlaegt beispielsweise `MSBTS_ServiceInstance` fehl, wird `BizTalk Suspended Instances` zwingend `UNKNOWN`; eine leere Ergebnisliste darf nicht als 'keine Suspensions' fehlinterpretiert werden.
+
 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:
@@ -198,6 +224,10 @@ Quellen:
 Das Plugin ist bewusst defensiv gebaut:
 
 - WMI-Queries haben ein konfigurierbares Timeout.
+- WMI-Namespace und Pflichtklassen werden getrennt auf Berechtigung, Konfiguration, Erreichbarkeit und Timeout geprueft.
+- Management- und MessageBox-Datenbank werden mit der echten Agent-Identitaet getestet.
+- SQL-Fehlernummern werden in Berechtigung, Erreichbarkeit, Timeout oder Providerfehler klassifiziert.
+- Fehlgeschlagene Pflichtabfragen erzeugen `UNKNOWN` statt irrefuehrender Nullwerte.
 - Optionale WMI-Klassen erzeugen Diagnosehinweise statt Totalabbruch.
 - Fehlende Properties werden als leer/unknown behandelt.
 - Local-Check-Ausgaben verwenden gueltige Checkmk-Zeilen mit genau vier Feldern.
@@ -214,6 +244,14 @@ Das Plugin ist bewusst defensiv gebaut:
 
 Dieser Service ist der Integrationsindikator. Wenn er `UNKNOWN` ist, sind Berechtigungen, BizTalk-Installation oder WMI-Repository zu pruefen.
 
+### BizTalk SQL Access
+
+- `OK`: Datenbankziele vollstaendig ermittelt und integrierte Anmeldung an allen Zielen erfolgreich.
+- `UNKNOWN`: Zielermittlung unvollstaendig, Anmeldung verweigert, SQL nicht erreichbar, Timeout oder Providerfehler.
+- Bei `ProbeSqlConnectivity=false`: `OK` mit sichtbarem Hinweis, dass die Probe deaktiviert ist.
+
+Metriken: `biztalk_sql_targets_total`, `biztalk_sql_targets_available` und `biztalk_sql_targets_failed`. Die Ausgabe nennt ausserdem `execution_identity`, `network_identity` und den Zustand jedes getesteten Datenbankziels.
+
 ### BizTalk Suspended Instances
 
 - `OK`: keine suspendierten Instanzen.
@@ -233,6 +271,7 @@ Dieser Service ist der Integrationsindikator. Wenn er `UNKNOWN` ist, sind Berech
 - `OK`: Artefakte lesbar, keine unbekannten Statuswerte.
 - `WARN`: nur wenn `AlertOnArtifactRuntimeIssues=true` und deaktivierte/inaktive Artefakte vorhanden sind.
 - `CRIT`: unbekannte Send-Port- oder Orchestration-Statuswerte.
+- `UNKNOWN`: mindestens eine erforderliche WMI-Artefaktklasse nicht lesbar.
 
 Deaktivierte Receive Locations und gestoppte Ports koennen in BizTalk fachlich korrekt sein. Deshalb ist die Alarmierung hier standardmaessig informativ.
 
@@ -247,19 +286,20 @@ Deaktivierte Receive Locations und gestoppte Ports koennen in BizTalk fachlich k
 
 Pro Umgebung sollte der BizTalk-Host in einem eigenen Host-Ordner oder Host-Tag fuer `ACC`, `DEV`, `TST`, `PRD` liegen. Im Dashboard eignen sich:
 
-- Service State Widgets fuer die fuenf BizTalk-Services
-- Graphen fuer `biztalk_suspended_total`, `biztalk_host_instances_stopped`, `biztalk_eventlog_errors`
+- Service State Widgets fuer die sechs stabilen BizTalk-Services
+- Graphen fuer `biztalk_sql_targets_failed`, `biztalk_suspended_total`, `biztalk_host_instances_stopped`, `biztalk_eventlog_errors`
 - Hostgruppe/Ordner pro Umgebung
 - Optional eine View gefiltert auf `Service starts with BizTalk`
 
 Empfohlene Reihenfolge im Dashboard:
 
 1. `BizTalk Platform`
-2. `BizTalk Suspended Instances`
-3. `BizTalk Host Instances`
-4. `BizTalk Event Log`
-5. `BizTalk Runtime Artifacts`
-6. SQL-Server-Services aus dem Checkmk-MSSQL-Plugin
+2. `BizTalk SQL Access`
+3. `BizTalk Suspended Instances`
+4. `BizTalk Host Instances`
+5. `BizTalk Event Log`
+6. `BizTalk Runtime Artifacts`
+7. SQL-Server-Services aus dem Checkmk-MSSQL-Plugin
 
 ## Rollout-Vorgehen
 
@@ -295,6 +335,15 @@ Der Checkmk Windows Agent laeuft normalerweise als LocalSystem. Daher immer auch
 "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump
 ```
 
+Die Diagnose im Service-Text nach `Massnahme:` abarbeiten. Wichtige Kategorien:
+
+- `Wmi/Permission`: lokale Namespace-ACL oder BizTalk-Operator-Zuordnung pruefen.
+- `Sql/Permission`: Maschinenkonto `DOMAIN\BIZTALKSERVER$` und BizTalk-Operator-Gruppe pruefen.
+- `Sql/Connectivity`: SQL-Server-/Instanzname, DNS, SQL-Dienst, TCP und Firewall pruefen.
+- `Sql/Timeout`: SQL- und Netzwerkauslastung pruefen; Timeout nicht als erste Massnahme erhoehen.
+
+Der direkte Aufruf des Wrappers kann wegen des angemeldeten Administratorkontos ein anderes Ergebnis liefern als der Agent-Dump. Fuer die Freigabe ist immer der Agent-Dump massgeblich.
+
 ### Keine Services in Discovery
 
 Pruefen: