certvia/seed/isms-vorlagenpaket-v2/00_Integrationsleitfaden_Wizard.md

# 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.