Axis 5: Procedures

SME Onboarding

The entry into Git-native compliance for SMEs follows a step-by-step path:

1. Initialize Git repository - structure with .gitcover/ directory, V7GUID configuration
2. Select OSCAL catalog - GoBD baseline, BSI modules, or individual profile
3. Activate OPA policies - pre-receive hooks for validation before commit
4. Set up GPG signing - one GPG key pair per actor
5. Start evidence chain - assign first V7GUIDs, begin prev-hash chaining

For entrepreneurs from side-business level

The entry can begin with a very simple story: GCDMS for record archiving, GCPN for evidence chains. Later expand: OSCAL policies, OPA validation, multi-tenant.

Interactive onboarding: The “Compliance City”

Instead of classic questionnaires, onboarding takes place as a modular construction following the concept of a city on a Lego baseplate. Every architectural decision and every subject-matter requirement corresponds to a building block or assembly (Lego set) that is stored and versioned as a structured module in the newly initialized default Git repository.

The analogy for the user:

• The baseplate: The empty Git repository newly created for the tenant in their infrastructure. It provides the standardized frame (the studs) onto which everything docks.
• The building blocks: Modular configuration and service files. Only when a building block clicks into place (Git commit) does the corresponding function or compliance check become active.

Phase 1—Lay out the baseplate (initialization & identity):

The system automatically creates the default repository for the tenant. The onboarding assistant determines the company's identity. The data is stored in a structured manner in the 'TOP' (Tenant Organization Profile) repository—the first Git commit is already the first auditable compliance process. Incidentally: tenants can of course also be organized hierarchically, like the corporate structures to which they belong.

Phase 2—Infrastructure cabling (supply network):

The assistant captures the IT landscape: laptop workstation, file server, cloud-first or hybrid infrastructure. Parameters such as internet connection, domain, storage paths, etc. flow into the infrastructure information and prepare the paths for cross-connections (others.json).

Phase 3—Erect buildings (subject-matter scope):

The user decides modularly which regulatory areas their city should cover:

At no point does the user see configuration files or code. Because every step immediately creates a clean Git commit, the system is documented fully audit-proof in accordance with GoBD and AO from the first minute.

Tenant isolation and access control

OIDC claims and others.json

Linking OIDC claims with others.json is the royal road for multi-tenant, layperson-safe compliance environments. others.json collects:

1. Canonical routes to the tenant's own Git repositories
2. Cross-connections to Git repositories of other tenants when the tenant is a member of a group

Access is controlled via OIDC claims (roles and custom claims such as tenant_id, org_unit_id, and group memberships). An inlet pipeline reads others.json depending on the user claim and injects the permitted paths as a system prompt:

You are the GitCover agent for tenant X. You have access exclusively to the following repositories: [Path 1], [Path 2]. Do not execute any commands outside these directories.

Two-level claim model for PII access

For access to personal data (PII), the GCBoK defines a claim hierarchy with two levels (see Techniques: Git as IdP):

others.json maps these claims to repository paths:

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

A user with org_unit_id = ORG-1-Portfolio gets access to PII/ORG-1-Portfolio but not to PII/ORG-2-IT—even with the same tenant_id. This implements the principle of least privilege (NIS2 Art. 21) at the repository level.

For the end user, this security apparatus remains invisible. They log in, see their familiar working environment, and the AI automatically knows where it may act.

AI-supported data capture via form bridging

Chat interfaces are suitable for contexts and analyses, not for strict data type capture (IBANs, postal codes, OSCAL schemas). The GCBoK therefore recommends form bridging:

1. AI recognizes need: The user says, “I want to add a new branch office.”
2. Dynamic form URL: The AI outputs a link to a validated web input form (Blazor WASM/PWA), coupled to session and user management.
3. Encapsulated input: The user fills out the form—hard-validated before storage.
4. Direct writing into Git: The form writes the result as a structured file directly into the working directory of the tenant repository and triggers the commit.
5. AI takes over again: The MCP server reports “file updated,” and the AI confirms in chat.

Advantage: Validation before storage protects the single source of truth. LLMs do not manipulate the writing process. Git hook/OPA validation is triggered immediately.

The .gitcover/ directory structure

The .gitcover/ directory at the root of a GitCover repository is the central archive for all non-code artifacts. It serves audit security, compliance (GoBD/AO), and audit trail maintenance.

Directory layout

.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

File naming convention

General format: {YYMMDD}_{human-readable-key}_{Beschreibung}.gc.md

The V7GUID and the docUid are in the data artifact, not in the filename; the filename carries the temporal signature {YYMMDD}.

Data artifact (.gc.md)

The data artifact follows the pattern “human-readable first, JSON last” (JSON-first, no YAML front matter):

{
  "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"
  }
}

Automation via Git hooks and webhooks

GitCover repos are automatically configured with hooks/webhooks during init or tenant onboarding:

• post-commit: Updates .gitcover/ on new commits
• pre-push: Validates .gitcover/ before push
• Webhooks: Issue creation, project changes, time tracking—each triggers export as .gc.md
• Compliance claim: Immediate activation of OSCAL/OPA mechanisms

The versioning of these hooks/webhooks also takes place via Git, so that changes are traceable and auditable (self-referential, versioned, audit-proof). The hooks themselves can be versioned code artifacts that reside in .gitcover/hooks/ and are updated as needed and documented in a GoBD- or NIS2-compliant manner.

Private HITL specifications - convention and agent rule

In addition to versioned compliance documentation, every working person maintains their personal specifications—i.e., how they want to work, set boundaries, and prioritize. This layer is private and protected: It remains local and unversioned (usually in a directory excluded via .gitignore in their own working context, pattern: projections/). It is therefore not part of the compliance documentation inventory and does not belong in committed repositories, issues, pull requests, reports, or views.

What it is for: It is the input material for what is documented—for decision documentation (ADR), for templates, for the weighting of initiatives, and for the design of the tools. What is documented is the result, not the assessment behind it.

Agent rules (binding):

1. Observe - the specifications shape expectations, tone, boundaries, and priorities; they are read and complied with.
2. Do not document, do not quote - no content from this layer in running text, code, decision documents, evidence, tickets, reports, or views, unless the HITL expressly releases it for documentation.
3. Do not publish - the layer remains local; for examples in community, OSS, or training material it is anonymized and described only as a pattern.
4. Evidence boundary - the versioned evidence chain references the effect of a specification (e.g., “allocation according to the HITL's specifications”), never its protected wording.

GitCover sidecars (.gc.md)

A GitCover sidecar is a *.gc.md metadata file that is stored alongside a digital original document—e.g., Rechnung_2026.pdf receives Rechnung_2026.pdf.gc.md in the same directory. The sidecar carries the metadata that Git cannot store inside a binary file (PDF, DOCX, EML, image), and thereby anchors the original in the evidence chain and in GCDMS.

Minimum information

Every sidecar mandatorily contains:

• sha256 - SHA-256 hash of the digital original document (integrity proof).

In addition, it generally carries identity, taxonomy, and location (for a template see Axis 6: Templates).

DocID assignment

If the document is not yet maintained in the DMS, a new DocID is generated. The DocID is the pure uuidv7—the concrete instance identifier (Object ID) of the dual identifier that materializes the individual document (cf. Axis 2: Concepts). It is therefore to be distinguished from the categorized v7guid, which encodes the subject context (class, tenant, sphere).

The DocID is generated from a timestamp, so that it is time-bound and sortable:

1. Tool: A sidecar tool generates a UUIDv7 from a TimeStamp argument as DocID.
2. Default source: the file timestamp (mtime) of the original document.
3. Subject source (if available): If the filename or content provides a subject-relevant date (e.g., invoice, email, or notice date), this is used instead of the mtime—the DocID thus binds to the document's creation date.

Both identifiers—DocID (uuidv7) and categorized v7guid—are maintained in the sidecar and linked via the composite_key ({v7guid}:{uuidv7}).

Relation to V7GUID and registry

• V7GUID: The v7g_taxonomy block classifies the document via its categorized v7guid into the six-level business hierarchy and the tenant sphere (see Axis 2: Concepts).
• Registry: The locations block documents the physical storage location (UNC path, validity period). Registered tenant identifiers are maintained in the central tenant register (Central Tenant Register, Axis 2).

Structure (example)

# 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 archiving: Gitea DB to Git fact base

Problem statement

Gitea issues are database entries—not native Git objects. They are not versioned and cannot be reconstructed if the Gitea database is lost. Commits reference issues only textually (Fixes #123); this reference is not interpreted by Git.

Solution: Automated export as .gc.md

The workflow from the Gitea database to the audit-proof fact base:

1. Gitea issue created → webhook triggers export
2. Export as .gc.md → save in .gitcover/issues/
3. Extract metadata → UUID, hashes, signatures
4. Git commit with signature → git commit -S
5. OSCAL/OPA validation → compliance check
6. Timestamp → ELSTER/Bundesanzeiger integration (if required)

OPA example rule for issue validation

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 compliance

Audit-Readiness

Audit readiness means: every audit can take place at any time—without post-processing.

Thesis: Forensics is the Git repo, HTML is only presentation The HTML audit package (audit website, generated reports) is a derivative for human readability. The forensic evidentiary value lies exclusively in the Git repository itself: immutable commit history, GPG-signed commits, V7GUID evidence chains, .gitcover/ registries/dictionaries in JSON/JSONL format. For an audit 10 years later, a git clone (or unpacking a git bundle) is sufficient—no web infrastructure, no database, no running services required. This corresponds to schema tiering (see Templates: V7GUID schema) and the derivative gcbok-audit-evidence-docs/docs/02-audit-website-als-pruefungsartefakt.

GoBD year-end closing

The GoBD year-end closing with Git-native compliance:

1. Close the period—freeze Git branch FY2026 (tag)
2. Validate evidence chain—check V7GUID chaining (script)
3. Generate OSCAL assessment results—automated from OPA validations
4. Issue GPG seal—closing commit with management signature
5. Archiving—.gc.zip container, gc-dms pack

NIS2 risk analysis

The NIS2 risk analysis on a Git basis:

1. Asset inventory—Git repositories as asset register
2. Risk identification—OPA policies for threat scenarios
3. Assessment—V7GUID classification for risk categories
4. Mitigation—pre-receive hooks for policy enforcement
5. Report—OSCAL assessment results as NIS2 evidence

Handling security incidents (Incident Response)

Principle: prove first, then assess. An incident report is a Git artifact with a change history—your own misjudgment belongs in it too. The robust statement is never “we are secure,” but: “For this period, these systems, and these log layers, there is no indication of exploitation—subject to the following evidence boundary.”

Process in seven steps

1. Capture and triage. What is known (CVE, warning, observation), which systems and services are in scope, what period must be considered? Record the trigger and timestamp.
2. Determine affectedness via inventory. Not “we use product X,” but: which SAPI, which services, which exposed endpoints? Identify internal paths, LAN-only ports, and orphaned sites separately.
3. Provide patch and configuration evidence. Package version and runtime (restart of the service), file integrity, effectiveness of the configuration. For every config statement, a cross-check: does the file exist, is it growing, does it rotate?
4. Evaluate logs across multiple layers. One layer never answers all questions; each has a blind spot that must be named in the report. Document the search space (paths, depth, time window)—a negative finding without a search space is not a finding.
5. Assess and check reporting obligation. NIS2 Art. 23 requires, for a significant security incident, an early warning (24 h), notification (72 h), and final report (one month). The decision “reportable / not reportable” is justified, not made silently.
6. Secure measures and evidence. Immediate measures, hardening, decommissioning of orphaned services. Secure evidence as an archive before the next rotation: compressed, owner root, permissions 640, checksum in the report.
7. Follow up. Lessons learned, measures as tasks with control reference, report version with change history. False findings are corrected and documented as a correction.

Log layers and their blind spots

In addition: package manager (patch time), Fail2ban (brute force), configuration history (what changed when). Only the combination supports a statement.

Typical false findings

Artifacts of the evidence chain

Relation to the other axes

• Fundamentals (Axis 1): NIS2 obligations and reporting deadlines.
• Techniques (Axis 4): Provable identities and signatures for reports and evidence (GPG, uuidV7, Git as IdP).
• Templates (Axis 6): The incident report follows the same structure as other audit reports—management summary, scope, evidence, assessment, measures, appendix.

AI server integration in the LAN

Architectural principle

The GCBoK describes a reference model for integrating a headless AI server in the LAN that centrally provides LLM inference and RAG-supported compliance agents. The AI environment runs in an isolated container environment (rootless Podman) but couples to natively host-installed services for inference and web search.

SSH Script Host (OSSH)

For demanding tasks (code compilation, Git operations, compliance checks) that go beyond the container sandbox, the agent uses an SSH Script Host—a controlled, key-based breakout to the host system:

1. Agent decides: “Run dotnet-build”
2. SSH channel: encrypted connection via id_rsa.pub to the host user
3. Native process: command is executed in the real operating system context
4. Stream return: stdout/stderr are returned as a text stream
5. Agent analyzes: compiler output in the LLM context

Security prerequisite: The SSH key generated in the container must be entered on the host in authorized_keys. Communication takes place purely via standard data streams (stdin, stdout, stderr)—without file transfer.

Consistent path addressing (FQN)

To avoid path inconsistencies between workstation, container, and script host, file server shares are mounted at identical mount points on all systems. AI agents and human developers reference identical absolute path specifications at all times.

Multi-device capability

Through centralization on the AI server, multiple devices can access the same environment in parallel:

• The developer starts a code analysis on the desktop
• They follow the agent's progress in real time on the smartphone via VPN
• No mutual blocking—the script host opens separate, short-lived shell processes

Share frontends: Nextcloud as a read-only frontend

Role distribution

Conditions for use

Nextcloud can be used selectively for shares in a GCBoK-based environment if:

1. Read-only shares only—no changes via Nextcloud; all mutations run through Git
2. Git integration—Nextcloud mounts Git repos as external storage (WebDAV, S3 gateway, or GCSYNC)
3. Policy validation—GCPN defines access rules (OPA/Rego); Nextcloud only enforces them
4. Audit logging—Nextcloud logs are forwarded to GCAL (Syslog/Loki)
5. Open-source compliance—community edition only, no proprietary plugins

Exclusion criteria

• Write access via Nextcloud (violates Git-native storage)
• Proprietary Nextcloud extensions (violates OSS principles)
• Missing Git integration (Nextcloud must be able to access Git repos)

See also: Templates for OSCAL catalogs and OPA policies in Axis 6: Templates.