Architecture

The components of the channel and how they connect end to end.

Overview

The flow has two halves: a private pipeline that decides what is published and a signed public chain anyone can verify. The decision point is decide.py: nothing reaches signing without going through it.

Diagram: End-to-end architecture

Drawing the diagram…

flowchart TB
  N["Nextron Systems<br/>Neo23x0/signature-base"]:::src
  C["Community rules<br/>Yara-Rules/rules"]:::src
  V["VirusTotal YARA-X<br/>recorded as engine, no rules"]:::src
  P["prepare.py<br/>pin commit, extract, normalize"]:::src
  R["rulecheck.py<br/>static classification"]:::val
  G["dynamic_gate.py + bench.py<br/>YARA engine measurements"]:::val
  D{"decide.py<br/>PUBLISH GATE"}:::gate
  H["SHA-256 per file<br/>make_public_candidate.py"]:::sec
  M["rules_root + manifest.json<br/>seal.py"]:::sec
  S["Sigstore keyless<br/>cosign in publish.yml"]:::sec
  RL["GitHub Release<br/>draft, then public"]:::pub
  W["GitHub Pages + Cloudflare mirror<br/>site.yml"]:::pub
  A["MacGuard GUI TUI CLI<br/>RuleInstaller"]:::pub
  Q[("Private quarantine store<br/>admin/worker D1")]:::qua
  API["Admin API and panel"]:::qua
  HR["Human review<br/>approve, delete or keep"]:::qua
  N --> P
  C --> P
  V -.-> P
  P --> R --> G --> D
  D -->|approved| H --> M --> S --> RL --> W --> A
  D -->|not approved| Q --> API --> HR
  HR -->|decision| R
  classDef src fill:#cfe3ff,stroke:#2f6df0,color:#0b1b33
  classDef val fill:#ffe9b8,stroke:#b8860b,color:#2b1d00
  classDef sec fill:#cdeedd,stroke:#1b6e3c,color:#08210f
  classDef pub fill:#e4d7ff,stroke:#6a3fd1,color:#1b0b3b
  classDef qua fill:#ffd4cc,stroke:#c0392b,color:#33100b
  classDef gate fill:#ffffff,stroke:#111111,stroke-width:3px,color:#111111

Diagram description

Three upstream sources feed prepare.py. Files are classified by rulecheck.py and measured by dynamic_gate.py. decide.py is the publish gate: approved files get SHA-256 hashes, a Merkle rules_root and a manifest, are signed with Sigstore in publish.yml, published as a GitHub Release, mirrored on GitHub Pages and Cloudflare Pages and installed by MacGuard. Files that do not pass go to the private quarantine store, are reviewed by a person through the admin API and are re-validated by the next daily run.

Mermaid code

flowchart TB
  N["Nextron Systems<br/>Neo23x0/signature-base"]:::src
  C["Community rules<br/>Yara-Rules/rules"]:::src
  V["VirusTotal YARA-X<br/>recorded as engine, no rules"]:::src
  P["prepare.py<br/>pin commit, extract, normalize"]:::src
  R["rulecheck.py<br/>static classification"]:::val
  G["dynamic_gate.py + bench.py<br/>YARA engine measurements"]:::val
  D{"decide.py<br/>PUBLISH GATE"}:::gate
  H["SHA-256 per file<br/>make_public_candidate.py"]:::sec
  M["rules_root + manifest.json<br/>seal.py"]:::sec
  S["Sigstore keyless<br/>cosign in publish.yml"]:::sec
  RL["GitHub Release<br/>draft, then public"]:::pub
  W["GitHub Pages + Cloudflare mirror<br/>site.yml"]:::pub
  A["MacGuard GUI TUI CLI<br/>RuleInstaller"]:::pub
  Q[("Private quarantine store<br/>admin/worker D1")]:::qua
  API["Admin API and panel"]:::qua
  HR["Human review<br/>approve, delete or keep"]:::qua
  N --> P
  C --> P
  V -.-> P
  P --> R --> G --> D
  D -->|approved| H --> M --> S --> RL --> W --> A
  D -->|not approved| Q --> API --> HR
  HR -->|decision| R
  classDef src fill:#cfe3ff,stroke:#2f6df0,color:#0b1b33
  classDef val fill:#ffe9b8,stroke:#b8860b,color:#2b1d00
  classDef sec fill:#cdeedd,stroke:#1b6e3c,color:#08210f
  classDef pub fill:#e4d7ff,stroke:#6a3fd1,color:#1b0b3b
  classDef qua fill:#ffd4cc,stroke:#c0392b,color:#33100b
  classDef gate fill:#ffffff,stroke:#111111,stroke-width:3px,color:#111111

Components

Component	What it does	Where
`daily.yml`	Daily 03:17 UTC or manual run: collects, classifies, measures, decides and requests publication.	`.github/workflows/daily.yml`
`publish.yml`	Signs and publishes the release; environment `stable-signing-auto` when `AUTO_PUBLISH=true`, otherwise `stable-signing` with a human approver.	`.github/workflows/publish.yml`
`site.yml`	Builds and verifies the site, deploys it and checks the public URL.	`.github/workflows/site.yml`
Servicio de cuarentena	Private store and review panel (Cloudflare Worker + D1).	`admin/worker/`
MacGuard	GUI, TUI and CLI sharing one engine.	`DMGTrustAuditor/DMGTrustAuditor/Core/`

CURRENT The quarantine service is implemented and tested against a local development server, but it is not deployed in production: Cloudflare Workers/D1 credentials and a GitHub OAuth app are missing. Meanwhile quarantine is applied inside the pipeline and only what passes every automatic check is published.

Trust boundaries

Diagram: Trust boundaries

Drawing the diagram…

flowchart LR
  subgraph UNTRUSTED["Untrusted input"]
    U1["upstream rule repositories"]:::src
  end
  subgraph PRIVATE["Private zone"]
    J["daily.yml review job"]:::val
    QS[("quarantine store")]:::qua
    AP["admin panel and API"]:::qua
  end
  subgraph SIGNING["Signing zone"]
    PW["publish.yml<br/>OIDC identity"]:::sec
  end
  subgraph PUBLIC["Public zone"]
    GR["GitHub Releases"]:::pub
    PG["Pages and Cloudflare mirror"]:::pub
  end
  subgraph CLIENT["Client"]
    MG["MacGuard<br/>pinned cosign, trusted checkpoint"]:::sec
  end
  U1 --> J
  J -->|only approved files and counts| PW
  J -->|everything else| QS
  QS --- AP
  PW --> GR --> PG --> MG
  classDef src fill:#cfe3ff,stroke:#2f6df0,color:#0b1b33
  classDef val fill:#ffe9b8,stroke:#b8860b,color:#2b1d00
  classDef sec fill:#cdeedd,stroke:#1b6e3c,color:#08210f
  classDef pub fill:#e4d7ff,stroke:#6a3fd1,color:#1b0b3b
  classDef qua fill:#ffd4cc,stroke:#c0392b,color:#33100b
  classDef gate fill:#ffffff,stroke:#111111,stroke-width:3px,color:#111111

Diagram description

Upstream sources are untrusted input. The private pipeline job and the quarantine store hold everything about rules that are not published. Only the approved set, aggregate numbers and the signed artifacts cross into the public zone. The client trusts the pinned Sigstore verifier, the workflow identity and its own saved checkpoint, not the hosting site.

Mermaid code

flowchart LR
  subgraph UNTRUSTED["Untrusted input"]
    U1["upstream rule repositories"]:::src
  end
  subgraph PRIVATE["Private zone"]
    J["daily.yml review job"]:::val
    QS[("quarantine store")]:::qua
    AP["admin panel and API"]:::qua
  end
  subgraph SIGNING["Signing zone"]
    PW["publish.yml<br/>OIDC identity"]:::sec
  end
  subgraph PUBLIC["Public zone"]
    GR["GitHub Releases"]:::pub
    PG["Pages and Cloudflare mirror"]:::pub
  end
  subgraph CLIENT["Client"]
    MG["MacGuard<br/>pinned cosign, trusted checkpoint"]:::sec
  end
  U1 --> J
  J -->|only approved files and counts| PW
  J -->|everything else| QS
  QS --- AP
  PW --> GR --> PG --> MG
  classDef src fill:#cfe3ff,stroke:#2f6df0,color:#0b1b33
  classDef val fill:#ffe9b8,stroke:#b8860b,color:#2b1d00
  classDef sec fill:#cdeedd,stroke:#1b6e3c,color:#08210f
  classDef pub fill:#e4d7ff,stroke:#6a3fd1,color:#1b0b3b
  classDef qua fill:#ffd4cc,stroke:#c0392b,color:#33100b
  classDef gate fill:#ffffff,stroke:#111111,stroke-width:3px,color:#111111

Sources are untrusted input. Details about unpublished rules (names, findings, content) never leave the private job except towards the private service; public artifacts, logs and the site carry counts only.