adebaumann/vgui-cicd

Fork 0

Files

Adrian A. Baumann 6af0b02442

Documentation for data import updated

2026-02-20 10:03:52 +01:00

10 KiB

Raw Blame History

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

python manage.py import-document <dateipfad> \
  --nummer <dokumentnummer> \
  --name "<dokumentname>" \
  --dokumententyp "<typ>"

Beispiel

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 zum Testen gedacht:

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!

python manage.py import-document r009.txt \
  --nummer "R0009" \
  --name "Serversysteme" \
  --dokumententyp "Standard IT-Sicherheit" \
  --purge

Mit --dry-run --purge kann zuerst geprüft werden, 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. Die bestehenden Themen sind - wie in den bestehenden Standards - aus dem IT-Grundschutz übernommen:

Organisation
Technik
Informationen
Systeme
Anwendungen
Zonen

Vorgabe-Felder

Nummer (Pflicht)

>>>Nummer 1

oder inline:

Die Nummer wird als Integer gespeichert. Sie ist nicht eindeutig innerhalb eines Dokuments und Themas. Wenn mehrere Vorgaben im selben Thema mit der selben Nummer vorkommen, darf sich der Geltungszeitraum der Vorgaben nicht überschneiden (wird beim Import geprüft).

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

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

Immer zuerst einen Dry-Run durchführen:

python manage.py import-document datei.txt \
  --nummer "R0XXX" \
  --name "Test" \
  --dokumententyp "Standard IT-Sicherheit" \
  --dry-run --verbose

2. Themen vorab erstellen

Sicherstellen, dass alle verwendeten Themen in der Datenbank existieren:

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 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 in der Autorenumgebung unter "Abschnitttypen".

5. UTF-8 Kodierung

Sicherstellen, dass die Importdatei UTF-8 kodiert ist, besonders bei Umlauten (ä, ö, ü) und Sonderzeichen.

6. Versionierung mit Purge

Beim Re-Import mit --purge:

# 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: Dokumententyp aus dem IT-Grundschutz verwenden, nötigenfalls hinzufügen in der Autorenumgebung oder per Shell.

"Thema not found, skipping Vorgabe"

Das in der Vorgabe verwendete Thema existiert nicht.

Lösung: Thema in der Autorenumgebung erstellen oder Importdatei anpassen.

"AbschnittTyp not found"

Ein verwendeter Abschnitttyp existiert nicht.

Lösung:

Schreibweise prüfen (Gross-/Kleinschreibung und "-"/" " wird normalisiert)
Wenn nötig Abschnitttyp in der Autorenumgebung erstellen (Achtung! Ausgabeformat muss im Code definiert werden)
Standardtypen: text, liste geordnet, liste ungeordnet, tabelle, code

Vorgabe wird nicht importiert

Prüfen:

Ist >>>Nummer gesetzt?
Ist >>>Titel gesetzt?
Existiert das Thema?

--dry-run --verbose für detaillierte Informationen.

Weitere Informationen

Beispieldateien

Beispieldateien:

Documentation/import formats/r009.txt
Documentation/import formats/r0126.txt

Export-Format

Der Export verwendet JSON statt Textformat. Für JSON-Export siehe:

python manage.py export_json --output dokumente.json

Oder über die Web-Oberfläche: /dokumente/R0066/?format=json

10 KiB Raw Blame History