Richtlinien & Verfahren (Phase 1): Import, Rendering-Engine, Bibliothek, Coverage
Fundament des VDA-ISA-2027-Richtlinienmoduls (Spec §1–9):
- Datenmodell: PolicyDocument, PolicyRequirement, PolicyVariable (Variablen +
Feature-Flags), PolicyBaselineParam, PolicyEvidence — inkl. RLS + Tenant-Guard
- Seed-Importer (import-policies.ts): liest die echten .md-Dateien (15 Richtlinien
L00/R01–R14 + 11 Verfahren), mapping.json (120 Anforderungen/46 Controls),
variables.schema.json (53 Variablen/Flags), Technische-Sicherheits-Baseline
(31 BL-Parameter) und Nachweisregister; idempotent pro Mandant
- 6 im Vorlagenpaket beschädigte Variablen-Tokens (VA-08/09/10/12/13) repariert
(dokumentiert im README des Übergabepakets)
- Rendering-Engine (policy-render.ts, Handlebars + marked): verschachtelte
{{#if FLAG}}, {{VARIABLE}}, {{LINK:…}}-Deeplinks, Hidden-Anker + BL-Referenzen
im Lesemodus entfernt (Wert bleibt), zentral verwaltete Abschnitte unterdrückt,
wiederholtes „Umsetzung bei <Org>" reduziert (§7a); lenienter Fallback +
Residue-Check über alle Flag-Kombinationen (analog _verify.py)
- UI: Bibliothek mit Typ-Chips/KPIs, Lesemodus-Popup (einklappbare Info-Tabelle,
Control-Chips, Richtlinie↔Verfahren-Verlinkung), Coverage-Matrix
(Control → Richtlinie → MUSS/SOLL → Verfahren → Anforderungs-IDs)
- Nav-Punkt „Richtlinien" aktiviert; de/en-Übersetzungen
Verifiziert: Import 28 Dokumente/120 Anforderungen; Rendering rückstandsfrei
über alle Flag-Kombinationen; Bibliothek, Lesemodus (R08 nested flags), Coverage
im Browser.
Später (Phase 2+): Bearbeiten/Freigabe-Workflow mit Versionierung, verwaltete
Tabellen (Krypto-/Risiko-/Klassifizierungsregister), Anwender-Handbuch,
DOCX/PDF-Export, Word-Upload, KI-Wizard, zentrale Baseline-/Variablen-Einstellseite.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,148 @@
|
||||
# Integrationsleitfaden für den Programmierer – ISMS-Vorlagenpaket v2
|
||||
|
||||
Dieses Dokument beschreibt, wie die Richtlinien-Templates, Variablen, das versteckte Anforderungs-Mapping und die Verlinkungen in den Wizard/das Tool eingebaut werden. Zielgruppe: die Person, die den Wizard implementiert.
|
||||
|
||||
## 1. Paketstruktur
|
||||
|
||||
```
|
||||
ISMS-Vorlagenpaket-v2/
|
||||
├── 00_Integrationsleitfaden_Wizard.md ← dieses Dokument
|
||||
├── variables.schema.json ← alle Wizard-Variablen (Single Source of Truth)
|
||||
├── mapping.json ← Anforderungs-Mapping (REQ/IMPL ↔ ISA-Control ↔ Richtlinie)
|
||||
├── ISA-Mapping-Matrix.md ← menschenlesbare ISA-Matrix (ersetzt "Bezug zu VDA ISA")
|
||||
├── Technische-Sicherheits-Baseline.md ← zentrale konkrete Parameter (BL-IDs), einzige Pflegestelle
|
||||
├── Nachweisregister_zentral.md ← zentrales Nachweis-Template
|
||||
├── richtlinien/
|
||||
│ ├── L00_Informationssicherheitsleitlinie.md
|
||||
│ └── R01 … R14
|
||||
└── verfahren/
|
||||
└── VA-01 … VA-13 ← Verfahrensanweisungen (Abläufe zu den Richtlinien)
|
||||
```
|
||||
|
||||
**Richtlinie vs. Verfahren:** Die Richtlinie (R01–R14) sagt *was* gilt und *wie* es grundsätzlich umgesetzt ist. Die Verfahrensanweisung (VA-01–VA-13) beschreibt den konkreten *Ablauf* (Auslöser → Schritte → RACI → Ergebnis/Nachweis). Jedes Verfahren trägt einen Hidden-Anker `<!-- FULFILLS <req-ids> | POLICY <Rxx> -->`; die erfüllten Anforderungen sind zusätzlich je Eintrag in `mapping.json` (`verfahren`-Liste) und je Anforderung (`verfahren`-Feld) hinterlegt. So fließen Verfahren automatisch in die Nachweisdokumentation ein.
|
||||
|
||||
## 2. Vier Bausteine im Überblick
|
||||
|
||||
1. **Variablen** (`{{NAME}}`, UPPER_SNAKE) – organisationsspezifische Werte, aus `variables.schema.json`.
|
||||
2. **Bedingungsblöcke** (`{{#if FLAG_X}} … {{/if}}`) – blenden Anforderungen/Abschnitte je nach Feature-Flag und Reifegrad ein/aus.
|
||||
3. **Hidden-Anker** (`<!-- REQ … -->` / `<!-- IMPL … -->`) – unsichtbare IDs je Einzelanforderung; Grundlage für Nachweis-Mapping und Deep-Links.
|
||||
4. **Link-Platzhalter** (`{{LINK:ZIEL}}`) – Verweise zwischen Dokumenten und zu Nachweisen, die das Tool zur Laufzeit auflöst.
|
||||
|
||||
## 3. Templating-Konvention (Handlebars-kompatibel)
|
||||
|
||||
| Konstrukt | Bedeutung |
|
||||
|-----------|-----------|
|
||||
| `{{ORG_NAME}}` | Variablen-Einsetzung |
|
||||
| `{{#if FLAG_CLOUD_USED}} … {{/if}}` | bedingter Block (Feature-Flag) |
|
||||
| `{{#if FLAG_INCLUDE_SHOULD}} … {{/if}}` | SOLL-Anforderungen ein-/ausblenden (Reifegrad) |
|
||||
| `[MUSS]` / `[SOLL]` | Text-Kennzeichnung der Anforderungsstufe |
|
||||
| `<!-- REQ 1.2.1-M1 -->` | Hidden-Anker vor einer Anforderung |
|
||||
| `<!-- IMPL 1.2.1-M1 -->` | Hidden-Anker vor dem zugehörigen Umsetzungstext |
|
||||
| `{{LINK:R02}}` | Link-Platzhalter (siehe Abschnitt 6) |
|
||||
|
||||
Beim Rendern: Variablen einsetzen, `{{#if}}`-Blöcke nach Kontext auflösen, `{{LINK:…}}` in echte Links übersetzen. Die `<!-- … -->`-Anker **im Dokument belassen** (sie sind im Lesemodus unsichtbar) – das Tool braucht sie zur Laufzeit für Deep-Links und Nachweiszuordnung. Für den PDF-/Druckexport können sie entfernt werden.
|
||||
|
||||
## 4. Aufbau einer thematischen Richtlinie (R01–R14)
|
||||
|
||||
```
|
||||
### 3.1 <Control-Titel> (ISA 1.2.1)
|
||||
|
||||
**Anforderung**
|
||||
<!-- REQ 1.2.1-M1 -->
|
||||
- **[MUSS]** <normativer Anforderungstext>
|
||||
{{#if FLAG_INCLUDE_SHOULD}}
|
||||
<!-- REQ 1.2.1-S1 -->
|
||||
- **[SOLL]** <SOLL-Anforderung>
|
||||
{{/if}}
|
||||
|
||||
**Umsetzung bei {{ORG_NAME}}**
|
||||
<!-- IMPL 1.2.1-M1 -->
|
||||
<vorformulierter Ist-Text mit Variablen/Optionalblöcken>
|
||||
```
|
||||
|
||||
Jede Anforderung (`REQ`) hat genau eine Umsetzung (`IMPL`) mit identischer ID. Ausnahme **L00** (Leitlinie): kombiniertes Dokument, dort ist `IMPL`-Anker = `REQ`-Anker (in `mapping.json` bereits so hinterlegt).
|
||||
|
||||
**ID-Schema:** `<ISA-Control>-<M|S><laufnr>`, z. B. `1.2.1-M1`, `5.2.9-S1`. MUSS und SOLL werden getrennt nummeriert.
|
||||
|
||||
## 5. `mapping.json` – das versteckte Anforderungs-Mapping
|
||||
|
||||
Zentrale Datei, die je Einzelanforderung Metadaten bündelt. Aufbau je Eintrag:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "1.2.1-M1",
|
||||
"policy": "R01",
|
||||
"policy_file": "R01_ISMS-Organisation-und-Rollen.md",
|
||||
"control": "1.2.1",
|
||||
"type": "MUSS",
|
||||
"req_anchor": "REQ 1.2.1-M1",
|
||||
"impl_anchor": "IMPL 1.2.1-M1",
|
||||
"condition": null,
|
||||
"requirement": "Der Geltungsbereich des ISMS … ist bestimmt und dokumentiert.",
|
||||
"implementation": "Der ISMS-Geltungsbereich ist im ISMS-Tool … dokumentiert.",
|
||||
"link": "{{LINK:R01#1.2.1}}",
|
||||
"nachweis_link": "{{LINK:NACHWEISREGISTER}}"
|
||||
}
|
||||
```
|
||||
|
||||
- `condition` = `null` (immer aktiv), `"FLAG_INCLUDE_SHOULD"` (nur bei SOLL) oder ein Feature-Flag. Anforderungen, deren Bedingung im Kontext `false` ist, erscheinen im Dokument nicht und werden in der Nachweisdoku übersprungen.
|
||||
- **Reading-Mode:** Der Anwender sieht nur Anforderung + Umsetzung, keine IDs. Das Tool blendet je Anforderung eine dezente Verlinkung („Nachweise") ein, die über `nachweis_link` bzw. die ID auf den Nachweiseintrag zeigt.
|
||||
|
||||
## 6. Link-Platzhalter `{{LINK:ZIEL}}` auflösen
|
||||
|
||||
Das Tool ersetzt Platzhalter durch echte Deep-Links (unabhängig von Dateipfaden):
|
||||
|
||||
| Platzhalter | Ziel |
|
||||
|-------------|------|
|
||||
| `{{LINK:L00}}` … `{{LINK:R14}}` | jeweiliges Richtlinien-Dokument |
|
||||
| `{{LINK:R01#1.2.1}}` | Sprungziel auf Control-Abschnitt (Anker aus ID ableitbar) |
|
||||
| `{{LINK:NACHWEISREGISTER}}` | zentrales Nachweisregister |
|
||||
| `{{LINK:ISA_MAPPING}}` | ISA-Mapping-Matrix |
|
||||
| `{{LINK:BASELINE}}` | Technische Sicherheits-Baseline |
|
||||
| `{{LINK:VA-01}}` … `{{LINK:VA-13}}` | Verfahrensanweisungen |
|
||||
|
||||
**Konkrete Parameter (Passwort, Fristen, Krypto …):** liegen ausschließlich in `Technische-Sicherheits-Baseline.md` und im Schema (Variablen wie `PW_MIN_LENGTH`, `LOG_RETENTION`). Die Umsetzungstexte referenzieren die Baseline-IDs (`BL-IAM-01` …) und rendern die Werte über dieselben Variablen – so gibt es genau eine Pflegestelle je Wert.
|
||||
|
||||
Empfehlung: eine Auflösungstabelle `DOC_ID → interne Tool-URL` pflegen; unbekannte Ziele als Warnung loggen.
|
||||
|
||||
## 7. Wizard-Ablauf (empfohlen)
|
||||
|
||||
1. **Schema laden** (`variables.schema.json`) → Eingabemasken erzeugen. Reihenfolge: Organisation → Geltungsbereich → Rollen → ISMS-Tool → Feature-Flags → Reifegrad → tech. Lösungen (TECH_*) → Metadaten.
|
||||
2. **Kontext validieren** (Pflichtfelder `required`, Defaults übernehmen).
|
||||
3. **Rendern** je Dokument: Variablen einsetzen, `{{#if}}` auflösen, `{{LINK}}` übersetzen, Hidden-Anker belassen.
|
||||
4. **Mapping filtern**: aus `mapping.json` alle Anforderungen entfernen, deren `condition` im Kontext `false` ist → ergibt die **aktive Anforderungsliste** dieses Mandanten.
|
||||
5. **Speichern/Verknüpfen** im Tool.
|
||||
|
||||
### Minimal-Render (Node/Handlebars)
|
||||
|
||||
```js
|
||||
import Handlebars from "handlebars";
|
||||
const render = (tpl, ctx) =>
|
||||
Handlebars.compile(tpl, { noEscape: true })(ctx) // Hidden-Anker bleiben erhalten
|
||||
.replace(/\{\{LINK:([^}]+)\}\}/g, (_, id) => resolveLink(id));
|
||||
```
|
||||
|
||||
## 8. Nachweisdokumentation aus dem Mapping bauen
|
||||
|
||||
Genau der Zweck des Mappings: Aus `mapping.json` + Nachweiseinträgen lässt sich per Knopfdruck eine Nachweisdoku erzeugen. Vorgehen:
|
||||
|
||||
1. Aktive Anforderungen ermitteln (Abschnitt 7, Schritt 4).
|
||||
2. Je Anforderung: `id`, `type`, `requirement`, `implementation`, Link zur Richtlinie (`link`) und zum Nachweis (`nachweis_link`) zusammenstellen.
|
||||
3. Nachweise aus {{TOOL_NAME}} anhängen (Owner/Turnus aus `Nachweisregister_zentral.md`).
|
||||
4. Ausgabe als Tabelle/Export (z. B. für das VDA-ISA-Assessment: Spalten „Implementation description" = `implementation`, „Reference documentation" = Nachweis-Link).
|
||||
|
||||
So entsteht die Assessment-Sicht, ohne dass der Anwender im Lesemodus mit IDs konfrontiert wird.
|
||||
|
||||
## 9. Cross-Links zwischen Dokumenten
|
||||
|
||||
Jede Richtlinie enthält einen Abschnitt **„Verwandte Dokumente"** mit `{{LINK:…}}` auf Leitlinie, ISA-Matrix, Nachweisregister und thematisch verwandte Richtlinien. Innerhalb der Umsetzungstexte stehen zusätzlich kontextbezogene Verweise (z. B. R08 verweist bei Zugriffsrechten auf R10). Das Tool löst alle Platzhalter einheitlich auf.
|
||||
|
||||
## 10. Pflege & Konsistenz
|
||||
|
||||
- **Neue Variable:** zuerst in `variables.schema.json`, dann im Template verwenden.
|
||||
- **Neue Anforderung/Control:** Anforderung + Umsetzung im Template ergänzen (mit `REQ`/`IMPL`-Ankern) **und** Eintrag in `mapping.json`; ISA-Matrix neu erzeugen.
|
||||
- **Konsistenzcheck vor Auslieferung (empfohlen):** (a) jeder `{{NAME}}` existiert im Schema; (b) jeder `REQ`/`IMPL`-Anker im Dokument hat einen `mapping.json`-Eintrag und umgekehrt; (c) jedes `{{LINK:…}}`-Ziel ist auflösbar. Die mitgelieferten Generatoren (`_generate_v2.py`, `_matrix.py`) sind die Referenzimplementierung dieser Regeln.
|
||||
|
||||
## 11. Reifegrad
|
||||
|
||||
`FLAG_INCLUDE_SHOULD = true` → Reifegrad 3 (MUSS + SOLL). `false` → reines MUSS-Set. Höhere Reifegrade (4/5) lassen sich später als zusätzliche `condition`-Stufe (z. B. `FLAG_LEVEL_4`) ergänzen, ohne die Struktur zu ändern.
|
||||
Reference in New Issue
Block a user