Achse 5: Vorgehensweisen

Onboarding KMU

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

1. Git-Repository initialisieren - Struktur mit .gitcover/-Verzeichnis, V7GUID-Konfiguration
2. OSCAL-Katalog auswählen - GoBD-Baseline, BSI-Bausteine oder individuelles Profil
3. OPA-Policies aktivieren - Pre-receive-Hooks für Validierung vor Commit
4. GPG-Signierung einrichten - Pro Akteur ein GPG-Schlüsselpaar
5. 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.

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:

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:

1. Kanonische Routen zu den Tenant-eigenen Git-Repositories
2. 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, org_unit_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.

Zwei-Ebenen-Claim-Modell für PII-Zugriff

Für den Zugriff auf personenbezogene Daten (PII) definiert das GCBoK eine Claim-Hierarchie mit zwei Ebenen (siehe Techniken: Git als IdP:

Die others.json mappt diese Claims auf Repository-Pfade:

{
  "tenant_id": "0197a3b2-f3c0-7b00-8001-000000000042",
  "org_unit_id": "ORG-1-Portfolio",
  "allowed_repos": [
    "TOP",
    "PII/ORG-1-Portfolio"
  ]
}

Ein Nutzer mit org_unit_id = ORG-1-Portfolio erhält Zugriff auf PII/ORG-1-Portfolio, aber nicht auf PII/ORG-2-IT — selbst bei demselben tenant_id. Dies setzt das Prinzip der geringsten Privilegien (NIS2 Art. 21) auf Repository-Ebene um.

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:

1. KI erkennt Bedarf: Der Anwender sagt „Ich möchte eine neue Betriebsstätte hinzufügen."
2. Dynamische Formular-URL: Die KI gibt einen Link zu einer validierten Web-Eingabemaske aus (Blazor WASM/PWA), gekoppelt an Session- und User-Management.
3. Gekapselte Eingabe: Der Anwender füllt das Formular aus - hart validiert vor Speicherung.
4. Direktes Schreiben in Git: Das Formular schreibt das Ergebnis als strukturierte Datei direkt ins Working-Directory des Mandanten-Repositories und triggert den Commit.
5. 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 .gc.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: {YYMMDD}_{human-readable-key}_{Beschreibung}.gc.md

Die V7GUID und die docUid stehen im Daten-Artefakt, nicht im Dateinamen; der Dateiname trägt die temporale Signatur {YYMMDD}.

Daten-Artefakt (.gc.md)

Das Daten-Artefakt folgt dem Muster „Human-Readable zuerst, JSON zuletzt“ (JSON-First, kein YAML-Frontmatter):

{
  "docUid": "018e312f-3e4f-7000-8000-000000000000",
  "v7guid": "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"
  },
  "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 .gc.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.

Private Vorgaben des HITL - Konvention und Agentenregel

Neben der versionierten Compliance-Dokumentation führt jede arbeitende Person ihre persönlichen Vorgaben - also wie sie selbst arbeiten, abgrenzen und priorisieren will. Diese Schicht ist privat und geschützt: Sie bleibt lokal und nicht versioniert (in der Regel in einem per .gitignore ausgeschlossenen Verzeichnis des eigenen Arbeitskontexts, Muster: projections/). Sie ist damit kein Bestandteil des Compliance-Dokumentationsbestands und gehört auch nicht in committete Repositories, Issues, Pull-Requests, Berichte oder Anzeigen.

Wozu sie dient: Sie ist das Eingangsmaterial für das, was dokumentiert wird - für Entscheidungsdokumentationen (ADR), für Vorlagen, für die Gewichtung von Vorhaben und für die Ausgestaltung der Werkzeuge. Dokumentiert wird das Ergebnis, nicht die Bewertung dahinter.

Regel für Agenten (verbindlich):

1. Beachten - die Vorgaben prägen Erwartungen, Ton, Abgrenzungen und Prioritäten; sie werden gelesen und eingehalten.
2. Nicht dokumentieren, nicht zitieren - kein Inhalt aus dieser Schicht in Fließtext, Code, Entscheidungsdokumenten, Belegen, Tickets, Berichten oder Anzeigen, sofern der HITL ihn nicht ausdrücklich zur Dokumentation freigibt.
3. Nicht veröffentlichen - die Schicht bleibt lokal; für Beispiele in Community, OSS oder Schulungsmaterial wird sie anonymisiert und nur als Muster beschrieben.
4. Nachweisgrenze - die versionierte Belegkette referenziert die Wirkung einer Vorgabe (etwa „Zuordnung nach den Vorgaben des HITL"), niemals deren geschützten Wortlaut.

GitCover-Sidecars (.gc.md)

Ein GitCover-Sidecar ist eine *.gc.md-Metadatendatei, die neben einem digitalen Originaldokument abgelegt wird - z. B. Rechnung_2026.pdf erhält Rechnung_2026.pdf.gc.md im selben Verzeichnis. Das Sidecar trägt die Metadaten, die Git nicht innerhalb einer Binärdatei (PDF, DOCX, EML, Bild) speichern kann, und verankert das Original damit in der Beleg-Kette und im GCDMS.

Mindestinformation

Jedes Sidecar enthält zwingend:

• sha256 - SHA-256-Hash des digitalen Originaldokuments (Integritätsnachweis).

Ergänzend führt es in der Regel Identität, Taxonomie und Verortung (Vorlage siehe Achse 6: Vorlagen).

DocID-Vergabe

Sofern das Dokument noch nicht im DMS geführt ist, wird eine neue DocID erzeugt. Die DocID ist die reine uuidv7 - der konkrete Instanz-Identifikator (Object ID) des Dual-Identifiers, der das einzelne Dokument materialisiert (vgl. Achse 2: Konzepte). Sie ist damit zu unterscheiden von der kategorisierten v7guid, die den fachlichen Kontext (Klasse, Tenant, Sphäre) kodiert.

Die DocID wird aus einem Zeitstempel generiert, so dass sie zeitgebunden und sortierbar ist:

1. Werkzeug: Ein Sidecar-Tool erzeugt eine UUIDv7 aus einem TimeStamp-Argument als DocID.
2. Default-Quelle: die Datei-Zeitmarke (mtime) des Originaldokuments.
3. Fachliche Quelle (falls verfügbar): Liefert der Dateiname oder der Inhalt ein fachlich bedeutsames Datum (z. B. Rechnungs-, E-Mail- oder Bescheid-Datum), wird dieses anstelle der mtime verwendet - die DocID bindet sich so an das Entstehungsdatum des Dokuments.

Beide Identifier - DocID (uuidv7) und kategorisierte v7guid - werden im Sidecar geführt und über den composite_key ({v7guid}:{uuidv7}) verknüpft.

Bezug zu V7GUID und Registry

• V7GUID: Der v7g_taxonomy-Block ordnet das Dokument über seine kategorisierte v7guid in die sechsstufige Business-Hierarchie und die Tenant-Sphäre ein (siehe Achse 2: Konzepte).
• Registry: Der locations-Block dokumentiert den physischen Speicherort (UNC-Pfad, Gültigkeitszeitraum). Registrierte Tenant-Identifier werden im zentralen Tenant-Register geführt (Zentrales Tenant-Register, Achse 2).

Aufbau (Beispiel)

# GitCover Sidecar - Rechnung_2026.pdf

**SHA-256:** `7d4e2f...`
**Tenant:** ORG-1
**Kategorie:** Finanzen und Buchführung
**Sphäre:** ideell

```json
{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-2.0.schema.json",
  "docUid": "0197a3b2-f3c0-7b00-8001-000000000042",
  "sha256": "7d4e2f...",
  "original_filename": "Rechnung_2026.pdf",
  "locations": [
    { "unc_path": "./ORG-1/FY2026/Rechnung_2026.pdf", "from": "260506", "to": null, "note": "Primärspeicherort" }
  ],
  "v7g_taxonomy": [
    { "v7guid": "0197a3b2-...-8001-...", "taxonomy": "ORG-1/Financial", "valid_from": "260506", "valid_to": null }
  ],
  "verification": { "verified_by": "auto", "method": "sha256_file", "intact": true }
}
```

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 .gc.md

Der Workflow von der Gitea-Datenbank zur revisionssicheren Faktenbasis:

1. Gitea-Issue erstellt → Webhook triggert Export
2. Export als .gc.md → Speichern in .gitcover/issues/
3. Metadaten extrahieren → UUID, Hashes, Signaturen
4. Git-Commit mit Signatur → git commit -S
5. OSCAL/OPA-Validierung → Compliance-Prüfung
6. 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

Audit-Readiness

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

These: Forensik ist das Git-Repo, HTML ist nur Präsentation Das HTML-Prüferpaket (Audit-Website, generierte Reports) ist ein Derivat zur menschlichen Lesbarkeit. Die forensische Beweiskraft liegt ausschließlich im Git-Repository selbst: unveränderliche Commit-History, GPG-signierte Commits, V7GUID-Belegketten, .gitcover/ Registries/Dictionaries im JSON/JSONL-Format. Bei einem Audit 10 Jahre später genügt ein git clone (oder git bundle Entpacken) — keine Web-Infrastruktur, keine Datenbank, keine laufenden Services nötig. Dies korrespondiert mit dem Schema-Tiering (siehe Vorlagen: V7GUID-Schema) und dem Derivat gcbok-audit-evidence-docs/docs/02-audit-website-als-pruefungsartefakt.

GoBD-Jahresabschluss

Der GoBD-Jahresabschluss mit Git-native Compliance:

1. Periode abschließen - Git-Branch FY2026 einfrieren (Tag)
2. Beleg-Kette validieren - V7GUID-Verkettung prüfen (Script)
3. OSCAL-Assessment-Results generieren - Automatisiert aus OPA-Validierungen
4. GPG-Siegelausstellung - Abschluss-Commit mit GF-Signatur
5. Archivierung - .gc.zip-Container, gc-dms pack

NIS2-Risikoanalyse

Die NIS2-Risikoanalyse auf Git-Basis:

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

Umgang mit Sicherheitsvorfällen (Incident Response)

Grundsatz: erst beweisen, dann bewerten. Ein Incident-Report ist ein Git-Artefakt mit Änderungshistorie — auch die eigene Fehleinschätzung gehört hinein. Die belastbare Aussage lautet nie „wir sind sicher“, sondern: „Für diesen Zeitraum, diese Systeme und diese Log-Ebenen gibt es keinen Hinweis auf Ausnutzung — bei folgender Nachweisgrenze.“

Ablauf in sieben Schritten

1. Erfassen und triagieren. Was ist bekannt (CVE, Warnung, Beobachtung), welche Systeme und Dienste sind im Wirkungsbereich, welcher Zeitraum ist zu betrachten? Auslöser und Zeitstempel festhalten.
2. Betroffenheit über Inventar bestimmen. Nicht „wir nutzen Produkt X“, sondern: Welche SAPI, welche Dienste, welche exponierten Endpunkte? Interne Pfade, LAN-only-Ports und verwaiste Sites getrennt ausweisen.
3. Patch- und Konfigurationsnachweis führen. Paketversion und Laufzeit (Neustart des Dienstes), Dateiintegrität, Wirksamkeit der Konfiguration. Bei jeder Config-Aussage eine Gegenprobe: Existiert die Datei, wächst sie, rotiert sie?
4. Logs über mehrere Ebenen auswerten. Eine Ebene beantwortet nie alle Fragen; jede hat eine Blindstelle, die im Bericht zu nennen ist. Suchraum (Pfade, Tiefe, Zeitfenster) dokumentieren — ein Negativbefund ohne Suchraum ist kein Befund.
5. Bewerten und Meldepflicht prüfen. NIS2 Art. 23 verlangt bei erheblichem Sicherheitsvorfall Frühwarnung (24 h), Meldung (72 h) und Abschlussbericht (ein Monat). Die Entscheidung „meldepflichtig / nicht meldepflichtig“ wird begründet, nicht stillschweigend getroffen.
6. Maßnahmen und Evidenz sichern. Sofortmaßnahmen, Härtung, Abbau verwaister Dienste. Beweismittel vor der nächsten Rotation als Archiv sichern: komprimiert, Eigentümer root, Rechte 640, Prüfsumme im Bericht.
7. Nachbereiten. Lessons Learned, Maßnahmen als Tasks mit Control-Bezug, Berichtsversion mit Änderungshistorie. Fehlbefunde werden korrigiert und als Korrektur dokumentiert.

Log-Ebenen und ihre Blindstellen

Ergänzend: Paketmanager (Patch-Zeitpunkt), Fail2ban (Bruteforce), Konfigurations-Historie (was hat sich wann geändert). Erst die Kombination trägt eine Aussage.

Typische Fehlbefunde

Artefakte der Nachweiskette

Bezug zu den anderen Achsen

• Grundlagen (Achse 1): NIS2-Pflichten und Meldefristen.
• Techniken (Achse 4): Nachweisbare Identitäten und Signaturen für Reports und Evidenz (GPG, uuidV7, Git als IdP).
• Vorlagen (Achse 6): Der Incident-Report folgt derselben Struktur wie andere Prüfberichte — Management Summary, Geltungsbereich, Nachweis, Bewertung, Maßnahmen, Anhang.

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:

1. Agent entscheidet: „Führe dotnet-build aus"
2. SSH-Kanal: verschlüsselte Verbindung via id_rsa.pub zu Host-User
3. Nativer Prozess: Befehl wird im echten Betriebssystem-Kontext ausgeführt
4. Stream-Rückgabe: stdout/stderr werden als Text-Stream zurückgegeben
5. 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

Share-Frontends: Nextcloud als Read-Only-Frontend

Rollenverteilung

Bedingungen für den Einsatz

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

1. Nur Read-Only-Shares - Keine Änderungen über Nextcloud; alle Mutationen laufen über Git
2. Git-Integration - Nextcloud mountet Git-Repos als externen Speicher (WebDAV, S3-Gateway oder GCSYNC)
3. Policy-Validierung - GCPN definiert Zugriffsregeln (OPA/Rego); Nextcloud setzt diese nur um
4. Audit-Logging - Nextcloud-Logs werden an GCAL weitergeleitet (Syslog/Loki)
5. 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.