Initial commit: BizTalk SAP environment inventory

2026-07-27 14:21:50 +02:00
commit 439427cc17
26 changed files with 5281 additions and 0 deletions
@@ -0,0 +1,407 @@
+# Technische Dokumentation: BEW BizTalk SAP Environment Inventory
+
+## 1. Zielbild und Topologie
+
+Das Tool erzeugt je Umgebung einen belastbaren Ist-Bericht der SAP-Adapterkonfiguration und der vollständigen BizTalk-Anwendungsliste.
+
+```text
+ACC
+  +-- 1 BizTalk Server 2020  <-- Tool lokal ausführen
+  +-- 1 SQL Server           <-- BizTalk-Datenbanken
+
+PROD
+  +-- 1 BizTalk Server 2020  <-- Tool lokal ausführen
+  +-- 1 SQL Server           <-- BizTalk-Datenbanken
+```
+
+Es gibt in ACC und PROD jeweils keinen zweiten BizTalk-Knoten, der verglichen werden müsste. Die Berichte sind getrennt zu erzeugen und anschließend gegenüberzustellen.
+
+Aufgabenbezug:
+
+- SAP-Adapter-Verbindungsparameter dokumentieren
+- vollständige BizTalk-Anwendungsliste statt einer unvollständigen bisherigen App-Liste erzeugen
+- tatsächliche Zuordnung der SAP-Verbindungen zu BizTalk-Anwendungen herstellen
+- ERP-/ISU-Receive- und Send-Hosts dokumentieren
+- SNC-Konfiguration, Bibliotheken und Zertifikats-/PSE-Metadaten erfassen
+- IDoc-Basistypen/Erweiterungen sowie WE20/WE21 als Nachweise adressieren
+- DR-Abhängigkeit zur SAP-seitigen Umschaltung nach Frankfurt sichtbar machen
+
+## 2. Architektur
+
+```text
+Administrative cmd.exe
+  |
+  +-- run-inventory.cmd ACC|PROD
+        |
+        +-- BizTalkSapEnvironmentInventory.exe
+              |
+              +-- SystemCollector
+              |     +-- Windows WMI
+              |     +-- BizTalk Registry
+              |     +-- Management SQL/DB
+              |
+              +-- BizTalkWmiCollector
+              |     +-- root\MicrosoftBizTalkServer
+              |     +-- Anwendungen und Artefakte
+              |     +-- Adapter, Hosts und Handler
+              |     +-- SAP-Endpunkt-Fallback
+              |
+              +-- BindingExportCollector
+              |     +-- BTSTask ExportBindings /GroupLevel
+              |     +-- WCF-SAP und WCF-Custom/sapBinding
+              |     +-- SAP-URI und CustomProps
+              |     +-- Secret-Redaktion
+              |
+              +-- SapRuntimeCollector
+              |     +-- Adapter Pack/NCo-Installationen
+              |     +-- Runtime-Dateiversion und Architektur
+              |     +-- SNC/PSE/Zertifikatsmetadaten
+              |
+              +-- DocxReportWriter
+                    +-- Office Open XML
+                    +-- atomare Ausgabe
+```
+
+Das Programm referenziert keine `Microsoft.BizTalk.*`-Assembly. Dadurch besteht das Deployment nur aus EXE, Konfiguration, Startskript und Dokumentation. Die BizTalk-Integration erfolgt über die offiziell vorhandenen Verwaltungsoberflächen WMI und `BTSTask.exe`.
+
+## 3. Datenquellen
+
+### 3.1 System und Registry
+
+Windows-Daten stammen aus `root\cimv2`. BizTalk-Installations- und Managementinformationen werden in beiden Registry-Ansichten unter folgenden Schlüsseln gesucht:
+
+```text
+HKLM\SOFTWARE\Microsoft\BizTalk Server\3.0
+HKLM\SOFTWARE\Microsoft\BizTalk Server\3.0\Administration
+```
+
+Ermittelt werden unter anderem:
+
+- Produktname, Version und Edition
+- Installationspfad
+- BizTalk Management SQL Server
+- BizTalk Management Database
+- Betriebssystem, Build und Prozessarchitektur
+
+Kommandozeilenparameter überschreiben automatisch ermittelte Management-DB-Werte.
+
+### 3.2 BizTalk-WMI
+
+Primärer Namespace:
+
+```text
+root\MicrosoftBizTalkServer
+```
+
+Pflichtquelle:
+
+- `MSBTS_Application`
+- `MSBTS_GroupSetting` wird zusätzlich zur sicheren Erkennung von Management SQL Server und Datenbank verwendet
+
+Optionale beziehungsweise versionsabhängige Artefaktklassen:
+
+- `MSBTS_Orchestration`
+- `MSBTS_SendPort`
+- `MSBTS_SendPortGroup`
+- `MSBTS_ReceivePort`
+- `MSBTS_ReceiveLocation`
+- `MSBTS_Assembly`
+- `MSBTS_Schema`
+- `MSBTS_Map`
+- `MSBTS_Pipeline`
+- `MSBTS_AdapterSetting`
+- `MSBTS_ReceiveHandler`
+- `MSBTS_SendHandler2` bzw. `MSBTS_SendHandler`
+- `MSBTS_HostSetting`
+- `MSBTS_HostInstance`
+
+Eine fehlende optionale Klasse erzeugt einen Hinweis, verhindert aber nicht die Anwendungsliste oder den Word-Bericht.
+
+Zum Schutz vor ungewöhnlich großen Artefaktmengen begrenzt `MaxArtifactDetailsPerType`
+die aufgenommenen Detaildatensätze pro WMI-Klasse auf standardmäßig 5000. Die
+Anwendungsliste selbst wird nicht begrenzt.
+
+### 3.3 BTSTask-Gruppenbinding
+
+Das Tool verwendet:
+
+```cmd
+BTSTask.exe ExportBindings ^
+  /GroupLevel ^
+  /Destination:"<temporäre Datei>" ^
+  /Server:"<Management SQL Server>" ^
+  /Database:"<Management Database>"
+```
+
+`/GroupLevel` ist entscheidend: Ohne diesen Parameter würde `BTSTask` nur die Default-Anwendung exportieren und die geforderte vollständige Port-/App-Zuordnung wäre nicht gewährleistet.
+
+Die temporäre XML-Datei wird:
+
+1. in einem eindeutigen Temp-Pfad erzeugt,
+2. mit deaktivierter DTD-/External-Entity-Auflösung gelesen,
+3. ausschließlich in sichere Berichtsmodelle überführt,
+4. im `finally`-Block gelöscht.
+
+Microsoft dokumentiert, dass Kennwörter beim Binding-Export entfernt werden. Zusätzlich redigiert das Tool sensitive Element-, Attribut- und URI-Werte.
+
+### 3.4 Offline-Binding
+
+Für Diagnose- oder Berechtigungsfälle kann ein vorhandener Export verarbeitet werden:
+
+```cmd
+BizTalkSapEnvironmentInventory.exe ^
+  --environment ACC ^
+  --binding-file C:\Temp\ACC-GroupBindings.xml
+```
+
+Die Datei wird nicht verändert.
+
+## 4. SAP-Endpunkterkennung
+
+Ein Endpunkt wird als SAP-relevant erkannt, wenn mindestens eines zutrifft:
+
+- Adaptername enthält `SAP`
+- Adresse beginnt mit `sap://`
+- Binding Type enthält `sapBinding`
+- Custom Properties enthalten `Microsoft.Adapters.SAP`
+
+Dadurch werden sowohl dedizierte `WCF-SAP`-Ports als auch `WCF-Custom`-Ports mit SAP Custom Binding erkannt.
+
+## 5. SAP-Verbindungsparameter
+
+### 5.1 SAP-URI
+
+Beispiel:
+
+```text
+sap://Client=100;lang=DE@A/sap.example.local/00
+  ?GwHost=gateway.example.local
+  &GwServ=sapgw00
+  &ListenerProgramId=BIZTALK_ACC
+```
+
+Ausgewertete Parameter:
+
+| Gruppe | Parameter |
+| --- | --- |
+| Login | `Client`, `Language` |
+| Application Server | Host, System Number |
+| Message Server | Host, R/3 System Name, Gruppe |
+| Destination | Destination Name |
+| Gateway | `GwHost`, `GwServ` |
+| RFC Listener | `ListenerDest`, `ListenerGwHost`, `ListenerGwServ`, `ListenerProgramId` |
+| Routing | `SAPROUTER` |
+| Security | `UseSnc` |
+
+### 5.2 Binding Properties
+
+`TransportTypeData` und `ReceiveLocationTransportTypeData` enthalten bei WCF-Adaptern verschachtelte `CustomProps` und teilweise nochmals XML-kodierte Bindingkonfiguration. Der Parser verarbeitet diese Ebenen begrenzt rekursiv und erfasst unter anderem:
+
+- `BindingType`
+- `UseSnc`
+- `SncLibrary`
+- `SncPartnerName`
+- `SncMyName`
+- `SncQop`
+- `AffiliateApplicationName`
+- `UserName`
+- `Action` und `ActionMapping`
+
+Große Werte werden im Bericht begrenzt. Sensitive Werte werden vor Aufnahme in das Modell redigiert.
+
+### 5.3 Anwendungszuordnung
+
+Die Zuordnung erfolgt in dieser Reihenfolge:
+
+1. `ApplicationName` im Gruppenbinding
+2. gleichnamiger Send Port oder Receive Port aus WMI
+3. keine Schätzung; stattdessen Finding
+
+Damit wird sichtbar, welche der vollständigen BizTalk-Anwendungen tatsächlich SAP-Ports verwendet.
+
+## 6. SAP NCo und Prozessarchitektur
+
+Gesucht werden:
+
+- installierter Microsoft BizTalk Adapter Pack/WCF LOB Adapter SDK
+- SAP .NET Connector
+- `sapnco.dll`
+- `sapnco_utils.dll`
+- SAP Cryptographic Library
+- `sapgenpse.exe`
+
+Für gefundene PE-Dateien werden Dateiversion, Produktversion, Änderungszeit und PE-Architektur dokumentiert. Dies unterstützt die Prüfung, ob der jeweilige 32-/64-Bit-BizTalk-Host zur installierten SAP-Laufzeit passt.
+
+Die Erfassung durchsucht nur klar begrenzte Installations- und Konfigurationspfade bis zu einer Maximalebene. Es findet keine unbeschränkte Volltextsuche über alle Laufwerke statt.
+
+## 7. SNC und Credential-Sicherheit
+
+Der Security-Modus wird aus den Bindingparametern klassifiziert:
+
+1. `UseSnc=true` → SAP SNC
+2. SSO Affiliate Application vorhanden → Enterprise SSO
+3. Benutzername vorhanden → SAP-Benutzer
+4. sonst nicht eindeutig ableitbar
+
+Dokumentiert werden dürfen:
+
+- SAP-Benutzername oder SSO-Referenz
+- SNC-Partner-/My-Name
+- SNC-Bibliothek und QOP
+- PSE-/Zertifikatspfad
+- Fingerprint und Gültigkeit
+- Vorhandensein eines privaten Schlüssels bei X.509-Zertifikaten
+
+Nicht dokumentiert werden:
+
+- Kennwörter
+- PSE-Inhalte
+- private Schlüssel
+- Tokens
+- entschlüsselbare Connection Strings
+
+Rotation und Owner sind keine technischen Bindingeigenschaften. Sie bleiben als manueller Security-Nachweis offen.
+
+## 8. IDoc, WE20 und WE21
+
+### 8.1 Automatisch belegbare Indikatoren
+
+Das Tool sucht nach SAP-/IDoc-Indikatoren in:
+
+- Schema- und Assemblynamen
+- Target Namespaces und Root Names
+- WCF Actions
+- SAP-Adapteroperationen
+
+Dies kann IDoc-Basistypen wie beispielsweise `ORDERS05` sichtbar machen, ist aber kein Ersatz für eine SAP-seitige Bestandsaufnahme.
+
+### 8.2 SAP-seitige Pflichtnachweise
+
+Von SAP Basis beziehungsweise dem Fachteam beizustellen:
+
+| Bereich | Benötigte Daten |
+| --- | --- |
+| WE20 | Partner, Nachrichtentyp, Basistyp, Erweiterung, Empfängerport, Verarbeitungsoptionen |
+| WE21 | Portname, RFC-Destination, IDoc-Version, WE20-Zuordnung |
+| RFC Destination | Typ, Zielsystem, Gateway, Program ID, Verbindungstest |
+| IDoc | vollständige Liste der Basistypen und kundeneigenen Erweiterungen |
+
+Das Tool markiert diese Punkte in jedem DOCX als offen, selbst wenn einzelne Namen aus dem BizTalk-Binding abgeleitet werden konnten.
+
+## 9. Disaster Recovery
+
+Der lokale BizTalk-Bericht zeigt die aktuell konfigurierten RFC-/Gateway-/Listenerwerte. Er kann nicht entscheiden, ob und wie die RFC-Destination im SAP-System auf Frankfurt umgeschaltet wird.
+
+Das DR-Runbook muss mindestens enthalten:
+
+1. Owner und Freigabe für die Umschaltung
+2. betroffene RFC-Destinationen
+3. Zielwerte in Frankfurt
+4. SNC-PSE/Bibliothek und Identität am DR-Ziel
+5. Reihenfolge BizTalk/SAP
+6. Verbindungstest
+7. Rückschaltung
+8. Dokumentation des letzten Tests
+
+## 10. Resilienz
+
+- Collector-Isolation mit eigenem Status und Zeitmessung
+- WMI-Timeout
+- Prozess-Timeout für `BTSTask`
+- WMI-Fallback für SAP-Endpunkte
+- Offline-Bindingmodus
+- optionale WMI-Klassen stoppen den Lauf nicht
+- begrenzte Dateisystemsuche
+- Fehlerisolation bei Registry, Zertifikaten und Dateimetadaten
+- XML-Parser ohne DTD/External Entities
+- atomare DOCX-Ausgabe
+- eindeutige Dateinamen mit Umgebung, Server und Zeitstempel
+- Exitcode `1` bei unvollständigem Pflichtabschnitt
+
+## 11. DOCX-Erzeugung ohne Office
+
+Der Report Writer erzeugt ein standardkonformes Office-Open-XML-Paket mit:
+
+```text
+[Content_Types].xml
+_rels/.rels
+docProps/core.xml
+docProps/app.xml
+word/document.xml
+word/styles.xml
+word/_rels/document.xml.rels
+```
+
+Alle Texte werden über `XmlWriter` geschrieben. Dadurch werden Host-, Anwendungs- und Portnamen als Text behandelt und können kein XML-Markup einschleusen.
+
+## 12. Lauf auf ACC und PROD
+
+Auf jedem der beiden BizTalk Server:
+
+1. Deployment in einen lokalen Ordner kopieren.
+2. Administrative `cmd.exe` öffnen.
+3. `BizTalkSapEnvironmentInventory.exe --self-test` ausführen.
+4. Erfassung starten.
+5. Exitcode prüfen.
+6. DOCX und Log gemeinsam kontrollieren.
+7. Anwendungsliste gegen BizTalk Administration abgleichen.
+8. SAP-Endpunkte und Hostzuordnung prüfen.
+9. WE20-/WE21-/Credential-/DR-Findings an SAP Basis geben.
+
+ACC:
+
+```cmd
+run-inventory.cmd ACC C:\BizTalk-Doku\ACC
+```
+
+PROD:
+
+```cmd
+run-inventory.cmd PROD C:\BizTalk-Doku\PROD
+```
+
+## 13. Build und Tests
+
+Buildbaseline:
+
+- klassisches MSBuild-Projekt
+- .NET Framework 4.7.2
+- C# 7.3
+- Visual Studio 2019/MSBuild 16.x
+- keine SDK-style-Projekte
+- keine NuGet-Pakete
+
+```cmd
+scripts\build-release.cmd
+scripts\package-release.cmd
+```
+
+Tests prüfen:
+
+- Secret-Redaktion in XML und SAP-URI
+- Parsing eines WCF-SAP-Gruppenbindings
+- SAP-Client, Host und `UseSnc`
+- Anwendungszuordnung
+- DOCX-Paketstruktur
+- XML-Gültigkeit aller DOCX-Parts
+- Ausschluss von Testkennwörtern
+
+## 14. Bekannte Grenzen
+
+- kein SAP-Login
+- kein aktiver RFC-Ping
+- keine direkte Abfrage von WE20, WE21 oder SM59
+- keine Auflösung von Credential-Owner oder Rotation
+- keine Garantie, dass Schemanamen alle verwendeten IDoc-Erweiterungen enthalten
+- dynamisch zur Laufzeit konstruierte SAP-Adressen können im statischen Binding fehlen
+- WMI-Klassen unterscheiden sich teilweise je BizTalk-Version/CU
+- lokaler Ist-Stand; ACC und PROD müssen getrennt ausgeführt werden
+
+## 15. Referenzen
+
+- Microsoft: BizTalk Server 2020 Hardware and Software Requirements
+- Microsoft: `BTSTask ExportBindings`
+- Microsoft: BizTalk WMI Technical Reference
+- Microsoft: WCF-SAP Port Configuration
+- Microsoft: SAP System Connection URI
+- Microsoft: Security between the SAP system and the adapter