274 lines
11 KiB
Markdown
274 lines
11 KiB
Markdown
# 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
|