From 7591de99e0e513db84775a1ecdcf020390bc4e44 Mon Sep 17 00:00:00 2001 From: "Adrian A. Baumann" Date: Mon, 10 Nov 2025 16:01:41 +0100 Subject: [PATCH] Documentation for file import and diagram service added --- Documentation/Datei-importieren.md | 491 ++++++++++++++++++++++++++ Documentation/diagramm.md | 544 +++++++++++++++++++++++++++++ 2 files changed, 1035 insertions(+) create mode 100644 Documentation/Datei-importieren.md create mode 100644 Documentation/diagramm.md diff --git a/Documentation/Datei-importieren.md b/Documentation/Datei-importieren.md new file mode 100644 index 0000000..400ec56 --- /dev/null +++ b/Documentation/Datei-importieren.md @@ -0,0 +1,491 @@ +# Dokumenten-Import: Anleitung + +Diese Anleitung beschreibt, wie Dokumente und Vorgaben mittels des `import-document` Management Commands in die VorgabenUI importiert werden können. + +## Übersicht + +Der `import-document` Command ermöglicht es, strukturierte Textdateien zu importieren, die Dokumente mit Einleitung, Geltungsbereich und Vorgaben enthalten. Das Format ist speziell für die einfache Erfassung und Pflege von IT-Sicherheitsstandards konzipiert. + +## Grundlegende Verwendung + +### Minimaler Aufruf + +```bash +python manage.py import-document \ + --nummer \ + --name "" \ + --dokumententyp "" +``` + +### Beispiel + +```bash +python manage.py import-document Documentation/import\ formats/r009.txt \ + --nummer "R0009" \ + --name "Serversysteme" \ + --dokumententyp "Standard IT-Sicherheit" +``` + +## Parameter + +### Pflichtparameter + +| Parameter | Beschreibung | Beispiel | +|-----------|--------------|----------| +| `file_path` | Pfad zur Importdatei | `Documentation/import formats/r009.txt` | +| `--nummer` | Dokumentnummer (eindeutig) | `R0009`, `R0066` | +| `--name` | Dokumentname | `"Logging"`, `"Serversysteme"` | +| `--dokumententyp` | Dokumententyp (muss bereits existieren) | `"Standard IT-Sicherheit"` | + +### Optionale Parameter + +| Parameter | Beschreibung | Verwendung | +|-----------|--------------|------------| +| `--gueltigkeit_von` | Startdatum der Gültigkeit | `--gueltigkeit_von 2024-01-01` | +| `--gueltigkeit_bis` | Enddatum der Gültigkeit | `--gueltigkeit_bis 2025-12-31` | +| `--dry-run` | Testlauf ohne Datenbankänderungen | `--dry-run` | +| `--verbose` | Ausführliche Ausgabe (mit `--dry-run`) | `--dry-run --verbose` | +| `--purge` | Löscht bestehende Einleitung/Geltungsbereich/Vorgaben vor Import | `--purge` | + +### Dry-Run Modus + +Der Dry-Run Modus ist besonders nützlich zum Testen: + +```bash +python manage.py import-document r009.txt \ + --nummer "R0009" \ + --name "Serversysteme" \ + --dokumententyp "Standard IT-Sicherheit" \ + --dry-run --verbose +``` + +Dies zeigt an, was importiert würde, ohne die Datenbank zu ändern. + +### Purge Modus + +**Achtung:** Der Purge-Modus löscht alle bestehenden Vorgaben des Dokuments! + +```bash +python manage.py import-document r009.txt \ + --nummer "R0009" \ + --name "Serversysteme" \ + --dokumententyp "Standard IT-Sicherheit" \ + --purge +``` + +Nutzen Sie `--dry-run --purge` zuerst, um zu sehen, was gelöscht würde. + +## Dateiformat + +### Grundstruktur + +Die Importdatei ist eine Textdatei (UTF-8 kodiert) mit speziellen Trennzeichen `>>>` am Zeilenanfang. + +### Aufbau + +``` +>>>Einleitung +>>>text +[Einleitungstext] + +>>>Geltungsbereich +>>>text +[Geltungsbereichstext] + +>>>Vorgabe [Thema] +>>>Nummer [nummer] +>>>Titel +[Titel der Vorgabe] +>>>Kurztext +>>>Text +[Kurztext-Inhalt] +>>>Langtext +>>>Text +[Langtext-Inhalt] +>>>Stichworte +[Stichwort1, Stichwort2, ...] +>>>Checkliste +[Frage 1] +[Frage 2] +``` + +### Abschnitt-Trenner + +Jeder Abschnitt beginnt mit `>>>` gefolgt vom Abschnittstyp: + +- `>>>Einleitung` - Startet den Einleitungsbereich +- `>>>Geltungsbereich` - Startet den Geltungsbereichsbereich +- `>>>Vorgabe [Thema]` - Startet eine neue Vorgabe mit angegebenem Thema + +### Abschnitttypen für Textinhalte + +Nach `>>>Einleitung`, `>>>Geltungsbereich`, `>>>Kurztext` oder `>>>Langtext` folgt ein Abschnitttyp: + +| Typ | Verwendung | Beispiel | +|-----|------------|----------| +| `>>>text` oder `>>>Text` | Normaler Fliesstext | `>>>text` | +| `>>>liste geordnet` oder `>>>Liste geordnet` | Nummerierte Liste | `>>>Liste geordnet` | +| `>>>liste ungeordnet` oder `>>>Liste ungeordnet` | Aufzählungsliste | `>>>liste ungeordnet` | + +**Hinweis:** Gross-/Kleinschreibung und Bindestriche (`liste-ungeordnet`) werden normalisiert. + +## Beispiele + +### Beispiel 1: Einfaches Dokument mit einer Vorgabe + +``` +>>>Einleitung +>>>text +Dieser Standard definiert Anforderungen für XYZ. + +>>>Geltungsbereich +>>>text +Dieser Standard gilt für alle Systeme im BIT. + +>>>Vorgabe Technik +>>>Nummer 1 +>>>Titel +Verschlüsselung verwenden +>>>Kurztext +>>>Text +Alle Verbindungen müssen verschlüsselt sein. +>>>Langtext +>>>Text +Die Verschlüsselung muss mindestens TLS 1.2 verwenden. +Es sind folgende Cipher Suites erlaubt: +>>>Liste ungeordnet +TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 +>>>Stichworte +Verschlüsselung, TLS, Kryptographie +>>>Checkliste +TLS 1.2 oder höher ist konfiguriert +Schwache Cipher Suites sind deaktiviert +``` + +### Beispiel 2: Mehrere Vorgaben mit gleichem Thema + +``` +>>>Vorgabe Organisation +>>>Nummer 1 +>>>Titel +CMDB-Erfassung +>>>Kurztext +>>>Text +Alle Assets müssen in der CMDB erfasst sein. +>>>Langtext +>>>Text +Jedes Asset muss dokumentiert werden... + +>>>Vorgabe Organisation +>>>Nummer 2 +>>>Titel +Verantwortlichkeiten +>>>Kurztext +>>>Text +Verantwortlichkeiten müssen definiert sein. +>>>Langtext +>>>Text +Für jedes System muss ein Verantwortlicher... +``` + +### Beispiel 3: Verschiedene Themen + +``` +>>>Vorgabe Technik +>>>Nummer 1 +>>>Titel +Firewall-Konfiguration +>>>Kurztext +>>>Text +Lokale Firewall muss aktiviert sein. +>>>Langtext +>>>Text +Details zur Firewall-Konfiguration... + +>>>Vorgabe Organisation +>>>Nummer 1 +>>>Titel +Dokumentation +>>>Kurztext +>>>Text +Konfiguration muss dokumentiert sein. +>>>Langtext +>>>Text +Die Firewall-Regeln müssen... + +>>>Vorgabe Informationen +>>>Nummer 1 +>>>Titel +Datenklassifizierung +>>>Kurztext +>>>Text +Daten müssen klassifiziert werden. +>>>Langtext +>>>Text +Klassifizierungsstufen sind... +``` + +### Beispiel 4: Mehrere Textabschnitte + +``` +>>>Vorgabe Technik +>>>Nummer 1 +>>>Titel +Komplexe Anforderung +>>>Kurztext +>>>Text +Erste Zusammenfassung. +>>>Langtext +>>>Text +Erster Absatz mit Details. +>>>Text +Zweiter Absatz mit weiteren Informationen. +>>>Liste ungeordnet +Punkt 1 +Punkt 2 +Punkt 3 +>>>Text +Abschliessender Text nach der Liste. +``` + +## Vorgaben-Struktur + +### Vorgabe-Header + +``` +>>>Vorgabe [Thema] +``` + +Das Thema muss in der Datenbank bereits als `Thema`-Objekt existieren. Übliche Themen: +- Organisation +- Technik +- Informationen +- Systeme +- Anwendungen +- Zonen + +### Vorgabe-Felder + +#### Nummer (Pflicht) + +``` +>>>Nummer 1 +``` + +oder inline: + +``` +>>>Nummer: 1 +``` + +Die Nummer wird als Integer gespeichert. Sie ist eindeutig innerhalb eines Dokuments und Themas. + +#### Titel (Pflicht) + +``` +>>>Titel +Titel der Vorgabe +``` + +oder inline: + +``` +>>>Titel: Titel der Vorgabe +``` + +#### Kurztext (Optional) + +``` +>>>Kurztext +>>>Text +Kurze Zusammenfassung der Vorgabe. +``` + +#### Langtext (Optional) + +``` +>>>Langtext +>>>Text +Ausführliche Beschreibung der Vorgabe. +>>>Liste ungeordnet +Punkt 1 +Punkt 2 +``` + +#### Stichworte (Optional) + +Komma-getrennte Liste: + +``` +>>>Stichworte +Firewall, Netzwerk, Sicherheit +``` + +oder als Block: + +``` +>>>Stichworte +>>>Text +Firewall, Netzwerk, Sicherheit +``` + +**Hinweis:** Stichworte werden automatisch in der Datenbank angelegt, falls sie noch nicht existieren. + +#### Checkliste (Optional) + +``` +>>>Checkliste +Ist die Firewall aktiviert? +Sind alle unnötigen Ports geschlossen? +Wurde die Konfiguration dokumentiert? +``` + +Jede Zeile wird als separate Checklistenfrage gespeichert. + +## Tipps und Best Practices + +### 1. Dry-Run vor Import + +Führen Sie immer zuerst einen Dry-Run durch: + +```bash +python manage.py import-document datei.txt \ + --nummer "R0XXX" \ + --name "Test" \ + --dokumententyp "Standard IT-Sicherheit" \ + --dry-run --verbose +``` + +### 2. Themen vorab erstellen + +Stellen Sie sicher, dass alle verwendeten Themen in der Datenbank existieren: + +```python +python manage.py shell +>>> from dokumente.models import Thema +>>> Thema.objects.get_or_create(name="Organisation") +>>> Thema.objects.get_or_create(name="Technik") +>>> Thema.objects.get_or_create(name="Informationen") +``` + +### 3. Dokumententyp vorab erstellen + +Der Dokumententyp muss existieren: + +```python +python manage.py shell +>>> from dokumente.models import Dokumententyp +>>> Dokumententyp.objects.get_or_create( +... name="Standard IT-Sicherheit", +... defaults={"verantwortliche_ve": "SR-SUR-SEC"} +... ) +``` + +### 4. Abschnitttypen prüfen + +Folgende Abschnitttypen müssen in der Datenbank existieren: +- `text` +- `liste geordnet` +- `liste ungeordnet` +- `code` +- `diagramm` + +Prüfen Sie diese in der Autorenumgebung unter "Abschnitttypen". + +### 5. UTF-8 Kodierung + +Stellen Sie sicher, dass Ihre Importdatei UTF-8 kodiert ist, besonders bei Umlauten (ä, ö, ü) und Sonderzeichen. + +### 6. Versionierung mit Purge + +Beim Re-Import mit `--purge`: + +```bash +# 1. Backup erstellen +python manage.py dumpdata dokumente.Dokument dokumente.Vorgabe > backup.json + +# 2. Import mit Purge +python manage.py import-document datei.txt \ + --nummer "R0009" \ + --name "Serversysteme" \ + --dokumententyp "Standard IT-Sicherheit" \ + --purge +``` + +### 7. Mehrzeilige Inhalte + +Mehrzeiliger Text wird automatisch erkannt: + +``` +>>>Langtext +>>>Text +Dies ist Zeile 1. +Dies ist Zeile 2. + +Dies ist ein neuer Absatz. +``` + +### 8. Leerzeilen + +Leerzeilen innerhalb eines Abschnitts werden beibehalten. Eine Leerzeile nach einem `>>>`-Trenner wird ignoriert. + +## Fehlerbehebung + +### "Dokumententyp does not exist" + +Der angegebene Dokumententyp existiert nicht in der Datenbank. + +**Lösung:** Erstellen Sie den Dokumententyp in der Autorenumgebung oder per Shell. + +### "Thema not found, skipping Vorgabe" + +Das in der Vorgabe verwendete Thema existiert nicht. + +**Lösung:** Erstellen Sie das Thema in der Autorenumgebung oder passen Sie die Importdatei an. + +### "AbschnittTyp not found" + +Ein verwendeter Abschnitttyp existiert nicht. + +**Lösung:** +- Prüfen Sie die Schreibweise (Gross-/Kleinschreibung wird normalisiert) +- Erstellen Sie den Abschnitttyp in der Autorenumgebung +- Standardtypen: `text`, `liste geordnet`, `liste ungeordnet` + +### Vorgabe wird nicht importiert + +Prüfen Sie: +- Ist `>>>Nummer` gesetzt? +- Ist `>>>Titel` gesetzt? +- Existiert das Thema? + +Verwenden Sie `--dry-run --verbose` für detaillierte Informationen. + +## Weitere Informationen + +### Beispieldateien + +Beispieldateien finden Sie in: +- `Documentation/import formats/r009.txt` +- `Documentation/import formats/r0126.txt` + +### Export-Format + +Der Export verwendet JSON statt Textformat. Für JSON-Export siehe: + +```bash +python manage.py export_json --output dokumente.json +``` + +Oder über die Web-Oberfläche: `/dokumente/R0066/?format=json` + +### Verwandte Commands + +- `export_json` - Exportiert Dokumente als JSON +- `sanity_check_vorgaben` - Prüft Vorgaben auf Konflikte +- `clear_diagram_cache` - Löscht Diagramm-Cache + +## Kontakt + +Bei Fragen oder Problemen wenden Sie sich an das Information Security Management BIT. diff --git a/Documentation/diagramm.md b/Documentation/diagramm.md new file mode 100644 index 0000000..137a1ca --- /dev/null +++ b/Documentation/diagramm.md @@ -0,0 +1,544 @@ +# Diagramme in VorgabenUI + +Diese Anleitung beschreibt, wie Diagramme in Textabschnitten verwendet werden können. VorgabenUI nutzt [Kroki](https://kroki.io/) zur Generierung von Diagrammen aus Textbeschreibungen. + +## Übersicht + +Der Abschnitttyp **"diagramm"** ermöglicht es, verschiedene Diagrammtypen direkt in Vorgaben, Einleitungen und Geltungsbereichen einzubinden. Die Diagramme werden aus Textbeschreibungen automatisch als SVG-Grafiken generiert und gecacht. + +## Grundlegende Verwendung + +### Format + +``` +[Diagrammtyp] +option: [HTML-Attribute] (optional) +[Diagramm-Code] +``` + +**Zeile 1:** Diagrammtyp (z.B. `plantuml`, `mermaid`, `graphviz`) +**Zeile 2 (optional):** `option:` gefolgt von HTML-Attributen für die Bildgrösse +**Zeile 3+:** Der eigentliche Diagramm-Quellcode + +### Standard-Einstellungen + +Wenn keine `option:`-Zeile angegeben wird, wird das Diagramm mit `width="100%"` dargestellt. + +### Grösse anpassen + +Um die Grösse des Diagramms anzupassen, verwenden Sie die `option:`-Zeile: + +``` +plantuml +option: width="50%" +@startuml +... +@enduml +``` + +Weitere Beispiele für Optionen: + +``` +option: width="800px" +option: width="60%" style="max-width: 600px;" +option: height="400px" +option: width="100%" class="img-fluid" +``` + +## Unterstützte Diagrammtypen + +Kroki unterstützt über 20 verschiedene Diagrammtypen. Die wichtigsten sind: + +| Typ | Beschreibung | Verwendung | +|-----|--------------|------------| +| `plantuml` | UML-Diagramme, Sequenzdiagramme, Aktivitätsdiagramme | Prozesse, Architekturen | +| `mermaid` | Flussdiagramme, Sequenzdiagramme, Gantt-Charts | Prozessabläufe, Zeitpläne | +| `graphviz` | Gerichtete/ungerichtete Graphen | Abhängigkeiten, Netzwerke | +| `blockdiag` | Block-Diagramme | Systemübersichten | +| `nwdiag` | Netzwerk-Diagramme | Netzwerktopologien | +| `seqdiag` | Sequenz-Diagramme | Kommunikationsabläufe | +| `c4plantuml` | C4-Modell Diagramme | Software-Architektur | +| `ditaa` | ASCII-Art zu Diagrammen | Einfache Skizzen | +| `excalidraw` | Hand-gezeichnete Diagramme | Präsentationen | +| `bpmn` | Business Process Model Notation | Geschäftsprozesse | + +Vollständige Liste: https://kroki.io/ + +## Beispiele + +### PlantUML: Sequenzdiagramm + +``` +plantuml +option: width="80%" +@startuml +Alice -> Bob: Authentifizierungsanfrage +Bob --> Alice: Authentifizierungsantwort + +Alice -> Bob: Weitere Anfrage +Alice <-- Bob: Weitere Antwort +@enduml +``` + +**Verwendung:** Darstellung von Kommunikationsabläufen, API-Interaktionen + +### PlantUML: Aktivitätsdiagramm + +``` +plantuml +@startuml +start +:Sicherheitsrichtlinie prüfen; +if (Richtlinie erfüllt?) then (ja) + :Zugriff gewähren; +else (nein) + :Zugriff verweigern; + :Incident loggen; +endif +stop +@enduml +``` + +**Verwendung:** Prozesse, Entscheidungsabläufe, Workflows + +### PlantUML: Komponentendiagramm + +``` +plantuml +option: width="70%" +@startuml +package "Web-Tier" { + [Web-Server] + [Load Balancer] +} + +package "App-Tier" { + [Application Server] + [Cache] +} + +package "Data-Tier" { + [Datenbank] +} + +[Load Balancer] --> [Web-Server] +[Web-Server] --> [Application Server] +[Application Server] --> [Cache] +[Application Server] --> [Datenbank] +@enduml +``` + +**Verwendung:** System-Architekturen, Komponenten-Übersicht + +### Mermaid: Flussdiagramm + +``` +mermaid +option: width="75%" +flowchart TD + Start[Log-Event empfangen] --> Check{Schweregrad?} + Check -->|CRITICAL| Alert[Alert auslösen] + Check -->|WARNING| Log[In Log-System speichern] + Check -->|INFO| Archive[Archivieren] + Alert --> SIEM[An SIEM weiterleiten] + Log --> SIEM + SIEM --> End[Fertig] + Archive --> End +``` + +**Verwendung:** Prozessabläufe, Entscheidungsbäume + +### Mermaid: Sequenzdiagramm + +``` +mermaid +sequenceDiagram + participant Benutzer + participant Firewall + participant Server + + Benutzer->>Firewall: Verbindungsanfrage + Firewall->>Firewall: Regel-Prüfung + alt Regel erlaubt + Firewall->>Server: Weiterleitung + Server-->>Firewall: Antwort + Firewall-->>Benutzer: Antwort + else Regel blockiert + Firewall-->>Benutzer: Verbindung abgelehnt + end +``` + +**Verwendung:** Kommunikationsabläufe mit Bedingungen + +### GraphViz: Abhängigkeitsgraph + +``` +graphviz +digraph G { + rankdir=LR; + node [shape=box, style=rounded]; + + "R0066\nLogging" -> "R0009\nServersysteme"; + "R0066\nLogging" -> "R0126\nNetzwerksicherheit"; + "R0009\nServersysteme" -> "R0135\nInformationssicherheit"; + "R0126\nNetzwerksicherheit" -> "R0135\nInformationssicherheit"; + + "R0135\nInformationssicherheit" [style="rounded,filled", fillcolor=lightblue]; +} +``` + +**Verwendung:** Abhängigkeiten zwischen Dokumenten/Standards + +### GraphViz: Netzwerk-Topologie + +``` +graphviz +option: width="100%" +graph G { + layout=neato; + + Internet [shape=cloud]; + Firewall [shape=box, style=filled, fillcolor=red]; + DMZ [shape=box, style=filled, fillcolor=yellow]; + LAN [shape=box, style=filled, fillcolor=green]; + + Internet -- Firewall [label="WAN"]; + Firewall -- DMZ [label="DMZ-Segment"]; + Firewall -- LAN [label="Internes Netz"]; +} +``` + +**Verwendung:** Netzwerk-Segmentierung, Zonen-Modelle + +### BlockDiag: System-Übersicht + +``` +blockdiag +blockdiag { + orientation = portrait; + + Client -> "Load Balancer" -> "Web-Server 1", "Web-Server 2"; + "Web-Server 1", "Web-Server 2" -> "App-Server"; + "App-Server" -> "Datenbank Primary"; + "Datenbank Primary" -> "Datenbank Replica"; + + "Load Balancer" [color = "lightblue"]; + "App-Server" [color = "lightgreen"]; + "Datenbank Primary" [color = "pink"]; +} +``` + +**Verwendung:** Einfache System-Diagramme, Datenflüsse + +### NwDiag: Netzwerk-Diagramm + +``` +nwdiag +nwdiag { + network dmz { + address = "192.168.1.0/24"; + + web01 [address = "192.168.1.10"]; + web02 [address = "192.168.1.11"]; + } + + network internal { + address = "10.0.0.0/8"; + + web01 [address = "10.0.1.10"]; + web02 [address = "10.0.1.11"]; + app01 [address = "10.0.2.10"]; + db01 [address = "10.0.3.10"]; + } +} +``` + +**Verwendung:** Netzwerk-Topologien mit IP-Adressen + +### SeqDiag: Authentifizierungsablauf + +``` +seqdiag +seqdiag { + Benutzer -> System: Benutzername + Passwort; + System -> LDAP: Authentifizierung prüfen; + LDAP --> System: Erfolgreich; + System -> 2FA: 2FA-Code anfordern; + 2FA --> Benutzer: Code per SMS; + Benutzer -> System: 2FA-Code eingeben; + System --> Benutzer: Zugriff gewährt; +} +``` + +**Verwendung:** Authentifizierungs- und Autorisierungsabläufe + +### C4 PlantUML: System-Kontext + +``` +c4plantuml +@startuml +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml + +Person(admin, "Administrator", "BIT System-Administrator") +System(vorgaben, "VorgabenUI", "IT-Sicherheits-Vorgaben Portal") +System_Ext(ldap, "LDAP", "Authentifizierung") + +Rel(admin, vorgaben, "Verwaltet Vorgaben") +Rel(vorgaben, ldap, "Authentifiziert über") +@enduml +``` + +**Verwendung:** Software-Architektur nach C4-Modell + +## Best Practices + +### 1. Diagramm-Grösse anpassen + +Verwenden Sie die `option:`-Zeile, um die Grösse für bessere Lesbarkeit anzupassen: + +``` +plantuml +option: width="60%" +... +``` + +Für sehr detaillierte Diagramme: +``` +plantuml +option: width="100%" style="max-width: 1200px;" +... +``` + +### 2. Einfachheit bevorzugen + +Halten Sie Diagramme einfach und fokussiert. Zu komplexe Diagramme sind schwer zu lesen. + +**Gut:** +``` +mermaid +flowchart LR + A[Start] --> B{Prüfung} + B -->|OK| C[Weiter] + B -->|Fehler| D[Abbruch] +``` + +**Zu komplex:** Vermeiden Sie Diagramme mit mehr als 15-20 Elementen. + +### 3. Konsistente Stil-Wahl + +Verwenden Sie für ähnliche Konzepte den gleichen Diagrammtyp: +- **Prozesse:** Mermaid Flowchart oder PlantUML Activity +- **Kommunikation:** Mermaid/PlantUML Sequence +- **Architektur:** PlantUML Component oder C4 +- **Netzwerke:** NwDiag oder GraphViz + +### 4. Beschriftungen auf Deutsch + +Verwenden Sie deutsche Beschriftungen für bessere Verständlichkeit: + +``` +mermaid +flowchart TD + Start[Anfrage empfangen] --> Prüfung{Berechtigung?} + Prüfung -->|Ja| Zugriff[Zugriff gewähren] + Prüfung -->|Nein| Ablehnung[Zugriff verweigern] +``` + +### 5. Farben sparsam einsetzen + +Nutzen Sie Farben zur Hervorhebung wichtiger Elemente: + +``` +graphviz +digraph { + node [shape=box]; + + Kritisch [style=filled, fillcolor=red, fontcolor=white]; + Wichtig [style=filled, fillcolor=orange]; + Normal [style=filled, fillcolor=lightgreen]; + + Kritisch -> Wichtig -> Normal; +} +``` + +### 6. Lesbarkeit testen + +Nach dem Speichern prüfen, ob das Diagramm in der Webansicht gut lesbar ist. Bei Bedarf: +- Grösse anpassen (`option: width="..."`) +- Diagramm vereinfachen +- Anderen Diagrammtyp wählen + +## Fehlerbehandlung + +### Diagramm wird nicht angezeigt + +**Mögliche Ursachen:** + +1. **Syntaxfehler im Diagramm-Code** + - Prüfen Sie die Syntax gemäss Dokumentation des Diagrammtyps + - Testen Sie den Code auf https://kroki.io/ + +2. **Falscher Diagrammtyp** + - Erste Zeile muss genau dem Kroki-Typ entsprechen + - Beispiel: `plantuml` (nicht `PlantUML` oder `plant-uml`) + +3. **Kroki-Server nicht erreichbar** + - Bei Fehlermeldung "Error generating diagram" Server prüfen + +### Fehlersuche + +1. **Code auf kroki.io testen:** + ``` + https://kroki.io/ + ``` + Geben Sie dort den Code ein und testen Sie die Generierung. + +2. **Diagramm-Cache leeren:** + ```bash + python manage.py clear_diagram_cache + ``` + +3. **Logs prüfen:** + Fehler werden im Application-Log ausgegeben. + +## Häufig verwendete Diagramm-Szenarien + +### IT-Sicherheit: Bedrohungsmodell + +``` +mermaid +flowchart TB + Asset[Schützenswertes Asset] + Threat[Bedrohung] + Vuln[Schwachstelle] + Control[Sicherheitsmassnahme] + + Threat -->|nutzt aus| Vuln + Vuln -->|betrifft| Asset + Control -->|schliesst| Vuln + Control -->|schützt| Asset +``` + +### Netzwerk-Segmentierung + +``` +nwdiag +nwdiag { + network internet { + address = "Internet"; + internet [shape = cloud]; + } + network dmz { + address = "DMZ (192.168.1.0/24)"; + fw [address = "192.168.1.1"]; + web [address = "192.168.1.10"]; + } + network internal { + address = "Intern (10.0.0.0/8)"; + fw [address = "10.0.0.1"]; + app [address = "10.0.1.10"]; + db [address = "10.0.2.10"]; + } + + internet -- fw; +} +``` + +### Patch-Management Prozess + +``` +plantuml +@startuml +start +:Patch-Benachrichtigung empfangen; +:Schweregrad bewerten; +if (Kritischer Patch?) then (ja) + :Sofort in Test-Umgebung testen; + if (Test erfolgreich?) then (ja) + :Notfall-Change erstellen; + :In Produktion ausrollen; + else (nein) + :Vendor kontaktieren; + endif +else (nein) + :In regulären Patch-Zyklus einplanen; + :Testen im Change-Window; + :Reguläres Rollout; +endif +:Dokumentation aktualisieren; +stop +@enduml +``` + +### Zugriffskontrolle + +``` +plantuml +@startuml +skinparam actorStyle awesome + +actor Benutzer +actor Administrator +actor "Security Team" as ST + +rectangle "VorgabenUI" { + usecase "Vorgaben lesen" as UC1 + usecase "Vorgaben bearbeiten" as UC2 + usecase "Vorgaben publizieren" as UC3 + usecase "Sicherheitsreview" as UC4 +} + +Benutzer --> UC1 +Administrator --> UC1 +Administrator --> UC2 +ST --> UC4 +UC2 .> UC4 : <> +UC4 --> UC3 +@enduml +``` + +## Weiterführende Ressourcen + +- **Kroki Dokumentation:** https://kroki.io/ +- **PlantUML Dokumentation:** https://plantuml.com/ +- **Mermaid Dokumentation:** https://mermaid.js.org/ +- **GraphViz Dokumentation:** https://graphviz.org/ +- **Live-Editor zum Testen:** https://kroki.io/ + +## Tipps für spezifische Diagrammtypen + +### PlantUML Tipps + +``` +@startuml +' Kommentare mit Apostroph +skinparam backgroundColor transparent +skinparam defaultFontName Arial +@enduml +``` + +### Mermaid Tipps + +``` +%%{ init: { 'theme': 'base' } }%% +flowchart LR + %% Kommentare mit doppeltem Prozent +``` + +### GraphViz Tipps + +``` +digraph { + // Kommentare mit doppeltem Slash + rankdir=LR; // Links nach Rechts + // rankdir=TB; // Top nach Bottom +} +``` + +## Support + +Bei Fragen oder Problemen mit Diagrammen: +1. Code auf https://kroki.io/ testen +2. Syntax-Dokumentation des jeweiligen Diagrammtyps konsultieren +3. Diagramm-Cache leeren: `python manage.py clear_diagram_cache` +4. Bei technischen Problemen: Information Security Management BIT kontaktieren