476 lines
10 KiB
Markdown
476 lines
10 KiB
Markdown
# 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 <dateipfad> \
|
|
--nummer <dokumentnummer> \
|
|
--name "<dokumentname>" \
|
|
--dokumententyp "<typ>"
|
|
```
|
|
|
|
### 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 zum Testen gedacht:
|
|
|
|
```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
|
|
```
|
|
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
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 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`:
|
|
|
|
```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:** 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:
|
|
|
|
```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
|