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:

{
  "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)

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.