Assessor_2.0/docs/CANONICAL_MODEL.md

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

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 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; die konkreten Abweichungen und ihre Begründung stehen in RESULT_CONTRACT.md. Dieses Dokument bleibt der fachlich verbindliche, implementierte Stand.