MACGUARD · DOCUMENTACIÓN
English

Actualización en MacGuard

Cómo la app descarga, verifica e instala las reglas.

Flujo normal

Diagrama: Actualización normal en MacGuard

Dibujando el diagrama…

Descripción del diagrama

La persona da su consentimiento, MacGuard toma el bloqueo de actualización, descarga a una carpeta de staging privada con límites de tamaño, extrae de forma segura, verifica la firma del manifiesto, cada hash, rules_root, la firma del checkpoint, la prueba de inclusión y la consistencia con el checkpoint de confianza, guarda el nuevo checkpoint y activa las reglas con dos renombrados.

Código Mermaid
sequenceDiagram
  autonumber
  participant U as User
  participant M as MacGuard RuleInstaller
  participant S as Channel (Pages)
  participant V as ChannelVerifier and cosign
  U->>M: update rules (consent)
  M->>M: flock update.lock, recover interrupted swaps
  M->>S: latest.json
  M->>S: tarball, manifest, bundles, proof, checkpoint, log.jsonl (byte caps)
  M->>M: safe extraction in staging
  M->>V: manifest signature, file hashes, rules_root
  M->>V: checkpoint signature, inclusion, consistency, rollback check
  V-->>M: all checks passed
  M->>M: save trusted checkpoint, rename live to previous, staging to live
  M-->>U: rules installed

La app no actualiza sola sin consentimiento. Descarga a una carpeta de staging privada con límites de tamaño por fichero, extrae con límites (sin enlaces ni rutas fuera del directorio) y solo activa las reglas cuando todas las comprobaciones han pasado.

Qué comprueba

Orígenes

La app descarga primero de GitHub Pages (https://macguard.github.io/macguard-yara-channel/) y, solo si ese origen no responde, del espejo de Cloudflare Pages (https://macguard-rules.pages.dev/). Cada intento instala de un único origen de principio a fin; nunca mezcla ficheros de los dos. Los dos sirven los mismos bytes firmados y la release se verifica igual en ambos casos. Un fallo de verificación no pasa al siguiente origen.

Motor YARA

MacGuard distribuye su propio motor YARA 4.5.8 (con OpenSSL 3.5.9) en versión universal Intel/ARM. Antes de usar el motor comprueba los hashes de su manifiesto, su firma de código, su versión, su arquitectura y una autoprueba. Cada fichero de reglas se carga en su propio espacio de nombres con las dependencias firmadas.

LÍMITE Firma con Developer ID y notarización de la app, del motor y del cosign incluido son pasos de publicación de la app que aún están pendientes.

Instalación atómica

Diagrama: Instalación atómica y recuperación

Dibujando el diagrama…

Descripción del diagrama

La activación escribe un diario, renombra la carpeta viva a previous y la carpeta de staging verificada a live. Si el proceso muere entre los dos renombrados, el siguiente arranque encuentra el diario, ve que falta live y devuelve previous a su sitio. Una segunda actualización simultánea la rechaza un bloqueo de fichero.

Código Mermaid
sequenceDiagram
  autonumber
  participant I as RuleInstaller
  participant FS as Filesystem
  I->>FS: write journal.json
  I->>FS: rename community to previous
  Note over I,FS: a crash here leaves community missing
  I->>FS: rename staging community to community
  I->>FS: delete journal.json
  Note over I,FS: next start, journal found and community missing, recoverIfNeeded renames previous back