# 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

```text
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.