Eje 5: Procedimientos

Onboarding para 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 directorio .gitcover/, configuración de V7GUID
2. Seleccionar catálogo OSCAL: línea base GoBD, módulos BSI o perfil individual
3. Activar políticas OPA: hooks pre-receive para validación antes del commit
4. Configurar 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 archivado de justificantes, GCPN para cadenas de prueba. Ampliar más adelante: políticas OSCAL, validación OPA, multiinquilino.

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 (Lego-Set), que se deposita como módulo estructurado en el repositorio Git por defecto recién inicializado y se versiona.

La analogía para el usuario:

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

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

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

Fase 2: cableado de 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 conexión a Internet, dominio, rutas de almacenamiento, etc., se incorporan a la información de infraestructura y preparan las rutas para conexiones cruzadas (others.json).

Fase 3: erigir edificios (alcance funcional):

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

El usuario no ve en ningún momento archivos de configuración ni código. Como cada paso genera de inmediato un commit limpio de Git, el sistema queda documentado desde el primer minuto de forma totalmente segura para revisión según GoBD y AO.

Aislamiento de inquilinos 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 multiinquilino y seguros para personas no técnicas. En others.json se reúnen:

1. Rutas canónicas a los repositorios Git propios del inquilino
2. Conexiones cruzadas a repositorios Git de otros inquilinos, si el inquilino 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 prompt de sistema:

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

Modelo de claims de dos niveles para 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 asigna 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 sucursal».
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, validado de forma estricta antes de guardarse.
4. Escritura directa en Git: el formulario escribe el resultado como archivo estructurado directamente en el directorio de trabajo del repositorio del inquilino y activa 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 única fuente de verdad. Los LLM no manipulan el proceso de escritura. La validación mediante 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 a la seguridad de revisión, al cumplimiento (GoBD/AO) y a la gestión del rastro de auditoría.

Disposición de directorios

.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

Convención de nombres de archivo

Formato general: {YYMMDD}_{human-readable-key}_{Beschreibung}.gc.md

La V7GUID y la docUid están en el artefacto de datos, no en el nombre del archivo; el nombre del archivo lleva la firma temporal {YYMMDD}.

Artefacto de datos (.gc.md)

El artefacto de datos sigue el patrón «primero legible por humanos, JSON al final» (JSON-First, sin frontmatter YAML):

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

Automatización mediante Git-Hooks y webhooks

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

• post-commit: actualiza .gitcover/ con nuevos commits
• pre-push: valida .gitcover/ antes del push
• Webhooks: creación de issues, cambios de proyecto, registro de tiempo; activan respectivamente la exportación como .gc.md
• Claim de cumplimiento: activación inmediata de mecanismos OSCAL/OPA

El versionado de estos hooks/webhooks también se realiza mediante Git, de modo que los cambios son trazables y auditables (autorreferente, versionado, seguro para revisión). Los propios hooks pueden ser artefactos de código versionados que residen 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 lo general en un directorio excluido mediante .gitignore del propio contexto de trabajo; patrón: projections/). Por tanto, no forma parte del conjunto de documentación de cumplimiento y tampoco pertenece a repositorios con commits, issues, pull requests, informes o anuncios.

Para qué sirve: es el material de entrada de lo que se documenta: documentación de decisiones (ADR), plantillas, ponderación de iniciativas y configuración de las herramientas. Se documenta el resultado, no la valoración subyacente.

Regla para agentes (vinculante):

1. Tenerlas en cuenta: las directrices configuran expectativas, tono, delimitaciones y prioridades; se leen y se cumplen.
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 de GitCover (.gc.md)

Un sidecar de GitCover es un archivo de metadatos *.gc.md que se deposita junto a un documento original digital; p. ej., Rechnung_2026.pdf recibe Rechnung_2026.pdf.gc.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 ancla así 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).

Además, suele incluir identidad, taxonomía y ubicación (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 de la v7guid categorizada, que codifica el contexto funcional (clase, inquilino, esfera).

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

1. Herramienta: una herramienta de sidecar genera un UUIDv7 a partir de un argumento TimeStamp como DocID.
2. Fuente por defecto: 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 significativa (p. ej., fecha de factura, de correo electrónico o de resolución), se utiliza esta en lugar del mtime; así, el DocID se vincula a la fecha de creación del documento.

Ambos identificadores —DocID (uuidv7) y v7guid categorizada— se incluyen 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 categorizada, en la jerarquía empresarial de seis niveles y en la esfera del inquilino (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 inquilino registrados se gestionan en el registro central de inquilinos (Registro central de inquilinos, Eje 2).

Estructura (ejemplo)

# 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 }
}
```

Archivado de issues: de la base de datos de Gitea a la base de hechos de 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 .gc.md

El flujo de trabajo desde la base de datos de Gitea hasta la base de hechos segura para revisión:

1. Issue de Gitea creado → el webhook activa la exportación
2. Exportación como .gc.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: cualquier auditoría puede celebrarse en cualquier momento, sin trabajo posterior.

Tesis: la forense es el repositorio Git; el HTML es solo presentación El paquete de pruebas 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 .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 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 (etiqueta)
2. Validar la cadena de justificantes: comprobar el encadenamiento V7GUID (script)
3. Generar OSCAL-Assessment-Results: de forma automatizada a partir de validaciones OPA
4. Emisión de sello GPG: commit de cierre con firma de la dirección (GF)
5. Archivado: contenedor .gc.zip, gc-dms pack

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

Gestión de incidentes de seguridad (Incident Response)

Principio: primero demostrar, luego evaluar. Un informe de incidente es un artefacto Git con historial de cambios; también la propia evaluación errónea debe figurar en él. La afirmación sólida nunca es «estamos seguros», sino: «Para este periodo, estos sistemas y estos niveles de log no hay indicios de explotación, con el siguiente límite de prueba».

Procedimiento en siete pasos

1. Registrar y triar. ¿Qué se conoce (CVE, alerta, observación), qué sistemas y servicios están en el ámbito de impacto, qué periodo debe considerarse? Registrar el desencadenante y la marca de tiempo.
2. Determinar la afectación mediante el inventario. No «usamos el producto X», sino: ¿qué SAPI, qué servicios, qué endpoints expuestos? Indicar por separado las rutas internas, los puertos solo de LAN y los 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 sobre la configuración, una contrapueba: ¿existe el archivo, crece, rota?
4. Evaluar los logs en varios niveles. Un nivel nunca responde a todas las preguntas; cada uno tiene un punto ciego que debe mencionarse en el informe. Documentar el espacio de búsqueda (rutas, profundidad, ventana temporal): un resultado negativo sin espacio de búsqueda no es un hallazgo.
5. Evaluar y comprobar la obligación de notificación. En caso de incidente de seguridad significativo, NIS2 Art. 23 exige una alerta temprana (24 h), una notificación (72 h) y un informe final (un mes). La decisión «sujeto a notificación / no sujeto a notificación» se fundamenta; no se toma en silencio.
6. Asegurar medidas y evidencia. Medidas inmediatas, endurecimiento, desmantelamiento de servicios huérfanos. Asegurar los medios de prueba como archivo antes de la siguiente rotación: comprimidos, propietario root, permisos 640, suma de verificación en el informe.
7. Realizar el seguimiento. Lecciones aprendidas, medidas como tareas con referencia a controles, versión del informe con historial de cambios. Los hallazgos erróneos se corrigen y se documentan como corrección.

Niveles 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 erróneos típicos

Artefactos de la cadena de prueba

Relación con los otros ejes

• Fundamentos (Eje 1): obligaciones y plazos de notificación de NIS2.
• Técnicas (Eje 4): identidades demostrables y firmas 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, evaluación, medidas, anexo.

Integración de servidor de IA en la LAN

Principio arquitectónico

El GCBoK describe un modelo de referencia para la integración de un servidor de IA headless en la LAN, que proporciona de forma central 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, para inferencia y búsqueda web, a servicios instalados de forma nativa en el host.

Host de scripts SSH (OSSH)

Para tareas exigentes (compilación de código, operaciones Git, comprobaciones de cumplimiento) que van más allá del sandbox del contenedor, el agente utiliza un SSH Script Host: 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 flujo 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 dentro de authorized_keys. La comunicación se realiza exclusivamente mediante flujos estándar (stdin, stdout, stderr), sin transferencia de archivos.

Direccionamiento de rutas coherente (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 los mismos puntos de montaje 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 para recursos compartidos: Nextcloud como frontend de solo lectura

Distribución de roles

Condiciones de uso

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

1. Solo recursos compartidos 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, puerta de enlace S3 o GCSYNC)
3. Validación de políticas: GCPN define las reglas de acceso (OPA/Rego); Nextcloud solo las aplica
4. Registro de auditoría: los logs de Nextcloud se reenvían a GCAL (Syslog/Loki)
5. Conformidad con código abierto: solo edición Community, 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 (infringen los principios del 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.