# Reglas del repositorio — CVE-2026-111497

Alcance: agentes y personas que trabajan en este repositorio.
Prioridad: la seguridad por encima de la velocidad. Toda acción irreversible va precedida de una
copia de seguridad y de una comprobación de la misma operación en un entorno aislado.

## Propósito

El repositorio contiene un agente de remediación reutilizable para **CVE-2026-111497**, una
escritura fuera de límites en el decodificador de Google Brotli. El núcleo son los scripts bash
deterministas de `src/`; devuelven un veredicto compacto legible por máquina y mantienen al mínimo
el gasto de tokens del modelo de lenguaje.

## Límites de responsabilidad

- `src/detect.sh` — **solo lectura.** No modifica ningún paquete, servicio ni archivo de
  configuración.
- `src/remediate.sh` — el único punto de mutación. Realiza la copia de seguridad, la puerta de
  autenticidad, la simulación, la instalación y el reinicio de los consumidores.
- `src/verify.sh` — **solo lectura.** Confirma el efecto realmente logrado.

## Invariantes obligatorios

1. **Copia de seguridad antes del cambio.** `remediate.sh` siempre crea
   `/root/cve-2026-111497-fix-<timestamp>/` con los archivos `.so` antiguos, el `.deb` descargable
   y una instantánea de `dpkg` antes de instalar nada.
2. **Puerta de autenticidad.** La instalación solo se realiza una vez confirmado que el changelog
   del candidato menciona `CVE-2026-111497`. En caso contrario el script se detiene y escala.
3. **Reiniciar los consumidores.** Ningún proceso puede seguir con el `libbrotlidec` vulnerable
   mapeado después de la remediación. Esto se comprueba mediante `/proc/*/maps` y la comparación de
   inodos.
4. **Cero secretos en el repositorio.** Sin claves, contraseñas, tokens, direcciones IP reales ni
   nombres de host. Los hosts de destino se pasan como alias SSH de `~/.ssh/config`.
5. **Formato de archivo.** LF, sin BOM, UTF-8. Los archivos `.sh` se confirman con modo `100755`.
6. **`.ragraf/` nunca se confirma** — la regla vive en el `.gitignore` de la raíz.

## Comandos

```bash
# syntax check before delivery
bash -n src/common.sh src/detect.sh src/remediate.sh src/verify.sh

# field order is fixed: detect -> remediate -> verify
bash src/detect.sh ; echo "exit=$?"
bash src/remediate.sh
bash src/verify.sh
```

## Verificación

Un cambio se acepta solo cuando se cumplen todas las condiciones siguientes:

```bash
bash -n src/*.sh                       # no syntax error
shellcheck src/*.sh                    # no unresolved finding
ghagent doc --root .                   # markdown and privacy contract
```

La prueba de comportamiento es una ejecución de campo en un host desechable: `detect.sh` devuelve
`1`, después `remediate.sh` devuelve `0` y a continuación `verify.sh` imprime `VERIFY: PASS`.

## Orden del commit (el propietario, no el agente)

Elimine las variables que sobrescriben la identidad y fíjela explícitamente:

```bash
unset GIT_AUTHOR_NAME GIT_AUTHOR_EMAIL GIT_COMMITTER_NAME GIT_COMMITTER_EMAIL
git -c user.name='Mikhail Deynekin' -c user.email='Mikhail@Deynekin.com' commit -m '...'
git log -1 --format='%an <%ae> | %cn <%ce>'   # owner, never zwork
```

## Trampas

| Trampa | Síntoma | Acción |
|---|---|---|
| `set -o pipefail` con un `head`/`awk` que termina antes | código de salida 141 (SIGPIPE) en un caso exitoso | `pipefail` se omite deliberadamente en `common.sh` |
| Cargar un archivo de estado como shell | error de sintaxis en `PRETTY_NAME` con paréntesis | leer los valores con `state_get` |
| Inodo capturado desde un glob | se registra el inodo del enlace simbólico y la comprobación de obsolescencia pasa en falso | `find -type f -printf '%i'` |
| `printf '%s'` sin salto de línea en un bucle de unidades | los nombres de unidad se concatenan y el reinicio no hace nada en silencio | `printf '%s\n'` |
| `systemctl restart` de una unidad de escritorio | sesión perdida, VPN caída | las unidades de escritorio e infraestructura están en `DESKTOP_INFRA_PAT` y se informan como diferidas |
| Reiniciar los demonios del panel ISPmanager con `kill` | corrupción del estado del panel | `mgrctl -m core --restart srvparam` |

## Prohibido

- Eliminar archivos que la tarea no menciona, sin el consentimiento explícito del propietario.
- Ejecutar `remediate.sh` sin un `detect.sh` previo (el estado inicial es obligatorio).
- Forzar la instalación de un paquete cuando la puerta de autenticidad no ha pasado.
- Habilitar la actualización automática o el reinicio desatendido en un host de destino por
  iniciativa propia.