Initial commit: BizTalk IIS inventory with DOCX reporting
Build und Test / build (push) Has been cancelled
Build und Test / build (push) Has been cancelled
This commit is contained in:
@@ -0,0 +1,273 @@
|
||||
# Technische Dokumentation
|
||||
|
||||
## 1. Ziel und Abgrenzung
|
||||
|
||||
Das Tool dokumentiert den für den Frankfurt-Aufbau relevanten IIS-/BizTalk-Bestand auf den BEW-Systemen `ACC` und `PROD`. Es ersetzt eine fehleranfällige manuelle Aufnahme und benötigt trotz eingeschränkter PowerShell-Umgebung keine PowerShell-Ausführung.
|
||||
|
||||
Die Anwendung ist:
|
||||
|
||||
- lokal und read-only
|
||||
- auf .NET Framework 4.7.2 ausgelegt
|
||||
- ohne BizTalk-ExplorerOM-/OperationsOM-Buildabhängigkeit
|
||||
- ohne `Microsoft.Web.Administration`-Deploymentabhängigkeit
|
||||
- fehlertolerant je Datenquelle
|
||||
- für Gitea-Build und Artefaktbereitstellung strukturiert
|
||||
|
||||
Die Anwendung ist **kein Backup-Werkzeug**. Sie dokumentiert, was für einen kontrollierten Transfer vorhanden sein muss. Webinhalte, Zertifikate, private Schlüssel und IIS-Konfigurationsschlüssel müssen über freigegebene Backup-/Exportprozesse übertragen werden.
|
||||
|
||||
## 2. Architektur
|
||||
|
||||
```text
|
||||
Administrative cmd.exe auf ACC oder PROD
|
||||
|
|
||||
+-- run-inventory.cmd
|
||||
|
|
||||
+-- BizTalkIisEnvironmentInventory.exe
|
||||
|
|
||||
+-- SystemCollector
|
||||
| +-- Win32_OperatingSystem
|
||||
| +-- Win32_ServerFeature
|
||||
| +-- Registry (.NET Framework)
|
||||
|
|
||||
+-- IisCollector
|
||||
| +-- applicationHost.config (XML, read-only)
|
||||
| +-- Webverzeichnisse und Dateimetadaten
|
||||
| +-- NTFS-ACL der Web-Stämme
|
||||
|
|
||||
+-- CertificateCollector
|
||||
| +-- LocalMachine\My
|
||||
| +-- CAPI/CNG-Metadaten und Key-Datei-ACL
|
||||
|
|
||||
+-- SecurityCollector
|
||||
| +-- Win32_Service
|
||||
| +-- secedit.exe /export
|
||||
|
|
||||
+-- BizTalkCollector
|
||||
| +-- Registry/Uninstall
|
||||
| +-- Dateiversionen
|
||||
| +-- root\MicrosoftBizTalkServer
|
||||
|
|
||||
+-- DocxReportWriter
|
||||
+-- Office Open XML (DOCX/ZIP)
|
||||
+-- atomarer Dateiwechsel
|
||||
```
|
||||
|
||||
Alle Collector-Abschnitte laufen nacheinander, weil sie lokale I/O- und WMI-Ressourcen verwenden und teilweise voneinander abhängen. Zertifikate werden beispielsweise gegen die vorher gelesenen IIS-Bindings markiert. Eine Exception beendet nur den betroffenen Abschnitt. Die übrigen Collectoren laufen weiter.
|
||||
|
||||
## 3. Datenquellen
|
||||
|
||||
### 3.1 Windows und Rollen
|
||||
|
||||
`Win32_ServerFeature` liefert installierte Rollen/Features. Der Report beschränkt die Ausgabe auf IIS-, Web-, HTTP-, WAS-, ASP.NET-, .NET-, MSMQ- und COM+-relevante Einträge. Betriebssystemdaten stammen aus `Win32_OperatingSystem`.
|
||||
|
||||
Auf Client-Windows oder Systemen ohne `Win32_ServerFeature` wird der Abschnitt als teilweise markiert. Das ist kein falscher leerer Bestand.
|
||||
|
||||
### 3.2 IIS
|
||||
|
||||
Standardpfad:
|
||||
|
||||
```text
|
||||
%WINDIR%\System32\inetsrv\config\applicationHost.config
|
||||
```
|
||||
|
||||
Die XML-Datei wird mit `FileShare.ReadWrite | FileShare.Delete` geöffnet, damit eine laufende IIS-Verwaltung die Aufnahme nicht unnötig blockiert. Es werden erfasst:
|
||||
|
||||
- Section-Deklarationen und globale Belegung
|
||||
- Protected-Configuration-Provider
|
||||
- Application Pools und ProcessModel-Identitäten
|
||||
- Sites, Bindings, SSL-Thumbprints
|
||||
- Anwendungen und virtuelle Verzeichnisse
|
||||
- physische Pfade
|
||||
|
||||
Der SHA-256-Wert im Report gehört zu einer **bereinigten logischen Konfiguration**. Vor dem Hashing werden sensible Attribute und verschlüsselte XML-Nutzdaten ersetzt. Er dient dem Vergleich ACC/PROD oder Vorher/Nachher, nicht als Hash der Originaldatei.
|
||||
|
||||
### 3.3 Webinhalte
|
||||
|
||||
Jeder physische Web-Stamm wird iterativ begangen. Dadurch entsteht keine tiefe Methodenrekursion. Schutzgrenzen:
|
||||
|
||||
| Einstellung | Default | Wirkung |
|
||||
| --- | ---: | --- |
|
||||
| `MaxFilesPerApplication` | 10000 | Maximale Zahl im Word-Dateimanifest; Gesamtzahl und Gesamtgröße werden weiter gezählt. |
|
||||
| `MaxContentDepth` | 30 | Maximale Verzeichnistiefe. |
|
||||
| `IncludeFileHashes` | `false` | SHA-256 nur bei ausdrücklicher Aktivierung. |
|
||||
|
||||
Reparse Points/Junctions werden nicht verfolgt. Das verhindert Schleifen und ein unbemerktes Verlassen des Web-Stamms. Sie erscheinen als Hinweis. Zugriffsfehler einzelner Dateien oder Verzeichnisse machen das Manifest sichtbar unvollständig, stoppen aber nicht die Site-Aufnahme.
|
||||
|
||||
Empfehlung für die erste ACC-/PROD-Aufnahme:
|
||||
|
||||
```cmd
|
||||
run-inventory.cmd ACC C:\IIS-Doku\ACC
|
||||
run-inventory.cmd PROD C:\IIS-Doku\PROD
|
||||
```
|
||||
|
||||
SHA-256 für jede Webdatei erst in einem zweiten Lauf aktivieren, wenn ein genauer Inhaltsvergleich benötigt wird:
|
||||
|
||||
```cmd
|
||||
BizTalkIisEnvironmentInventory.exe --environment ACC --output C:\IIS-Doku\ACC-Hash --include-file-hashes
|
||||
```
|
||||
|
||||
### 3.4 Zertifikate und private Schlüssel
|
||||
|
||||
Der Collector öffnet `LocalMachine\My` read-only. Für jedes Zertifikat werden unter anderem Thumbprint, Gültigkeit, Issuer, Algorithmus, Key Usage und IIS-Nutzung dokumentiert.
|
||||
|
||||
Bei privatem Schlüssel werden – soweit die ACL es zulässt – nur folgende Informationen gelesen:
|
||||
|
||||
- CAPI-/CNG-Provider
|
||||
- eindeutiger Containername
|
||||
- Provider-Exportpolicy
|
||||
- Pfad der Containerdatei
|
||||
- NTFS-ACL der Containerdatei
|
||||
|
||||
Der Code ruft weder `X509Certificate2.Export` noch `CngKey.Export` auf. Es gelangt kein Schlüsselmaterial in Log oder DOCX. `Exportierbar = Ja` bedeutet lediglich, dass ein separater, autorisierter Export technisch möglich sein sollte.
|
||||
|
||||
### 3.5 Dienstkonten und lokale Sicherheit
|
||||
|
||||
Anwendungspoolkonten stammen aus der IIS-Konfiguration. Relevante BizTalk-/IIS-/SSO-/MSMQ-Windows-Dienste werden über `Win32_Service` gelesen.
|
||||
|
||||
Für lokale User Rights und grundlegende Security-/Audit-Policy startet die .NET-Anwendung:
|
||||
|
||||
```text
|
||||
secedit.exe /export /areas USER_RIGHTS SECURITYPOLICY
|
||||
```
|
||||
|
||||
Das ist ein signiertes Windows-Bordmittel und keine PowerShell-Ausführung. Der Prozess hat einen Timeout von 60 Sekunden. Die temporäre INF-Datei wird nach dem Parsen gelöscht. Scheitert `secedit`, bleibt der Rest des Reports verwendbar.
|
||||
|
||||
### 3.6 BizTalk
|
||||
|
||||
Der Collector benötigt keine BizTalk-Assembly. Er verwendet:
|
||||
|
||||
- `HKLM\SOFTWARE\Microsoft\BizTalk Server\3.0` in 32-/64-Bit-Registry-View
|
||||
- Windows-Uninstall-Einträge
|
||||
- Dateiversionen zentraler BizTalk-Programme und Assemblies
|
||||
- WMI-Namespace `root\MicrosoftBizTalkServer`
|
||||
|
||||
Geprüfte Klassen:
|
||||
|
||||
- `MSBTS_GroupSetting`
|
||||
- `MSBTS_Host`
|
||||
- `MSBTS_HostInstance`
|
||||
- `MSBTS_ReceivePort`
|
||||
- `MSBTS_ReceiveLocation`
|
||||
- `MSBTS_SendPort`
|
||||
- `MSBTS_Orchestration`
|
||||
- `MSBTS_Server`
|
||||
|
||||
Je Klasse wird die Instanzzahl dokumentiert. Klassenfehler erscheinen einzeln als Finding und nicht als irreführende Null.
|
||||
|
||||
## 4. Secret-Bereinigung
|
||||
|
||||
XML-Attribute mit typischen Fragmenten wie `password`, `secret`, `token`, `connectionString`, `privateKey`, `validationKey` oder `decryptionKey` werden durch `[ENTFERNT]` ersetzt. Inhalte von `EncryptedData`, `CipherData` und `CipherValue` werden ebenfalls nicht übernommen.
|
||||
|
||||
Zusätzlich gelten:
|
||||
|
||||
- Logmeldungen enthalten keine XML-Dumps.
|
||||
- Registrywerte mit sensitiven Namen werden nicht ausgegeben.
|
||||
- Alle Berichtswerte werden über einen sicheren XML-Writer in WordprocessingML geschrieben.
|
||||
- Das DOCX enthält keine Makros, externen Links, Skripte, Fonts oder Tracking-Ressourcen.
|
||||
|
||||
Der Report enthält dennoch Infrastrukturinformationen und ACLs und muss entsprechend der internen Schutzklasse gespeichert werden.
|
||||
|
||||
## 5. Berechtigungen
|
||||
|
||||
Für eine möglichst vollständige Aufnahme ist eine lokale administrative `cmd.exe` empfohlen.
|
||||
|
||||
Ohne Erhöhung funktionieren häufig:
|
||||
|
||||
- IIS-XML-Topologie
|
||||
- öffentlich lesbare Webinhalte
|
||||
- Zertifikatsmetadaten
|
||||
- Registry-Grunddaten
|
||||
|
||||
Erhöhte Rechte können erforderlich sein für:
|
||||
|
||||
- ACL geschützter Webverzeichnisse
|
||||
- private Key-Container/ACLs
|
||||
- `secedit /export`
|
||||
- einzelne BizTalk-WMI-Klassen
|
||||
- Dateien unter geschützten Installationspfaden
|
||||
|
||||
Fehlende Rechte werden im Log und DOCX ausgewiesen. Das Tool verändert keine ACL und fordert keine zusätzlichen Rechte an.
|
||||
|
||||
## 6. Resilienz und Betriebsverhalten
|
||||
|
||||
- WMI-Timeout je Query, Default 30 Sekunden
|
||||
- Collector-Isolation durch zentralen Safe-Runner
|
||||
- iterative Dateibegehung mit Maximalgrenzen
|
||||
- Reparse-Point-Schutz
|
||||
- geteiltes Lesen aktiver Konfigurations-/Webdateien
|
||||
- Fehlerisolation je Datei, Verzeichnis, Zertifikat und WMI-Klasse
|
||||
- atomare DOCX-Ausgabe über temporäre Datei und Replace/Move
|
||||
- eindeutige Zeitstempel in Report- und Logdateien
|
||||
- sichtbarer Fortschritt auf der Konsole
|
||||
- Exitcode `1` bei verwertbarem Teilreport
|
||||
|
||||
Bei sehr großen Webverzeichnissen kann `--skip-content-manifest` verwendet werden. Bei produktiver Last sollten Datei-Hashes außerhalb der Hauptbetriebszeit berechnet werden.
|
||||
|
||||
## 7. Vergleich ACC und PROD
|
||||
|
||||
Empfohlenes Vorgehen:
|
||||
|
||||
1. Deployment unverändert nach ACC und PROD kopieren.
|
||||
2. Auf beiden Systemen als lokaler Administrator ausführen.
|
||||
3. Prüfen, dass Exitcode `0` erreicht oder jeder Teilfehler begründet ist.
|
||||
4. DOCX-Berichte sicher auf den Dokumentationsarbeitsplatz übertragen.
|
||||
5. Vergleichen:
|
||||
- acht erwartete Anwendungen vorhanden
|
||||
- App-Pool-Modus, 32-Bit und Dienstidentitäten
|
||||
- Bindings und Zertifikatsablauf
|
||||
- Webpfade, Dateizahlen und Änderungsstände
|
||||
- NTFS-/Private-Key-ACLs
|
||||
- User Rights der Dienstkonten
|
||||
- BizTalk-Produkte, Binärversionen und WMI-Komponenten
|
||||
6. Abweichungen fachlich als beabsichtigt oder als Migrationslücke klassifizieren.
|
||||
|
||||
Die DOCX-Dateien können mit Word-Bordmitteln durchsucht und verglichen werden. Für einen maschinellen Diff kann optional in einer Folgestufe ein JSON-Export ergänzt werden; die aktuelle Übergabe ist bewusst auf die gewünschte Word-Dokumentation beschränkt.
|
||||
|
||||
## 8. Build, Test und Gitea
|
||||
|
||||
```cmd
|
||||
scripts\build-release.cmd
|
||||
```
|
||||
|
||||
Das Skript:
|
||||
|
||||
1. findet MSBuild über `vswhere.exe` oder `PATH`
|
||||
2. baut Solution und Tests in `Release`
|
||||
3. führt den abhängigen Konsolen-Testläufer aus
|
||||
4. führt den eingebauten `--self-test` aus
|
||||
|
||||
Tests decken ab:
|
||||
|
||||
- Optionsnormalisierung
|
||||
- Secret-Bereinigung
|
||||
- IIS-XML-/Content-Parsing
|
||||
- secedit-INF-Parsing
|
||||
- DOCX-Paketstruktur und XML-Injection-Schutz
|
||||
|
||||
Auf Nicht-Windows-Buildsystemen wird zusätzlich ein .NET-10-Testziel für die plattformneutralen Tests
|
||||
(Optionsparser, Secret-Bereinigung und DOCX-Paketvalidierung) angeboten. Die Windows-spezifischen IIS- und
|
||||
`secedit`-Parsertests werden im normalen `net472`-Lauf auf dem Windows-Runner ausgeführt.
|
||||
|
||||
Die Gitea-Workflowdatei `.gitea/workflows/build.yml` erwartet einen Windows-Runner mit Visual Studio Build Tools und .NET Framework 4.7.2 Developer Pack.
|
||||
|
||||
## 9. Bekannte Grenzen
|
||||
|
||||
- Das Tool exportiert keine Websites, Dateien, Zertifikate oder Keys.
|
||||
- Windows Feature-Namen kommen lokalisiert aus WMI.
|
||||
- Effektive delegierte IIS-Konfiguration aus jeder einzelnen `web.config` wird nicht vollständig aufgelöst; die Dateien stehen im Inhaltsmanifest.
|
||||
- ACLs werden am Web-Stamm und an Key-Dateien dokumentiert, nicht an jeder Webdatei.
|
||||
- Gruppenverschachtelungen in Active Directory werden nicht aufgelöst.
|
||||
- Private Keys in HSM/KSP können keinen Dateipfad besitzen.
|
||||
- WMI-Komponentenzahlen sind eine Bestandsaufnahme, kein Laufzeitmonitoring.
|
||||
- Der Report ist eine Momentaufnahme; aktive Deployments können sich während des Laufs ändern.
|
||||
|
||||
## 10. Wiederholbarkeit
|
||||
|
||||
Für vergleichbare Ergebnisse auf ACC und PROD:
|
||||
|
||||
- dieselbe EXE-/Config-Version verwenden
|
||||
- denselben Berechtigungskontext verwenden
|
||||
- Dateihashes auf beiden Systemen gleich aktivieren oder deaktivieren
|
||||
- Aufnahme nicht während eines Deployments ausführen
|
||||
- DOCX und Log gemeinsam archivieren
|
||||
- Datum, Umgebung und Servername im generierten Dateinamen unverändert lassen
|
||||
Reference in New Issue
Block a user