MACGUARD · DOCUMENTATION
Español

Failures and recovery

What the app does when something fails: signature, network, altered file, rollback or a crash during install.

In every case the result is the same: nothing new is installed, the already installed rules keep working and the reason is explained to the person with the technical detail.

Signature failure

Diagram: Signature failure

Drawing the diagram…

Diagram description

If the Sigstore verification of the manifest or checkpoint fails, or if the pinned verifier is missing, MacGuard rejects the release before touching the installed rules and tells the user why.

Mermaid code
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

Network failure

Diagram: Network failure

Drawing the diagram…

Diagram description

A network error, timeout or incomplete download ends the attempt. The streamed download is cancelled, the staging folder is removed and the installed rules keep working. If the primary origin fails, only the next authorised origin is tried, never a mix of files from two origins.

Mermaid code
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

Altered file

Diagram: Altered file

Drawing the diagram…

Diagram description

If a rule file or the package differs from the signed manifest, the hash comparison fails after extraction. The release is rejected as untrustworthy and nothing is installed. A file added or removed in the package also fails, because the file list is part of the signed rules_root.

Mermaid code
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

Rollback or fork

Diagram: Rollback detected

Drawing the diagram…

Diagram description

MacGuard keeps the newest verified log checkpoint. A release whose checkpoint is smaller than that, or has a different root at the same size, or grows without a consistency proof, is refused. The trusted state is never moved backwards.

Mermaid code
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

The trust state (the newest verified checkpoint) is stored in a file with 0600 permissions and is saved before the rules are activated, so a crash cannot leave it behind.

Crash during install

See the diagram in Atomic install. A journal lets the next start finish or undo the swap, and a file lock prevents two updates at once.