Daten importieren

Überblick

Alle Befehle laufen im Container im Verzeichnis /var/www/html (bei Instanzen von Nerd-IT führt das Betriebsteam den Import aus).

Der Befehl swark:import:datamodel

php artisan swark:import:datamodel <pfad> [--governance] [--compliance] [--it] [--auditing] [--markdown-only]

Ablauf:

1. Excel (falls vorhanden und nicht --markdown-only): Blätter werden über ihren Namen gefunden und in fester Reihenfolge eingelesen. Fehlt ein Blatt einer aktivierten Kategorie, bricht der Import mit «Specified sheet 'X' does not exist» ab. Zusätzliche Blätter werden ignoriert. Der Excel-Import läuft in einer Datenbanktransaktion; bei einem Fehler wird er vollständig zurückgerollt.
2. Markdown/YAML: Unterordner regulations/ (nur wenn Kategorie Compliance aktiv ist).
3. Nachlauf: Bei aktiver Kategorie Compliance werden die Geltungsbereiche aller Regeln neu ermittelt.

Fehlt import.xlsx, erscheint eine Warnung und der Import fährt mit Schritt 2 fort.

Verhalten bei wiederholtem Import

• Objekte werden über ihre Scomp-ID gefunden und aktualisiert (Upsert). Objekte ohne Scomp-Spalte werden über ihre natürlichen Schlüssel gefunden (zum Beispiel Release über Software und Version).
• Es wird nichts gelöscht: Zeilen, die aus der Excel-Datei entfernt wurden, bleiben in der Datenbank.
• Zuordnungen von Findings, Massnahmen und KPIs werden je Zeile gelöscht und neu geschrieben, ebenso die Messung eines KPI.
• Für einen sauberen Neuaufbau: Datenbank leeren (php artisan migrate:fresh --force) und neu importieren. Das löscht auch alle Benutzer und alle im Admin-Bereich erfassten Daten.

Kategorien und Reihenfolge

Die Reihenfolge der Blätter in der Datei ist egal; swark liest in dieser Reihenfolge:

Wer nur eine Kategorie importiert, braucht nur die Blätter dieser Kategorie und der Grunddaten. Referenzen auf Objekte aus nicht importierten Kategorien funktionieren nur innerhalb desselben Laufs; ein Blatt kann nur auf Scomp-IDs verweisen, die im selben Importlauf schon eingelesen wurden (Ausnahme: Resource Type db-schema, siehe unten).

Aufbau eines Blatts

• Die ersten 1 bis 3 Zeilen sind Kopfzeilen; ihre Anzahl ist je Blatt fest (Spalte «Kopf» in den Tabellen unten). Die Daten beginnen in der Zeile danach.
• Spalten werden über ihre Position (A, B, C …) gelesen, nicht über die Überschrift. Die Überschriften dürfen frei formuliert sein, die Reihenfolge nicht.
• Leere Zeilen werden übersprungen.
• Pflichtfelder (in den Tabellen mit «Pflicht» markiert): Ist die Zelle leer, bricht der Import mit «Invalid empty string at [Sheet:'…',row:…,col:…]» ab.
• Spalten mit dem Vermerk «nicht importiert» werden gelesen, aber nicht gespeichert.
• Datumswerte am besten als Text im Format JJJJ-MM-TT (oder TT.MM.JJJJ) eingeben, nicht als Excel-Datumszahl.

Referenz-Syntax

Die zweite Kopfzeile vieler Blätter beschreibt, was in eine Spalte gehört. Die Notation:

Besondere Schlüssel:

• <software>:latest verweist auf die Release, die beim Einlesen der Software als «latest» markiert war. Beim ersten Import ist das die automatisch angelegte Platzhalter-Release *.
• <technologie>:latest verweist auf die automatisch angelegte Version latest einer Technologie.
• Regulierungskapitel: <regulierung>:<kapitelnummer>, Controls: <regulierung>:<control-id>, Fragen und Ziele: <strategie>:<scomp-id> (Ziele zusätzlich auch nur <scomp-id>).
• Protokoll-Stacks werden über ihren Namen in Kleinbuchstaben angesprochen (zum Beispiel https, json/rest over https).
• Logische Zonen sind in Klein- und Grossschreibung ansprechbar (intern und INTERN).

Verweist eine Zelle auf einen unbekannten Schlüssel, bricht der Import mit «Key 'x' of type 'y' is not registered» ab und listet die bekannten Werte.

Die Tabellenblätter

Das Beispiel-Workbook der Demo (Importvorlage mit Lumen-Daten herunterladen) enthält alle 33 Blätter. Spalten der Reihe nach ab A.

Grunddaten

Technologies (Kopf: 1)

Beispiel: TLS | tls | protocol | 1.2,1.3. Hinweis: Protokoll-Stacks im Demo-Datensatz verweisen auf eine Technologie any, die deshalb ebenfalls angelegt sein muss.

Criticality (Kopf: 1)

Protection goals (Kopf: 1)

Data classifications (Kopf: 1)

Compliance

Regulations (Kopf: 1): A Name, B Scomp-ID (Pflicht).

Regulation chapters (Kopf: 2)

Regulation controls (Kopf: 2)

Auditing

Scope templates (Kopf: 1)

Policies (Kopf: 1): A Name, B Scomp-ID (Pflicht), C Description (Markdown).

Rules (Kopf: 2)

Beispiel E: logical-zones-by-scomp-id:{"scomp_ids":["b2x"]}.

Governance

Strategies (Kopf: 1): A Name, B Scomp-ID (Pflicht).

Strategy questions (Kopf: 2)

Strategy objectives (Kopf: 2)

Measurement periods (Kopf: 2)

Die erste Periode im Blatt ist die Standardperiode für alle Messungen aus dem Blatt «Metrics».

Findings, Massnahmen, Metriken

Findings (Kopf: 2)

Actions (Kopf: 2)

Metrics (Kopf: 2)

Infrastruktur und Architektur (Kategorie it)

Actors (Kopf: 1): A Name, B Scomp-ID (Pflicht).

Logical zones (Kopf: 2)

Die Zugriffsregeln werden erst nach allen Zonen eingelesen; Vorwärtsverweise auf spätere Zeilen sind daher erlaubt.

Stages (Kopf: 1): A Name (Pflicht), B Scomp-ID (Pflicht).

Protocol stacks (Kopf: 2)

In 0.2.1 müssen alle fünf Schichtspalten befüllt sein; eine leere Zelle führt zum Abbruch.

Resource types (Kopf: 2)

Pflichteintrag: Ein Resource Type mit der Scomp-ID db-schema muss existieren (in diesem Blatt oder schon in der Datenbank), sobald die Kategorie it importiert wird. Sonst bricht der Import beim Blatt «Application instances» ab.

Software (Kopf: 1)

Jede neue Software erhält automatisch eine Platzhalter-Release *.

Systems (Kopf: 2)

Releases (Kopf: 2): A Software (Pflicht, ${software.scomp_id}), B Version (Pflicht). Jede Zeile markiert ihre Version als «latest» der Software; die letzte Zeile einer Software gewinnt.

Managed accounts (Kopf: 2)

Managed offers (Kopf: 3)

Managed subscriptions (Kopf: 2)

Baremetals (Kopf: 3)

D bis G nur für gemietete Maschinen; D und E müssen dann beide gesetzt sein.

Clusters (Kopf: 2)

Die Mitglieder werden erst nach Hosts, Runtimes und Application Instances zugeordnet; Verweise auf später eingelesene Objekte sind daher erlaubt.

Hosts (Kopf: 2)

Ein Eltern-Host muss in einer früheren Zeile stehen.

Runtimes (Kopf: 2)

Application instances (Kopf: 3)

Genau ein Executor ist nötig: H, sonst I, sonst M mit O. Fehlt er, bricht der Import mit «Can not locate executor type» ab.

Beispiele aus dem Demo-Datensatz:

wsus | wsus-prod | INFRA | prod | | mssql-wsus-prod:wsus | | dc1
rancher | rancher-infra | INFRA | prod | | | kubernetes-prod:ssh:22,kubernetes-prod:https:8443 | | | | | | kubernetes-prod | | rancher

Einschränkung 0.2.1: Eine bestimmte Version lässt sich für eine Application Instance im Excel nicht angeben; das Frontend zeigt die Version *. Die Release kann danach im Panel Operations geändert werden; ein erneuter Import setzt sie wieder auf latest zurück.

Markdown- und YAML-Import

Liegt neben import.xlsx ein Ordner regulations/, liest der Import ihn ein (Kategorie Compliance muss aktiv sein; mit --markdown-only nur dieser Teil):

<import-ordner>/
├── import.xlsx
└── regulations/
    └── <regulierung>/            Ordnername = Scomp-ID der Regulierung
        ├── data.yaml             optional: name, scomp_id
        └── <kapitel>/            Ordnername = Kapitelnummer
            ├── law.md            Frontmatter heading, relevancy (yes | partly | no); Inhalt = amtlicher Text
            ├── summary.md        Inhalt = Zusammenfassung
            ├── actual.md         Inhalt = Ist-Zustand
            ├── target.md         Inhalt = Soll-Zustand
            └── controls/
                └── <beliebig>.md Frontmatter external_id, name; Inhalt = Control-Text

Beispiel law.md:

---
relevancy: partly
heading: Meldepflichten
---

Text des Artikels …

Beispiel controls/1.md:

---
name: Konzepte für Risikoanalyse
external_id: 21.2.a
---
Konzepte in Bezug auf die Risikoanalyse sind vorhanden.

Regeln:

• Alle Dateien sind optional. Existiert law.md, muss das Frontmatter heading und relevancy enthalten.
• Kapitel werden über Regulierung und Kapitelnummer gefunden und aktualisiert, Controls über Regulierung und external_id.
• Eigene Ist- und Sollzustände für die mitgelieferte NIS2 lassen sich in einem eigenen Import-Ordner ablegen: regulations/nis2/21/actual.md usw. Nur vorhandene Dateien überschreiben die jeweiligen Felder.

Frontmatter ist YAML zwischen zwei Zeilen --- am Dateianfang.

Weitere Artisan-Befehle

Ein Export der Daten als Excel-Vorlage ist im Code vorbereitet, aber in 0.2.1 weder als Befehl noch in der Oberfläche erreichbar. Die README von swark nennt die Befehle app:import und app:import:content; diese existieren in 0.2.1 nicht (richtig: swark:import:datamodel und swark:import:content).

Zusätzlich stehen die Laravel- und Filament-Standardbefehle zur Verfügung, etwa migrate, migrate:fresh, optimize, optimize:clear, storage:link, route:list und make:filament-user.

Vorgehen für einen Erstimport

1. Die Importvorlage als Ausgangspunkt nehmen, Demo-Zeilen löschen, Kopfzeilen stehen lassen.
2. Blätter in der Reihenfolge der Abhängigkeiten befüllen: Grunddaten → Zonen, Stages, Technologien, Protokoll-Stacks, Resource Types (mit db-schema) → Software und Releases → Baremetals, Hosts, Runtimes, Cluster → Application Instances → Strategie, Compliance, Findings, Massnahmen, Metriken.
3. Für leere Kategorien die Blätter trotzdem stehen lassen (nur Kopfzeilen) oder den Import mit Kategorie-Optionen einschränken.
4. Import ausführen und die Ausgabe prüfen («Importing sheet …», «… done»). Bei einem Abbruch nennt die Meldung Blatt, Zeile und Spalte bzw. den unbekannten Schlüssel.
5. Optional NIS2: php artisan swark:import:datamodel --markdown-only default-importables.