MACGUARD · DOCUMENTACIÓN
English

Fallos y recuperación

Qué hace la app cuando algo falla: firma, red, fichero alterado, retroceso o corte durante la instalación.

En todos los casos el resultado es el mismo: no se instala nada nuevo, las reglas ya instaladas siguen funcionando y se explica el motivo a la persona con el detalle técnico.

Fallo de firma

Diagrama: Fallo de firma

Dibujando el diagrama…

Descripción del diagrama

Si falla la verificación Sigstore del manifiesto o del checkpoint, o si falta el verificador fijado, MacGuard rechaza la release antes de tocar las reglas instaladas y le explica el motivo a la persona.

Código Mermaid
sequenceDiagram
  participant M as MacGuard
  participant V as cosign pinned
  participant L as Installed rules
  M->>V: verify-blob manifest.json
  V-->>M: identity or signature does not match
  M->>M: delete staging, keep trusted checkpoint unchanged
  M-->>L: untouched
  M->>M: show plain explanation and technical detail

Fallo de red

Diagrama: Fallo de red

Dibujando el diagrama…

Descripción del diagrama

Un error de red, un timeout o una descarga incompleta termina el intento. La descarga en streaming se cancela, la carpeta de staging se elimina y las reglas instaladas siguen funcionando. Si falla el origen principal solo se prueba el siguiente origen autorizado, nunca una mezcla de ficheros de dos orígenes.

Código Mermaid
sequenceDiagram
  participant M as MacGuard
  participant O1 as Origin 1
  participant O2 as Origin 2 (if configured)
  participant L as Installed rules
  M->>O1: download release files
  O1--xM: timeout or incomplete
  M->>M: remove staging
  M->>O2: start again from the beginning
  O2--xM: unreachable
  M-->>L: previous rules stay in use
  M->>M: report the failure, nothing installed

Fichero alterado

Diagrama: Fichero alterado

Dibujando el diagrama…

Descripción del diagrama

Si un fichero de reglas o el paquete difiere del manifiesto firmado, la comparación de hashes falla tras la extracción. La release se rechaza como no fiable y no se instala nada. Un fichero añadido o quitado en el paquete también falla, porque la lista de ficheros forma parte del rules_root firmado.

Código Mermaid
sequenceDiagram
  participant M as MacGuard
  participant V as ChannelVerifier
  M->>M: extract package into staging
  M->>V: signature of manifest.json ok
  V->>V: SHA-256 of every listed file
  V-->>M: one file does not match the manifest
  M->>M: release is not trustworthy, delete staging
  M->>M: keep the installed rules

Retroceso o bifurcación

Diagrama: Rollback detectado

Dibujando el diagrama…

Descripción del diagrama

MacGuard guarda el checkpoint verificado más reciente. Una release cuyo checkpoint es menor, o tiene otra raíz con el mismo tamaño, o crece sin una prueba de consistencia, se rechaza. El estado de confianza nunca retrocede.

Código Mermaid
sequenceDiagram
  participant M as MacGuard
  participant T as trust.json (0600)
  participant V as ChannelVerifier
  M->>T: load newest verified checkpoint (size, root)
  M->>V: verify the new release
  V->>V: compare size and root with the trusted ones
  alt smaller, or another root at the same size
    V-->>M: rollback or fork
    M->>M: refuse, do not replace the rules
  else larger
    V->>V: consistency proof from the trusted checkpoint
    V-->>M: ok, save the new checkpoint
  end

El estado de confianza (el checkpoint verificado más reciente) se guarda en un fichero con permisos 0600 y se escribe antes de activar las reglas, así que un corte no lo deja atrás.

Corte durante la instalación

Ver el diagrama de Instalación atómica. Un diario permite al siguiente arranque terminar o deshacer la sustitución, y un bloqueo de fichero impide dos actualizaciones a la vez.