95 lines
5.7 KiB
Markdown
95 lines
5.7 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 |
|
|
|
|
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.
|
|
|
|
## 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.
|