adebaumann/vgui-cicd

Fork 0

Files

Adrian A. Baumann 0866e604bc

SonarQube Scan / SonarQube Trigger (push) Successful in 55s

Details

Documentation change regarding diagram cache

2025-12-08 15:01:14 +01:00

12 KiB

Raw Blame History

Diagramme in VorgabenUI

Diese Anleitung beschreibt, wie Diagramme in Textabschnitten verwendet werden können. VorgabenUI nutzt Kroki 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:

Syntaxfehler im Diagramm-Code
- Prüfen Sie die Syntax gemäss Dokumentation des Diagrammtyps
- Testen Sie den Code auf https://kroki.io/
Falscher Diagrammtyp
- Erste Zeile muss genau dem Kroki-Typ entsprechen
- Beispiel: plantuml (nicht PlantUML oder plant-uml)
Kroki-Server nicht erreichbar
- Bei Fehlermeldung "Error generating diagram" Server prüfen

Fehlersuche

Code auf kroki.io testen:
```
https://kroki.io/
```
Geben Sie dort den Code ein und testen Sie die Generierung.
Diagramm-Cache leeren:
```
python manage.py clear_diagram_cache
```
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 : <<extends>>
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:

Code auf https://kroki.io/ testen
Syntax-Dokumentation des jeweiligen Diagrammtyps konsultieren
(Nur mit Shell-Zugriff auf Kubernetes-Pod möglich): Diagramm-Cache leeren: python manage.py clear_diagram_cache
Bei technischen Problemen: Information Security Management BIT kontaktieren

12 KiB Raw Blame History