98 lines
5.7 KiB
Markdown
98 lines
5.7 KiB
Markdown
# ASSESSOR – Kanonisches Finding- und Assessment-Modell
|
||
|
||
Stand: 2026-07-17
|
||
Schema-Version: 1
|
||
Zugehörige Planphase: Phase 2
|
||
|
||
## Zweck und Grenze
|
||
|
||
Das kanonische Modell ist die fachliche Zielsprache zwischen semantischem Mapping, Vergleich, Persistenz und Darstellung. Es ist weder ein Parser-Zwischenmodell noch ein konkretes PostgreSQL-Schema. Die bestehenden Typen `ImportedDataset` und `FindingRecord` bleiben bis zur Umsetzung der Phasen 3 und 4 als kompatible Import- und UI-Baseline bestehen.
|
||
|
||
Die verbindlichen TypeScript-Typen stehen in `src/domain/canonical-model.ts`. `src/domain/canonical-validation.ts` prüft Referenzen und zentrale Invarianten ohne React-, Browser-, Tauri- oder Datenbankabhängigkeit.
|
||
|
||
## Beziehungen
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
P["Projekt"] --> A["Assessment"]
|
||
A --> R["Scan-Lauf"]
|
||
R --> F["Importdatei"]
|
||
F --> T["Quelltabelle"]
|
||
R --> O["Finding-Vorkommen"]
|
||
F --> O
|
||
T -. "optional" .-> O
|
||
D["Finding-Definition"] --> O
|
||
O --> E["Evidenz"]
|
||
D -.-> V["Review"]
|
||
O -.-> V
|
||
F --> I["Importdiagnose"]
|
||
T -.-> I
|
||
```
|
||
|
||
## Kernentscheidungen
|
||
|
||
### Definition und Vorkommen sind getrennt
|
||
|
||
Eine `FindingDefinition` beschreibt die stabile fachliche Identität eines Findings. Ein `FindingOccurrence` beschreibt dessen Auftreten in genau einem Scan-Lauf. Dadurch kann dieselbe Definition in mehreren Scanständen vorkommen, ohne dupliziert zu werden. Die Vergleichsengine aus Phase 8 verwendet diese Beziehung für neu, weiterhin vorhanden, behoben und wieder aufgetreten.
|
||
|
||
### Original und normalisiert sind getrennt
|
||
|
||
Semantisch zugeordnete Werte verwenden `MappedValue`. Darin bleiben `originalValue`, `normalizedValue` und die Mappingherkunft getrennt. Severity, Status, Score und betroffenes Asset dürfen deshalb normalisiert werden, ohne den Quellwert zu überschreiben.
|
||
|
||
Jedes Vorkommen besitzt zusätzlich eine geordnete Liste `originalFields`. Sie erhält Feldschlüssel, sichtbare Beschriftung, strukturierten Wert, optionalen Rohwert, Objektpfad und Spaltenposition. Eine Liste statt eines einfachen Objekts erlaubt doppelte Spaltennamen und erhält die Quellreihenfolge.
|
||
|
||
### Herkunft ist Bestandteil des Modells
|
||
|
||
Ein Vorkommen verweist auf Scan-Lauf, Importdatei und optional Quelltabelle. `SourcePosition` kann Zeile, Spalte, Zellreferenz, Objektpfad oder HTML-Selektor aufnehmen. Die Importdatei dokumentiert Toolerkennung, Parser-, Profil- und Mappingversion sowie Hash und Ablageart des Originalartefakts.
|
||
|
||
Die Ablageentscheidung bleibt offen: Eine Quelldatei kann eingebettet, über einen geschützten Storage-Key referenziert oder ausdrücklich nicht aufbewahrt werden. Der Validator meldet die letzte Variante als Warnung.
|
||
|
||
### Reviews verändern keine Importdaten
|
||
|
||
`FindingReview` ist ein eigenständiges Objekt mit Revision. Ein Review kann sich auf eine Definition oder ein einzelnes Vorkommen beziehen. Workflowstatus, Priorität, Owner, Frist, Kommentar und Maßnahmeninformationen werden niemals in importierte Originalfelder geschrieben.
|
||
|
||
### Konfidenz ist nachvollziehbar
|
||
|
||
Toolerkennung und Feldzuordnungen besitzen Konfidenzklasse, numerischen Wert von 0 bis 1 und Begründungen. Zusätzlich wird festgehalten, ob die Entscheidung automatisch, aus der Quelle selbst oder nach Benutzerbestätigung entstanden ist.
|
||
|
||
## Abbildung der Pilotquellen
|
||
|
||
| Quelle | Stabile Identität | Typische Originalwerte | Kanonische Abbildung |
|
||
|---|---|---|---|
|
||
| Purple Knight | Indicator-/Rule-ID | Name, Severity, Status, Result-Referenzen | Definition, Vorkommen, Severity/Status, Evidenz |
|
||
| PingCastle | `RiskId` | Kategorie, Punkte, Rationale, technische Details | Definition, Vorkommen, Score, Kategorie, Evidenz |
|
||
| CIS-CAT | Recommendation-/Rule-ID | Titel, Pass/Fail, Profil, Level, Assessment und Remediation | Definition, Vorkommen, Status, Referenzen, Evidenz |
|
||
| Maester | Test-ID | Title, Result, Severity, Tag, Block, Description, ResultDetail | Definition, Vorkommen, Severity/Status, Evidenz |
|
||
| generische Quelle | abgeleiteter stabiler Schlüssel | sämtliche Spalten oder Objektpfade | niedrig-konfidente Zuordnung plus vollständige `originalFields` |
|
||
|
||
Unbekannte Zusatzfelder bleiben in `originalFields`; verschachtelte Inhalte können als `JsonValue` erhalten werden. Dadurch erzwingt das Modell keinen Informationsverlust, auch wenn ein Profil ein Feld noch nicht semantisch versteht.
|
||
|
||
## Validierte Invarianten
|
||
|
||
- IDs sind innerhalb jeder Objektart eindeutig.
|
||
- alle Referenzen auf Scan-Läufe, Dateien, Tabellen, Definitionen, Vorkommen und Reviews sind auflösbar,
|
||
- Datei, Tabelle und Vorkommen gehören zum selben Scan-Lauf,
|
||
- Konfidenzwerte liegen zwischen 0 und 1,
|
||
- Tabellenmaße, Scan-Reihenfolge, Dateigröße und Review-Revision sind gültig,
|
||
- jedes Finding-Vorkommen enthält Originalfelder,
|
||
- Quellpositionen verwenden nicht negative Indizes,
|
||
- nicht aufbewahrte Originaldateien erzeugen eine sichtbare Warnung.
|
||
|
||
## Bewusst noch nicht umgesetzt
|
||
|
||
- Überführung der heutigen UI-Datensätze in kanonische Mehrlaufprojekte: Phasen 10 und 12
|
||
- konkrete dauerhafte Ablage der Repository-Daten: Phase 11
|
||
- PostgreSQL-Schema und Migrationen: Phase 11
|
||
|
||
## Verhältnis zu RESULT_CONTRACT 1.0.0
|
||
|
||
Seit der Integrationsentscheidung vom 2026-07-23 (Pfad A, additiv) ergänzt der
|
||
externe Vertrag [`RESULT_CONTRACT.md`](RESULT_CONTRACT.md) dieses Modell um zwei
|
||
orthogonale Achsen (`result_type`, `is_ioe`) und eine Asset-/Kantenschicht. Beide
|
||
sind additiv auf das hier beschriebene Modell abgebildet, nicht als eigenständige
|
||
Haupttabelle. Der unveränderte externe Vertragstext liegt unter
|
||
[`CANONICAL_MODEL_1.0.0.md`](CANONICAL_MODEL_1.0.0.md); die konkreten Abweichungen
|
||
und ihre Begründung stehen in
|
||
[`RESULT_CONTRACT.md`](RESULT_CONTRACT.md#abweichungen-der-assessor-realisierung).
|
||
Dieses Dokument bleibt der fachlich verbindliche, implementierte Stand.
|