biztalk-sap-environment-inventory/Dokumentation.md

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.

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

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:

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:

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:

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:

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:

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:

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

run-inventory.cmd ACC C:\BizTalk-Doku\ACC

PROD:

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

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