diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 59da4602..31ad95ee 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -59,6 +59,7 @@ jobs: - name: Build (CodeQL traced) run: | dotnet restore --locked-mode -v minimal FileClassifier.sln + dotnet restore --locked-mode -v minimal src/FileClassifier.CSCore/FileClassifier.CSCore.csproj dotnet build -c Release --no-restore -v minimal FileClassifier.sln - name: Perform CodeQL Analysis diff --git a/Directory.Build.props b/Directory.Build.props index f4e72a30..c2a21c5c 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -4,7 +4,28 @@ true true + + + + + + + + + + + + + - 6.0.0 + 6.1.13 diff --git a/Directory.Packages.props b/Directory.Packages.props index 38e66a0e..15b1b322 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -5,19 +5,26 @@ + + + + + + + - \ No newline at end of file + diff --git a/docs/001_INDEX_CORE.MD b/docs/001_INDEX_CORE.MD index c530f4a2..b43e01c4 100644 --- a/docs/001_INDEX_CORE.MD +++ b/docs/001_INDEX_CORE.MD @@ -39,7 +39,7 @@ Zentrale Einstiegsstelle für alle Projektdokumente mit klarer Trennung nach Ver ## 6. Test- und Nachweisdokumente 1. [Test Matrix - Deterministic Hashing](https://github.com/tomtastisch/FileClassifier/blob/main/docs/verification/004_MATRIX_HASHING.MD) 2. [BDD-Satzkatalog (Deutsch, kanonisch)](https://github.com/tomtastisch/FileClassifier/blob/main/docs/verification/003_CATALOG_BDD.MD) -3. [BDD-Ausfuehrung und Gherkin-Flow](https://github.com/tomtastisch/FileClassifier/blob/main/docs/verification/002_FLOW_BDD.MD) +3. [BDD-Ausführung und Gherkin-Flow](https://github.com/tomtastisch/FileClassifier/blob/main/docs/verification/002_FLOW_BDD.MD) ## 7. Modulnahe Dokumentation - [FileTypeDetection Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/README.md) diff --git a/docs/0_de/001_INDEX_CORE.MD b/docs/0_de/001_INDEX_CORE.MD new file mode 100644 index 00000000..23ad3086 --- /dev/null +++ b/docs/0_de/001_INDEX_CORE.MD @@ -0,0 +1,66 @@ + +[DE](001_INDEX_CORE.MD) | [EN](../1_en/001_INDEX_CORE.MD) + + +# Dokumentationsindex + +## 1. Zweck +Zentrale Einstiegsstelle für alle Projektdokumente mit klarer Trennung nach Verantwortungsbereichen. + +## 2. Standards und Leitplanken +- Dokumentationsstandard (verbindlich): [Dokumentationsstandard (SSOT)](https://github.com/tomtastisch/FileClassifier/blob/main/docs/governance/004_POLICY_DOCUMENTATION.MD) +- CI-/Qualitätsnachweise: [CI-Pipeline (SSOT)](https://github.com/tomtastisch/FileClassifier/blob/main/docs/ci/001_PIPELINE_CI.MD) +- Auto-Labeling und Auto-Versionierung: [Auto-Labeling und Auto-Versionierung (SSOT)](https://github.com/tomtastisch/FileClassifier/blob/main/docs/versioning/004_POLICY_LABELING.MD) +- Testdokumentation (BDD): [Testdokumentation (BDD)](https://github.com/tomtastisch/FileClassifier/blob/main/docs/verification/001_INDEX_TESTS.MD) + +## 3. Kernarchitektur (SSOT) +1. [01 - Funktionen](https://github.com/tomtastisch/FileClassifier/blob/main/docs/010_API_CORE.MD) +2. [02 - Gesamtarchitektur und Ablaufflüsse](https://github.com/tomtastisch/FileClassifier/blob/main/docs/020_ARCH_CORE.MD) +3. [03 - Referenzen](https://github.com/tomtastisch/FileClassifier/blob/main/docs/references/001_REFERENCES_CORE.MD) +4. [04 - EvidenceHashing API Contract](https://github.com/tomtastisch/FileClassifier/blob/main/docs/contracts/001_CONTRACT_HASHING.MD) +5. [DIN-orientierte Spezifikation (DE) - FileTypeDetection](https://github.com/tomtastisch/FileClassifier/blob/main/docs/specs/001_SPEC_DIN.MD) +6. [Production Readiness Checklist - FileTypeDetection](https://github.com/tomtastisch/FileClassifier/blob/main/docs/quality/001_CHECKLIST_PRODUCTION.MD) +7. [Secure Hash Key Setup (HMAC)](https://github.com/tomtastisch/FileClassifier/blob/main/docs/secure/001_HMAC_KEY_SETUP.MD) + +## 4. Versionierung und Governance +1. [Versionierungs- und Release-Policy (SSOT)](https://github.com/tomtastisch/FileClassifier/blob/main/docs/versioning/001_POLICY_VERSIONING.MD) +2. [Versionslinie (Commit → Version)](https://github.com/tomtastisch/FileClassifier/blob/main/docs/versioning/002_HISTORY_VERSIONS.MD) +3. [Changelog](https://github.com/tomtastisch/FileClassifier/blob/main/docs/versioning/003_CHANGELOG_RELEASES.MD) +4. [Labeling Ownership](https://github.com/tomtastisch/FileClassifier/blob/main/docs/governance/002_POLICY_LABELING.MD) + +## 5. Guides und Umsetzungsplaybooks +1. [Guides - Change Playbooks](https://github.com/tomtastisch/FileClassifier/blob/main/docs/guides/000_INDEX_GUIDES.MD) +2. [Playbook: Options anlegen und anpassen](https://github.com/tomtastisch/FileClassifier/blob/main/docs/guides/001_GUIDE_OPTIONS.MD) +3. [Playbook: Neue Datatypes und API-Modelle erweitern](https://github.com/tomtastisch/FileClassifier/blob/main/docs/guides/002_GUIDE_DATATYPE.MD) + +## 5.1 Migration Notes +1. [Migration: Hashing Rename](https://github.com/tomtastisch/FileClassifier/blob/main/docs/migrations/001_HASHING_RENAME.MD) + +## 6. Test- und Nachweisdokumente +1. [Test Matrix - Deterministic Hashing](https://github.com/tomtastisch/FileClassifier/blob/main/docs/verification/004_MATRIX_HASHING.MD) +2. [BDD-Satzkatalog (Deutsch, kanonisch)](https://github.com/tomtastisch/FileClassifier/blob/main/docs/verification/003_CATALOG_BDD.MD) +3. [BDD-Ausführung und Gherkin-Flow](https://github.com/tomtastisch/FileClassifier/blob/main/docs/verification/002_FLOW_BDD.MD) + +## 7. Modulnahe Dokumentation +- [FileTypeDetection Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/README.md) +- [Index - Detection](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Detection/README.md) +- [Index - Infrastructure](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Infrastructure/README.md) +- [Index - Configuration](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Configuration/README.md) +- [Index - Abstractions](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/README.md) +- [Abstractions Detection Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/Detection/README.md) +- [Abstractions Archive Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/Archive/README.md) +- [Abstractions Hashing Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/Hashing/README.md) +- [Readme](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileClassifier.App/README.md) +- [Readme](https://github.com/tomtastisch/FileClassifier/blob/main/tests/FileTypeDetectionLib.Tests/README.md) + +## 8. Pflegeprozess +Pflichtprüfung bei Doku-Änderungen: +```bash +python3 tools/check-docs.py +``` + +## Dokumentpflege-Checkliste +- [ ] Inhalt auf aktuellen Code-Stand geprüft. +- [ ] Links und Anker mit `python3 tools/check-docs.py` geprüft. +- [ ] Beispiele/Kommandos lokal verifiziert. +- [ ] Verweise auf SSOT-Dokumente konsistent gehalten. diff --git a/docs/0_de/010_API_CORE.MD b/docs/0_de/010_API_CORE.MD new file mode 100644 index 00000000..f7fd8049 --- /dev/null +++ b/docs/0_de/010_API_CORE.MD @@ -0,0 +1,275 @@ + +[DE](010_API_CORE.MD) | [EN](../1_en/010_API_CORE.MD) + + +# 01 - Funktionen + +## 1. Zweck & Scope +Dieses Dokument beschreibt alle öffentlichen Einstiegspunkte der API mit Signaturen, Einsatzfall, Seiteneffekten und minimalen Aufrufbeispielen. + +## 2. Definitionen +- Fail-closed: Fehlerpfade liefern nur sichere Rückgaben (`Unknown`, `False`, leere Liste). +- Side-Effects: Dateisystemschreibvorgänge oder globale Optionsänderungen. +- Flow-ID: Verweis auf Architekturabläufe in `docs/020_ARCH_CORE.MD`. + +## 2.1 API-Semantik (prominent) +- `TryValidateArchive(...)` ist die kanonische Validierungs-API. +- Die Methode validiert **alle intern unterstützten Archivformate** fail-closed (u. a. ZIP/TAR/GZIP/7z/RAR). +- Technisch passiert die Typfeststellung über `ArchiveTypeResolver` + `ArchiveSafetyGate`; OOXML-Refinement bleibt container-spezifisch für ZIP-basierte OOXML-Dateien. +- Begriffsklärung: `ContainerType` bezeichnet das **physische Archivformat** (z. B. ZIP/TAR/GZIP/7z/RAR). Generische Archive werden kompatibel als `FileKind.Zip` zurückgegeben; ZIP-basierte OOXML-Container können auf `Docx`/`Xlsx`/`Pptx` verfeinert werden. + +## 2.2 Weiterführende Detailquellen pro Familie +| API-Familie | Detailquelle | Zweck | +|---|---|---| +| `FileTypeDetector` / `ArchiveProcessing` | [Detection Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Detection/README.md) | SSOT-Detektion, Header-Magic, Aliaslogik | +| `FileTypeDetector` / `ArchiveProcessing` / `FileMaterializer` | [Infrastructure Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Infrastructure/README.md) | Archive-Gate, Guards, Extraktions-Engine | +| `FileTypeOptions` / `FileTypeProjectBaseline` | [Configuration Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Configuration/README.md) | globale Optionen und Baseline | +| Rückgabemodelle (`FileType`, `DetectionDetail`, `ZipExtractedEntry`, `Hash*`) | [Abstractions Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/README.md) | Modellverträge der Public API | +| Modulnavigation | [FileClassifier Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/README.md) | Übersicht und Einstieg je Leserrolle | + +## 2.2.1 Physische Modellablage (ohne Funktionsänderung) +Die Rückgabemodelle sind rein organisatorisch in Unterordner aufgeteilt; die API-Semantik bleibt unverändert: +- Detection-Modelle: [Abstractions Detection Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/Detection/README.md) +- Archive-Modelle: [Abstractions Archive Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/Archive/README.md) +- Hashing-Modelle: [Abstractions Hashing Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/Hashing/README.md) + +## 2.3 Glossar (kanonische Begriffe) +| Begriff | Bedeutung | +|---|---| +| Archivformat | Physischer Container wie ZIP, TAR, TAR.GZ, 7z oder RAR. | +| ContainerType | Interner technischer Typ für das physische Archivformat. | +| FileKind.Zip | Öffentlicher, kompatibler logischer Rückgabetyp für generische Archive (z. B. TAR/TAR.GZ/7z/RAR). | +| PhysicalHash | SHA-256 über die unveränderten Rohbytes einer Datei oder eines Byte-Arrays. | +| LogicalHash | SHA-256 über kanonisierten Inhaltszustand (Entry-Pfad + Inhalt), unabhängig von Containerdetails. | +| FastHash | Optionaler, nicht-kryptografischer Vergleichsdigest (`XxHash3`) für Performance-Shortcuts. | +| SecureHash | Optionaler, keyed Digest (`HMAC-SHA256`) für Authentizität/Tamper-Evidence (via `FILECLASSIFIER_HMAC_KEY_B64`). | +| Fail-closed | Unsichere oder ungültige Eingaben liefern nur sichere Rückgaben (`Unknown`, `False`, leere Liste). | + +## 3. Vollständige Methodenmatrix (Public API) +| Familie | Methode | Input | Output | Side-Effects | Primarer Flow | +|---|---|---|---|---|---| +| `FileTypeDetector` | `ReadFileSafe(path)` | Datei-Pfad | `Byte()` | keine (read-only) | `F0` | +| `FileTypeDetector` | `Detect(path)` | Datei-Pfad | `FileType` | keine | `F1` | +| `FileTypeDetector` | `Detect(path, verifyExtension)` | Datei-Pfad + Bool | `FileType` | keine | `F1` | +| `FileTypeDetector` | `DetectDetailed(path)` | Datei-Pfad | `DetectionDetail` | keine | `F1` | +| `FileTypeDetector` | `DetectDetailed(path, verifyExtension)` | Datei-Pfad + Bool | `DetectionDetail` | keine | `F1` | +| `FileTypeDetector` | `DetectAndVerifyExtension(path)` | Datei-Pfad | `Boolean` | keine | `F8` | +| `FileTypeDetector` | `TryValidateArchive(path)` | Datei-Pfad | `Boolean` | keine | `F3` | +| `FileTypeDetector` | `Detect(data)` | `Byte()` | `FileType` | keine | `F2` | +| `FileTypeDetector` | `IsOfType(data, kind)` | `Byte()` + `FileKind` | `Boolean` | keine | `F2` | +| `FileTypeDetector` | `ExtractArchiveSafe(path, destination, verifyBeforeExtract)` | Pfad + Ziel + Bool | `Boolean` | schreibt auf Disk | `F5` | +| `FileTypeDetector` | `ExtractArchiveSafeToMemory(path, verifyBeforeExtract)` | Pfad + Bool | `IReadOnlyList(Of ZipExtractedEntry)` | keine | `F4` | +| `ArchiveProcessing` | `TryValidate(path)` | Datei-Pfad | `Boolean` | keine | `F3` | +| `ArchiveProcessing` | `TryValidate(data)` | `Byte()` | `Boolean` | keine | `F3` | +| `ArchiveProcessing` | `ExtractToMemory(path, verifyBeforeExtract)` | Pfad + Bool | `IReadOnlyList(Of ZipExtractedEntry)` | keine | `F4` | +| `ArchiveProcessing` | `TryExtractToMemory(data)` | `Byte()` | `IReadOnlyList(Of ZipExtractedEntry)` | keine | `F4` | +| `FileMaterializer` | `Persist(data, destinationPath)` | `Byte()` + Zielpfad | `Boolean` | schreibt auf Disk | `F6` | +| `FileMaterializer` | `Persist(data, destinationPath, overwrite)` | `Byte()` + Zielpfad + Bool | `Boolean` | schreibt auf Disk | `F6` | +| `FileMaterializer` | `Persist(data, destinationPath, overwrite, secureExtract)` | `Byte()` + Zielpfad + 2 Bool | `Boolean` | schreibt auf Disk | `F5`/`F6` | +| `EvidenceHashing` | `HashFile(path)` | Datei-Pfad | `HashEvidence` | keine | `F9` | +| `EvidenceHashing` | `HashFile(path, options)` | Datei-Pfad + Optionen | `HashEvidence` | keine | `F9` | +| `EvidenceHashing` | `HashBytes(data)` | `Byte()` | `HashEvidence` | keine | `F9` | +| `EvidenceHashing` | `HashBytes(data, label)` | `Byte()` + Label | `HashEvidence` | keine | `F9` | +| `EvidenceHashing` | `HashBytes(data, label, options)` | `Byte()` + Label + Optionen | `HashEvidence` | keine | `F9` | +| `EvidenceHashing` | `HashEntries(entries)` | `IReadOnlyList(Of ZipExtractedEntry)` | `HashEvidence` | keine | `F9` | +| `EvidenceHashing` | `HashEntries(entries, label)` | Entries + Label | `HashEvidence` | keine | `F9` | +| `EvidenceHashing` | `HashEntries(entries, label, options)` | Entries + Label + Optionen | `HashEvidence` | keine | `F9` | +| `EvidenceHashing` | `VerifyRoundTrip(path)` | Datei-Pfad | `HashRoundTripReport` | schreibt temp-Datei intern und räumt auf | `F9` | +| `EvidenceHashing` | `VerifyRoundTrip(path, options)` | Datei-Pfad + Optionen | `HashRoundTripReport` | schreibt temp-Datei intern und räumt auf | `F9` | +| `FileTypeOptions` | `LoadOptions(json)` | JSON | `Boolean` | ändert globale Optionen | `F7` | +| `FileTypeOptions` | `GetOptions()` | - | `String` (JSON) | keine | `F7` | +| `FileTypeProjectBaseline` | `ApplyDeterministicDefaults()` | - | `Void` | ändert globale Optionen | `F7` | + +## 4. Methodenfamilien +### 4.1 FileTypeDetector +Details: [FileClassifier Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/README.md), [Detection Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Detection/README.md), [Infrastructure Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Infrastructure/README.md). + +**Wichtiger Semantikhinweis:** `TryValidateArchive(path)` validiert generische Archivcontainer über dieselbe fail-closed Pipeline wie Extraktion und Materialisierung. + +```mermaid +flowchart TD + I0["Input: Path or Bytes"] + D1["Detect / DetectDetailed"] + D2["DetectAndVerifyExtension"] + V1["TryValidateArchive"] + X1["ExtractArchiveSafe / ExtractArchiveSafeToMemory"] + O0["Output: Type / Detail / Bool / Entries"] + + I0 --> D1 --> O0 + I0 --> D2 --> O0 + I0 --> V1 --> O0 + I0 --> X1 --> O0 +``` + +```csharp +using Tomtastisch.FileClassifier; + +var detector = new FileTypeDetector(); +var t = detector.Detect("/data/invoice.pdf", verifyExtension: true); +var d = detector.DetectDetailed("/data/archive.docx", verifyExtension: true); +bool archiveOk = FileTypeDetector.TryValidateArchive("/data/archive.zip"); +var entries = detector.ExtractArchiveSafeToMemory("/data/archive.zip", verifyBeforeExtract: true); + +Console.WriteLine($"{t.Kind} / {d.ReasonCode} / {archiveOk} / {entries.Count}"); +``` + +### 4.2 ArchiveProcessing +API-Name bleibt aus Kompatibilitätsgründen erhalten; intern werden Archivcontainer einheitlich behandelt. +Details: [FileClassifier Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/README.md), [Infrastructure Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Infrastructure/README.md). + +```mermaid +flowchart LR + ZI["Input: Path or Bytes"] + ZV["TryValidate(path|data)"] + ZE["ExtractToMemory / TryExtractToMemory"] + ZO["Output: Bool or Entries"] + + ZI --> ZV --> ZO + ZI --> ZE --> ZO +``` + +```csharp +using Tomtastisch.FileClassifier; + +bool okPath = ArchiveProcessing.TryValidate("/data/archive.zip"); +bool okBytes = ArchiveProcessing.TryValidate(File.ReadAllBytes("/data/archive.zip")); +var entriesPath = ArchiveProcessing.ExtractToMemory("/data/archive.zip", verifyBeforeExtract: true); +var entriesBytes = ArchiveProcessing.TryExtractToMemory(File.ReadAllBytes("/data/archive.zip")); +``` + +### 4.3 FileMaterializer +Details: [FileClassifier Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/README.md), [Infrastructure Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Infrastructure/README.md). + +```mermaid +flowchart TD + MI["Input: Byte Payload + destinationPath"] + MP["Persist(...)"] + BR["secureExtract and archive?"] + RW["Raw Byte Write"] + ZE["Validated Archive Extract to Disk"] + MO["Output: Bool"] + + MI --> MP --> BR + BR -->|"No"| RW --> MO + BR -->|"Yes"| ZE --> MO +``` + +```csharp +using Tomtastisch.FileClassifier; + +byte[] payload = File.ReadAllBytes("/data/input.bin"); +byte[] archivePayload = File.ReadAllBytes("/data/archive.zip"); + +bool rawOk = FileMaterializer.Persist(payload, "/data/out/input.bin", overwrite: false, secureExtract: false); +bool archiveExtractOk = FileMaterializer.Persist(archivePayload, "/data/out/unpacked", overwrite: false, secureExtract: true); +``` + +### 4.4 FileTypeOptions + FileTypeProjectBaseline +Details: [FileClassifier Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/README.md), [Configuration Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Configuration/README.md). + +```mermaid +flowchart LR + C0["Config Input: JSON or Baseline Call"] + C1["LoadOptions(json)"] + C2["ApplyDeterministicDefaults()"] + C3["Global Snapshot"] + C4["GetOptions()"] + + C0 --> C1 --> C3 + C0 --> C2 --> C3 + C3 --> C4 +``` + +```csharp +using Tomtastisch.FileClassifier; + +FileTypeProjectBaseline.ApplyDeterministicDefaults(); +bool loaded = FileTypeOptions.LoadOptions("{\"maxBytes\":134217728}"); +string snapshot = FileTypeOptions.GetOptions(); +Console.WriteLine($"Loaded={loaded}; Snapshot={snapshot}"); +``` + +### 4.5 EvidenceHashing +Details: [FileClassifier Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/README.md), [Abstractions Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/README.md). +Formaler API-Contract: [04 - EvidenceHashing API Contract](https://github.com/tomtastisch/FileClassifier/blob/main/docs/contracts/001_CONTRACT_HASHING.MD). + +```mermaid +flowchart LR + HI["Input: File/Bytes/Entries"] + H1["Physical SHA-256 (raw bytes)"] + H2["Logical SHA-256 (canonical content)"] + H3["optional Fast XxHash3"] + HR["RoundTrip h1-h4 report"] + + HI --> H1 + HI --> H2 + HI --> H3 + HI --> HR +``` + +```csharp +using Tomtastisch.FileClassifier; + +var evidence = EvidenceHashing.HashFile("/data/archive.zip"); +var report = EvidenceHashing.VerifyRoundTrip("/data/archive.zip"); + +Console.WriteLine($"{evidence.Digests.PhysicalSha256} / {evidence.Digests.LogicalSha256}"); +Console.WriteLine($"LogicalConsistent={report.LogicalConsistent}"); +``` + +Hinweis: +- `PhysicalSha256` und `LogicalSha256` sind Security-SSOT. +- `Fast*XxHash3` ist optionaler Performance-Digest und kein kryptografischer Integritätsnachweis. +- Overloads ohne `options` verwenden die globale Policy `FileTypeOptions.GetSnapshot().DeterministicHash`. + +## 5. Nicht-Ziele +- Keine interne Low-Level-Implementierung im Detail (siehe `docs/references/001_REFERENCES_CORE.MD`). +- Keine Norm/Compliance-Herleitung (siehe `docs/specs/001_SPEC_DIN.MD`). + +## 6. Security-Gate Mini-Contract (neutral) +Die folgenden Regeln gelten für `ArchiveSafetyGate` + `ArchiveExtractor`: + +| Regel | Default | Vertrag | +|---|---|---| +| Link-Entries (`symlink`/`hardlink`) | `RejectArchiveLinks = true` | Link-Targets werden fail-closed verworfen. Override nur per explizitem Opt-In (`false`) und eigener Risikoentscheidung des Consumers. | +| Unknown Entry Size | `AllowUnknownArchiveEntrySize = false` | "Unknown" bedeutet `Size` nicht vorhanden oder negativ. Dann wird fail-closed geblockt bzw. per bounded Streaming gemessen; bei Grenzverletzung -> `False`. | +| Path-Sicherheit | aktiv | Entry-Name wird normalisiert (`\\` -> `/`), root/traversal/leer werden verworfen, Zielpfad muss Prefix-Check bestehen. | +| Grenzen | aktiv | Entry-Anzahl, per-Entry-Bytes, Gesamtbytes, Rekursionstiefe und archivformat-spezifische Ratio/Nested-Regeln bleiben fail-closed. | + +## 7. Formatmatrix (implementierte Semantik) +Implementiert bedeutet hier: Archivformat wird geöffnet, Gate angewendet und Extraktion über dieselbe Pipeline ausgeführt. + +| Format | Detection (`Detect`) | Validate (`TryValidateArchive` / `ArchiveProcessing.TryValidate`) | Extract-to-Memory (`ArchiveProcessing.TryExtractToMemory`) | Extract-to-Disk (`FileMaterializer.Persist(..., secureExtract:=True)`) | +|---|---|---|---|---| +| ZIP | Ja (Magic + Gate + optional OOXML-Refinement) | Ja | Ja | Ja | +| TAR | Ja (Container-Erkennung + Gate, logisches `FileKind.Zip`) | Ja | Ja | Ja | +| TAR.GZ | Ja (GZIP-Container, Nested-Archive-Pfad) | Ja | Ja | Ja | +| 7z | Ja (Container-Erkennung + Gate, logisches `FileKind.Zip`) | Ja | Ja | Ja | +| RAR | Ja (Container-Erkennung + Gate, logisches `FileKind.Zip`) | Ja | Ja | Ja | + +Hinweis zur Typausgabe: Für generische Archive bleibt der öffentliche Rückgabetyp kompatibel (`FileKind.Zip`); ZIP-basierte OOXML-Container können auf `Docx`/`Xlsx`/`Pptx` verfeinert werden. + +## 8. Nachweis Umwandlung/Absicherung + Testabdeckung +Die Byte-Pfade (Detect/Validate/Extract/Persist) sind auf die gleiche Gate-Pipeline gelegt. + +| Format | Detection | Validate | Extract Memory | Extract Disk | Testnachweis | +|---|---|---|---|---|---| +| ZIP | abgedeckt | abgedeckt | abgedeckt | abgedeckt | `tests/FileTypeDetectionLib.Tests/Unit/ArchiveProcessingFacadeUnitTests.cs`, `tests/FileTypeDetectionLib.Tests/Unit/ArchiveExtractionUnitTests.cs`, `tests/FileTypeDetectionLib.Tests/Unit/FileMaterializerUnitTests.cs` | +| TAR | abgedeckt | indirekt über unified validate | implizit über Backend-Pfad | implizit über Backend-Pfad | `tests/FileTypeDetectionLib.Tests/Unit/UnifiedArchiveBackendUnitTests.cs` | +| TAR.GZ | abgedeckt | abgedeckt | abgedeckt | abgedeckt | `tests/FileTypeDetectionLib.Tests/Unit/UnifiedArchiveBackendUnitTests.cs` | +| 7z | abgedeckt | abgedeckt | abgedeckt | abgedeckt | `tests/FileTypeDetectionLib.Tests/Features/FTD_BDD_040_ARCHIVE_TYPEN_BYTEARRAY_UND_MATERIALISIERUNG.feature` | +| RAR | abgedeckt | abgedeckt | abgedeckt | abgedeckt | `tests/FileTypeDetectionLib.Tests/Features/FTD_BDD_040_ARCHIVE_TYPEN_BYTEARRAY_UND_MATERIALISIERUNG.feature` | + +Zusatznachweis Security: +- Link-Entry fail-closed (`RejectArchiveLinks=true`): `tests/FileTypeDetectionLib.Tests/Unit/UnifiedArchiveBackendUnitTests.cs`. +- Archiv-Fail-closed Regressionen (Traversal, malformed Header, Overwrite/Target-Guards): `tests/FileTypeDetectionLib.Tests/Unit/FileMaterializerUnitTests.cs`. + +Portabilität/Struktur: +- Public API bleibt stabil; interne Verantwortungen sind getrennt (`Detection` SSOT, `Infrastructure` Gate/Backend/Extractor, `Configuration` Policies, `Abstractions` Rückgabemodelle). +- Wiederverwendung erfolgt über ein neutrales Entry-Modell + einheitliche Gate- und Extractor-Pfade. + +## Dokumentpflege-Checkliste +- [ ] Inhalt auf aktuellen Code-Stand geprüft. +- [ ] Links und Anker mit `python3 tools/check-docs.py` geprüft. +- [ ] Beispiele/Kommandos lokal verifiziert. +- [ ] Begriffe mit `docs/010_API_CORE.MD` abgeglichen. diff --git a/docs/0_de/020_ARCH_CORE.MD b/docs/0_de/020_ARCH_CORE.MD new file mode 100644 index 00000000..17eef4fd --- /dev/null +++ b/docs/0_de/020_ARCH_CORE.MD @@ -0,0 +1,384 @@ + +[DE](020_ARCH_CORE.MD) | [EN](../1_en/020_ARCH_CORE.MD) + + +# 02 - Gesamtarchitektur und Ablaufflüsse + +## 1. Zweck und Scope +Dieses Dokument beschreibt die öffentliche API (Use-Cases), die interne Kernpipeline sowie die wesentlichen Laufzeitflüsse (Detektion, Archiv-Validierung, Extraktion, Persistenz). +Es dient als Architektur- und Ablaufreferenz auf Dokumentationsebene und ersetzt keine Code-Reviews der Guards. + +## 2. Begriffe und Notation +### 2.1 Konventionen +- Knoten = Verantwortungsbereich, Komponente oder Artefakt. +- Pfeil = Datenfluss oder Aufrufpfad (je nach Diagrammtyp). +- fail-closed = bei Unsicherheit oder Verstoss: `Unknown`, `false` oder leere Liste. + +### 2.2 Flow-IDs (Legende) +- `F0`: ReadFileSafe Utility +- `F1`: Detect (Path) +- `F2`: Detect (Bytes) +- `F3`: Archive Validate +- `F4`: Archive Extract to Memory +- `F5`: Archive Extract to Disk +- `F6`: Raw Byte Materialize (Persist) +- `F7`: Global Options/Baseline +- `F8`: Extension Policy Check +- `F9`: Deterministic Hashing / h1-h4 RoundTrip + +### 2.3 Mermaid-Layout (global) +Hinweis: Diese `init`-Konfiguration reduziert Kreuzungen und erhöht Lesbarkeit. +Sie kann pro Diagramm überschrieben werden, sollte aber konsistent bleiben. + +```mermaid +%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 80, "rankSpacing": 90}, "themeVariables": {"fontSize": "16px"}}}%% +flowchart LR + A["Mermaid Init: aktiviert (Referenz)"] +``` + +### 2.4 Detailquellen für tieferes Drill-Down +- Detection-Details: [Detection Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Detection/README.md) +- Infrastructure-Details (Guards/Archive internals): [Infrastructure Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Infrastructure/README.md) +- Konfigurationsdetails: [Configuration Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Configuration/README.md) +- Rückgabemodelle: [Abstractions Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/README.md) +- Rückgabemodelle Detection: [Abstractions Detection Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/Detection/README.md) +- Rückgabemodelle Archive: [Abstractions Archive Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/Archive/README.md) +- Rückgabemodelle Hashing: [Abstractions Hashing Modul](https://github.com/tomtastisch/FileClassifier/blob/main/src/FileTypeDetection/Abstractions/Hashing/README.md) +- Funktionskatalog mit Beispielen: [01 - Funktionen](https://github.com/tomtastisch/FileClassifier/blob/main/docs/010_API_CORE.MD) + +## 3. Architekturübersicht (Systemkontext) +### 3.1 E2E-Systemkontext (kompakt) +Dieses Diagramm zeigt die Schichten des Laufzeitflusses: +Inputs -> Public API -> Kernkomponenten -> Outputs. +Detailentscheidungen (Archivfall, Refinement, Persistenzzweig) folgen in 3.2 und Abschnitt 4. + +```mermaid +%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 80, "rankSpacing": 90}, "themeVariables": {"fontSize": "16px"}}}%% +flowchart LR + subgraph INPUT["Input"] + FP["File Path"] + BP["Byte Payload"] + end + + subgraph API["Public API"] + FTD["FileTypeDetector"] + AP["ArchiveProcessing"] + FM["FileMaterializer"] + DH["EvidenceHashing"] + end + + subgraph CORE["Kernkomponenten"] + REG["FileTypeRegistry"] + GATE["ArchiveSafetyGate"] + EXT["ArchiveExtractor"] + COL["ArchiveEntryCollector"] + REF["OpenXmlRefiner"] + end + + subgraph OUT["Outputs"] + T["FileType / DetectionDetail"] + V["Bool"] + E["Entries"] + F["Files / Directories"] + H["HashEvidence / RoundTripReport"] + end + + FP --> FTD + BP --> FTD + FP --> AP + BP --> AP + BP --> FM + FP --> DH + BP --> DH + + FTD --> REG + FTD --> GATE + FTD --> REF + AP --> GATE + AP --> EXT + FM --> EXT + DH --> COL + DH --> REG + + FTD --> T + AP --> V + AP --> E + FM --> V + FM --> F + DH --> H +``` + +Kurzlesehilfe: +- Nur Schichtsicht, keine Branch-Details. +- Branch- und Sicherheitsentscheidungen stehen in Abschnitt 4. + +### 3.2 Entscheidungsübersicht (kompakt) +Dieses Diagramm zeigt die zentrale Entscheidungslogik in einer vertikalen Lesespur. + +```mermaid +%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 80, "rankSpacing": 90}, "themeVariables": {"fontSize": "16px"}}}%% +flowchart TD + A["Input lesen"] --> B{"Magic erkannt?"} + B -- "Nein" --> U["Unknown / fail-closed"] + B -- "Ja" --> C{"Archivtyp?"} + C -- "Nein" --> T["Direkter Typ-Output"] + C -- "Ja" --> G["ArchiveSafetyGate"] + G -- "Fail" --> U + G -- "Pass" --> R{"OOXML Marker?"} + R -- "Ja" --> O["OpenXmlRefiner"] + R -- "Nein" --> Z["Archive Generic"] + O --> T + Z --> T +``` + +## 4. Flussdiagramme (entscheidungsrelevante Abläufe) +### 4.1 Ablauf A: Detektion und Archiv-Validierung +Dieses Diagramm zeigt die Kernentscheidung: `Magic == Archiv?` sowie die fail-closed-Kaskade über `ArchiveSafetyGate`. +Oben: Typdetektion (`FileType`/`DetectionDetail`). +Unten: reine Archiv-Validierung (`bool`) über denselben Gate-Knoten. + +```mermaid +%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 70, "rankSpacing": 80}, "themeVariables": {"fontSize": "16px"}}}%% +flowchart TD + I1["Input: path or bytes"] --> D1["Detect(...) / DetectDetailed(...)"] + D1 --> H1["ReadHeader"] + H1 --> M1["DetectByMagic"] + M1 --> Q1{"Magic == Archiv?"} + + Q1 -->|"No"| T1["Resolve(kind) -> Type Output"] + Q1 -->|"Yes"| G1["ArchiveSafetyGate"] --> Q2{"Archiv safe?"} + + Q2 -->|"No"| U1["Unknown (fail-closed)"] + Q2 -->|"Yes"| R1["OpenXmlRefiner"] --> T2["Refined or Generic Archive -> Type Output"] + + I1 --> V1["TryValidateArchive / ArchiveProcessing.TryValidate(...)"] + V1 --> G1 + Q2 --> V2["Validate Output: Bool"] +``` + +Kurzlesehilfe: +- `ArchiveSafetyGate` ist SSOT für Archiv-Sicherheit in den gezeigten Pfaden. +- `OpenXmlRefiner` läuft nur im Archiv-OK-Fall. + +### 4.2 Ablauf B: Extraktion (Memory) vs. Persistenz (Disk) +Dieses Diagramm zeigt zwei Archiv-Use-Cases: +(1) sichere In-Memory-Extraktion (Entries-Liste) +(2) Persistenz auf Disk (Raw Write oder Archiv-Extract), jeweils mit fail-closed Ergebnissen. + +```mermaid +%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 80, "rankSpacing": 90}, "themeVariables": {"fontSize": "16px"}}}%% +flowchart LR +%% --- INPUTS --- + subgraph INPUT["Input"] + direction TB + IN["path | bytes"] + OPT["Options / Baseline"] + end + +%% --- USE CASES --- + subgraph UC["Public Use-Cases"] + direction TB + UC2["ExtractArchiveEntries
(ArchiveProcessing)"] + UC3["PersistBytes
(FileMaterializer)"] + end + +%% --- ARCHIVE CORE (SSOT) --- + subgraph CORE["Archive Core (SSOT)"] + direction TB + G["ArchiveSafetyGate"] + X["ArchiveExtractor"] + G --> X + end + +%% --- OUTPUTS --- + subgraph OUT["Outputs"] + direction TB + O3["Entries (Memory Extract)"] + O4["Files / Directories"] + O2A["Bool (Validate)"] + O2B["Bool (Persist)"] + end + +%% wiring: inputs -> use cases + IN --> UC2 + IN --> UC3 + +%% options context (no dataflow) + OPT -.-> UC2 + OPT -.-> UC3 + +%% use cases -> gate + UC2 --> G + UC3 --> G + +%% gate outcomes + G --> O2A + UC3 --> O2B + +%% extractor outcomes + X --> O3 + X --> O4 +``` + +Kurzlesehilfe: +- Memory-Extraktion und Persistenz teilen sich Gate/Extractor. +- Persistenz liefert immer `Bool` als Rückgabekontrakt. + +## 5. Sequenzflüsse (Runtime-Interaktionen) +### 5.1 Detect(path) mit Archivfall +Dieser Sequenzfluss zeigt den Archivfall im Detektor: +Detektion -> Gate -> optionales Refinement -> Rückgabe. +Der fail-closed-Pfad liefert `Unknown`. + +```mermaid +sequenceDiagram + participant Caller as Consumer + participant API as FileTypeDetector + participant REG as FileTypeRegistry + participant GATE as ArchiveSafetyGate + participant REF as OpenXmlRefiner + + Caller->>API: Detect(path, verifyExtension) + API->>API: ReadHeader(path) + API->>REG: DetectByMagic(header) + + alt non-archive + REG-->>API: FileKind + API-->>Caller: FileType + else archive + API->>GATE: IsArchiveSafeStream(...) + GATE-->>API: pass/fail + + alt pass + API->>REF: TryRefineStream(...) + REF-->>API: refined-kind | unknown + API-->>Caller: FileType + else fail + API-->>Caller: Unknown + end + end +``` + +### 5.2 Validate + Extract (Memory) +Fokus: Byte-Pfad über `ArchiveProcessing`. +Fail-closed endet mit leerer Liste. + +```mermaid +sequenceDiagram + participant Caller as Consumer + participant ZP as ArchiveProcessing + participant Collect as ArchiveEntryCollector + + Caller->>ZP: TryExtractToMemory(data) + ZP->>Collect: TryCollectFromBytes(data, opt, entries) + Collect-->>ZP: pass/fail + entries + + alt pass + ZP-->>Caller: entries list + else fail + ZP-->>Caller: empty list + end +``` + +### 5.3 Materializer: Branching (Persist) +Fokus: Zielpfadprüfung, danach entweder sicherer Archiv-Zweig oder Raw-Write. +Rückgabe ist immer boolesch. + +```mermaid +sequenceDiagram + participant Caller as Consumer + participant MAT as FileMaterializer + participant Guard as DestinationPathGuard + participant Resolver as ArchiveTypeResolver + participant Gate as ArchiveSafetyGate + participant Extract as ArchiveExtractor + participant FS as FileSystem + + Caller->>MAT: Persist(data, destination, overwrite, secureExtract) + MAT->>Guard: PrepareMaterializationTarget(destination, overwrite) + + alt invalid target + MAT-->>Caller: false + else valid target + alt secureExtract and archive + MAT->>Resolver: TryDescribeBytes(data) + Resolver-->>MAT: descriptor/none + MAT->>Gate: IsArchiveSafeBytes(data, descriptor) + Gate-->>MAT: pass/fail + + alt pass + MAT->>Extract: TryExtractArchiveStream(...) + Extract-->>Caller: true/false + else fail + MAT-->>Caller: false + end + else raw write + MAT->>FS: CreateNew + Write bytes + FS-->>Caller: true/false + end + end +``` + +## 6. NSD-Sichten (strukturierter Kontrollfluss) +### 6.1 NSD: FileMaterializer.Persist(...) +Diese Sicht reduziert verschachtelte Bedingungen auf strukturierten Kontrollfluss. +Jeder negative Prüfpfad endet sofort fail-closed mit `false`. + +```mermaid +%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 65, "rankSpacing": 70}, "themeVariables": {"fontSize": "16px"}}}%% +flowchart TD + S0["Start Persist(...)"] --> S1{"Input valid?
(data, size, destination)"} + S1 -->|"No"| E1["Return false"] + S1 -->|"Yes"| S2{"secureExtract and archive?"} + + S2 -->|"No"| A1["MaterializeRawBytes(...)"] --> R1["Return bool"] + S2 -->|"Yes"| S3{"Readable archive?"} + + S3 -->|"No"| E2["Return false"] + S3 -->|"Yes"| S4{"ArchiveSafetyGate pass?"} + + S4 -->|"No"| E3["Return false"] + S4 -->|"Yes"| A2["MaterializeArchiveBytes(...)"] --> R2["Return bool"] +``` + +### 6.2 NSD: FileTypeDetector.Detect(path, verifyExtension) +Die Endungsprüfung ist ein nachgelagerter Policy-Filter. +Bei Mismatch wird fail-closed `UnknownType` zurückgegeben. + +```mermaid +%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 65, "rankSpacing": 70}, "themeVariables": {"fontSize": "16px"}}}%% +flowchart TD + D0["Start Detect(path, verifyExtension)"] --> D1["detected := DetectPathCore(path)"] + D1 --> D2{"verifyExtension?"} + + D2 -->|"No"| D3["Return detected"] + D2 -->|"Yes"| D4{"ExtensionMatchesKind(path, detected.Kind)?"} + + D4 -->|"Yes"| D5["Return detected"] + D4 -->|"No"| D6["Return UnknownType"] +``` + +## 7. Zuordnung Public API -> Flows +| Methode | Flow-ID | +|---|---| +| `ReadFileSafe(path)` | `F0` | +| `Detect(path)` / `DetectDetailed(path)` | `F1` | +| `Detect(data)` / `IsOfType(data, kind)` | `F2` | +| `TryValidateArchive(path)` / `ArchiveProcessing.TryValidate(path|data)` | `F3` | +| `ExtractArchiveSafeToMemory(path, ...)` / `ArchiveProcessing.ExtractToMemory(...)` / `ArchiveProcessing.TryExtractToMemory(data)` | `F4` | +| `ExtractArchiveSafe(path, destination, ...)` | `F5` | +| `FileMaterializer.Persist(..., secureExtract:=False)` | `F6` | +| `FileTypeOptions.LoadOptions/GetOptions` / `FileTypeProjectBaseline.ApplyDeterministicDefaults` | `F7` | +| `DetectAndVerifyExtension(path)` / `Detect(..., verifyExtension)` | `F8` | +| `EvidenceHashing.HashFile/HashBytes/HashEntries/VerifyRoundTrip` | `F9` | + +## 8. Grenzen und Nicht-Ziele +- Kein Ersatz für Quellcode-Reviews interner Guards (z. B. Payload-/Path-Guards). +- Keine Policy-Festlegung für konkrete Grenzwerte; diese kommen aus `FileTypeProjectOptions` und der Baseline. +- Keine Aussage über konkrete Threat-Model-Abdeckung ausserhalb der beschriebenen fail-closed-Semantik. + +## Dokumentpflege-Checkliste +- [ ] Inhalt auf aktuellen Code-Stand geprüft. +- [ ] Links und Anker mit `python3 tools/check-docs.py` geprüft. +- [ ] Beispiele/Kommandos lokal verifiziert. +- [ ] Begriffe mit `docs/010_API_CORE.MD` abgeglichen. diff --git a/docs/0_de/021_USAGE_NUGET.MD b/docs/0_de/021_USAGE_NUGET.MD new file mode 100644 index 00000000..4647f1d3 --- /dev/null +++ b/docs/0_de/021_USAGE_NUGET.MD @@ -0,0 +1,128 @@ + +[DE](021_USAGE_NUGET.MD) | [EN](../1_en/021_USAGE_NUGET.MD) + + +# NuGet Nutzung + +## A) Zweck +`Tomtastisch.FileClassifier` stellt die öffentliche Bibliotheksoberfläche für Dateityperkennung, sichere Archivverarbeitung, Byte-Materialisierung und deterministische Hashing-Nachweise bereit. + +## B) Installation (Consumer) +```bash +dotnet add package Tomtastisch.FileClassifier --version X.Y.Z +``` + +```xml + + + +``` + +Version-Pinning: +- Für Releases gilt SVT: Git-Tag `vX.Y.Z` entspricht Paketversion `X.Y.Z`. +- Consumer sollten exakt auf die freigegebene Version pinnen. + +## C) Minimalbeispiel (Consumer) +```csharp +using Tomtastisch.FileClassifier; + +var payload = "%PDF-1.7\nsample\n"u8.ToArray(); +var detector = new FileTypeDetector(); +var detected = detector.Detect(payload); + +if (detected.Kind == FileKind.Pdf) +{ + var evidence = EvidenceHashing.HashBytes(payload, "sample.pdf"); + _ = FileMaterializer.Persist(payload, "out/sample.bin", overwrite: true, secureExtract: false); +} +``` + +## D) Verifikation (Consumer) +Lokale Paketprüfung (nur Paketmetadata gegen Erwartung): +```bash +EXPECTED_VERSION=X.Y.Z VERIFY_ONLINE=0 bash tools/ci/verify_nuget_release.sh +``` + +Online-Prüfung (Search, Registration, Flatcontainer): +```bash +EXPECTED_VERSION=X.Y.Z bash tools/ci/verify_nuget_release.sh +``` + +Relevante Inputs: +- `EXPECTED_VERSION`: erwartetes Ziel (`X.Y.Z`). +- `NUPKG_PATH`: expliziter Paketpfad (optional). +- `NUPKG_DIR`: Suchverzeichnis (Default `artifacts/nuget`, falls `NUPKG_PATH` nicht gesetzt). +- `VERIFY_ONLINE=0`: überspringt Netzwerkchecks deterministisch. +- `RETRY_COUNT`: Anzahl zusätzlicher Wiederholungen nach dem Erstversuch für Online-Checks (Default `6`). +- `RETRY_SLEEP_SECONDS`: Wartezeit zwischen Retries in Sekunden (Default `10`). +- `REQUIRE_SEARCH`: aktiviert/deaktiviert Search als Pflichtcheck (`1`/`0`, Default `1`). +- `REQUIRE_REGISTRATION`: aktiviert/deaktiviert Registration als Pflichtcheck (`1`/`0`, Default `1`). +- `REQUIRE_FLATCONTAINER`: aktiviert/deaktiviert Flatcontainer als Pflichtcheck (`1`/`0`, Default `1`). + +Release-Gate-4 (post-publish) nutzt eigene Defaults über den Wrapper: +- `SVT_POSTPUBLISH_RETRY_SCHEDULE_SECONDS` (Default `2,3,5,8,13,21,34,55,89,89,89`) +- `SVT_POSTPUBLISH_RETRY_COUNT` (Default: Anzahl Schedule-Elemente, aktuell `11`; optional explizit überschreibbar) +- `SVT_POSTPUBLISH_RETRY_SLEEP_SECONDS` (Default `10`) +- Blocking-Scope im Release: + - `REQUIRE_SEARCH=0` + - `REQUIRE_REGISTRATION=1` + - `REQUIRE_FLATCONTAINER=1` + +Asynchrone Full-Convergence: +- Workflow `.github/workflows/nuget-online-convergence.yml` prüft nach erfolgreichem Release weiterhin alle drei Endpunkte mit längerem Retry-Fenster. + +## E) Maintainer: Token Storage and Local Publish (Secure) +Keychain (prompt-basiert): +```bash +security add-generic-password -a "$USER" -s "NUGET_API_KEY" -U -w +``` + +Abruf (silent): +```bash +security find-generic-password -a "$USER" -s "NUGET_API_KEY" -w 2>/dev/null +``` + +Sicherer lokaler Publish-Flow: +```bash +EXPECTED_VERSION=X.Y.Z bash tools/ci/publish_nuget_local.sh +``` + +Hinweise: +- Token nie ausgeben oder in Logs schreiben. +- `dotnet nuget push` läuft mit `--skip-duplicate`. +- Nach Push führt der Helper eine SVT-Onlineprüfung aus. + +## F) Troubleshooting +- `404` bei Registration/Flatcontainer kann durch Replikationsverzögerung entstehen; der Verifier retried deterministisch. +- Bei Versionsabweichung (`expected != actual`) failt der Gate vor Publish; Version-Quelle (Tag/Pack-Overrides) korrigieren. +- Wenn direkt nach Publish `missing_version` erscheint, ist das meist NuGet-Propagation. Für Incident-Checks: + ```bash + EXPECTED_VERSION=X.Y.Z VERIFY_ONLINE=1 RETRY_COUNT=60 RETRY_SLEEP_SECONDS=10 bash tools/ci/verify_nuget_release.sh + ``` +- Release-Gate-4 prüft Search bewusst nicht blockierend. Search-Konvergenz wird separat im Async-Workflow geprüft und bei Fehlern als Incident eskaliert. + +## G) Runbook: RC-Version in Visual Studio nicht sichtbar +Symptom: +- NuGet-Package-Manager zeigt nur stabile Versionen (z. B. `Aktuellste stabile Version`). + +Determinische Ursache: +- Pre-Release-Filter ist in der Visual-Studio-Ansicht nicht aktiv oder lokale Metadaten sind veraltet. + +Schritte: +1. Im NuGet-Package-Manager `Include prerelease` aktivieren. +2. Quelle prüfen: [NuGet v3 Index](https://api.nuget.org/v3/index.json). +3. Lokalen Cache leeren: + ```bash + dotnet nuget locals all --clear + ``` +4. Visual Studio neu starten und Paketliste aktualisieren. +5. Falls weiterhin unsichtbar, Version explizit pinnen: + ```xml + + + + ``` + +Verifikation: +- Search ohne Pre-Release-Flag zeigt nur stabile Versionen. +- Search mit `prerelease=true&semVerLevel=2.0.0` zeigt RC-Versionen. diff --git a/docs/0_de/audit/000_HASHING_BASELINE.MD b/docs/0_de/audit/000_HASHING_BASELINE.MD new file mode 100644 index 00000000..cff511dc --- /dev/null +++ b/docs/0_de/audit/000_HASHING_BASELINE.MD @@ -0,0 +1,93 @@ + +[DE](000_HASHING_BASELINE.MD) | [EN](../../1_en/audit/000_HASHING_BASELINE.MD) + + +# Hashing-Baseline Evidence (Historischer Snapshot: vor EvidenceHashing-Rename) + +Erfasst am: 2026-02-10 + +Pinned Baseline-Commit (vor Rename): +- `373146f0d2c178533ea6ac442e6cc2a117cb4331` + +Rename-Commit (Deterministic* -> Evidence/Hash*): +- `7c6e94dad37b440c32386719e796d0bb6100c741` + +## Zweck und Scope +Dieses Dokument ist historische Evidence für das Verhalten der Hashing-Fassade und des Evidence-Modells **vor** dem public Rename: +- `DeterministicHashing` -> `EvidenceHashing` +- `DeterministicHash*` -> `Hash*` + +Es darf nicht als Beschreibung der aktuellen API-Oberfläche auf `main` verwendet werden. +SSOT für den aktuellen Stand: +- API-Surface: `docs/010_API_CORE.MD` +- Contract: `docs/contracts/001_CONTRACT_HASHING.MD` +- Implementation: `src/FileTypeDetection/EvidenceHashing.vb` +- Models: `src/FileTypeDetection/Abstractions/Hashing/*` + +## Verifikation (repo-lokal, deterministisch) +Alle Referenzen unten sind auf den Baseline-Commit gepinnt (via `git show`): + +```bash +BASE=373146f0d2c178533ea6ac442e6cc2a117cb4331 + +git show "$BASE":src/FileTypeDetection/DeterministicHashing.vb | nl -ba | sed -n '1,260p' +git show "$BASE":src/FileTypeDetection/Abstractions/Hashing/DeterministicHashEvidence.vb | nl -ba | sed -n '1,220p' +git show "$BASE":src/FileTypeDetection/Abstractions/Hashing/DeterministicHashDigestSet.vb | nl -ba | sed -n '1,240p' +git show "$BASE":src/FileTypeDetection/Abstractions/Hashing/DeterministicHashOptions.vb | nl -ba | sed -n '1,240p' +git show "$BASE":src/FileTypeDetection/Abstractions/Hashing/DeterministicHashRoundTripReport.vb | nl -ba | sed -n '1,260p' +git show "$BASE":src/FileTypeDetection/Abstractions/Hashing/DeterministicHashSourceType.vb | nl -ba | sed -n '1,120p' +``` + +## Baseline-Fassade (vor Rename) +Pinned File (Baseline-Commit): +- `src/FileTypeDetection/DeterministicHashing.vb` @ `373146f0` + +Ausgewählte public Entrypoints (Baseline): +- `HashFile(path)` / `HashFile(path, options)` +- `HashBytes(data)` / `HashBytes(data, label, options)` +- `HashEntries(entries, label, options)` +- `VerifyRoundTrip(path, options)` + +## Semantik der kanonischen Bytes (Baseline) +Pinned File: `src/FileTypeDetection/DeterministicHashing.vb` @ `373146f0` + +Raw-Payload-Mode (`BuildEvidenceFromRawPayload`): +- Physical SHA-256 und Logical SHA-256 werden beide aus denselben `safePayload` Bytes berechnet. +- Fast-Hashes werden beide aus denselben `safePayload` Bytes berechnet. + +Archive/Entries-Mode (`BuildEvidenceFromEntries`): +- Logical Bytes sind ein kanonisches Manifest (`BuildLogicalManifestBytes`) aus normalisierten Entries. +- Physical Bytes sind die Original-Archive-Bytes nur dann, wenn `compressedBytes` vorhanden und nicht leer ist. + +Kanonische Manifest-Struktur: +- Enthält `LogicalManifestVersion` Header und Entry-Count. +- Pro Entry: schreibt Path-Bytes + Content-Length + SHA-256(content) Bytes. + +Formatierung: +- SHA-256 Hex: lowercase (`ToLowerInvariant()` nach `Convert.ToHexString(...)`). +- xxHash3: lowercase fixed-width `x16` via `ToString("x16", CultureInfo.InvariantCulture)`. +- Wenn `IncludeFastHash` false ist (oder options null), sind Fast-Digests leer. + +## Evidence-Model Types (Baseline-Namen) +Pinned Files @ `373146f0`: +- `src/FileTypeDetection/Abstractions/Hashing/DeterministicHashDigestSet.vb` +- `src/FileTypeDetection/Abstractions/Hashing/DeterministicHashEvidence.vb` +- `src/FileTypeDetection/Abstractions/Hashing/DeterministicHashOptions.vb` +- `src/FileTypeDetection/Abstractions/Hashing/DeterministicHashRoundTripReport.vb` +- `src/FileTypeDetection/Abstractions/Hashing/DeterministicHashSourceType.vb` + +## Current Implementation Pointers (nach Rename) +Aktuelle Fassade + Models auf `main`: +- `src/FileTypeDetection/EvidenceHashing.vb` +- `src/FileTypeDetection/Abstractions/Hashing/HashDigestSet.vb` +- `src/FileTypeDetection/Abstractions/Hashing/HashEvidence.vb` +- `src/FileTypeDetection/Abstractions/Hashing/HashOptions.vb` +- `src/FileTypeDetection/Abstractions/Hashing/HashRoundTripReport.vb` +- `src/FileTypeDetection/Abstractions/Hashing/HashSourceType.vb` + +## Baseline-Tests +Historisches Kommando (Baseline): +- `dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj -v minimal` + +Hinweis: +- Die aktuelle Test-Suite-Größe und exakte Counts können von der Baseline abweichen; der autoritative Check ist der CI-Job `tests-bdd-coverage` und lokal `dotnet test` auf `main`. diff --git a/docs/0_de/audit/000_INDEX.MD b/docs/0_de/audit/000_INDEX.MD new file mode 100644 index 00000000..f637d9f7 --- /dev/null +++ b/docs/0_de/audit/000_INDEX.MD @@ -0,0 +1,54 @@ + +[DE](000_INDEX.MD) | [EN](../../1_en/audit/000_INDEX.MD) + + +# Audit-Index + +## Zweck und Geltungsbereich +Zentraler Index für Nachweis-/Hardeningsdokumente, die Aussagen aus `SECURITY.md` belegbar machen, ohne `SECURITY.md` selbst zu ändern. +Zentrale Einstiegsseite für Dritte: `SECURITY_ASSURANCE_INDEX.md`. + +## Dokumente +- `docs/audit/000_HASHING_BASELINE.MD` +- `docs/audit/000_INDEX.MD` +- `docs/audit/002_AUDIT_CONTRACT_AND_GUARDRAILS.MD` +- `docs/audit/003_SECURITY_ASSERTION_TRACEABILITY.MD` +- `docs/audit/004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD` +- `docs/audit/005_CODE_ANALYSIS_METHOD.MD` +- `docs/audit/006_CODE_REVIEW_FINDINGS.MD` +- `docs/audit/007_THREAT_MODEL.MD` +- `docs/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD` +- `docs/audit/009_SUPPLY_CHAIN_BASELINE.MD` +- `docs/audit/010_REFACTOR_BACKLOG.MD` +- `docs/audit/011_SECURITY_BENCHMARK.MD` +- `docs/audit/012_WAVE_EXECUTION_DOD.MD` +- `docs/audit/013_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD` +- `docs/audit/014_EVIDENCE_REPORT_ISSUE_67.MD` +- `docs/audit/compat/001_NETSTANDARD2_POLICY_SNAPSHOT.MD` +- `docs/audit/compat/002_NETSTANDARD2_INVENTORY.MD` +- `docs/audit/compat/003_NETSTANDARD2_COMPAT_EVIDENCE.MD` + +## Maschinelle Nachweise +- `artifacts/ci/security-claims-evidence/` +- `artifacts/ci/code-analysis-evidence/` +- `artifacts/audit/code_inventory.json` +- `artifacts/audit/callgraph_inventory.json` +- `artifacts/audit/dead_code_candidates.json` +- `artifacts/audit/redundancy_candidates.json` +- `artifacts/audit/hardening_candidates.json` + +## Repro-Kommandos +Alle Kommandos sind für Ausführung im Repository-Root gedacht. +```bash +bash tools/audit/verify-security-claims.sh +bash tools/audit/verify-code-analysis-evidence.sh +bash tools/audit/generate-code-analysis-json.sh +python3 tools/check-docs.py +bash tools/versioning/verify-version-convergence.sh +``` + +## Externe Nachweise +- OpenSSF Scorecard Workflow: `.github/workflows/scorecard.yml` +- Artifact Attestations im Release-Workflow: `.github/workflows/release.yml` +- Deep Analysis Evidence Workflow: `.github/workflows/code-analysis-evidence.yml` +- GitHub Code Scanning Default Setup (state muss `not-configured` sein): `gh api "repos///code-scanning/default-setup"` diff --git a/docs/0_de/audit/002_AUDIT_CONTRACT_AND_GUARDRAILS.MD b/docs/0_de/audit/002_AUDIT_CONTRACT_AND_GUARDRAILS.MD new file mode 100644 index 00000000..46041eaa --- /dev/null +++ b/docs/0_de/audit/002_AUDIT_CONTRACT_AND_GUARDRAILS.MD @@ -0,0 +1,41 @@ + +[DE](002_AUDIT_CONTRACT_AND_GUARDRAILS.MD) | [EN](../../1_en/audit/002_AUDIT_CONTRACT_AND_GUARDRAILS.MD) + + +# Audit-Vertrag und Guardrails + +## 1. Zweck +Deterministische Evidence-Regeln für die Verifikation von Claims in `SECURITY.md`. + +## 2. Statusmodell +Statuswerte im Result-Contract: +- `pass`: keine blockierenden Verstöße. +- `fail`: mindestens ein blockierender Verstoss. +- `warn`: report-only Findings. + +Operationales Tri-State-Mapping (Claim-Engine): +- `pass` -> schema `pass` +- `fail` -> schema `fail` +- `unknown` -> schema `warn` with explicit reason code in `rule_violations[].message` + +## 3. Blocking-Policy +Blockierende Checks sind nur zulässig, wenn sie deterministisch sind. +Live GitHub API Checks sind blocker-eligible mit strikten Anti-Flake-Kontrollen: +- 3 retries +- exponential backoff (2s, 4s, 8s) +- current implementation emits generic API failure messages after retries + +Wenn alle Retries erschöpft sind: +- Blocker-Claims failen mit Reason-Code +- Report-only Claims emittieren `warn` + +## 4. Evidence-Contract +Erforderliche Artefakte pro Check: +- `raw.log` +- `summary.md` +- `result.json` (muss `tools/ci/schema/result.schema.json` matchen) + +## 5. Drift-Handling +- Policy-Drift ist fail-closed für Blocker-Claims. +- Unknown-States werden nie stillschweigend ignoriert. +- Jeder Failure muss einen Evidence-Pfad und ein reproduzierbares Kommando enthalten. diff --git a/docs/0_de/audit/003_SECURITY_ASSERTION_TRACEABILITY.MD b/docs/0_de/audit/003_SECURITY_ASSERTION_TRACEABILITY.MD new file mode 100644 index 00000000..2c8b3f42 --- /dev/null +++ b/docs/0_de/audit/003_SECURITY_ASSERTION_TRACEABILITY.MD @@ -0,0 +1,41 @@ + +[DE](003_SECURITY_ASSERTION_TRACEABILITY.MD) | [EN](../../1_en/audit/003_SECURITY_ASSERTION_TRACEABILITY.MD) + + +# Rückverfolgbarkeit: Sicherheitsaussagen (SECURITY.md) + +## Zweck und Geltungsbereich +Abbildung von Aussagen in `SECURITY.md` auf Nachweisquellen und Verifikationskommandos. + +| Claim ID | SECURITY-Anker | Claim-Zusammenfassung | Nachweisquelle | Verifikationskommando | Pass-Kriterium | Blocker | +|---|---|---|---|---|---|---| +| SEC-CLAIM-001 | 2. Unterstützte Versionen | Security-Support ist an Major 6 gebunden | `src/FileTypeDetection/FileTypeDetectionLib.vbproj` | `sed -n 's:.*\([^<]*\).*:\1:p' src/FileTypeDetection/FileTypeDetectionLib.vbproj` | Version-Major ist `6` | yes | +| SEC-CLAIM-002 | 3. Meldung | Private Vulnerability Reporting ist aktiv | GitHub API `private-vulnerability-reporting` | `gh api "repos/$REPO/private-vulnerability-reporting"` | `.enabled == true` | yes | +| SEC-CLAIM-003 | 9. Nachweisbarkeit | Dependabot Security Updates sind aktiv | GitHub API (`security_and_analysis` oder `automated-security-fixes`) | `gh api "repos/$REPO" --jq '.security_and_analysis.dependabot_security_updates.status' || gh api "repos/$REPO/automated-security-fixes" --jq '.enabled'` | `enabled` oder `true` | yes | +| SEC-CLAIM-004 | 9. Nachweisbarkeit | Secret Scanning ist aktiv | GitHub API (`security_and_analysis` oder Secret-Scanning-Alerts Endpoint) | `gh api "repos/$REPO" --jq '.security_and_analysis.secret_scanning.status' || gh api "repos/$REPO/secret-scanning/alerts?per_page=1"` | `enabled` oder Endpoint erfolgreich erreichbar | yes | +| SEC-CLAIM-005 | 9. Nachweisbarkeit | Required Status Checks/Contexts sind fixiert | GitHub API branch rules (primär), branch protection (Fallback) | `gh api "repos/$REPO/rules/branches/main" || gh api "repos/$REPO/branches/main/protection"` | erwartete Context-Liste vorhanden | yes | +| SEC-CLAIM-006 | 9. Nachweisbarkeit | CI-Gate `security-nuget` existiert | `.github/workflows/ci.yml` | `rg -n "security-nuget|run\\.sh security-nuget" .github/workflows/ci.yml` | Gate + Runner-Call existieren | yes | +| SEC-CLAIM-007 | 9. Nachweisbarkeit | OIDC Trusted Publishing ist konfiguriert | `.github/workflows/release.yml` | `rg -n "NuGet/login@v1|assert OIDC temp key present" .github/workflows/release.yml` | beide Marker vorhanden | yes | +| SEC-CLAIM-008 | 5. SLA | Reaktionsziel sind 5 Geschäftstage | Policy-Statement | manueller Policy-Review + Incident-Log-Review | gepflegte Prozess-Evidence existiert | report-only | +| SEC-CLAIM-009 | 6. Safe Harbor | Safe-Harbor Constraints sind dokumentiert | `SECURITY.md` + Runbook | `rg -n "Safe Harbor|gutgläubige" SECURITY.md` | Section vorhanden + Runbook aligned | report-only | +| SEC-CLAIM-010 | 7. Koordinierte Offenlegung | Koordinierter Disclosure-Prozess existiert | Runbook + Advisory-Usage | Review `docs/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD` | Workflow dokumentiert und umsetzbar | report-only | +| SEC-CLAIM-011 | 3. Meldung | Public Issue Tracker ist kein primärer Disclosure-Channel | `SECURITY.md` Policy-Text | `rg -n "nicht.*öffentliche Issues|Nicht unterstützte" SECURITY.md` | Policy-Text vorhanden | report-only | +| SEC-CLAIM-012 | 4. Erforderliche Angaben | Minimum-Reportfelder sind explizit gelistet | `SECURITY.md` Section 4 | `rg -n "Erforderliche Angaben|Reproduktionsschritte|Impact" SECURITY.md` | Section + Required Bullets vorhanden | report-only | +| SEC-CLAIM-013 | 9. Nachweisbarkeit | Lokale Minimum-Evidence-Kommandos sind ausführbar | Build/Test + Claim-Script | `dotnet build FileClassifier.sln -v minimal && dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj -c Release -v minimal && bash tools/audit/verify-security-claims.sh` | alle Kommandos exit 0 | yes | +| SEC-CLAIM-014 | 9. Nachweisbarkeit | Optionale erweiterte Check-IDs sind verfügbar | CI-Runner-Implementation | `rg -n "tests-bdd-coverage|api-contract|pack|consumer-smoke|package-backed-tests" tools/ci/bin/run.sh` | alle IDs resolvable | yes | +| SEC-CLAIM-015 | 1. Zweck/Geltungsbereich | ISO/IEC 29147 und 30111 Orientierung ist dokumentiert | Policy + Roadmap-Dokus | `rg -n "29147|30111" SECURITY.md docs/audit/004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD` | Referenzen vorhanden (ohne Zertifizierungsclaim) | report-only | +| SEC-CLAIM-016 | 9. Zertifizierungsgrenze | Es wird keine formale Produkt-Zertifizierung behauptet | `SECURITY.md` Section 9 | `rg -n "keine.*Zertifizierung|kein.*Rechtsgutachten" SECURITY.md` | expliziter Non-Claim vorhanden | yes | + +## Vollständigkeits-Hinweis +Claims, die normative Prozessaussagen sind (Policy-Intent), werden als `report-only` klassifiziert, solange sie nicht in deterministische maschinelle Checks überführt werden können. + +## CI-Claim-Abbildung +Das Verifikationsscript verwendet `CI-SEC-CLAIM-*` Rule-IDs. Mapping auf normative Claims: +- `CI-SEC-CLAIM-001` -> `SEC-CLAIM-002` (Repository/Reporting-Context ist auflösbar) +- `CI-SEC-CLAIM-002` -> `SEC-CLAIM-001` (Supported-Major-Version-Claim) +- `CI-SEC-CLAIM-003` -> `SEC-CLAIM-006` (CI-Gate `security-nuget` existiert) +- `CI-SEC-CLAIM-004` -> `SEC-CLAIM-007` (OIDC Trusted Publishing Marker) +- `CI-SEC-CLAIM-005` -> `SEC-CLAIM-003` (Dependabot Security Updates aktiv / äquivalenter Endpoint) +- `CI-SEC-CLAIM-006` -> `SEC-CLAIM-004` (Secret Scanning aktiv / äquivalenter Endpoint) +- `CI-SEC-CLAIM-007` -> `SEC-CLAIM-002` (Private Vulnerability Reporting aktiv) +- `CI-SEC-CLAIM-008` -> `SEC-CLAIM-005` (Required Status Checks Baseline) diff --git a/docs/0_de/audit/004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD b/docs/0_de/audit/004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD new file mode 100644 index 00000000..e87bf6aa --- /dev/null +++ b/docs/0_de/audit/004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD @@ -0,0 +1,63 @@ + +[DE](004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD) | [EN](../../1_en/audit/004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD) + + +# Roadmap: Zertifizierung und Attestationen + +## 1. Positionierung +Dieses Projekt unterscheidet: +- Assurance/Attestation-Evidence (technisch, reproduzierbar) +- Formale Third-Party-Zertifizierung (externer Audit, ausserhalb des aktuellen Scopes) + +Dieses Repository macht keinen formalen Zertifizierungs-Claim. + +## 2. Minimum Set (Wave 1) +1. OpenSSF Scorecard (kostenlos, extern, GitHub-nativ) +2. GitHub Artifact Attestations für Release-Artefakte +3. Dokumentierte Verifikationskommandos für Provenance/Attestationen + +## 3. Optional Set +- OpenSSF Best Practices Badge (Self-Attested Programm, extern sichtbar) + +## 4. NuGet-relevante Evidence +Alle Kommandos sind für Ausführung im Repository-Root gedacht. +- Paket-Signaturen verifizieren: +```bash +NUPKG="$(find artifacts/nuget -maxdepth 1 -type f -name '*.nupkg' | head -n 1)" +test -n "$NUPKG" +dotnet nuget verify "$NUPKG" +``` +- Build-Provenance Attestation verifizieren: +```bash +NUPKG="$(find artifacts/nuget -maxdepth 1 -type f -name '*.nupkg' | head -n 1)" +test -n "$NUPKG" +gh attestation verify "$NUPKG" --repo tomtastisch/FileClassifier +``` + +## 5. Akzeptanzkriterien +- Scorecard-Workflow läuft und speichert Artefakte. +- Release-Workflow emittiert Attestationen für nupkg-Artefakte. +- Verifikationskommandos sind dokumentiert und reproduzierbar. + +## 6. Code-Scanning-Mode-Constraint +Dieses Repository nutzt GitHub Code Scanning Advanced Setup (workflow-basierte CodeQL Analyse) und erfordert, +dass GitHub Code Scanning Default Setup deaktiviert bleibt (state: `not-configured`). +Wenn Default Setup aktiv ist, können Advanced-CodeQL SARIF Uploads von GitHub abgelehnt werden. + +Operative Regeln für dieses Repo: +- Default Setup für CodeQL deaktiviert halten (siehe `docs/security/010_CODEQL_DEFAULT_SETUP_GUARDRAIL.MD`). +- Default-Setup-Drift als fail-closed Blocker behandeln und vor Merge/Release beheben. +- Nicht-CodeQL SARIF Uploads (z. B. OpenSSF Scorecard SARIF) sind zulässig. + +## 7. OpenSSF-Scorecard-Constraint für Third-Party GitHub Actions +- Score-Werte, die z. B. `actions/dependency-review-action` für wiederverwendete GitHub Actions zeigt, werden aus den Upstream-Action-Repositories berechnet (nicht aus diesem Repository). +- Dieses Repository kann SHA-Pinning durchsetzen und Actions auswählen, aber nicht direkt Upstream-Scorecard-Werte erhöhen. + +Operatives Handling: +- PR-Kommentare enthalten keine OpenSSF Scorecard Tabelle (`show-openssf-scorecard: false`). +- Warning-Threshold bleibt definiert (`warn-on-openssf-scorecard-level: 9`) als machine-readable Policy-Intent. + +Repro-Kommando für Upstream-Scores: +```bash +curl -fsSL "https://api.securityscorecards.dev/projects/github.com/actions/checkout" | jq -r '.date,.score,.repo.name' +``` diff --git a/docs/0_de/audit/005_CODE_ANALYSIS_METHOD.MD b/docs/0_de/audit/005_CODE_ANALYSIS_METHOD.MD new file mode 100644 index 00000000..3e7b1b94 --- /dev/null +++ b/docs/0_de/audit/005_CODE_ANALYSIS_METHOD.MD @@ -0,0 +1,16 @@ + +[DE](005_CODE_ANALYSIS_METHOD.MD) | [EN](../../1_en/audit/005_CODE_ANALYSIS_METHOD.MD) + + +# Code-Analyse-Methode + +## 1. Ziel +Reproduzierbare File-Level- und Line-Level-Analyseartefakte erzeugen, ohne die public API zu ändern. + +## 2. Machine Outputs (nur JSON) +Erzeugt durch `tools/audit/generate-code-analysis-json.sh`: +- `artifacts/audit/code_inventory.json` +- `artifacts/audit/callgraph_inventory.json` +- `artifacts/audit/dead_code_candidates.json` +- `artifacts/audit/redundancy_candidates.json` +- `artifacts/audit/hardening_candidates.json` diff --git a/docs/0_de/audit/006_CODE_REVIEW_FINDINGS.MD b/docs/0_de/audit/006_CODE_REVIEW_FINDINGS.MD new file mode 100644 index 00000000..b57233be --- /dev/null +++ b/docs/0_de/audit/006_CODE_REVIEW_FINDINGS.MD @@ -0,0 +1,67 @@ + +[DE](006_CODE_REVIEW_FINDINGS.MD) | [EN](../../1_en/audit/006_CODE_REVIEW_FINDINGS.MD) + + +# Code-Review Findings + +## Zweck und Scope +Wave-1 Baseline-Findings aus JSON-Analyseartefakten. + +## Aktueller Stand +Package A (Cluster 7C) hat generische Entry-Point-Catches für die gescopten Files entfernt (merged 2026-02-15). +Package B (Cluster 7C) reduziert duplizierte Archive/Stream-Guard-Fragmente in `Infrastructure/*` bei unverändertem Verhalten. +Evidence-backed Kandidaten werden getrackt in: +- `artifacts/audit/dead_code_candidates.json` +- `artifacts/audit/redundancy_candidates.json` +- `artifacts/audit/hardening_candidates.json` +- `artifacts/ci/code-analysis-evidence/result.json` + +## Baseline-Findings (Wave 1) +1. Generische `Catch ex As Exception` Nutzung wurde aus den Package-A Entry-Point-Files entfernt (`FileTypeDetector`, `FileMaterializer`, `EvidenceHashing`). + Verbleibende broad catches benötigen Follow-up in Infrastructure-Internals (Package B/C Scope). + - Beispiele: + - `src/FileTypeDetection/Infrastructure/CoreInternals.vb:58` + - `src/FileTypeDetection/Infrastructure/ArchiveManagedInternals.vb:70` + - `src/FileTypeDetection/Infrastructure/ArchiveInternals.vb:99` + - `src/FileTypeDetection/Infrastructure/ArchiveInternals.vb:201` + - `src/FileTypeDetection/Infrastructure/ArchiveInternals.vb:546` + - Evidence: `artifacts/audit/hardening_candidates.json` + +2. Wiederholte Long-Line-Patterns deuten auf potenzielle Guard-/Path-Handling-Duplikation in Archive- und Detector-Internals hin. + - Beispiele: + - `src/FileTypeDetection/Infrastructure/CoreInternals.vb:66` + - `src/FileTypeDetection/Infrastructure/ArchiveManagedInternals.vb:29` + - `src/FileTypeDetection/Infrastructure/ArchiveInternals.vb:109` + - Evidence: `artifacts/audit/redundancy_candidates.json` + - Status: Package B konsolidiert wiederholte Stream-Guards via `StreamGuard` (SSOT) und ersetzt duplizierte `stream.CanRead`/Rewind-Patterns in den gescopten `Infrastructure/*` Files. + +3. Dead-Code-Kandidaten-Scan lieferte unter der implementierten Heuristik aktuell keine low-reference Source-Declarations in `src/`. + - Evidence: `artifacts/audit/dead_code_candidates.json` + +4. `DetectDetailed(...).ReasonCode` nutzte einen generischen Bucket `"Exception"` für unterschiedliche Exception-Klassen (IO, Security, Argument, etc.). + - Impact: reduzierte Auditierbarkeit von fail-closed Pfaden (Root-Causes waren im Ergebnis nicht unterscheidbar). + - Status: Package C mappt File-Access-Exceptions auf deterministische, typisierte Reason-Codes. + +## Repro-Evidence-Kommandos +Alle Kommandos sind für Ausführung im Repository-Root gedacht. +```bash +bash tools/audit/verify-code-analysis-evidence.sh +jq '.candidates | length' artifacts/audit/hardening_candidates.json +jq '.candidates | length' artifacts/audit/redundancy_candidates.json +rg -n "Catch\\s+ex\\s+As\\s+Exception" src/FileTypeDetection/FileTypeDetector.vb src/FileTypeDetection/FileMaterializer.vb src/FileTypeDetection/EvidenceHashing.vb +rg -n "If\\s+stream\\s+Is\\s+Nothing\\s+OrElse\\s+Not\\s+stream\\.CanRead" src/FileTypeDetection/Infrastructure/ArchiveManagedInternals.vb src/FileTypeDetection/Infrastructure/ArchiveInternals.vb +rg -n "If\\s+stream\\.CanSeek\\s+Then\\s+stream\\.Position\\s*=\\s*0" src/FileTypeDetection/Infrastructure/ArchiveManagedInternals.vb src/FileTypeDetection/Infrastructure/ArchiveInternals.vb +``` + +## Findings-Format (für die nächsten PRs) +- ID +- file + line +- reproduzierbares Evidence-Kommando +- impact/risk +- proposed change +- required regression tests + +## Prioritäts-Policy +- P1: Security-Korrektheit oder Behavioral-Risk +- P2: wahrscheinlich dead/redundant code mit mittlerer Confidence +- P3: Readability/Perf Opportunities mit geringem Risiko diff --git a/docs/0_de/audit/007_THREAT_MODEL.MD b/docs/0_de/audit/007_THREAT_MODEL.MD new file mode 100644 index 00000000..638411a1 --- /dev/null +++ b/docs/0_de/audit/007_THREAT_MODEL.MD @@ -0,0 +1,76 @@ + +[DE](007_THREAT_MODEL.MD) | [EN](../../1_en/audit/007_THREAT_MODEL.MD) + + +# Threat Model + +## 1. Zweck und Scope +In scope: +- Library-Verhalten in `src/FileTypeDetection/*` +- CI/CD und Release-Kontrollen in `.github/workflows/*` +- Security Reporting und Evidence-Lifecycle in `SECURITY.md` und `docs/audit/*` + +Out of scope: +- Downstream Deployment-Hardening von konsumierenden Systemen +- Host-Level-Kontrollen ausserhalb dieses Repositories + +## 2. Assets +- A1: Untrusted File-Payloads, die in Detection-/Extraction-Pfade gelangen +- A2: Extrahierte Archive-Entries im Memory +- A3: Hash-/Evidence-Artefakte für Integritäts-Assertions +- A4: Erzeugtes NuGet-Paket (`.nupkg`) und dessen Provenance +- A5: Vulnerability-Reports und Status der koordinierten Offenlegung + +## 3. Trust Boundaries +- B1: Caller-Input -> Detector/Archive-Internals (`src/FileTypeDetection/FileTypeDetector.vb`) +- B2: Repository-Source -> CI-Execution (`.github/workflows/ci.yml`) +- B3: CI-erzeugtes Paket -> NuGet Publication (`.github/workflows/release.yml`) +- B4: Externer Reporter -> Maintainer-Triage (GitHub Private Vulnerability Reporting) + +## 4. Attacker Capabilities +- C1: Crafted Files/Archives einspeisen, um unsafe Parsing/Extraction-Logik zu triggern +- C2: Path Traversal oder Resource Exhaustion über Archive-Payloads versuchen +- C3: Supply-Chain-Tampering zwischen Build und Publication versuchen +- C4: Disclosure-Abuse über öffentliche Kanäle vor Fix-Readiness versuchen + +## 5. Threat Scenarios und Kontrollen +- T1: Archive Traversal (zip-slip style path escape) + - Impact: Write/Read ausserhalb des intended Scope während der Extraktion. + - Current controls: fail-closed Archive-Safety-Gates in Archive-Internals und Detector-Pfaden; Extraction-APIs sind auf sichere Flows eingeschränkt. + - Evidence: `tests/FileTypeDetectionLib.Tests/*` plus CI-Job `tests-bdd-coverage` in `.github/workflows/ci.yml`. +- T2: Decompression/Resource Exhaustion + - Impact: Memory/CPU Pressure, möglicher Denial-of-Service. + - Current controls: guarded Archive-Processing-Pfade und bounded Validation/Extraction-Flows. + - Evidence: Source-Pfade unter `src/FileTypeDetection/Infrastructure/*` und CI Execution Traces. +- T3: Release-Artifact Provenance Tampering + - Impact: Consumer installieren untrusted Package-Build-Output. + - Current controls: OIDC Trusted Publishing und Provenance Attestation in `.github/workflows/release.yml`. + - Evidence: Release-Workflow Step `actions/attest-build-provenance@v2` und `gh attestation verify` Output-Artefakt. +- T4: Vulnerable Dependency Ingress + - Impact: bekannte vulnerable transitive Komponenten im shipped Package. + - Current controls: CI-Gate `security-nuget` (`dotnet list ... --vulnerable --include-transitive`) mit High/Critical fail behavior. + - Evidence: `tools/ci/bin/run.sh` (`run_security_nuget`) und CI-Artefakte `artifacts/ci/security-nuget/*`. +- T5: Unkoordinierte Public Disclosure vor Patch + - Impact: Exploitability-Window erhöht sich, bevor Mitigation verfügbar ist. + - Current controls: Private Vulnerability Reporting Path und Coordinated Disclosure Prozess (wie in `SECURITY.md` deklariert). + - Evidence: `tools/audit/verify-security-claims.sh` Claim-Checks und `docs/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD`. + +## 6. Annahmen +- Maintainer-Access-Controls und Repo-Permissions bleiben korrekt konfiguriert. +- GitHub-hosted Security-Features bleiben für das Repository verfügbar. +- Consumer setzen ihre eigenen Runtime-Hardening-Kontrollen um; dieses Repository kann sie nicht erzwingen. + +## 7. Residual Risks +- R1: Runtime Denial-of-Service Risk kann für hostile Inputs nur reduziert, nicht eliminiert werden. +- R2: Organisatorische Response-Speed hängt von Maintainer-Verfügbarkeit ab. +- R3: Third-Party-Platform-Outages können Triage/Release-Aktionen verzögern. + +## 8. Reproduzierbare Verifikation +Alle Kommandos sind für Ausführung im Repository-Root gedacht. +```bash +bash tools/audit/verify-security-claims.sh +bash tools/ci/bin/run.sh security-nuget +NUPKG="$(find artifacts/nuget -maxdepth 1 -type f -name '*.nupkg' | head -n 1)" +test -n "$NUPKG" +gh attestation verify "$NUPKG" --repo tomtastisch/FileClassifier +``` diff --git a/docs/0_de/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD b/docs/0_de/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD new file mode 100644 index 00000000..b0e344b7 --- /dev/null +++ b/docs/0_de/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD @@ -0,0 +1,78 @@ + +[DE](008_INCIDENT_RESPONSE_RUNBOOK.MD) | [EN](../../1_en/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD) + + +# Incident-Response-Runbook + +## 1. Trigger Events +- Private Vulnerability Report via GitHub Security Reporting +- CI-Security-Gate-Failure mit exploitablem Impact (`security-nuget`, Provenance-Verifikation oder äquivalent) +- glaubwürdiger externer Report zu aktiver Exploitation + +## 2. Rollen +- Incident Owner: Repository-Maintainer on duty +- Technical Triage: Maintainer mit Code-Area-Ownership +- Release Owner: Maintainer mit Release-Permissions +- Communications Owner: Maintainer, der Disclosure/Advisory-Text koordiniert + +## 3. SLA und Zeitziele +- Intake-Acknowledgement: innerhalb von 5 Geschäftstagen (gemäß `SECURITY.md`) +- Triage-Decision: so früh wie möglich nach bestätigter Reproduzierbarkeit +- Fix- und Disclosure-Timeline: risiko- und komplexitätsbasiert, koordiniert mit Reporter + +## 4. Severity-Modell (operational) +- Sev-1: bestätigte kritische Exploitability oder aktive Exploitation +- Sev-2: hoher Impact mit realistischem Exploit-Pfad +- Sev-3: mittel/niedriger Impact oder schwer ausnutzbare Bedingungen + +## 5. Vorgehen +1. Intake +- Report-Channel bestätigen und Duplicate/New-Case klassifizieren. +- Interne Tracking-Notiz mit Timestamp und Reporter-Kontext erstellen. + +2. Triage +- Reproduktion in isolierter Umgebung mit minimalem PoC. +- Betroffene Versionen und Impact-Surface bestimmen. + +3. Containment +- Temporäre Mitigations (Config/Workaround/Doku-Guardrails) definieren, falls Fix nicht unmittelbar ist. +- Kein Public-Issue-Disclosure vor abgestimmtem, koordiniertem Plan. + +4. Remediation +- Minimal-Risk-Patch in fokussierten Commit(s) implementieren. +- Regression-Tests für den Exploit-Pfad ergänzen/anpassen. + +5. Verifikation +- Security-relevante Checks ausführen und exakte Command-Outputs dokumentieren: + Alle Kommandos sind für Ausführung im Repository-Root gedacht. +```bash +dotnet build FileClassifier.sln -v minimal +dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj -c Release -v minimal +bash tools/ci/bin/run.sh security-nuget +bash tools/audit/verify-security-claims.sh +``` + +6. Release und Disclosure +- Advisory/Release Notes mit affected/fixed versions vorbereiten. +- Koordinierte Offenlegung veröffentlichen, sobald Fix-Verfügbarkeit bestätigt ist. + +7. Abschluss +- Post-Incident Summary, Root Cause und Follow-ups dokumentieren. +- Fix-Commit(s), Tests und Evidence-Artefakte verlinken. + +## 6. Evidence-Checkliste +- Timeline mit UTC Timestamps +- Severity-Assignment inkl. Begründung +- Affected Version Range und Fixed Version +- Repro-Schritte und Verifikationskommandos +- Commit-SHAs und PR-Referenzen +- Advisory/Disclosure-Referenz + +## 7. Evidence Storage +- CI-Artefakte: `artifacts/ci/*` +- Claim-Evidence: `artifacts/ci/security-claims-evidence/*` +- Package/Release-Evidence: `artifacts/nuget/*` (wenn verfügbar) + +## 8. Non-Goals +- Dieses Runbook ist keine Rechtsberatung. +- Dieses Runbook behauptet für sich genommen keine formale Zertifizierung oder regulatorische Abdeckung. diff --git a/docs/0_de/audit/009_SUPPLY_CHAIN_BASELINE.MD b/docs/0_de/audit/009_SUPPLY_CHAIN_BASELINE.MD new file mode 100644 index 00000000..586d7120 --- /dev/null +++ b/docs/0_de/audit/009_SUPPLY_CHAIN_BASELINE.MD @@ -0,0 +1,77 @@ + +[DE](009_SUPPLY_CHAIN_BASELINE.MD) | [EN](../../1_en/audit/009_SUPPLY_CHAIN_BASELINE.MD) + + +# Supply-Chain-Basislinie + +## 1. Ziel +Minimum an reproduzierbaren Kontrollen für Source-to-Package-Integrität in diesem Repository definieren. + +## 2. Kontroll-Basislinie +- S1 Source-Integrität: + - Branch-Protections und Required Status Checks auf dem Default-Branch + - deterministische CI-Gates (`preflight`, `build`, `security-nuget`, `summary`) +- S2 Build-Integrität: + - `dotnet restore --locked-mode` in CI/Release-Pfaden + - fail-closed Policy-Checks in `tools/ci/bin/run.sh` +- S3 Release-Integrität: + - OIDC Trusted Publishing in `.github/workflows/release.yml` + - Provenance Attestation via `actions/attest-build-provenance@v2` +- S4 Vulnerability Hygiene: + - NuGet Vulnerability Gate (`security-nuget`) + - Security-Claims-Verifikation (`security-claims-evidence`) + +## 3. Nachweis-Abbildung +- E1 CI-Workflow-Nachweise: + - `.github/workflows/ci.yml` + - `artifacts/ci/*` +- E2 Security-Claim-Nachweise: + - `.github/workflows/security-claims-evidence.yml` + - `artifacts/ci/security-claims-evidence/result.json` +- E3 Code-Analysis-Nachweise: + - `.github/workflows/code-analysis-evidence.yml` + - `artifacts/ci/code-analysis-evidence/result.json` +- E4 Release/Provenance-Nachweise: + - `.github/workflows/release.yml` + - `artifacts/nuget/attestation-verify.txt` (wenn der Release-Workflow läuft) +- E5 Dependency-Canary-Nachweise: + - `.github/workflows/dependency-canary.yml` + - Workflow-Artefakte `canary-*` mit Qodana-Contract-Output (`artifacts/ci/qodana/`) + - Laufhistorie: https://github.com/tomtastisch/FileClassifier/actions/workflows/dependency-canary.yml + +## 4. Verifikationskommandos +Alle Kommandos sind für Ausführung im Repository-Root gedacht. +```bash +bash tools/ci/bin/run.sh security-nuget +bash tools/audit/verify-security-claims.sh +bash tools/audit/verify-code-analysis-evidence.sh +NUPKG="$(find artifacts/nuget -maxdepth 1 -type f -name '*.nupkg' | head -n 1)" +test -n "$NUPKG" +dotnet nuget verify "$NUPKG" +gh attestation verify "$NUPKG" --repo tomtastisch/FileClassifier +# Optionaler Canary-Nachweis: +gh run list --workflow dependency-canary.yml --limit 5 +``` + +## 5. Operative Kadenz +- Jede PR: CI, Security-Claims und Code-Analysis Evidence Workflows +- Jeder Release: Attestation-Generierung und Verifikation +- Regelmäßiger Review: Baseline-Dokus aktualisieren, wenn sich Controls oder Workflows ändern + +## 6. Grenzen und Limits +- Diese Basislinie liefert Assurance-Nachweise, keine formale Third-Party-Zertifizierung. +- Downstream Runtime-Hardening bleibt Verantwortung von Deployern/Operatoren. + +## 7. Dependency-Strategie für netstandard2.0-Transitives +- D1 Kontrollierte Pinning-Strategie: + - `System.Text.Encoding.CodePages` wird explizit als direkte Abhängigkeit gepinnt (SSOT: `Directory.Packages.props`), damit SharpCompress-bezogene Encoding-Pfade nicht von impliziten Transitives abhängen. +- D2 Dokumentierte Ausnahme (Meta-Paket): + - `Microsoft.NETCore.Platforms` bleibt als `netstandard2.0`-Transitiv aus `NETStandard.Library` sichtbar. + - Diese Abweichung wird aktuell akzeptiert, da sie aus dem TFM-Meta-Paket stammt und nicht als eigenständiger Runtime-Upgrade-Pfad für das Produkt genutzt wird. + - Security-Gate bleibt fail-closed: jede neue High/Critical-Vulnerability in diesem Pfad bleibt blocker. + +Verifikationskommandos: +```bash +dotnet list FileClassifier.sln package --outdated --include-transitive +dotnet list FileClassifier.sln package --vulnerable --include-transitive +``` diff --git a/docs/0_de/audit/010_REFACTOR_BACKLOG.MD b/docs/0_de/audit/010_REFACTOR_BACKLOG.MD new file mode 100644 index 00000000..57b6a310 --- /dev/null +++ b/docs/0_de/audit/010_REFACTOR_BACKLOG.MD @@ -0,0 +1,89 @@ + +[DE](010_REFACTOR_BACKLOG.MD) | [EN](../../1_en/audit/010_REFACTOR_BACKLOG.MD) + + +# Refactor-Backlog (Cluster 7C) + +## 1. Quelle +Der Backlog wird abgeleitet aus: +- `artifacts/audit/hardening_candidates.json` +- `artifacts/audit/redundancy_candidates.json` +- `docs/audit/006_CODE_REVIEW_FINDINGS.MD` + +Baseline Snapshot (2026-02-15, vor Package A): +- hardening candidates: `21` +- redundancy candidates: `18` +- dead-code candidates: `0` + +Current Snapshot (2026-02-15, nach Package A): +- hardening candidates: `12` + +Repro (repo root): +```bash +bash tools/audit/verify-code-analysis-evidence.sh +jq '.candidates | length' artifacts/audit/hardening_candidates.json +``` + +## 2. Priorisierte PR-Packages + +### Package A (P1) - Broad exception catches in high-traffic entry points einengen +Scope candidates: +- `src/FileTypeDetection/FileTypeDetector.vb` +- `src/FileTypeDetection/FileMaterializer.vb` +- `src/FileTypeDetection/EvidenceHashing.vb` + +Rules: +- generisches `Catch ex As Exception` durch engere Exception-Behandlung ersetzen, wo deterministisch möglich +- fail-closed Verhalten beibehalten +- aktuelle public API und Return-Contracts erhalten + +Required checks: +Alle Kommandos sind für Ausführung im Repository-Root gedacht. +```bash +dotnet build FileClassifier.sln -v minimal +dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj -c Release -v minimal +bash tools/ci/bin/run.sh tests-bdd-coverage +``` + +### Package B (P2) - Archive/path guard duplication reduction +Scope candidates: +- `src/FileTypeDetection/Infrastructure/CoreInternals.vb` +- `src/FileTypeDetection/Infrastructure/ArchiveInternals.vb` +- `src/FileTypeDetection/Infrastructure/ArchiveManagedInternals.vb` + +Rules: +- duplizierte Guard-Fragmente nur konsolidieren, wenn das Verhalten auf Outputs byte-for-byte äquivalent bleibt +- fokussierte Regression-Tests für Guard-Edge-Cases ergänzen + +Required checks: +```bash +dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj -c Release --filter "Category=ApiContract" -v minimal +bash tools/ci/bin/run.sh package-backed-tests +bash tools/ci/bin/run.sh consumer-smoke +``` + +### Package C (P3) - Exception reason code normalization +Scope candidates: +- broad catch sites, die nach Package A bewusst generisch bleiben + +Rules: +- Exception-to-Result-Mapping mit deterministischen Reason-Codes anreichern +- keine versteckten Behavior-Changes im Success-Pfad + +Required checks: +```bash +dotnet build FileClassifier.sln -v minimal +dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj -c Release -v minimal +bash tools/audit/verify-code-analysis-evidence.sh +``` + +## 3. Ausführungsreihenfolge +1. Package A +2. Package B +3. Package C + +## 4. Definition of Done pro Package +- Targeted Code-Changes sind auf den Package-Scope begrenzt +- Regression-Tests sind für geänderte Behavior-Branches hinzugefügt/aktualisiert +- Full CI auf der PR ist grün +- `docs/audit/006_CODE_REVIEW_FINDINGS.MD` wurde mit geschlossenen/verschobenen Findings aktualisiert diff --git a/docs/0_de/audit/011_SECURITY_BENCHMARK.MD b/docs/0_de/audit/011_SECURITY_BENCHMARK.MD new file mode 100644 index 00000000..5cfd7acf --- /dev/null +++ b/docs/0_de/audit/011_SECURITY_BENCHMARK.MD @@ -0,0 +1,98 @@ + +[DE](011_SECURITY_BENCHMARK.MD) | [EN](../../1_en/audit/011_SECURITY_BENCHMARK.MD) + + +# Security-Policy-Benchmark (Stand: 2026-02-13) + +## 1. Ziel und Geltungsbereich +Vergleich der Security-Policy-Reife von `tomtastisch/FileClassifier` (PR-Branch `tomtastisch-patch-1`) mit verbreiteten .NET-Open-Source-Repositories anhand nachweisbarer GitHub- und Repository-Fakten. +Dieser Benchmark ist ein Snapshot vor dem Merge in `main` (Stand 2026-02-13). + +Verglichene Repositories: +- `tomtastisch/FileClassifier` +- `dotnet/runtime` +- `dotnet/aspnetcore` +- `JamesNK/Newtonsoft.Json` +- `DapperLib/Dapper` +- `serilog/serilog` +- `AutoMapper/AutoMapper` +- `App-vNext/Polly` +- `FluentValidation/FluentValidation` +- `xunit/xunit` +- `NLog/NLog` + +## 2. Methodik (nur faktenbasiert) +Erhoben über GitHub API und lokale Dateiinspektion: +- Vorhandensein `SECURITY.md` (FileClassifier: repo-root `SECURITY.md`; andere Repos ggf. alternativ `.github/SECURITY.md`) +- Status `private-vulnerability-reporting` +- Sichtbare `security_and_analysis`-Felder (`dependabot_security_updates`, `secret_scanning`) +- Vorhandensein `.github/dependabot.yml` +- Vorhandensein von Workflow-Dateien mit `codeql` im Dateinamen +- Inhaltsmerkmale der `SECURITY.md`: Support-Tabelle, Reporting, SLA-Zeitangaben, Safe Harbor, ISO/IEC 29147/30111, koordinierte Offenlegung + +## 3. Ergebnis A - Plattform-/Repository-Merkmale +| Repository | SECURITY.md | Private Vulnerability Reporting | Dependabot Security Updates | Secret Scanning | CodeQL Workflow-Datei | dependabot.yml | +|---|---|---|---|---|---|---| +| tomtastisch/FileClassifier | nein (Snapshot vor Merge in `main`) | true | enabled | enabled | nein | nein | +| dotnet/runtime | ja | false_or_unavailable | unknown | unknown | nein | ja | +| dotnet/aspnetcore | ja | false_or_unavailable | unknown | unknown | nein | ja | +| JamesNK/Newtonsoft.Json | nein | false_or_unavailable | unknown | unknown | ja | nein | +| DapperLib/Dapper | nein | false_or_unavailable | unknown | unknown | nein | nein | +| serilog/serilog | ja | true | unknown | unknown | nein | nein | +| AutoMapper/AutoMapper | nein | true | unknown | unknown | nein | nein | +| App-vNext/Polly | ja | true | unknown | unknown | nein | ja | +| FluentValidation/FluentValidation | nein | false_or_unavailable | unknown | unknown | nein | nein | +| xunit/xunit | nein | false_or_unavailable | unknown | unknown | nein | nein | +| NLog/NLog | ja | true | unknown | unknown | nein | ja | + +Hinweis: +- `unknown` bedeutet: Feld wird über GitHub API für das betrachtete Fremdrepo nicht veröffentlicht bzw. nicht sichtbar geliefert. +- `false_or_unavailable` bedeutet: API liefert für den Endpunkt keine aktive Konfiguration. + +## 4. Ergebnis B - SECURITY.md Inhaltsvergleich +| Repository | Support-Versionen | Reporting-Abschnitt | SLA-Zeitwerte | Safe Harbor | ISO/IEC 29147/30111 | Koordinierte Offenlegung | +|---|---|---|---|---|---|---| +| dotnet/runtime | ja | ja | ja | nein | nein | nein | +| dotnet/aspnetcore | ja | ja | ja | nein | nein | nein | +| serilog/serilog | ja | ja | nein | nein | nein | nein | +| App-vNext/Polly | nein | ja | ja | nein | nein | nein | +| NLog/NLog | ja | ja | nein | nein | nein | nein | +| tomtastisch/FileClassifier (lokal, PR) | ja | ja | ja | ja | ja | ja | + +## 5. Interpretation (faktennah) +- Die neue `SECURITY.md` von FileClassifier ist inhaltlich umfangreicher als die untersuchten Vergleichsdateien (insbesondere Safe Harbor, ISO/IEC-Orientierung, koordinierte Offenlegung). +- Snapshot-Hinweis: Zum Erhebungszeitpunkt lag die Datei im PR-Branch `tomtastisch-patch-1` und noch nicht in `main`. +- Repo-seitige Sicherheitsmechanismen sind für FileClassifier nachweisbar aktiv: + - Private Vulnerability Reporting (`enabled=true`) + - Dependabot Security Updates (`enabled`) + - Secret Scanning (`enabled`) + - CI-Sicherheitsgate `security-nuget` (lokal mit `pass` verifiziert) + +## 6. Rest-Gaps für "zertifizierungsnahe" Einsatzfähigkeit +Diese Punkte sind ausserhalb einer einzelnen `SECURITY.md`, aber notwendig für belastbare Audit-/Zertifizierungsfähigkeit: +- formaler SDLC-Nachweis (dokumentierte Rollen, Freigaben, Change-Management) +- Threat-Modeling-Artefakte mit regelmäßiger Aktualisierung +- Incident-Response-Runbooks mit Uebungen und Nachweisen +- SBOM/Provenance-Strategie für Releases (inkl. Aufbewahrung) +- formaler Nachweis für Produktionsbetriebskontrollen beim Betreiber + +## 7. Reproduzierbarkeit +Verwendete Kommandos (Auszug): +Alle Kommandos sind für die Ausführung im Repository-Root gedacht. +```bash +REPO="/" +gh api "repos/$REPO" +gh api "repos/$REPO/private-vulnerability-reporting" +gh api "repos/$REPO/contents/SECURITY.md" +gh api "repos/$REPO/contents/.github/SECURITY.md" +gh api "repos/$REPO/contents/.github/workflows" +gh api "repos/$REPO/contents/.github/dependabot.yml" +``` + +Lokale Verifikation für FileClassifier: +```bash +python3 tools/check-docs.py +dotnet build FileClassifier.sln -v minimal +dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj -c Release -v minimal +bash tools/ci/bin/run.sh security-nuget +``` diff --git a/docs/0_de/audit/012_WAVE_EXECUTION_DOD.MD b/docs/0_de/audit/012_WAVE_EXECUTION_DOD.MD new file mode 100644 index 00000000..eef19161 --- /dev/null +++ b/docs/0_de/audit/012_WAVE_EXECUTION_DOD.MD @@ -0,0 +1,54 @@ + +[DE](012_WAVE_EXECUTION_DOD.MD) | [EN](../../1_en/audit/012_WAVE_EXECUTION_DOD.MD) + + +# Wave Execution DoD Matrix + +Stand: 2026-02-13 +Scope: Finalisierung aller offenen Security-/Governance-Punkte nach Wave-Plan. + +## Cluster 0 - Guardrails & Contract +- DoD-0.1: `tools/ci/schema/result.schema.json` validiert alle erzeugten `result.json` in CI ohne Sonderfall-Bypass. +- DoD-0.2: Für jeden blockierenden Check existiert ein eindeutiger Fail-Reason im Artefakt (`rule_id`, `message`, `evidence_paths`). + +## Cluster 1 - SECURITY Truth Matrix +- DoD-1.1: Jede Aussage aus `SECURITY.md` hat eine `SEC-CLAIM-*`-Zuordnung in `docs/audit/003_SECURITY_ASSERTION_TRACEABILITY.MD`. +- DoD-1.2: Jede blocker-klassifizierte Aussage hat mindestens ein reproduzierbares Kommando mit `exit 0/!=0`-Kriterium. + +## Cluster 2 - Evidence Engine +- DoD-2.1: `bash tools/audit/verify-security-claims.sh` erzeugt `raw.log`, `summary.md`, `result.json` schema-valide. +- DoD-2.2: API-Fehler sind in Reason-Codes klassifiziert (`auth|rate-limit|network|5xx|unknown`). + +## Cluster 3 - CI Integration +- DoD-3.1: `security-claims-evidence` und `code-analysis-evidence` laufen auf `push` und `pull_request` gegen `main`. +- DoD-3.2: Blocker-Claims failen deterministisch; report-only Claims blockieren Merge nicht. + +## Cluster 4 - Externe Audits/Attestations +- DoD-4.1: OpenSSF Scorecard Workflow erzeugt SARIF und lädt Artefakte hoch. +- DoD-4.2: Release Workflow erzeugt und verifiziert Build-Attestation (`gh attestation verify`). + +## Cluster 5 - Sichtbarkeit Repo/NuGet +- DoD-5.1: Root-Nachweisdatei `SECURITY_ASSURANCE_INDEX.md` ist vorhanden und verlinkt alle Kern-Evidenzen. +- DoD-5.2: README enthält sichtbare Sektion `Security Assurance & Evidence` mit Audit-/Runbook-/Threat-Links. + +## Cluster 6 - CodeQL / Scanning Quality +- DoD-6.1: Für jeden Main-Commit laufen `Analyze (actions|csharp|javascript-typescript|python)` erfolgreich. +- DoD-6.2: Kein paralleler inkompatibler CodeQL-Uploadpfad (Default-Setup konfliktfrei dokumentiert/angewendet). + +## Cluster 7 - Deep Analysis (JSON-only) +- DoD-7.1: JSON-Artefakte `code_inventory|callgraph_inventory|dead_code_candidates|redundancy_candidates|hardening_candidates` werden erzeugt. +- DoD-7.2: Findings mit Datei+Zeile sind in `docs/audit/006_CODE_REVIEW_FINDINGS.MD` reproduzierbar referenziert. + +## Cluster 8 - Governance Closure +- DoD-8.1: Threat Model, Incident Runbook, Supply-Chain Baseline sind vorhanden und gegenseitig konsistent. +- DoD-8.2: Dokumente referenzieren reale, bestehende Workflows/Artefakte ohne Platzhalter. + +## Snapshot Warning Hardening (Dependency Review) +- DoD-SW.1: `dependency-review` verwendet `retry-on-snapshot-warnings: true`. +- DoD-SW.2: PR-Kommentar-Output erfolgt nur bei Failure (`comment-summary-in-pr: on-failure`), damit Warnhinweise nicht als Dauerrauschen erscheinen. +- DoD-SW.3: OpenSSF-Scorecard-Tabelle in PR-Kommentaren ist deaktiviert (`show-openssf-scorecard: false`), um nicht steuerbare Fremd-Repo-Scores nicht als Merge-Rauschen zu propagieren. +- DoD-SW.4: Policy-Schwelle für Action-Score ist explizit gesetzt (`warn-on-openssf-scorecard-level: 9`) und im Workflow nachweisbar. + +## Release Finalisierung +- DoD-R.1: Nach Merge ist Tag `v5.1.0` erstellt und Release-Pipeline erfolgreich abgeschlossen. +- DoD-R.2: `git version == nupkg version == nuget version` ist im Release-Artefakt nachweisbar. diff --git a/docs/0_de/audit/013_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD b/docs/0_de/audit/013_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD new file mode 100644 index 00000000..aeb9c4c6 --- /dev/null +++ b/docs/0_de/audit/013_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD @@ -0,0 +1,56 @@ + +[DE](013_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD) | [EN](../../1_en/audit/013_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD) + + +# Scorecard Governance Alert Mapping (Ruleset/Prozess) + +Stand: 2026-02-13 + +## Verifizierter Ist-Stand (2026-02-13) +- Branch Protection `main`: + - `required_pull_request_reviews.required_approving_review_count = 1` + - `require_code_owner_reviews = true` + - `require_last_push_approval = true` +- Fuzzing: + - Workflow `.github/workflows/fuzzing-baseline.yml` aktiv. + - Letzter manueller Nachweis-Run: `22003901268` (`success`). + +## Ziel +Diese Datei mappt die repo-/governance-basierten Scorecard-Alerts ohne konkrete Datei (`no file associated`) auf verifizierbare Repository-Regeln und Prozesse. + +## Scope +- `MaintainedID` +- `CodeReviewID` +- `BranchProtectionID` +- `FuzzingID` +- `CIIBestPracticesID` + +## Nicht im Scope +- Codezeilen-Analyzer-Hinweise (z. B. `UseCollectionExpression`, `RedundantQualifier`). +- File-basierte Alerts (`TokenPermissionsID`, `PinnedDependenciesID`), da separat in Code/Workflow gefixt. + +## Mapping (Claim -> Steuerung -> Evidence) + +| Alert-ID | Steuerung (Soll) | Aktuelle Umsetzung | Evidence (deterministisch) | DoD A | DoD B | +|---|---|---|---|---|---| +| `BranchProtectionID` | `main` nur via PR + required checks | Branch Protection/Ruleset aktiv, required checks konfiguriert | `gh api repos/tomtastisch/FileClassifier/branches/main/protection` | `required_status_checks` vorhanden | direkter Push auf `main` technisch blockiert | +| `CodeReviewID` | Mindestens 1 PR-Review vor Merge | PR-Review-Policy in Branch Protection/Ruleset | `gh api repos/tomtastisch/FileClassifier/branches/main/protection --jq '.required_pull_request_reviews'` | `required_approving_review_count >= 1` | Merge ohne Review nicht möglich | +| `MaintainedID` | Nachweis aktiver Wartung | Kontinuierliche Commits/Releases + aktive CI | `gh api repos/tomtastisch/FileClassifier/commits?per_page=20` und `gh api repos/tomtastisch/FileClassifier/actions/runs?per_page=20` | in den letzten 90 Tagen Commits vorhanden | in den letzten 30 Tagen erfolgreiche Workflow-Runs vorhanden | +| `FuzzingID` | Fuzzing-Baseline vorhanden (mind. report-only) | Workflow `.github/workflows/fuzzing-baseline.yml` | `gh workflow view fuzzing-baseline.yml --yaml` und `gh run list --workflow fuzzing-baseline.yml --limit 10` | Workflow existiert und ist ausführbar | mindestens ein erfolgreicher Run in den letzten 30 Tagen | +| `CIIBestPracticesID` | Prozess-/Security-Baseline dokumentiert und nachvollziehbar | Audit-/Governance-Docs + CI-Evidence + Security Policy | `ls docs/audit` + `bash tools/audit/verify-security-claims.sh` | Audit-Index vorhanden und verlinkt | Security-Claims-Evidence liefert `pass` für Blocker-Claims | + +## Hinweis zur Scorecard-Interpretation +- Diese Alerts bewerten Governance-Reife, nicht nur Codeinhalt. +- Ein Alert kann trotz technischer Teilumsetzung offen bleiben, wenn Scorecard öffentliche Signale anders gewichtet. +- Für Merge-Gates gelten nur intern deterministisch definierte Blocker-Checks. + +## Operativer Prozess (fail-closed) +1. Wöchentlicher Snapshot der offenen Scorecard-Alerts. +2. Für jeden Governance-Alert Evidence-Befehl ausführen und Artefakt in `artifacts/security/` persistieren. +3. Bei Drift (`fail`) sofortige Korrektur in Ruleset/Workflow. +4. Nach Korrektur Re-Run von Scorecard + Security-Claims-Evidence. +5. Merge-Gate: `security/code-scanning/tools` muss `0` offene Alerts liefern. + - Standard: Gate prüft `main` (verhindert Merges, solange `main` rot ist). + - Ausnahme für Remediation-PRs: PRs mit Label `area:qodana` prüfen die Alerts gegen den PR-Ref (`refs/pull//merge`), damit ein Qodana-Fix-PR trotz bereits rotem `main` mergebar bleibt. + - Implementierung: `tools/ci/check-code-scanning-tools-zero.sh` (ref-Auswahl über PR-Label). +6. Nicht technisch remediierbare Heuristik-Alerts (z. B. Repo-Alter `<90 Tage`) werden nur mit begründetem Dismissal-Kommentar geschlossen und im PR-Evidence protokolliert. diff --git a/docs/0_de/audit/014_EVIDENCE_REPORT_ISSUE_67.MD b/docs/0_de/audit/014_EVIDENCE_REPORT_ISSUE_67.MD new file mode 100644 index 00000000..c3f94e21 --- /dev/null +++ b/docs/0_de/audit/014_EVIDENCE_REPORT_ISSUE_67.MD @@ -0,0 +1,151 @@ + +[DE](014_EVIDENCE_REPORT_ISSUE_67.MD) | [EN](../../1_en/audit/014_EVIDENCE_REPORT_ISSUE_67.MD) + + +# Evidence Report — Issue #67 (Full Refactor & Production-Readiness Hardening) + +## 1. Ziel / Scope +Dieser Report ist das zentrale, reproduzierbare Evidence-Dokument für Issue #67. +Er umfasst: +- Baseline Snapshot (Repo-Status, Tool-Versionen, ausgeführte Checks) +- Inventory (Module/Dateien als machine-readable JSON) +- Findings (priorisiert, zitierbar, mit Evidence-Quelle) +- PR-Mapping (geplante/umgesetzte PR-Pakete) + +Nicht enthalten (Non-Goals): +- Keine Änderung von `SECURITY.md` (eingefroren). +- Keine Commit-basierten Artefakte unter `artifacts/` (werden reproduzierbar erzeugt und sind `.gitignore`d). + +## 2. Baseline Snapshot (Phase 0) +Snapshot-Commit: +- Commit: `0c78a9664a6f4abc7fd9d25da92d5c5c741aeb92` +- Datum (Commit): `2026-02-15 16:18:30 +0100` +- Branch (lokal): `codex/docs/issue-67-baseline-snapshot` + +Tooling (lokal, Baseline): +- dotnet SDK: `10.0.102` (siehe `global.json`) +- Node: `v25.5.0` +- Python: `3.14.2` +- jq: `jq-1.8.1` +- ripgrep: `15.1.0` +- gh: `2.86.0` + +ASSUMPTION: +- Tool-Versionen können sich lokal/CI unterscheiden (GitHub Actions verwendet `ubuntu-latest` + `actions/setup-*`). + Verifikation: Baseline wird in CI über die PR-Checks erzwungen (`.github/workflows/ci.yml`). + +## 3. Baseline Checks (Phase 0) +Alle Kommandos sind vom Repo-Root aus ausführbar. Artefakte werden unter `artifacts/ci//` erzeugt. + +Hinweis (CI-Governance): +- PR-Beschreibungen werden fail-closed validiert (Pflichtsektionen/Checklisten) via `tools/ci/check-pr-governance.sh`. + +Ausgeführte Checks (lokal) + Evidence-Pfade: +```bash +bash tools/ci/bin/run.sh preflight +bash tools/ci/bin/run.sh docs-links-full +bash tools/ci/bin/run.sh build +bash tools/ci/bin/run.sh api-contract +bash tools/ci/bin/run.sh pack +bash tools/ci/bin/run.sh consumer-smoke +bash tools/ci/bin/run.sh package-backed-tests +bash tools/ci/bin/run.sh security-nuget +bash tools/ci/bin/run.sh tests-bdd-coverage +bash tools/ci/bin/run.sh naming-snt +bash tools/ci/bin/run.sh versioning-svt +bash tools/ci/bin/run.sh version-convergence +``` + +Ergebnis (Baseline, lokal): PASS für alle oben genannten Checks. +Evidence: +- `artifacts/ci//summary.md` +- `artifacts/ci//result.json` +- `artifacts/ci//raw.log` + +Zusatz-Evidence (Audit): +```bash +bash tools/audit/verify-code-analysis-evidence.sh +bash tools/audit/verify-security-claims.sh +``` +Evidence: +- `artifacts/ci/code-analysis-evidence/summary.md` +- `artifacts/ci/security-claims-evidence/summary.md` + +## 4. Inventory & Semantics Map (Phase 1) +Machine Inventory (JSON, erzeugt durch `tools/audit/generate-code-analysis-json.sh`): +- `artifacts/audit/code_inventory.json` +- `artifacts/audit/callgraph_inventory.json` + +Snapshot-Metriken (aus Inventory JSON): +- Dateien (src, `.vb`/`.cs`): `22` +- LOC (src): `3918` +- Methoden-/Sub-Deklarationen (heuristisch): `683` + +Hinweis: +- Verantwortung/Intent pro Teilbereich ist in den Modul-READMEs dokumentiert, z. B.: + - `src/FileTypeDetection/README.md` + - `src/FileTypeDetection/Infrastructure/README.md` + - `src/FileTypeDetection/Detection/README.md` + - `src/FileTypeDetection/Configuration/README.md` + +## 5. Findings (Phase 2) +Quellen (reproduzierbar): +```bash +bash tools/audit/verify-code-analysis-evidence.sh +jq '.candidates | length' artifacts/audit/hardening_candidates.json +jq '.candidates | length' artifacts/audit/redundancy_candidates.json +jq '.candidates | length' artifacts/audit/dead_code_candidates.json +``` + +### Finding A (P1, hardening): Broad Exception Catches +Evidence: +- `artifacts/audit/hardening_candidates.json` + +Status (Baseline): +- Kandidaten: `21` +- Schwerpunkte (Count pro Datei): + - `src/FileTypeDetection/Infrastructure/ArchiveInternals.vb` (8) + - `src/FileTypeDetection/FileTypeDetector.vb` (5) + - `src/FileTypeDetection/FileMaterializer.vb` (3) + - `src/FileTypeDetection/Infrastructure/ArchiveManagedInternals.vb` (2) + - `src/FileTypeDetection/EvidenceHashing.vb` (1) + - `src/FileTypeDetection/FileTypeOptions.vb` (1) + - `src/FileTypeDetection/Infrastructure/CoreInternals.vb` (1) + +Risiko/Impact: +- Catch-all kann unerwartete/programmatische Fehler maskieren; gleichzeitig wird fail-closed Verhalten benötigt. + +Fix-Strategie (Package A): +- Catch-Scopes minimieren / differenzieren (wo deterministisch möglich). +- Catch-All nur als "non-fatal" Guard (fatal exceptions nicht schlucken) und mit klarer, stabiler Reason-Logik. +- Regression-Tests für fail-closed Branches/Reason-Codes. + +### Finding B (P2, maintainability): Guard/Path Handling Duplication +Evidence: +- `artifacts/audit/redundancy_candidates.json` + +Status (Baseline): +- Kandidaten: `18` (heuristisch; nicht jeder Eintrag ist actionable). + +Fix-Strategie (Package B): +- Duplikate nur konsolidieren, wenn Outputs byte-for-byte identisch bleiben. +- Edge-Case Regression-Tests für Guards (Traversal, Root, invalid path, staging cleanup). + +### Finding C (P3, report-only): Dead-Code Candidates +Evidence: +- `artifacts/audit/dead_code_candidates.json` + +Status (Baseline): +- Kandidaten: `0` (heuristikbasiert). + +## 6. PR-Mapping (Issue #67 Deliverables) +Geplante/iterative PR-Pakete (aus `docs/audit/010_REFACTOR_BACKLOG.MD`): +1. Package A (P1) - Narrow broad exception catches in high-traffic entry points +2. Package B (P2) - Archive/path guard duplication reduction +3. Package C (P3) - Exception reason code normalization + +Dieses Dokument ist PR-übergreifend; pro Package wird die Findings-/Status-Sektion aktualisiert. + +## 7. Decision Log +- 2026-02-15: Baseline Evidence wird ausschliesslich über reproduzierbare Kommandos + `artifacts/` erzeugt (nicht committen). +- 2026-02-15: Findings-Quelle ist initial JSON-Heuristik (`tools/audit/generate-code-analysis-json.sh`), nachfolgend durch zielgerichtete Tests/Evidence zu erharten. diff --git a/docs/0_de/audit/015_DOC_BILINGUAL_MAPPING.MD b/docs/0_de/audit/015_DOC_BILINGUAL_MAPPING.MD new file mode 100644 index 00000000..17a0114e --- /dev/null +++ b/docs/0_de/audit/015_DOC_BILINGUAL_MAPPING.MD @@ -0,0 +1,279 @@ + +[DE](015_DOC_BILINGUAL_MAPPING.MD) | [EN](../../1_en/audit/015_DOC_BILINGUAL_MAPPING.MD) + + +# Bilinguale Dokumentation: DE<->EN Mapping (0NN_ -> 1NN_) + +## 1. Ziel und Geltungsbereich +Dieser Report dokumentiert deterministisch das Mapping aller Dokumente nach dem Schema `NNN_*` (DE ist primär) auf ihre englischen Spiegeldateien `1NN_*`. + +Geltungsbereich: +- Betrifft alle Dokumente mit Dateinamen `NNN_.md` oder `NNN_.MD` (unabhängig vom Ordner). +- EN ist semantisch äquivalent zur DE-Version (gleiche Struktur/Abschnitte; Codeblöcke/Commands identisch). + +Nicht-Ziele: +- Keine Code-/Build-/CI-Änderungen (ausser Markdown-Linkfixes innerhalb von `.md/.MD`). + +## 2. Namensregeln (SSOT) +- DE-Datei: `0NN_.` mit dreistelliger Nummer `0NN` (z. B. `030_...`). +- EN-Datei: `1NN_.`. +- `NN` = letzte zwei Ziffern der DE-Nummer. +- `slug` und Extension bleiben identisch (deterministisches Mapping). + +Mapping-Funktion: +- `0NN_*` -> `1NN_*` (gleicher Ordner, gleicher `slug`, gleiche Extension). + +## 3. Bestand + Mapping-Tabelle +| DE_PFAD | EN_PFAD | STATUS | HINWEISE | +|---|---|---|---| +| `docs/001_INDEX_CORE.MD` | `docs/101_INDEX_CORE.MD` | vorhanden | | +| `docs/010_API_CORE.MD` | `docs/110_API_CORE.MD` | vorhanden | | +| `docs/020_ARCH_CORE.MD` | `docs/120_ARCH_CORE.MD` | vorhanden | | +| `docs/021_USAGE_NUGET.MD` | `docs/121_USAGE_NUGET.MD` | vorhanden | | +| `docs/audit/000_HASHING_BASELINE.MD` | `docs/audit/100_HASHING_BASELINE.MD` | vorhanden | | +| `docs/audit/000_INDEX.MD` | `docs/audit/100_INDEX.MD` | vorhanden | | +| `docs/audit/002_AUDIT_CONTRACT_AND_GUARDRAILS.MD` | `docs/audit/102_AUDIT_CONTRACT_AND_GUARDRAILS.MD` | vorhanden | | +| `docs/audit/003_SECURITY_ASSERTION_TRACEABILITY.MD` | `docs/audit/103_SECURITY_ASSERTION_TRACEABILITY.MD` | vorhanden | | +| `docs/audit/004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD` | `docs/audit/104_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD` | vorhanden | | +| `docs/audit/005_CODE_ANALYSIS_METHOD.MD` | `docs/audit/105_CODE_ANALYSIS_METHOD.MD` | vorhanden | | +| `docs/audit/006_CODE_REVIEW_FINDINGS.MD` | `docs/audit/106_CODE_REVIEW_FINDINGS.MD` | vorhanden | | +| `docs/audit/007_THREAT_MODEL.MD` | `docs/audit/107_THREAT_MODEL.MD` | vorhanden | | +| `docs/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD` | `docs/audit/108_INCIDENT_RESPONSE_RUNBOOK.MD` | vorhanden | | +| `docs/audit/009_SUPPLY_CHAIN_BASELINE.MD` | `docs/audit/109_SUPPLY_CHAIN_BASELINE.MD` | vorhanden | | +| `docs/audit/010_REFACTOR_BACKLOG.MD` | `docs/audit/110_REFACTOR_BACKLOG.MD` | vorhanden | | +| `docs/audit/011_SECURITY_BENCHMARK.MD` | `docs/audit/111_SECURITY_BENCHMARK.MD` | vorhanden | | +| `docs/audit/012_WAVE_EXECUTION_DOD.MD` | `docs/audit/112_WAVE_EXECUTION_DOD.MD` | vorhanden | | +| `docs/audit/013_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD` | `docs/audit/113_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD` | vorhanden | | +| `docs/audit/014_EVIDENCE_REPORT_ISSUE_67.MD` | `docs/audit/114_EVIDENCE_REPORT_ISSUE_67.MD` | vorhanden | | +| `docs/audit/015_DOC_BILINGUAL_MAPPING.MD` | `docs/audit/115_DOC_BILINGUAL_MAPPING.MD` | vorhanden | Mapping-Report-Dateipaar (DE->EN). | +| `docs/ci/001_PIPELINE_CI.MD` | `docs/ci/101_PIPELINE_CI.MD` | vorhanden | | +| `docs/ci/002_NUGET_TRUSTED_PUBLISHING.MD` | `docs/ci/102_NUGET_TRUSTED_PUBLISHING.MD` | vorhanden | | +| `docs/contracts/001_CONTRACT_HASHING.MD` | `docs/contracts/101_CONTRACT_HASHING.MD` | vorhanden | | +| `docs/governance/001_POLICY_CI.MD` | `docs/governance/101_POLICY_CI.MD` | vorhanden | | +| `docs/governance/002_POLICY_LABELING.MD` | `docs/governance/102_POLICY_LABELING.MD` | vorhanden | | +| `docs/governance/002_POLICY_NAMING_UNIFIED.MD` | `docs/governance/102_POLICY_NAMING_UNIFIED.MD` | vorhanden | | +| `docs/governance/003_INDEX_GOVERNANCE.MD` | `docs/governance/103_INDEX_GOVERNANCE.MD` | vorhanden | | +| `docs/governance/003_POLICY_VERSIONING_SVT.MD` | `docs/governance/103_POLICY_VERSIONING_SVT.MD` | vorhanden | | +| `docs/governance/004_POLICY_DOCUMENTATION.MD` | `docs/governance/104_POLICY_DOCUMENTATION.MD` | vorhanden | | +| `docs/governance/005_POLICY_NAMING.MD` | `docs/governance/105_POLICY_NAMING.MD` | vorhanden | | +| `docs/governance/006_INDEX_CI_RULES.MD` | `docs/governance/106_INDEX_CI_RULES.MD` | vorhanden | | +| `docs/governance/007_POLICY_BRANCH_PR_NAMING_DE.MD` | `docs/governance/107_POLICY_BRANCH_PR_NAMING_DE.MD` | vorhanden | | +| `docs/guides/000_INDEX_GUIDES.MD` | `docs/guides/100_INDEX_GUIDES.MD` | vorhanden | | +| `docs/guides/001_GUIDE_OPTIONS.MD` | `docs/guides/101_GUIDE_OPTIONS.MD` | vorhanden | | +| `docs/guides/002_GUIDE_DATATYPE.MD` | `docs/guides/102_GUIDE_DATATYPE.MD` | vorhanden | | +| `docs/guides/003_GUIDE_PORTABLE.MD` | `docs/guides/103_GUIDE_PORTABLE.MD` | vorhanden | | +| `docs/guides/004_GUIDE_MIGRATE_LEGACY_NUGET.MD` | `docs/guides/104_GUIDE_MIGRATE_LEGACY_NUGET.MD` | vorhanden | | +| `docs/migrations/001_HASHING_RENAME.MD` | `docs/migrations/101_HASHING_RENAME.MD` | vorhanden | | +| `docs/quality/001_CHECKLIST_PRODUCTION.MD` | `docs/quality/101_CHECKLIST_PRODUCTION.MD` | vorhanden | | +| `docs/references/001_REFERENCES_CORE.MD` | `docs/references/101_REFERENCES_CORE.MD` | vorhanden | | +| `docs/secure/001_HMAC_KEY_SETUP.MD` | `docs/secure/101_HMAC_KEY_SETUP.MD` | vorhanden | | +| `docs/security/010_CODEQL_DEFAULT_SETUP_GUARDRAIL.MD` | `docs/security/110_CODEQL_DEFAULT_SETUP_GUARDRAIL.MD` | vorhanden | | +| `docs/specs/001_SPEC_DIN.MD` | `docs/specs/101_SPEC_DIN.MD` | vorhanden | | +| `docs/verification/001_INDEX_TESTS.MD` | `docs/verification/101_INDEX_TESTS.MD` | vorhanden | | +| `docs/verification/002_FLOW_BDD.MD` | `docs/verification/102_FLOW_BDD.MD` | vorhanden | | +| `docs/verification/003_CATALOG_BDD.MD` | `docs/verification/103_CATALOG_BDD.MD` | vorhanden | | +| `docs/verification/004_MATRIX_HASHING.MD` | `docs/verification/104_MATRIX_HASHING.MD` | vorhanden | | +| `docs/versioning/001_POLICY_VERSIONING.MD` | `docs/versioning/101_POLICY_VERSIONING.MD` | vorhanden | | +| `docs/versioning/002_HISTORY_VERSIONS.MD` | `docs/versioning/102_HISTORY_VERSIONS.MD` | vorhanden | | +| `docs/versioning/003_CHANGELOG_RELEASES.MD` | `docs/versioning/103_CHANGELOG_RELEASES.MD` | vorhanden | | +| `docs/versioning/004_POLICY_LABELING.MD` | `docs/versioning/104_POLICY_LABELING.MD` | vorhanden | | + +## 4. Checks (fail-closed) +Alle Checks sind vom Repo-Root ausführbar. + +### 4.1 Inventory-Listen (sorted) +Kommandos: +```bash +find . -type f \( -name '0??_*.md' -o -name '0??_*.MD' \) -print | sed 's|^\./||' | sort > /tmp/docs_0nn.txt +find . -type f \( -name '1??_*.md' -o -name '1??_*.MD' \) -print | sed 's|^\./||' | sort > /tmp/docs_1nn.txt +``` + +Ausgabe (0NN): +```text +docs/001_INDEX_CORE.MD +docs/010_API_CORE.MD +docs/020_ARCH_CORE.MD +docs/021_USAGE_NUGET.MD +docs/audit/000_HASHING_BASELINE.MD +docs/audit/000_INDEX.MD +docs/audit/002_AUDIT_CONTRACT_AND_GUARDRAILS.MD +docs/audit/003_SECURITY_ASSERTION_TRACEABILITY.MD +docs/audit/004_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD +docs/audit/005_CODE_ANALYSIS_METHOD.MD +docs/audit/006_CODE_REVIEW_FINDINGS.MD +docs/audit/007_THREAT_MODEL.MD +docs/audit/008_INCIDENT_RESPONSE_RUNBOOK.MD +docs/audit/009_SUPPLY_CHAIN_BASELINE.MD +docs/audit/010_REFACTOR_BACKLOG.MD +docs/audit/011_SECURITY_BENCHMARK.MD +docs/audit/012_WAVE_EXECUTION_DOD.MD +docs/audit/013_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD +docs/audit/014_EVIDENCE_REPORT_ISSUE_67.MD +docs/audit/015_DOC_BILINGUAL_MAPPING.MD +docs/ci/001_PIPELINE_CI.MD +docs/ci/002_NUGET_TRUSTED_PUBLISHING.MD +docs/contracts/001_CONTRACT_HASHING.MD +docs/governance/001_POLICY_CI.MD +docs/governance/002_POLICY_LABELING.MD +docs/governance/002_POLICY_NAMING_UNIFIED.MD +docs/governance/003_INDEX_GOVERNANCE.MD +docs/governance/003_POLICY_VERSIONING_SVT.MD +docs/governance/004_POLICY_DOCUMENTATION.MD +docs/governance/005_POLICY_NAMING.MD +docs/governance/006_INDEX_CI_RULES.MD +docs/governance/007_POLICY_BRANCH_PR_NAMING_DE.MD +docs/guides/000_INDEX_GUIDES.MD +docs/guides/001_GUIDE_OPTIONS.MD +docs/guides/002_GUIDE_DATATYPE.MD +docs/guides/003_GUIDE_PORTABLE.MD +docs/guides/004_GUIDE_MIGRATE_LEGACY_NUGET.MD +docs/migrations/001_HASHING_RENAME.MD +docs/quality/001_CHECKLIST_PRODUCTION.MD +docs/references/001_REFERENCES_CORE.MD +docs/secure/001_HMAC_KEY_SETUP.MD +docs/security/010_CODEQL_DEFAULT_SETUP_GUARDRAIL.MD +docs/specs/001_SPEC_DIN.MD +docs/verification/001_INDEX_TESTS.MD +docs/verification/002_FLOW_BDD.MD +docs/verification/003_CATALOG_BDD.MD +docs/verification/004_MATRIX_HASHING.MD +docs/versioning/001_POLICY_VERSIONING.MD +docs/versioning/002_HISTORY_VERSIONS.MD +docs/versioning/003_CHANGELOG_RELEASES.MD +docs/versioning/004_POLICY_LABELING.MD +``` + +Ausgabe (1NN): +```text +docs/101_INDEX_CORE.MD +docs/110_API_CORE.MD +docs/120_ARCH_CORE.MD +docs/121_USAGE_NUGET.MD +docs/audit/100_HASHING_BASELINE.MD +docs/audit/100_INDEX.MD +docs/audit/102_AUDIT_CONTRACT_AND_GUARDRAILS.MD +docs/audit/103_SECURITY_ASSERTION_TRACEABILITY.MD +docs/audit/104_CERTIFICATION_AND_ATTESTATION_ROADMAP.MD +docs/audit/105_CODE_ANALYSIS_METHOD.MD +docs/audit/106_CODE_REVIEW_FINDINGS.MD +docs/audit/107_THREAT_MODEL.MD +docs/audit/108_INCIDENT_RESPONSE_RUNBOOK.MD +docs/audit/109_SUPPLY_CHAIN_BASELINE.MD +docs/audit/110_REFACTOR_BACKLOG.MD +docs/audit/111_SECURITY_BENCHMARK.MD +docs/audit/112_WAVE_EXECUTION_DOD.MD +docs/audit/113_SCORECARD_GOVERNANCE_ALERT_MAPPING.MD +docs/audit/114_EVIDENCE_REPORT_ISSUE_67.MD +docs/audit/115_DOC_BILINGUAL_MAPPING.MD +docs/ci/101_PIPELINE_CI.MD +docs/ci/102_NUGET_TRUSTED_PUBLISHING.MD +docs/contracts/101_CONTRACT_HASHING.MD +docs/governance/101_POLICY_CI.MD +docs/governance/102_POLICY_LABELING.MD +docs/governance/102_POLICY_NAMING_UNIFIED.MD +docs/governance/103_INDEX_GOVERNANCE.MD +docs/governance/103_POLICY_VERSIONING_SVT.MD +docs/governance/104_POLICY_DOCUMENTATION.MD +docs/governance/105_POLICY_NAMING.MD +docs/governance/106_INDEX_CI_RULES.MD +docs/governance/107_POLICY_BRANCH_PR_NAMING_DE.MD +docs/guides/100_INDEX_GUIDES.MD +docs/guides/101_GUIDE_OPTIONS.MD +docs/guides/102_GUIDE_DATATYPE.MD +docs/guides/103_GUIDE_PORTABLE.MD +docs/guides/104_GUIDE_MIGRATE_LEGACY_NUGET.MD +docs/migrations/101_HASHING_RENAME.MD +docs/quality/101_CHECKLIST_PRODUCTION.MD +docs/references/101_REFERENCES_CORE.MD +docs/secure/101_HMAC_KEY_SETUP.MD +docs/security/110_CODEQL_DEFAULT_SETUP_GUARDRAIL.MD +docs/specs/101_SPEC_DIN.MD +docs/verification/101_INDEX_TESTS.MD +docs/verification/102_FLOW_BDD.MD +docs/verification/103_CATALOG_BDD.MD +docs/verification/104_MATRIX_HASHING.MD +docs/versioning/101_POLICY_VERSIONING.MD +docs/versioning/102_HISTORY_VERSIONS.MD +docs/versioning/103_CHANGELOG_RELEASES.MD +docs/versioning/104_POLICY_LABELING.MD +``` + +### 4.2 Zählung + Diff-Listen (missing/orphan/collision) +Kommandos: +```bash +sed 's|/0\\([0-9][0-9]\\)_|/1\\1_|' /tmp/docs_0nn.txt | sort > /tmp/docs_expected_1nn.txt +echo "count_0 $(wc -l < /tmp/docs_0nn.txt)" +echo "count_1 $(wc -l < /tmp/docs_1nn.txt)" +echo "count_expected_1 $(wc -l < /tmp/docs_expected_1nn.txt)" +echo 'fehlende_en:'; comm -23 /tmp/docs_expected_1nn.txt /tmp/docs_1nn.txt +echo 'verwaiste_en:'; comm -13 /tmp/docs_expected_1nn.txt /tmp/docs_1nn.txt +echo 'mapping_kollisionen:'; sort /tmp/docs_expected_1nn.txt | uniq -d +``` + +Ausgabe: +```text +count_0 51 +count_1 51 +count_expected_1 51 +fehlende_en: +verwaiste_en: +mapping_kollisionen: +``` + +### 4.3 Keine NNN_* ausserhalb 0NN/1NN +Kommandos: +```bash +find . -type f \( -name '*.md' -o -name '*.MD' \) -name '[0-9][0-9][0-9]_*' -print \ + | sed 's|^\./||' | sort \ + | rg -v '(^|/)0[0-9]{2}_.+\\.(md|MD)$|(^|/)1[0-9]{2}_.+\\.(md|MD)$' +``` + +Ausgabe: +```text +``` + +### 4.4 Link-Konsistenz (EN verweist nicht auf 0NN) +Kommandos: +```bash +rg -n --glob 'docs/**/1??_*.M{D,d}' -S 'docs/0[0-9]{2}_' docs +``` + +Ausgabe: +```text +``` + +### 4.5 Repo-Checks (Doku) +Kommandos: +```bash +python3 tools/check-docs.py +python3 tools/check-doc-consistency.py +python3 tools/check-doc-shell-compat.py +``` + +Ausgabe: +```text +Doc check OK +Doc consistency check OK +Doc shell compatibility check OK +``` + +### 4.6 Guardrail: Keine Nicht-Markdown-Diffs +Kommandos: +```bash +git diff --name-only main...HEAD | rg -v '\\.(md|MD)$' +``` + +Ausgabe: +```text +``` + +## 5. Edge Cases +- Nummern ausserhalb `0NN` (z. B. `230_*`): keine gefunden (siehe Check 4.3). +- `docs/verification/103_CATALOG_BDD.MD`: enthält kanonische deutsche Satzmuster (Gherkin) als SSOT; EN-Dokument erläutert die Patterns, aber die Pattern-Texte selbst bleiben absichtlich deutsch. +- `docs/versioning/102_HISTORY_VERSIONS.MD`: Spalte "Short description" wird für deterministische Traceability bewusst nicht auf eine Sprache normalisiert (Original-Commit/PR-Intent). +- `docs/audit/103_SECURITY_ASSERTION_TRACEABILITY.MD`: Spalte "SECURITY Anchor" nutzt die originalen deutschen Überschriften aus der eingefrorenen `SECURITY.md` als SSOT. + +## 6. Decision Log +- 2026-02-15: EN-Spiegeldateien initial durch 1:1 Copy angelegt (Translation + Link-Fixes folgen). +- 2026-02-15: Repo-weite Link-Ausrichtung in EN-Dokumenten (EN soll primär EN referenzieren), ohne Änderung von Codeblöcken/CLI-Beispielen. +- 2026-02-15: `docs/120_ARCH_CORE.MD` vollständig ins Englische überführt, Struktur identisch zu `docs/020_ARCH_CORE.MD`. diff --git a/docs/0_de/audit/compat/001_NETSTANDARD2_POLICY_SNAPSHOT.MD b/docs/0_de/audit/compat/001_NETSTANDARD2_POLICY_SNAPSHOT.MD new file mode 100644 index 00000000..a24bbfcf --- /dev/null +++ b/docs/0_de/audit/compat/001_NETSTANDARD2_POLICY_SNAPSHOT.MD @@ -0,0 +1,56 @@ + +[DE](001_NETSTANDARD2_POLICY_SNAPSHOT.MD) | [EN](../../../1_en/audit/compat/001_NETSTANDARD2_POLICY_SNAPSHOT.MD) + + +# Policy Snapshot: netstandard2 Compat Refactor + +## 1. Zweck +Dieses Dokument extrahiert verbindliche Anforderungen für den netstandard2.0-Kompatibilitätsrefactor. + +## 2. Geltungsbereich +- Quelle A: `docs/governance/045_CODE_QUALITY_POLICY_DE.MD` +- Quelle B: `docs/versioning/001_POLICY_VERSIONING.MD` +- Quelle C: `docs/governance/004_POLICY_DOCUMENTATION.MD` + +## 3. Regeln/Architektur +### 3.1 Muss (verbindlich) +- Keine Public-Signaturänderungen und kein Behavior-Drift in bestehenden Public APIs. +- Build/Test müssen erfolgreich sein. +- Fail-closed Verhalten (Fehlerpfade und Logging) darf nicht aufgeweicht werden. +- Versionierungsentscheidung muss SemVer-konform sein. +- Dokumentdateien unter `docs/` müssen `UPPER_SNAKE_CASE` mit `.MD` nutzen. +- Doku-Checks sind verpflichtend: + - `python3 tools/check-doc-consistency.py` + - `python3 tools/check-docs.py` + +### 3.2 Kann (erlaubt unter Bedingungen) +- Interne Refactorings und Strukturverbesserungen sind erlaubt, wenn Public API und Semantik erhalten bleiben. +- Interne Abstraktionen für TFM-sensitive APIs sind erlaubt. + +### 3.3 Nicht erlaubt +- Runtime-Provider-Switching oder environment-basierte Pfadwahl. +- Unbelegte Annahmen ohne Evidence. +- Nicht-policy-konforme Dokumentbenennung. + +## 4. Verifikation/Nachweise +Auszüge der Policyquellen: +- `docs/governance/045_CODE_QUALITY_POLICY_DE.MD:36-39` (keine Semantikänderung, keine Signaturänderung) +- `docs/governance/045_CODE_QUALITY_POLICY_DE.MD:196-204` (DoD Build/Test, keine Public-Signature-Änderung) +- `docs/versioning/001_POLICY_VERSIONING.MD:22-26` (MINOR/PATCH Klassifikation) +- `docs/governance/004_POLICY_DOCUMENTATION.MD:16-24` (Benennungsregeln) +- `docs/governance/004_POLICY_DOCUMENTATION.MD:55-59` (Doku-Pflichtchecks) + +## 5. Grenzen/Nicht-Ziele +- Keine Änderung an `SECURITY.md`. +- Keine Erweiterung der fachlichen Semantik. +- Keine Einführung neuer externer Runtime-Abhängigkeiten ausser zur Kompatibilität notwendige Library-Referenzen. + +## 6. Verlinkte SSOT-Quellen +- [Code Quality Policy DE](https://github.com/tomtastisch/FileClassifier/blob/main/docs/governance/045_CODE_QUALITY_POLICY_DE.MD) +- [Versioning Policy DE](https://github.com/tomtastisch/FileClassifier/blob/main/docs/versioning/001_POLICY_VERSIONING.MD) +- [Documentation Policy DE](https://github.com/tomtastisch/FileClassifier/blob/main/docs/governance/004_POLICY_DOCUMENTATION.MD) + +## RoC-Bezug +- [Artifact-Contract-Regel](https://github.com/tomtastisch/FileClassifier/blob/main/tools/ci/policies/rules/artifact_contract.yaml) +- [Docs-Drift-Regel](https://github.com/tomtastisch/FileClassifier/blob/main/tools/ci/policies/rules/docs_drift.yaml) +- [Shell-Safety-Regeln](https://github.com/tomtastisch/FileClassifier/blob/main/tools/ci/policies/rules/shell_safety.yaml) diff --git a/docs/0_de/audit/compat/002_NETSTANDARD2_INVENTORY.MD b/docs/0_de/audit/compat/002_NETSTANDARD2_INVENTORY.MD new file mode 100644 index 00000000..1b9719b4 --- /dev/null +++ b/docs/0_de/audit/compat/002_NETSTANDARD2_INVENTORY.MD @@ -0,0 +1,70 @@ + +[DE](002_NETSTANDARD2_INVENTORY.MD) | [EN](../../../1_en/audit/compat/002_NETSTANDARD2_INVENTORY.MD) + + +# Inventory: netstandard2 Compat Baseline + +## 1. Zweck +Dieses Dokument protokolliert den Ausgangs-/Zwischenstand der TFM- und API-sensitiven Fundstellen für den netstandard2.0-Refactor. + +## 2. Geltungsbereich +- Library-Projekt: `src/FileTypeDetection/FileTypeDetectionLib.vbproj` +- Produktionscode: `src/FileTypeDetection/**/*.vb` +- Tests: `tests/FileTypeDetectionLib.Tests/**/*` + +## 3. Regeln/Architektur +Erfasste Suchmuster: +- `Convert.ToHexString` +- `SHA256.HashData` +- `System.IO.Hashing` +- `XxHash3` +- `FrameworkReference Microsoft.AspNetCore.App` +- `TargetFrameworks` + +## 4. Verifikation/Nachweise +### 4.1 Projekt/TFMs +Befehl: +```bash +rg -n "TargetFrameworks|FrameworkReference|PackageReference Include=\"System\.IO\.Hashing\"|PackageReference Include=\"Microsoft\.Extensions\.Logging\.Abstractions\"" src/FileTypeDetection/FileTypeDetectionLib.vbproj +``` +Ausgabe: +- `src/FileTypeDetection/FileTypeDetectionLib.vbproj:6` -> `TargetFrameworks netstandard2.0;net8.0;net10.0` +- `src/FileTypeDetection/FileTypeDetectionLib.vbproj:26` -> `Microsoft.Extensions.Logging.Abstractions` +- `src/FileTypeDetection/FileTypeDetectionLib.vbproj:29` -> `System.IO.Hashing` + +### 4.2 Produktionscode +Befehl: +```bash +rg -n "Convert\.ToHexString|SHA256\.HashData|System\.IO\.Hashing|XxHash3" src/FileTypeDetection --glob '*.vb' --glob '*.vbproj' +``` +Relevante Treffer: +- `src/FileTypeDetection/Providers/Net8_0Plus/HashPrimitivesProvider.vb:49` (`Convert.ToHexString`) +- `src/FileTypeDetection/Providers/Net8_0Plus/HashPrimitivesProvider.vb:64` (`SHA256.HashData`) +- `src/FileTypeDetection/Providers/Net8_0Plus/HashPrimitivesProvider.vb:77` (`XxHash3`) +- `src/FileTypeDetection/Providers/NetStandard2_0/HashPrimitivesProvider.vb:91` (`XxHash3`) + +### 4.3 AspNetCore FrameworkReference +Befehl: +```bash +rg -n "Microsoft\.AspNetCore\.App|AspNetCore" src/FileTypeDetection --glob '*.vb' --glob '*.vbproj' +``` +Ausgabe: +- Keine Treffer (exit code 1) -> FrameworkReference entfernt. + +### 4.4 Tests +Befehl: +```bash +rg -n "Convert\.ToHexString|SHA256\.HashData|System\.IO\.Hashing|XxHash3" tests/FileTypeDetectionLib.Tests --glob '*.cs' --glob '*.txt' +``` +Relevante Treffer (expected in tests): +- `tests/FileTypeDetectionLib.Tests/Support/FixtureManifestCatalog.cs:133-134` +- `tests/FileTypeDetectionLib.Tests/Unit/HashingEvidenceTests.cs:2,45,61,349,372-373` +- `tests/FileTypeDetectionLib.Tests/Contracts/public-api.snapshot.txt:75-76` + +## 5. Grenzen/Nicht-Ziele +- Dieses Inventar ist ein technischer Suchlauf und ersetzt keine Laufzeit- oder CI-Verifikation. +- Nicht gelistet sind reine Dokumenttexte ausserhalb des Produktions-/Testcodes. + +## 6. Verlinkte SSOT-Quellen +- [Versioning Policy](https://github.com/tomtastisch/FileClassifier/blob/main/docs/versioning/001_POLICY_VERSIONING.MD) +- [Code Quality Policy](https://github.com/tomtastisch/FileClassifier/blob/main/docs/governance/045_CODE_QUALITY_POLICY_DE.MD) diff --git a/docs/0_de/audit/compat/003_NETSTANDARD2_COMPAT_EVIDENCE.MD b/docs/0_de/audit/compat/003_NETSTANDARD2_COMPAT_EVIDENCE.MD new file mode 100644 index 00000000..ea5d23a8 --- /dev/null +++ b/docs/0_de/audit/compat/003_NETSTANDARD2_COMPAT_EVIDENCE.MD @@ -0,0 +1,137 @@ + +[DE](003_NETSTANDARD2_COMPAT_EVIDENCE.MD) | [EN](../../../1_en/audit/compat/003_NETSTANDARD2_COMPAT_EVIDENCE.MD) + + +# Evidence Report: netstandard2 Compat + +## 1. Zweck +Dieser Report dokumentiert die technische Umsetzung und Verifikation für die net48-Kompatibilität über `netstandard2.0` inklusive fail-closed Office-/Archiv-Refinement. + +## 2. Geltungsbereich +- Library: `src/FileTypeDetection/FileTypeDetectionLib.vbproj` +- Detektion/Refinement: `src/FileTypeDetection/FileTypeDetector.vb`, `src/FileTypeDetection/Detection/FileTypeRegistry.vb`, `src/FileTypeDetection/Infrastructure/CoreInternals.vb` +- Tests: `tests/FileTypeDetectionLib.Tests/Unit/*` + +## 3. Regeln/Architektur +### 3.1 Before/After TargetFrameworks +- Before: `net8.0;net10.0` +- After: `netstandard2.0;net8.0;net10.0` +- Nachweisdatei: `src/FileTypeDetection/FileTypeDetectionLib.vbproj` + +### 3.2 Interface-Abstraktionen und API-Mapping +- `IHexCodec` + - abstrahiert: Lower-Hex-Encoding (`Convert.ToHexString(...).ToLowerInvariant()` bzw. nibble-map) +- `ISha256Primitives` + - abstrahiert: `SHA256.HashData`/`SHA256.Create().ComputeHash` +- `IFastHash64` + - abstrahiert: `System.IO.Hashing.XxHash3.HashToUInt64` +- `IHashPrimitives` + - Aggregation + `ProviderMarker` + +### 3.3 Hashing-Verhalten je TFM +- `netstandard2.0`: + - SHA256: `SHA256.Create()` + - Hex: deterministischer lower-hex nibble-codec + - FastHash: `XxHash3.HashToUInt64(...).ToString("x16")` +- `net8.0` und `net10.0`: + - SHA256: `SHA256.HashData` + - Hex: `Convert.ToHexString(...).ToLowerInvariant()` + - FastHash: `XxHash3.HashToUInt64(...).ToString("x16")` +- FastHash ist auf `netstandard2.0` nicht deaktiviert. + +### 3.4 Provider-Selektion (compile-time) +MSBuild-Conditionen in `src/FileTypeDetection/FileTypeDetectionLib.vbproj`: +- global: `` +- `netstandard2.0`: `` +- `net8.0|net10.0`: `` + +### 3.5 Office-/Archiv-Semantik (fail-closed) +- Office/OpenDocument-Endungen werden alias-basiert auf gruppierte Typen aufgelöst (`Docx`, `Xlsx`, `Pptx`). +- Legacy-OLE2 (`.doc/.xls/.ppt`) wird über `LegacyOfficeBinaryRefiner` markerbasiert fail-closed verfeinert. +- `TryValidateArchive` und Extraktion akzeptieren nur echte extrahierbare Archiv-Container (`Zip`); Office-Container werden nicht als extrahierbares Archiv behandelt. +- Endungsprüfung bleibt nachgelagerte Policy und wird nur bei explizitem Verify-Flag als Fehlerpfad erzwungen. + +## 4. Verifikation/Nachweise +### 4.1 Befehle und Exit-Codes +1. `dotnet --info` -> `0` (`artifacts/ci/netstandard2-compat/dotnet-info.txt`) +2. `dotnet restore FileClassifier.sln -v minimal` -> `0` +3. `dotnet restore --locked-mode FileClassifier.sln -v minimal` -> `0` +4. `dotnet build FileClassifier.sln -c Release --no-restore -warnaserror -v minimal` -> `0` +5. `dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj -c Release --no-build -v minimal` -> `0` (`544` Tests grün) +6. `dotnet pack src/FileTypeDetection/FileTypeDetectionLib.vbproj -c Release --no-build -o artifacts/ci/netstandard2-compat/nuget -v minimal` -> `0` +7. `dotnet build src/FileTypeDetection/FileTypeDetectionLib.vbproj -c Release -f netstandard2.0 -v diag > artifacts/ci/netstandard2-compat/build-netstandard2.0.log` -> `0` +8. `dotnet build src/FileTypeDetection/FileTypeDetectionLib.vbproj -c Release -f net8.0 -v diag > artifacts/ci/netstandard2-compat/build-net8.0.log` -> `0` +9. `dotnet build src/FileTypeDetection/FileTypeDetectionLib.vbproj -c Release -f net10.0 -v diag > artifacts/ci/netstandard2-compat/build-net10.0.log` -> `0` +10. `python3 tools/check-doc-consistency.py` -> `0` +11. `python3 tools/check-docs.py` -> `0` +12. `EXPECTED_RELEASE_TAG=v5.2.0-rc.6 REQUIRE_RELEASE_TAG=1 bash tools/ci/bin/run.sh versioning-svt` -> `0` +13. `bash tools/ci/bin/run.sh version-convergence` -> `0` +14. `bash tools/ci/bin/run.sh security-nuget` -> `0` + +### 4.2 Build-/Pack-Proof +- Build-Matrix erfolgreich: + - `src/FileTypeDetection/bin/Release/netstandard2.0/Tomtastisch.FileClassifier.dll` + - `src/FileTypeDetection/bin/Release/net8.0/Tomtastisch.FileClassifier.dll` + - `src/FileTypeDetection/bin/Release/net10.0/Tomtastisch.FileClassifier.dll` +- NUPKG-Inhalt (`artifacts/ci/netstandard2-compat/nuget/Tomtastisch.FileClassifier.5.2.0.nupkg`): + - `lib/netstandard2.0/Tomtastisch.FileClassifier.dll` + - `lib/net8.0/Tomtastisch.FileClassifier.dll` + - `lib/net10.0/Tomtastisch.FileClassifier.dll` + +### 4.3 Provider-Compile-Proof +- Build-Task-Proof je TFM: `artifacts/ci/netstandard2-compat/provider-compile-proof-short.txt` + - `netstandard2.0` -> `Providers/NetStandard2_0/HashPrimitivesProvider.vb` + - `net8.0` -> `Providers/Net8_0Plus/HashPrimitivesProvider.vb` + - `net10.0` -> `Providers/Net8_0Plus/HashPrimitivesProvider.vb` +- Runtime-Marker-Proof: `artifacts/ci/netstandard2-compat/provider-marker-proof.txt` + - `netstandard2.0:NetStandard2_0` + - `net8.0:Net8_0Plus` + - `net10.0:Net8_0Plus` + +### 4.4 Forbidden-API Grep-Proof (Core) +Befehl: +```bash +rg -n "Convert\.ToHexString|SHA256\.HashData|System\.IO\.Hashing|Microsoft\.AspNetCore\.App" src/FileTypeDetection/Core +``` +Ergebnis: +- keine Treffer (`artifacts/ci/netstandard2-compat/core-forbidden-apis.txt` hat `0` Zeilen) + +### 4.5 Test-/Semantik-Proof (Office/OpenOffice/Archive) +- Neue/erweiterte Tests decken u. a. ab: + - falsche Endung vs. Inhaltsdetektion (`verifyExtension=false/true`) + - Legacy-OLE Office (`doc/xls/ppt`) + - OpenDocument (`odt/ods/odp`) + - echte Archive vs. Office-Container + - korrupte Payloads und Konfliktmarker (fail-closed) +- Relevante Testdateien: + - `tests/FileTypeDetectionLib.Tests/Unit/EndToEndFailClosedMatrixUnitTests.cs` + - `tests/FileTypeDetectionLib.Tests/Unit/LegacyOfficeBinaryRefinerUnitTests.cs` + - `tests/FileTypeDetectionLib.Tests/Unit/OpenXmlRefinerUnitTests.cs` + - `tests/FileTypeDetectionLib.Tests/Unit/ExtensionCheckUnitTests.cs` + - `tests/FileTypeDetectionLib.Tests/Unit/ArchiveExtractionUnitTests.cs` + +### 4.6 Version-/Release-Konvergenz +- `artifacts/versioning_report.json` -> `status: pass`, `expected_version: 5.2.0-rc.6` +- `artifacts/ci/versioning-svt/versioning-svt-summary.json` -> `status: pass` +- `artifacts/ci/version-convergence/summary.json` -> `status: pass`, `repo_version=5.2.0`, `vbproj_version=5.2.0`, `docs_latest_version=5.2.0` +- RC-PreRelease-NUPKG für SVT-Probe: `artifacts/nuget/Tomtastisch.FileClassifier.5.2.0-rc.6.nupkg` + +### 4.7 Policy/Konvergenz-Notiz +Ambiguität zwischen: +- `docs/versioning/001_POLICY_VERSIONING.MD` (Tag `vX.Y.Z[-prerelease]` als SSOT für Publish), und +- Repo-Konvergenzregeln (`RepoVersion`/`Version`/`PackageVersion` bleiben Kernversion `X.Y.Z`). + +Entscheidung für diesen Scope: +- fail-closed nach bestehendem CI/Repo-Vertrag: Kernversionen bleiben auf `5.2.0` konvergent. +- Pre-Release wird über Tag/NUPKG-Version `v5.2.0-rc.6` abgebildet und via SVT geprüft. + +## 5. Grenzen/Nicht-Ziele +- Keine öffentliche API-Signatur geändert. +- Keine Runtime-Provider-Umschaltung eingeführt. +- Keine Blocker-Datei notwendig (`999_NETSTANDARD2_BLOCKERS.MD` nicht erstellt). + +## 6. Verlinkte SSOT-Quellen +- [Versioning Policy](https://github.com/tomtastisch/FileClassifier/blob/main/docs/versioning/001_POLICY_VERSIONING.MD) +- [Code Quality Policy](https://github.com/tomtastisch/FileClassifier/blob/main/docs/governance/045_CODE_QUALITY_POLICY_DE.MD) +- [Documentation Policy](https://github.com/tomtastisch/FileClassifier/blob/main/docs/governance/004_POLICY_DOCUMENTATION.MD) +- [Audit Index](https://github.com/tomtastisch/FileClassifier/blob/main/docs/audit/000_INDEX.MD) diff --git a/docs/0_de/ci/001_PIPELINE_CI.MD b/docs/0_de/ci/001_PIPELINE_CI.MD new file mode 100644 index 00000000..76ba5c4c --- /dev/null +++ b/docs/0_de/ci/001_PIPELINE_CI.MD @@ -0,0 +1,106 @@ + +[DE](001_PIPELINE_CI.MD) | [EN](../../1_en/ci/001_PIPELINE_CI.MD) + + +# CI-Pipeline (SSOT) + +## Zweck und Geltungsbereich +Dieses Dokument beschreibt die ausführbare CI-Topologie und den Artefaktvertrag. +Normative Policy-Schwellenwerte und Regelparameter liegen in `tools/ci/policies/rules/` und `docs/governance/001_POLICY_CI.MD`. + +## Erforderliche Status-Contexts +Die Branch-Protection auf `main` verlangt exakt diese Contexts (`strict: true`): `preflight`, `version-policy`, `build`, `api-contract`, `pack`, `consumer-smoke`, `package-backed-tests`, `security-nuget`, `tests-bdd-coverage`. +Nachweis: Branch-Protection-API-Ausgabe (`required_status_checks.contexts`), `.github/workflows/ci.yml:59-347` und `.github/workflows/ruleset-placeholders.yml` (Context `version-policy`). +Hinweis: Die normative Versionierungsentscheidung (RaC) wird zusätzlich durch `.github/workflows/version-policy.yml` als Check `versioning-policy` ausgewertet (nicht Teil der Branch-Protection-Contexts). + +## Workflow-Topologie +- `pr-labeling` läuft nur auf `pull_request` und ist getrennt vom erforderlichen technischen Gate-Pfad (`.github/workflows/ci.yml:22-58`). +- Der technische Gate-Pfad startet bei `preflight` und fächert in Downstream-Jobs über `needs` auf (`.github/workflows/ci.yml:89-427`). +- `summary` aggregiert Downstream-Artefakte und führt Contract-Checks aus (`.github/workflows/ci.yml:349-427`, `tools/ci/bin/run.sh:446`). + +```mermaid +flowchart TD + pr["pr-labeling"]:::meta + pre["preflight"] --> docs["docs-links-full"] + pre --> svt["versioning-svt"] + pre --> vc["version-convergence"] + pre --> naming["naming-snt"] + pre --> build["build"] + svt --> build + vc --> build + naming --> build + build --> api["api-contract"] + build --> pack["pack"] + svt --> pack + pack --> smoke["consumer-smoke"] + pack --> pkg["package-backed-tests"] + build --> sec["security-nuget"] + build --> bdd["tests-bdd-coverage"] + docs --> sum["summary"] + naming --> sum + svt --> sum + vc --> sum + api --> sum + smoke --> sum + pkg --> sum + sec --> sum + bdd --> sum + + req["Branch protection required contexts"]:::gate + pre -.-> req + build -.-> req + api -.-> req + pack -.-> req + smoke -.-> req + pkg -.-> req + sec -.-> req + bdd -.-> req + vp["version-policy (ruleset placeholder workflow)"]:::meta -.-> req + rac["versioning-policy (RaC policy workflow)"]:::meta -.-> req + + classDef gate fill:#e9f5ff,stroke:#2a6f97,color:#073b4c; + classDef meta fill:#f8f9fa,stroke:#6c757d,color:#343a40; +``` + +## Artefaktvertrag +Jeder Aufruf `tools/ci/bin/run.sh ` initialisiert und finalisiert ein fixes Artefakt-Set: +- `raw.log` +- `summary.md` +- `result.json` +- `diag.json` + +Nachweis: +- Artefaktpfad-Initialisierung: `tools/ci/lib/result.sh:12-20`. +- File-Materialisierung: `tools/ci/lib/result.sh:28-34`. +- Finale `result.json` Komposition: `tools/ci/lib/result.sh:78-112`. +- Universelles Runner-Wiring: `tools/ci/bin/run.sh:16-28`. + +## Vertragsmatrix +| Job | Entrypoint | Artefaktpfad | Vertragsvalidierung | Evidence | +|---|---|---|---|---| +| `preflight` | `bash tools/ci/bin/run.sh preflight` | `artifacts/ci/preflight/` | Result contract + policy bridge | `.github/workflows/ci.yml:77-87`, `tools/ci/bin/run.sh:159-171` | +| `version-policy` | `.github/workflows/ruleset-placeholders.yml` | N/A | N/A (placeholder required context) | `.github/workflows/ruleset-placeholders.yml:20-24` | +| `versioning-policy` | `bash tools/versioning/run-versioning-policy.sh` | `artifacts/policy/` | RaC policy evaluation | `.github/workflows/version-policy.yml:25-37` | +| `build` | `bash tools/ci/bin/run.sh build` | `artifacts/ci/build/` | Result contract | `.github/workflows/ci.yml:177-187`, `tools/ci/bin/run.sh:179-183` | +| `api-contract` | `bash tools/ci/bin/run.sh api-contract` | `artifacts/ci/api-contract/` | Result contract | `.github/workflows/ci.yml:202-212`, `tools/ci/bin/run.sh:185-189` | +| `pack` | `bash tools/ci/bin/run.sh pack` | `artifacts/ci/pack/` | Result contract + package metadata checks | `.github/workflows/ci.yml:227-237`, `tools/ci/bin/run.sh:191-230` | +| `consumer-smoke` | `bash tools/ci/bin/run.sh consumer-smoke` | `artifacts/ci/consumer-smoke/` | Result contract + package-consumer execution | `.github/workflows/ci.yml:257-267`, `tools/ci/bin/run.sh:252-283` | +| `package-backed-tests` | `bash tools/ci/bin/run.sh package-backed-tests` | `artifacts/ci/package-backed-tests/` | Result contract + package-backed tests | `.github/workflows/ci.yml:287-297`, `tools/ci/bin/run.sh:285-315` | +| `security-nuget` | `bash tools/ci/bin/run.sh security-nuget` | `artifacts/ci/security-nuget/` | Result contract + High/Critical fail-close | `.github/workflows/ci.yml:312-322`, `tools/ci/bin/run.sh:317-329` | +| `tests-bdd-coverage` | `bash tools/ci/bin/run.sh tests-bdd-coverage` | `artifacts/ci/tests-bdd-coverage/` | Result contract + coverage threshold execution | `.github/workflows/ci.yml:337-347`, `tools/ci/bin/run.sh:331-348` | +| `version-convergence` | `bash tools/ci/bin/run.sh version-convergence` | `artifacts/ci/version-convergence/` | Result contract + convergence script | `.github/workflows/ci.yml:142-162`, `tools/versioning/verify-version-convergence.sh` | +| `summary` | `bash tools/ci/bin/run.sh summary` | `artifacts/ci/summary/` | Policy contract aggregation | `.github/workflows/ci.yml:417-427`, `tools/ci/bin/run.sh:424-430` | +| `pr-labeling` | `bash tools/ci/bin/run.sh pr-labeling` | `artifacts/ci/pr-labeling/` | Label decision schema + apply+verify | `.github/workflows/ci.yml:45-57`, `tools/ci/bin/run.sh:350-400` | + +## Labeling- und Versionierungsentscheidungs-Pfad +- Entscheidungs-Generierung: `compute-pr-labels.js` schreibt `decision.json` (`tools/ci/bin/run.sh:371-372`). +- Schema-Validierung: `validate-label-decision.js` (`tools/ci/bin/run.sh:374`). +- Label-Anwendung und Post-Apply-Verifikation: deterministischer GitHub-API-PUT (curl-backed) und anschliessender Re-Read (`tools/ci/bin/run.sh:375-399`, `tools/ci/bin/github_api.py`). +- Workflow-Token-Quelle: `GH_TOKEN: ${{ github.token }}` (`.github/workflows/ci.yml:46-50`). + +## Qodana: Vertragsposition +Qodana läuft in einem separaten Workflow und wird durch `run.sh qodana` validiert: +- Qodana-Action-Ausführung und SARIF-Ausgabepfad (`.github/workflows/qodana.yml:34-40`, `.github/workflows/qodana.yml:59`). +- Vertragscheck-Aufruf (`.github/workflows/qodana.yml:47-48`, `tools/ci/bin/run.sh:402-422`). +- Qodana-Artefakt-Upload (`.github/workflows/qodana.yml:54-60`). +- Fail-closed Pflicht-Gate in trusted Kontexten: für `push` und interne PRs wird `QODANA_TOKEN` erzwungen; untrusted PR-Kontexte (Fork/Dependabot) werden explizit ausgenommen (`.github/workflows/qodana.yml:14-33`). diff --git a/docs/0_de/ci/002_NUGET_TRUSTED_PUBLISHING.MD b/docs/0_de/ci/002_NUGET_TRUSTED_PUBLISHING.MD new file mode 100644 index 00000000..92f9c7ed --- /dev/null +++ b/docs/0_de/ci/002_NUGET_TRUSTED_PUBLISHING.MD @@ -0,0 +1,42 @@ + +[DE](002_NUGET_TRUSTED_PUBLISHING.MD) | [EN](../../1_en/ci/002_NUGET_TRUSTED_PUBLISHING.MD) + + +# NuGet Trusted Publishing (OIDC) + +## 1. Zweck +Release-Publish auf nuget.org erfolgt per OIDC Trusted Publishing in `.github/workflows/release.yml` via `NuGet/login@v1`. + +## 2. Binding +Die aktive Trusted-Publishing-Policy ist an folgende Identität gebunden: +- Repository: `tomtastisch/FileClassifier` +- Workflow: `release.yml` +- Environment: ungenutzt + +## 3. Secret-Verwendung +- Publish verwendet **nicht** `secrets.NUGET_API_KEY`. +- `secrets.NUGET_API_KEY` bleibt nur Fallback für Legacy-Operationen (z. B. delete/unlist/deprecate) außerhalb des OIDC-Publish-Pfads. + +## 4. Post-Publish SVT Gate (Propagation-Delay) +- Nach erfolgreichem `dotnet nuget push` kann die NuGet-Indexierung (Search/Registration/Flatcontainer) zeitverzögert sichtbar sein. +- Gate 4 im Release-Workflow bleibt **fail-closed** für publish-kritische Endpunkte: + - `REQUIRE_FLATCONTAINER=1` + - `REQUIRE_REGISTRATION=1` für stabile Tags `vX.Y.Z` + - `REQUIRE_REGISTRATION=0` für Pre-Release-Tags `vX.Y.Z-