Assessor_2.0/docs/TOOL_PROFILES.md

Deklarative Toolprofile

Stand: 2026-09-10 Profilschema: 1

Zweck

Toolprofile bündeln alle werkzeugspezifischen Kenntnisse außerhalb der Formatparser und React-Komponenten. Ein Profil beschreibt Daten; die gemeinsame Profil-Fabrik erzeugt daraus die ausführbare Erkennung, Sheetpriorisierung, Standardansicht und Statusfilterung.

Profilinhalt

Eine ToolProfileDefinition enthält:

• stabile Profil-ID, Anzeigename und semantische Profilversion
• gewichtete Erkennungssignale für Dateiname, Inhalt, Tabellen, Kopfzeilen und Zellwerte
• bevorzugte und nachrangige Tabellennamen
• Synonyme für kanonische Feldrollen
• Status- und Severity-Normalisierung
• Titel-, Severity- und Sortierfelder für die Darstellung
• deklarative Statusfilter
• priorisierte Vergleichsschlüssel
• Kennzeichnung als generischer Fallback

Das Schema steht in src/domain/tool-profile-definition.ts. Die gemeinsame Laufzeitumsetzung liegt in src/profiles/profile-factory.ts.

Vorhandene Profile

Profil	Version	Schwerpunkt
Generic	1.0.0	verlustfreier Fallback für unbekannte Tabellen
Purple Knight	1.0.0	Indicator Results, IOE-Status, Weight und Ergebnisverweise
PingCastle	1.0.0	Healthcheck, Risk Scores und Regelkennungen
CIS-CAT Pro	1.0.0	Assessment Results, Recommendation und Pass/Fail
Maester	1.0.0	flache TestResults-Exporte, MT-IDs und ResultDetail
Microsoft Defender for IoT	1.2.0	Asset-Summary, Mock-CVE-CSV, Device-Inventar, Device-ID-Verknuepfung und Sensorprovenienz
Microsoft Defender for IoT Alerts	1.6.0	OT-Sensor-Alertexport (CSV oder XLSX mit einer CSV-Zeile je Zelle), ein Finding je Alert-Typ

Die Definitionen liegen jeweils im Verzeichnis des Werkzeugs. profile-definition-catalog.ts stellt sie der Erkennungsengine bereit; profile-catalog.ts stellt die daraus erzeugten Laufzeitprofile für den Import und die Oberfläche bereit.

Verarbeitungsablauf

ToolProfileDefinition
  -> Quellen- und Mappingerkennung
  -> createImportProfile
  -> Profilwahl
  -> Sheetpriorisierung
  -> UI-Defaults und Statusfilter

Die Formatparser kennen keine Profile. Die Erkennungsengine liest Quellsignale, Feldregeln und Tabellenregeln ausschließlich aus dem Definitionskatalog. Die React-Anwendung verwendet lediglich den fertigen Laufzeitkatalog.

Versionierung

Jede fachliche Änderung an Erkennung, Mapping, Normalisierung oder Vergleichsschlüsseln benötigt eine neue Profilversion. Die beim Import verwendete Version wird als profileVersion im ImportedDataset gespeichert. Damit können zukünftige Re-Imports und Mappingmigrationen nachvollziehen, mit welchem Regelstand ein Datensatz verarbeitet wurde.

Neues Profil ergänzen

Ein neues Werkzeug benötigt:

1. eine versionierte Profildefinition,
2. die Registrierung im Definitionskatalog,
3. ein aus der Fabrik erzeugtes Laufzeitprofil,
4. die Registrierung im Laufzeitkatalog,
5. synthetische oder anonymisierte Fixture-Tests.

Formatparser, Erkennungsalgorithmus und React-Komponenten müssen dafür nicht geändert werden.

Microsoft Defender for IoT verwendet weiterhin den generischen Excel-/CSV-Formatadapter. Ein kleiner Source Extractor verarbeitet sowohl das bisherige Summary-/Detailtabellenpaar als auch die synthetischen Mock-Defender-CSV-Dateien cves.csv und device_inventory.csv. Die Mock-CVE-Datei wiederholt Site und Sensor als ausdruecklich simulierte Fixture-Felder, damit ein Einzelimport die CVE-Ansicht vollstaendig speist; bei einem Mehrdateiimport verbindet das Domain-Modell CVE- und Inventarzeilen weiterhin ausschliesslich ueber die explizite Device ID. Fehlende Kontext- oder Beschreibungswerte werden nicht erfunden. Der Extractor erzeugt genau ein Finding-Vorkommen je Device und CVE, aggregiert diese je CVE und bewahrt CVSS Score, Component, Status sowie wiederholte Sensorzeilen als Evidenz. Summary-Werte ohne Detail-CVE bleiben separate Aggregate und werden nicht in Findings umgewandelt. Die fachlichen CVE-, Device- und Site-Projektionen liegen ausserhalb der React-Komponente in einem deterministischen Domain-Modell.

Microsoft Defender for IoT Alerts (Profil defender-for-iot-alerts, Nutzerentscheidungen 2026-09-30) liest den OT-Sensor-Alertexport mit den Spalten Id, Title, First Detection, Last Detection, Last Activity, Severity, Description, Acknowledged, Additional Information, Source Address, Destination Address. Akzeptiert werden der native CSV-Export und eine Arbeitsmappe, deren Zellen in Spalte A je eine unveraenderte CSV-Zeile enthalten; die Originalzeile bleibt dann als rawLine Provenienz. Zeilen mit derselben Id bilden einen Alert und unterscheiden sich nur in Additional Information; alle Zeilen bleiben Evidenz, abweichende Wiederholungsspalten werden diagnostiziert. Ein Finding entspricht einem Alert-Typ (Title als Rule ID) mit einer Alerts-Tabelle im Ergebnisfenster, die jede Quellzeile einzeln zeigt (ab Profil 1.2.0). Alert Count zaehlt eindeutige Alert-Ids, Detail Rows (ab Profil 1.3.0) die Tabellenzeilen. Ab Profil 1.4.0 zeigt ein Alert-Typ mit unterschiedlichen Beschreibungen die allen Beschreibungen gemeinsamen Woerter, abweichende Stellen als …; ab Profil 1.5.0 unter dem schlichten Label Description (Feldschluessel common-description; Nutzerausnahme, siehe AGENTS.md). Severity wird eins zu eins abgebildet (Critical->Critical, Major->High, Minor->Medium, Warning->Low); Defender Severity behaelt den Nativwert. Unacknowledged (mindestens ein Alert mit Acknowledged=False) ist Deviation, vollstaendig bestaetigte Typen bleiben als Acknowledged sichtbar und sind keine Deviation. Der Export ist findings-only ohne nativen Gesamtscore und liefert deshalb keinen Pass-Rate-Beitrag; Zeitstempel bleiben unveraendert als Quelltext (Format ohne Zeitzone). Unlesbare Zeilen und fehlende Titel brechen die Extraktion ausdruecklich ab.

Darstellung von Textfeldern

Verbindlich für alle Werkzeuge und alle Ansichten: kein Aufrufer formatiert einen Feldwert selbst. Jeder werkzeuggelieferte Fließtext wird über RichTextValue ausgegeben, das die Auswertung an src/shared/markdown.ts delegiert. Ein neues Profil braucht dafür keine eigene Regel.

Behandelt werden:

• HTML-Auszeichnung, auf eine erlaubte Liste beschränkt; aktive Inhalte werden verworfen
• Markdown-Überschriften, geordnete und ungeordnete Aufzählungen, Tabellen, Codeblöcke
• **fett**, *kursiv*, `code`, [Titel](Adresse) — auch ineinander verschachtelt
• nackte Adressen im Fließtext
• Markdown-Tabellen ohne Zeilenumbrüche, wie Maester sie exportiert
• Überschriften, die mitten in einer Zeile stehen

Bewusst nicht behandelt: nummerierte Aufzählungen innerhalb einer Zeile. 1. ist ebenso oft der Anfang einer Kennung wie „1.1.1 (L1)"; eine Trennung dort würde Fachtext zerschneiden.

Zwei Regeln stützen das:

• cellText (statt clean) erhält die Zeilenstruktur eines Zellwerts. clean bleibt für Schlüssel, Kopfzeilen und Vergleiche zuständig — dort ist die Faltung richtig, im Inhalt zerstört sie die Gliederung.
• Schreibt ein Werkzeug seine Ergebnistabelle in ein Textfeld statt in eine eigene Datei, projiziert inlineResultTableSheets sie als Blatt. Sie ist dann über dieselbe Results-Schaltfläche erreichbar wie eine verknüpfte Datei.

Fällt bei einem neuen Werkzeug Auszeichnung auf, die hier fehlt, gehört sie nach src/shared/markdown.ts — nicht in das Profil und nicht in eine Komponente.

Fallback und Sicherheit

Wenn kein Werkzeugprofil ausreichend viele Signale erreicht, gewinnt das generische Profil. Nicht erkannte Felder bleiben als additional erhalten. Profile führen keinen importierten Inhalt aus und erweitern weder Netzwerk- noch Tauri-Berechtigungen.