Achse 5: Vorgehensweisen

Onboarding KMU

Der Einstieg für KMU in Git-native Compliance folgt einem schrittweisen Pfad:

Git-Repository initialisieren — Struktur mit .gitcover/-Verzeichnis, V7GUID-Konfiguration
OSCAL-Katalog auswählen — GoBD-Baseline, BSI-Bausteine oder individuelles Profil
OPA-Policies aktivieren — Pre-receive-Hooks für Validierung vor Commit
GPG-Signierung einrichten — Pro Akteur ein GPG-Schlüsselpaar
Beleg-Kette starten — Erste V7GUIDs vergeben, prev-hash-Verkettung beginnen

Für Entrepreneurs ab Nebenerwerbs-Level

Der Einstieg kann mit einer sehr einfachen Geschichte beginnen: GCDMS für Belegarchivierung, GCPN für Nachweisketten. Später erweitern: OSCAL-Policies, OPA-Validierung, Multi-Tenant.

Interaktives Onboarding: Die „Compliance City"

Anstelle klassischer Fragebögen erfolgt das Onboarding als modularer Aufbau dem Konzept einer Stadt auf einer Lego-Grundplatte. Jede architektonische Entscheidung und jede fachliche Anforderung entspricht einem Baustein oder einer Baugruppe (Lego-Set), das als strukturiertes Modul im neu initialisierten Default-Git-Repository abgelegt und versioniert wird.

Die Analogie für den Anwender:

Die Grundplatte: Das leere, frisch für den Tenant angelegte Git-Repository in seiner Infrastruktur. Es bietet den genormten Rahmen (die Noppen), auf dem alles andockt.
Die Bausteine: Modulare Konfiguration und Servicedateien. Erst wenn ein Baustein einrastet (Git-Commit), wird die entsprechende Funktion oder Compliance-Prüfung aktiv.

Phase 1 — Grundplatte auslegen (Initialisierung & Identität):

Das System erstellt automatisiert das Default-Repository für den Tenant. Der Onboarding-Assistent ermittelt die Identität des Unternehmens. Die Daten werden strukturiert im 'TOP' (Tenant Organization Profile) Repository abgelegt — der erste Git-Commit ist bereits der erste auditierbare Compliance-Prozess. Übrigens: Tenants können natürlich auch hierarchisch organisiert werden, wie Unternehmensstrukturen, denen sie zugehören.

Baustein	Technische Entsprechung	Zweck
Grundplatte	`git init --object-format=sha256`	Basis aller Tenant-Aktivitäten im 'TOP' Git-Repository und Verzeichnis
Rathaus	`./.gitcover`	GitCover Dot-Directory, in dem die Tenant Dictionaries und Configurations liegen

Phase 2 — Infrastruktur-Verkabelung (Versorgungsnetz):

Der Assistent erfasst die IT-Landschaft: Laptop-Arbeitsplatz, File-Server, Cloud-first oder hybride Infrastruktur. Parameter wie Internet-Anschluss, Domäne, Storage-Pfade usw. fließen in die Infrastruktur Informationen ein und bereiten die Pfade für Quer-Verbindungen (others.json) vor.

Phase 3 — Gebäude errichten (Fachlicher Scope):

Der Anwender entscheidet modular, welche regulatorischen Bereiche seine Stadt absichern soll:

Baustein	Umfang	Aktion
Marktplatz (GoBD/AO-Basis)	Pflicht für jedes KMU — Verfahrensdokumentation	z.B. Modul & Ordner `/compliance/gobd/` wird aktiviert
Bank & Kasse (Finanzbuchhaltung)	Journalführung, Hauptbücher, Bank-Schnittstellen	z.B. Modul & Ordner `/finance/journal/` und `/finance/ledgers/` wird aktiviert
Werkstor (Sicherheit/NIS2)	Optionale erweiterte IT-Sicherheit und Meldepflichten	z.B. Modul & Ordner `/compliance/nis2/` wird aktiviert

Der Anwender sieht zu keinem Zeitpunkt Konfigurationsdateien oder Code. Da jeder Schritt sofort einen sauberen Git-Commit erzeugt, ist das System ab der ersten Minute vollständig revisionssicher gemäß GoBD und AO dokumentiert.

Mandanten-Isolation und Zugriffskontrolle

OIDC-Claims und others.json

Die Verknüpfung von OIDC-Claims mit der others.json ist der Königsweg für mandantenfähige, laien sichere Compliance-Umgebungen. In others.json sammeln sich:

Kanonische Routen zu den Tenant-eigenen Git-Repositories
Quer-Verbindungen zu Git-Repositories anderer Tenants, wenn der Tenant Member einer Gruppe ist

Der Zugriff wird über OIDC-Claims (Rollen und Custom Claims wie tenant_id und Gruppenzugehörigkeiten) gesteuert. Eine Inlet-Pipeline liest die others.json je nach User-Claim und injiziert die erlaubten Pfade als System-Prompt:

Du bist der GitCover Agent für Mandant X. Du hast ausschließlich Zugriff auf folgende Repositories: [Pfad 1], [Pfad 2]. Führe keine Befehle außerhalb dieser Verzeichnisse aus.

Für den Endanwender bleibt dieser Sicherheitsapparat unsichtbar. Er loggt sich ein, sieht seine gewohnte Arbeitsumgebung und die KI weiss automatisch, wo sie agieren darf.

KI-gestützte Datenerfassung über Formular-Bridging

Chat-Interfaces sind für Kontexte und Analysen geeignet, nicht für strikte Datentyperfassung (IBANs, Postleitzahlen, OSCAL-Schemata). Das GCBoK empfiehlt daher ein Formular-Bridging:

KI erkennt Bedarf: Der Anwender sagt „Ich möchte eine neue Betriebsstätte hinzufügen."
Dynamische Formular-URL: Die KI gibt einen Link zu einer validierten Web-Eingabemaske aus (Blazor WASM/PWA), gekoppelt an Session- und User-Management.
Gekapselte Eingabe: Der Anwender füllt das Formular aus — hart validiert vor Speicherung.
Direktes Schreiben in Git: Das Formular schreibt das Ergebnis als strukturierte Datei direkt ins Working-Directory des Mandanten-Repositories und triggert den Commit.
KI übernimmt wieder: Der MCP-Server meldet „Datei aktualisiert", die KI bestätigt im Chat.

Vorteil: Validierung vor Speicherung schützt die Single Source of Truth. LLMs manipulieren den Schreibprozess nicht. Die Git-Hook/OPA-Validierung wird sofort angestossen.

Die `.gitcover/`-Verzeichnisstruktur

Das .gitcover/-Verzeichnis im Root eines GitCover-Repositories ist das zentrale Archiv für alle nicht-Code-Artefakte. Es dient der Revisionssicherheit, Compliance (GoBD/AO) und Audit-Trail-Führung.

Verzeichnislayout

.gitcover/
├── issues/              # Gitea-Issues als .v7g.md
├── projects/            # Projekt-Management-Daten
├── time_tracking/       # Zeiterfassung und Aufwandsnachweise
├── workflows/           # Workflow-Zustände und Genehmigungen
├── compliance/
│   ├── oscals/          # OSCAL-Dokumente (System Security Plans)
│   ├── opa/             # OPA-Regeln (Rego-Policies)
│   └── hooks/           # Git-Hooks für Automatisierung
├── audit/
│   ├── signatures/      # Kryptografische Signaturen
│   ├── timestamps/      # Zeitstempel (ELSTER/Bundesanzeiger)
│   └── logs/            # Protokolle
└── README.md            # Dokumentation der Struktur

Dateinamenkonvention

Allgemeines Format: {uuidV7}_{human-readable-key}_{Beschreibung}.v7g.md

Artefakt-Typ	Beispiel	Begründung
Issue	`018e312f-..._#123_Bugfix-Login.v7g.md`	UUIDv7 für Sortierbarkeit, # für Identifikation
Projekt	`018e312f-..._Projekt-X.v7g.md`	Eindeutig, zeitlich sortierbar
Zeiterfassung	`018e312f-..._2026-06-29_Axel-D.v7g.md`	Datum und User im Klartext
Sidecar (PDF/DOCX)	`Rechnung_2026.pdf.v7g.md`	Metadaten zum Originaldokument

Metadaten-Schema (.v7g.md Frontmatter)

---
uuid: 018e312f-3e4f-7000-8000-000000000000
key: "#123"
type: "issue"
title: "Bugfix: Login-Modul"
original_source: "Gitea"
original_repo_hash: "a1b2c3d4e5f6..."
related_commits: ["abc123", "def456"]
related_elements:
  project: "Projekt-X"
  milestone: "v1.0"
forensic_attributes:
  created_at: "2026-06-29T12:00:00Z"
  updated_at: "2026-06-29T14:30:00Z"
  created_by: "Axel D."
compliance:
  gobd_relevant: true
  audit_trail: true
  signature: "GPG-Signatur-Hash"
  timestamp: "ELSTER-2026-06-29-120000"
---

Automatisierung durch Git-Hooks und Webhooks

GitCover-Repos werden beim init bzw. Tenant Onboarding automatisch mit Hooks/Webhooks konfiguriert:

post-commit: Aktualisiert .gitcover/ bei neuen Commits
pre-push: Validiert .gitcover/ vor dem Push
Webhooks: Issue-Erstellung, Projekt-Änderungen, Zeiterfassung — triggern jeweils Export als .v7g.md
Compliance-Claim: Sofortige Aktivierung von OSCAL/OPA-Mechanismen

Die Versionierung dieser Hooks/Webhooks erfolgt ebenfalls über Git, sodass Änderungen nachvollziehbar und auditierbar sind (selbstreferenziell, versioniert, revisionssicher). Die HOoks selbst können versionierte Code-Artefakte sein, die in .gitcover/hooks/ liegen und bei Bedarf aktualisiert werden und GoBD- oder NIS2-konform dokumentiert werden.

Issue-Archivierung: Gitea-DB zu Git-Faktenbasis

Problemstellung

Gitea-Issues sind Datenbank-Einträge — keine nativen Git-Objekte. Sie werden nicht versioniert und sind bei Verlust der Gitea-Datenbank nicht rekonstruierbar. Commits referenzieren Issues nur textuell (Fixes #123); diese Referenz wird von Git nicht interpretiert.

Lösung: Automatisierter Export als .v7g.md

Der Workflow von der Gitea-Datenbank zur revisionssicheren Faktenbasis:

Gitea-Issue erstellt → Webhook triggert Export
Export als .v7g.md → Speichern in .gitcover/issues/
Metadaten extrahieren → UUID, Hashes, Signaturen
Git-Commit mit Signatur → git commit -S
OSCAL/OPA-Validierung → Compliance-Prüfung
Zeitstempel → ELSTER/Bundesanzeiger-Integration (wenn erforderlich)

OPA-Beispiel-Regel für Issue-Validierung

package gcbok.compliance

violation[msg] {
  input.path == "issues"
  file := input.files[_]
  not startswith(file.name, "018")  # UUIDv7-Prüfung
  msg := sprintf("Issue %s hat keine gueltige UUIDv7 im Dateinamen", [file.name])
}

GoBD/AO-Konformität

GoBD-Anforderung	Umsetzung in `.gitcover/`
Nachvollziehbarkeit	Jede Änderung wird in `.gitcover/audit/logs/` protokolliert
Unveränderlichkeit	`.v7g.md`-Dateien werden nie überschrieben, sondern versioniert
Aufbewahrungspflicht	10 Jahre (DE) — `.gitcover/` als zentrales Archiv
Belegfunktion	`.v7g.md`-Dateien als digitale Belege
Prüfbarkeit	Signaturen und Zeitstempel ermöglichen forensische Validierung

Audit-Readiness

Audit-Readiness bedeutet: Jeder Audit kann jederzeit stattfinden — ohne Nachbereitung.

Voraussetzung	Git-native Erfüllung
Vollständiger Audit-Trail	Git-History (commit-log)
Nachweisbare Identitäten	GPG-Signaturen
Zeitliche Sortierbarkeit	V7GUID-Zeitstempel
Maschinenlesbare Nachweise	OSCAL-Assessment-Results
Policy-Konformität	OPA-Validierungsergebnisse

GoBD-Jahresabschluss

Der GoBD-Jahresabschluss mit Git-native Compliance:

Periode abschließen — Git-Branch FY2026 einfrieren (Tag)
Beleg-Kette validieren — V7GUID-Verkettung prüfen (Script)
OSCAL-Assessment-Results generieren — Automatisiert aus OPA-Validierungen
GPG-Siegelausstellung — Abschluss-Commit mit GF-Signatur
Archivierung — .v7g.zip-Container, v7g-export

NIS2-Risikoanalyse

Die NIS2-Risikoanalyse auf Git-Basis:

Asset-Inventar — Git-Repositories als Asset-Register
Risiko-Identifikation — OPA-Policies für Bedrohungsszenarien
Bewertung — V7GUID-Klassifizierung für Risikokategorien
Mitigation — Pre-receive-Hooks für Policy-Enforcement
Bericht — OSCAL-Assessment-Results als NIS2-Nachweis

KI-Server-Integration im LAN

Architekturprinzip

Das GCBoK beschreibt ein Referenzmodell für die Integration eines headless KI-Servers im LAN, der LLM-Inferenz und RAG-gestützte Compliance-Agenten zentral bereitstellt. Die KI-Umgebung läuft in einer isolierten Container-Umgebung (Rootless Podman), koppelt sich jedoch für Inferenz und Websuche an nativ auf dem Host installierte Dienste.

SSH Script Host (OSSH)

Für anspruchsvolle Aufgaben (Code-Kompilierung, Git-Operationen, Compliance-Prüfungen), die über die Container-Sandbox hinausgehen, nutzt der Agent einen SSH Script Host — einen kontrollierten, schlüsselbasierten Ausbruch auf das Host-System:

Agent entscheidet: „Führe dotnet-build aus"
SSH-Kanal: verschlüsselte Verbindung via id_rsa.pub zu Host-User
Nativer Prozess: Befehl wird im echten Betriebssystem-Kontext ausgeführt
Stream-Rückgabe: stdout/stderr werden als Text-Stream zurückgegeben
Agent analysiert: Compiler-Ausgabe im LLM-Kontext

Sicherheitsvoraussetzung: Der im Container generierte SSH-Schlüssel muss auf dem Host in authorized_keys eingepflegt werden. Die Kommunikation erfolgt rein über Standard-Datenströme (stdin, stdout, stderr) — ohne Dateitransfer.

Konsistente Pfad-Adressierung (FQN)

Um Pfad-Inkonsistenzen zwischen Workstation, Container und Script-Host zu vermeiden, werden File-Server-Freigaben auf allen Systemen an identischen Mount-Points eingehängt. KI-Agenten und menschliche Entwickler referenzieren zu jedem Zeitpunkt identische, absolute Pfadangaben.

Multi-Device-Fähigkeit

Durch Zentralisierung auf den KI-Server können mehrere Endgeräte parallel auf dieselbe Umgebung zugreifen:

Der Entwickler startet eine Code-Analyse am Desktop
Er verfolgt den Fortschritt des Agenten in Echtzeit auf dem Smartphone über VPN
Keine gegenseitigen Blockaden — der Script-Host öffnet separate, kurzlebige Shell-Prozesse

Rollenverteilung

Komponente	Rolle	GCBoK-Konformität
GCDMS	Primärer Speicherort für Compliance-Artefakte in Git	Vollständig
GCPN	Policy-Validierung (OPA/Rego) und Compliance-Regeln	Vollständig
GCUCB	Kontext-Bus für KI-Agenten, OPA-Validatoren, Audit-Systeme	Vollständig
Nextcloud	Nur für Shares/Freigaben (externe Nutzer, mobile Zugriffe)	Eingeschränkt

Bedingungen für den Einsatz

Nextcloud kann in einer GCBoK-basierten Umgebung punktuell für Shares eingesetzt werden, wenn:

Nur Read-Only-Shares — Keine Änderungen über Nextcloud; alle Mutationen laufen über Git
Git-Integration — Nextcloud mountet Git-Repos als externen Speicher (WebDAV, S3-Gateway oder GCSYNC)
Policy-Validierung — GCPN definiert Zugriffsregeln (OPA/Rego); Nextcloud setzt diese nur um
Audit-Logging — Nextcloud-Logs werden an GCAL weitergeleitet (Syslog/Loki)
Open-Source-Konformität — Nur Community-Edition, keine proprietären Plugins

Ausschlusskriterien

Schreibzugriff über Nextcloud (verstösst gegen Git-native Speicherung)
Proprietäre Nextcloud-Erweiterungen (verstösst gegen OSS-Prinzipien)
Fehlende Git-Integration (Nextcloud muss auf Git-Repos zugreifen können)

Siehe auch: Vorlagen für OSCAL-Kataloge und OPA-Policies in Achse 6: Vorlagen.