98 lines
7.6 KiB
Markdown
98 lines
7.6 KiB
Markdown
# 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.
|