Eje 5: Procedimientos

Onboarding de PYMES

La entrada de las PYMES en el cumplimiento nativo de Git sigue una ruta paso a paso:

1. Inicializar el repositorio Git - Estructura con el directorio .gitcover/, configuración de V7GUID
2. Seleccionar el catálogo OSCAL - Línea base GoBD, módulos BSI o perfil individual
3. Activar las políticas OPA - Hooks pre-receive para la validación antes del commit
4. Configurar la firma GPG - Un par de claves GPG por actor
5. Iniciar la cadena de justificantes - Asignar los primeros V7GUID, comenzar el encadenamiento prev-hash

Para emprendedores desde el nivel de actividad secundaria

La entrada puede comenzar con una historia muy sencilla: GCDMS para el archivo de justificantes, GCPN para las cadenas de prueba. Ampliar más adelante: políticas OSCAL, validación OPA, multi-tenant.

Onboarding interactivo: la «Compliance City»

En lugar de cuestionarios clásicos, el onboarding se realiza como una construcción modular siguiendo el concepto de una ciudad sobre una placa base de Lego. Cada decisión arquitectónica y cada requisito funcional corresponde a una pieza o a un conjunto de construcción (set de Lego), que se deposita y versiona como módulo estructurado en el repositorio Git predeterminado recién inicializado.

La analogía para el usuario:

• La placa base: El repositorio Git vacío, recién creado para el tenant en su infraestructura. Ofrece el marco normalizado (las clavijas) sobre el que todo se conecta.
• Las piezas de construcción: Configuración modular y archivos de servicio. Solo cuando una pieza encaja (commit de Git), se activa la función o la comprobación de cumplimiento correspondiente.

Fase 1 - Colocar la placa base (inicialización e identidad):

El sistema crea automáticamente el repositorio predeterminado para el tenant. El asistente de onboarding determina la identidad de la empresa. Los datos se depositan de forma estructurada en el repositorio 'TOP' (Tenant Organization Profile): el primer commit de Git ya es el primer proceso de cumplimiento auditable. Por cierto: los tenants también pueden organizarse jerárquicamente, como las estructuras empresariales a las que pertenecen.

Fase 2 - Cableado de la infraestructura (red de suministro):

El asistente registra el panorama de TI: puesto de trabajo portátil, servidor de archivos, infraestructura cloud-first o híbrida. Parámetros como la conexión a Internet, el dominio, las rutas de almacenamiento, etc., se incorporan a la información de infraestructura y preparan las rutas para las conexiones transversales (others.json).

Fase 3 - Construir edificios (alcance funcional):

El usuario decide de forma modular qué áreas regulatorias debe proteger su ciudad:

El usuario no ve en ningún momento archivos de configuración ni código. Dado que cada paso genera inmediatamente un commit de Git limpio, el sistema queda documentado desde el primer minuto como plenamente trazable y a prueba de auditoría conforme a GoBD y AO.

Aislamiento de tenants y control de acceso

Claims OIDC y others.json

La vinculación de claims OIDC con others.json es la vía regia para entornos de cumplimiento multi-tenant y seguros para usuarios no expertos. En others.json se recopilan:

1. Rutas canónicas a los repositorios Git propios del tenant
2. Conexiones transversales a repositorios Git de otros tenants, cuando el tenant es miembro de un grupo

El acceso se controla mediante claims OIDC (roles y claims personalizados como tenant_id, org_unit_id y pertenencias a grupos). Una pipeline de entrada lee others.json según el claim del usuario e inyecta las rutas permitidas como system prompt:

Eres el agente de GitCover para el tenant X. Tienes acceso exclusivamente a los siguientes repositorios: [Ruta 1], [Ruta 2]. No ejecutes comandos fuera de estos directorios.

Modelo de claims de dos niveles para el acceso a PII

Para el acceso a datos personales (PII), el GCBoK define una jerarquía de claims con dos niveles (véase Técnicas: Git como IdP):

others.json mapea estos claims a rutas de repositorio:

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

Un usuario con org_unit_id = ORG-1-Portfolio obtiene acceso a PII/ORG-1-Portfolio, pero no a PII/ORG-2-IT, incluso con el mismo tenant_id. Esto aplica el principio de mínimo privilegio (NIS2 Art. 21) a nivel de repositorio.

Para el usuario final, este aparato de seguridad permanece invisible. Inicia sesión, ve su entorno de trabajo habitual y la IA sabe automáticamente dónde puede actuar.

Captura de datos asistida por IA mediante puente de formularios

Las interfaces de chat son adecuadas para contextos y análisis, no para la captura estricta de tipos de datos (IBAN, códigos postales, esquemas OSCAL). Por ello, el GCBoK recomienda un puente de formularios:

1. La IA detecta la necesidad: El usuario dice «Quiero añadir una nueva sede operativa».
2. URL dinámica del formulario: La IA emite un enlace a una máscara de entrada web validada (Blazor WASM/PWA), vinculada a la gestión de sesiones y usuarios.
3. Entrada encapsulada: El usuario rellena el formulario, con validación estricta antes del almacenamiento.
4. Escritura directa en Git: El formulario escribe el resultado como archivo estructurado directamente en el directorio de trabajo del repositorio del tenant y desencadena el commit.
5. La IA retoma el control: El servidor MCP informa «Archivo actualizado» y la IA lo confirma en el chat.

Ventaja: La validación antes del almacenamiento protege la Single Source of Truth. Los LLM no manipulan el proceso de escritura. La validación Git-Hook/OPA se activa de inmediato.

La estructura de directorios .gitcover/

El directorio .gitcover/ en la raíz de un repositorio GitCover es el archivo central para todos los artefactos que no son código. Sirve para la seguridad de auditoría, el cumplimiento (GoBD/AO) y la llevanza del audit trail.

Estructura de directorios

.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

Convención de nombres de archivo

Formato general: {uuidV7}_{human-readable-key}_{Beschreibung}.v7g.md

Esquema de metadatos (frontmatter de .v7g.md)

---
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: "Person A"
compliance:
  gobd_relevant: true
  audit_trail: true
  signature: "GPG-Signatur-Hash"
  timestamp: "ELSTER-2026-06-29-120000"
---

Automatización mediante Git hooks y webhooks

Los repositorios de GitCover se configuran automáticamente con hooks/webhooks durante init o el onboarding del tenant:

• post-commit: Actualiza .gitcover/ con los nuevos commits
• pre-push: Valida .gitcover/ antes del push
• Webhooks: Creación de issues, cambios de proyecto, registro de tiempos: desencadenan respectivamente la exportación como .v7g.md
• Claim de cumplimiento: Activación inmediata de los mecanismos OSCAL/OPA

El versionado de estos hooks/webhooks también se realiza mediante Git, de modo que los cambios son trazables y auditables (autorreferencial, versionado, a prueba de auditoría). Los propios hooks pueden ser artefactos de código versionados que se encuentran en .gitcover/hooks/, se actualizan cuando es necesario y se documentan conforme a GoBD o NIS2.

Directrices privadas del HITL: convención y regla para agentes

Además de la documentación de cumplimiento versionada, cada persona que trabaja mantiene sus directrices personales, es decir, cómo quiere trabajar, delimitar y priorizar por sí misma. Esta capa es privada y protegida: permanece local y sin versionar (por regla general, en un directorio excluido mediante .gitignore del propio contexto de trabajo; patrón: projections/). Por tanto, no forma parte del acervo de documentación de cumplimiento y tampoco pertenece a repositorios, issues, pull requests, informes o anuncios commiteados.

Para qué sirve: Es el material de entrada para lo que se documenta: para documentaciones de decisiones (ADR), para plantillas, para la ponderación de iniciativas y para la configuración de las herramientas. Se documenta el resultado, no la valoración que hay detrás.

Regla para agentes (vinculante):

1. Tenerlas en cuenta: las directrices configuran expectativas, tono, delimitaciones y prioridades; se leen y se respetan.
2. No documentar, no citar: ningún contenido de esta capa en texto corrido, código, documentos de decisión, justificantes, tickets, informes o anuncios, salvo que el HITL lo autorice expresamente para su documentación.
3. No publicar: la capa permanece local; para ejemplos en la comunidad, OSS o material de formación se anonimiza y se describe solo como patrón.
4. Límite de prueba: la cadena de justificantes versionada referencia el efecto de una directriz (por ejemplo, «asignación según las directrices del HITL»), nunca su redacción protegida.

Sidecars V7GUID

Un sidecar V7GUID es un archivo de metadatos *.v7g.md que se deposita junto a un documento original digital; por ejemplo, Rechnung_2026.pdf recibe Rechnung_2026.pdf.v7g.md en el mismo directorio. El sidecar contiene los metadatos que Git no puede almacenar dentro de un archivo binario (PDF, DOCX, EML, imagen) y, con ello, ancla el original en la cadena de justificantes y en el GCDMS.

Información mínima

Cada sidecar contiene obligatoriamente:

• sha256: hash SHA-256 del documento original digital (prueba de integridad).

Adicionalmente, suele incluir identidad, taxonomía y ubicación (para la plantilla, véase Eje 6: Plantillas).

Asignación de DocID

Si el documento aún no se gestiona en el DMS, se genera un nuevo DocID. El DocID es el uuidv7 puro: el identificador de instancia concreto (Object ID) del identificador dual que materializa el documento individual (cf. Eje 2: Conceptos). Por tanto, debe distinguirse del v7guid categorizado, que codifica el contexto funcional (clase, tenant, esfera).

El DocID se genera a partir de una marca de tiempo, de modo que está vinculado al tiempo y es ordenable:

1. Herramienta: Una herramienta de sidecar genera un UUIDv7 a partir de un argumento TimeStamp como DocID.
2. Fuente predeterminada: la marca de tiempo del archivo (mtime) del documento original.
3. Fuente funcional (si está disponible): Si el nombre del archivo o el contenido proporciona una fecha funcionalmente relevante (p. ej., fecha de factura, de correo electrónico o de resolución), se utiliza esta en lugar de la mtime; así, el DocID se vincula a la fecha de creación del documento.

Ambos identificadores —DocID (uuidv7) y v7guid categorizado— se mantienen en el sidecar y se vinculan mediante el composite_key ({v7guid}:{uuidv7}).

Relación con V7GUID y el registro

• V7GUID: El bloque v7g_taxonomy clasifica el documento mediante su v7guid categorizado en la jerarquía empresarial de seis niveles y en la esfera del tenant (véase Eje 2: Conceptos).
• Registro: El bloque locations documenta la ubicación física de almacenamiento (ruta UNC, periodo de validez). Los identificadores de tenant registrados se mantienen en el registro central de tenants (Zentrales Tenant-Register, Eje 2).

Estructura (ejemplo)

# V7G 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-1.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 }
}
```

Archivado de issues: de la base de datos de Gitea a la base de hechos en Git

Planteamiento del problema

Los issues de Gitea son entradas de base de datos, no objetos Git nativos. No se versionan y, si se pierde la base de datos de Gitea, no se pueden reconstruir. Los commits referencian issues solo textualmente (Fixes #123); Git no interpreta esta referencia.

Solución: exportación automatizada como .v7g.md

El flujo de trabajo desde la base de datos de Gitea hasta la base de hechos a prueba de auditoría:

1. Se crea un issue de Gitea → el webhook desencadena la exportación
2. Exportación como .v7g.md → guardado en .gitcover/issues/
3. Extraer metadatos → UUID, hashes, firmas
4. Commit de Git con firma → git commit -S
5. Validación OSCAL/OPA → comprobación de cumplimiento
6. Marca de tiempo → integración con ELSTER/Bundesanzeiger (si es necesario)

Regla OPA de ejemplo para la validación de issues

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])
}

Conformidad con GoBD/AO

Preparación para auditorías

Preparación para auditorías significa que cualquier auditoría puede tener lugar en cualquier momento, sin trabajo posterior.

Tesis: la forense es el repositorio Git; el HTML es solo presentación El paquete de verificación HTML (sitio web de auditoría, informes generados) es un derivado para la legibilidad humana. La fuerza probatoria forense reside exclusivamente en el propio repositorio Git: historial de commits inmutable, commits firmados con GPG, cadenas de justificantes V7GUID, registros/diccionarios de .gitcover/ en formato JSON/JSONL. En una auditoría 10 años después basta con un git clone (o descomprimir un git bundle): no se necesita infraestructura web, ni base de datos, ni servicios en ejecución. Esto se corresponde con el Schema-Tiering (véase Plantillas: Esquema V7GUID) y con el derivado gcbok-audit-evidence-docs/docs/02-audit-website-als-pruefungsartefakt.

Cierre anual GoBD

El cierre anual GoBD con cumplimiento nativo de Git:

1. Cerrar el periodo: congelar la rama Git FY2026 (tag)
2. Validar la cadena de justificantes: comprobar el encadenamiento V7GUID (script)
3. Generar OSCAL-Assessment-Results: de forma automatizada a partir de las validaciones OPA
4. Emisión del sello GPG: commit de cierre con firma de la dirección
5. Archivado: contenedor .v7g.zip, v7g-export

Análisis de riesgos NIS2

El análisis de riesgos NIS2 basado en Git:

1. Inventario de activos: repositorios Git como registro de activos
2. Identificación de riesgos: políticas OPA para escenarios de amenaza
3. Evaluación: clasificación V7GUID para categorías de riesgo
4. Mitigación: hooks pre-receive para la aplicación de políticas
5. Informe: OSCAL-Assessment-Results como prueba NIS2

Tratamiento de incidentes de seguridad (Incident Response)

Principio: primero probar, después valorar. Un informe de incidente es un artefacto Git con historial de cambios — incluida la propia equivocación. Una afirmación sostenible nunca es «estamos seguros», sino: «Para este periodo, estos sistemas y estas capas de log no hay indicio de explotación — con el siguiente límite de prueba.»

Procedimiento en siete pasos

1. Registrar y triar. ¿Qué se sabe (CVE, aviso, observación), qué sistemas y servicios están en el ámbito, qué periodo debe examinarse? Documentar el desencadenante y las marcas de tiempo.
2. Determinar la afectación mediante inventario. No «usamos el producto X», sino: ¿qué SAPI, qué servicios, qué puntos expuestos? Indicar por separado rutas internas, puertos solo LAN y sitios huérfanos.
3. Aportar prueba de parche y configuración. Versión del paquete y tiempo de ejecución (reinicio del servicio), integridad de archivos, eficacia de la configuración. Para cada afirmación de configuración, una contraprueba: ¿el archivo existe, crece, rota?
4. Evaluar logs en varias capas. Una capa nunca responde a todo; cada una tiene un punto ciego que debe nombrarse en el informe. Documentar el espacio de búsqueda (rutas, profundidad, ventana temporal) — un hallazgo negativo sin espacio de búsqueda documentado no es un hallazgo.
5. Valorar y comprobar obligaciones de notificación. El art. 23 de NIS2 exige, ante un incidente de seguridad significativo, advertencia temprana (24 h), notificación (72 h) e informe final (un mes). La decisión «notificable / no notificable» se razona, no se toma en silencio.
6. Asegurar medidas y evidencia. Medidas inmediatas, endurecimiento, desmontaje de servicios huérfanos. Asegurar la evidencia antes de la siguiente rotación como archivo: comprimido, propietario root, permisos 640, suma de verificación en el informe.
7. Cerrar el ciclo. Lessons Learned, medidas como tareas con referencia de control, versión del informe con historial de cambios. Los hallazgos falsos se corrigen y se documentan como corrección.

Capas de log y sus puntos ciegos

Además: gestor de paquetes (momento del parche), Fail2ban (fuerza bruta), historial de configuración (qué cambió y cuándo). Solo la combinación sostiene una afirmación.

Hallazgos falsos típicos

Artefactos de la cadena de prueba

Relación con los demás ejes

• Fundamentos (eje 1): obligaciones NIS2 y plazos de notificación.
• Técnicas (eje 4): identidades y firmas verificables para informes y evidencia (GPG, uuidV7, Git como IdP).
• Plantillas (eje 6): el informe de incidente sigue la misma estructura que otros informes de auditoría — resumen ejecutivo, alcance, prueba, valoración, medidas, anexo.

Integración del servidor de IA en la LAN

Principio de arquitectura

El GCBoK describe un modelo de referencia para la integración de un servidor de IA headless en la LAN, que proporciona de forma centralizada inferencia LLM y agentes de cumplimiento asistidos por RAG. El entorno de IA se ejecuta en un entorno de contenedores aislado (Podman rootless), pero se acopla a servicios instalados de forma nativa en el host para la inferencia y la búsqueda web.

Host de scripts SSH (OSSH)

Para tareas exigentes (compilación de código, operaciones Git, comprobaciones de cumplimiento) que van más allá de la sandbox del contenedor, el agente utiliza un host de scripts SSH: una salida controlada y basada en claves hacia el sistema host:

1. El agente decide: «Ejecuta dotnet-build»
2. Canal SSH: conexión cifrada mediante id_rsa.pub al usuario del host
3. Proceso nativo: el comando se ejecuta en el contexto real del sistema operativo
4. Devolución por stream: stdout/stderr se devuelven como stream de texto
5. El agente analiza: la salida del compilador en el contexto del LLM

Requisito de seguridad: La clave SSH generada en el contenedor debe incorporarse en el host en authorized_keys. La comunicación se realiza exclusivamente mediante flujos de datos estándar (stdin, stdout, stderr), sin transferencia de archivos.

Direccionamiento coherente de rutas (FQN)

Para evitar inconsistencias de rutas entre la estación de trabajo, el contenedor y el host de scripts, los recursos compartidos del servidor de archivos se montan en puntos de montaje idénticos en todos los sistemas. Los agentes de IA y los desarrolladores humanos referencian en todo momento rutas absolutas idénticas.

Capacidad multidispositivo

Gracias a la centralización en el servidor de IA, varios dispositivos pueden acceder en paralelo al mismo entorno:

• El desarrollador inicia un análisis de código en el escritorio
• Sigue el progreso del agente en tiempo real en el smartphone mediante VPN
• Sin bloqueos mutuos: el host de scripts abre procesos de shell separados y de corta duración

Frontends de compartición: Nextcloud como frontend de solo lectura

Distribución de roles

Condiciones para su uso

Nextcloud puede utilizarse de forma puntual para shares en un entorno basado en GCBoK si:

1. Solo shares de solo lectura: sin cambios a través de Nextcloud; todas las mutaciones pasan por Git
2. Integración con Git: Nextcloud monta repositorios Git como almacenamiento externo (WebDAV, S3-Gateway o GCSYNC)
3. Validación de políticas: GCPN define las reglas de acceso (OPA/Rego); Nextcloud solo las aplica
4. Audit-Logging: los logs de Nextcloud se reenvían a GCAL (Syslog/Loki)
5. Conformidad con open source: solo Community Edition, sin plugins propietarios

Criterios de exclusión

• Acceso de escritura a través de Nextcloud (infringe el almacenamiento nativo de Git)
• Extensiones propietarias de Nextcloud (infringe los principios OSS)
• Falta de integración con Git (Nextcloud debe poder acceder a repositorios Git)

Véase también: Plantillas para catálogos OSCAL y políticas OPA en Eje 6: Plantillas.