msolarczekandClaude Opus 5
c8e6f30a27
Unveränderter Stand von certvia/dev (a48c5fb) plus Craftvia-Spezifikation und Brandbook unter docs/craftvia/. ISMS-Module werden im Folgecommit entfernt. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
149 lines
8.8 KiB
Markdown
149 lines
8.8 KiB
Markdown
# 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.
|