ff2f30f47a
DEVICE-002: ARM machine-ID fallback — device-tree model + /etc/machine-id combo, then /proc/cpuinfo Serial (all-zero rejected), before the weak hostname fallback. Hardware-bound IDs on DMI-less devices. DEVICE-001: agent detects device_type (server/desktop/phone/tablet) from /sys signals — system battery (scope=Device peripherals excluded, UPS excluded), DRM connector state, framebuffer min-dimension for phone/tablet split. Reports device_type/device_model/os_distro in registration and system-info paths. SERVER-001: migration 061 — device_type, device_type_manual (operator override, never agent-written), device_model, os_distro on agents. effective_device_type computed into every serialized agent. SERVER-002: PUT /admin/agents/:id/device-type — set/clear override, enum-validated, journaled. WEB-001: device-type icons + fleet filter, device model in list, detail header badge with reclassify dropdown, os_distro surfaced. INSTALL-003: arm64 install path unblocked — helper (required manifest component) now cross-built aarch64-unknown-linux-musl via rust-lld in the server image, signed at boot (helperArches += arm64), listed in the release manifest. Install template already handled uname -m and pacman. Plus in-flight: desktop tray wiring, enrollment page polish, CI workflow updates, RAF session-broker/pacman-scanner docs, native installer scaffold.
8.1 KiB
Start Here: RedFlag Architecture Overview
Version: v0.2.9.3 (July 2026)
This is the entry point into the RedFlag Architecture Framework. Read this first to understand the shape of the system, then follow the links into the detailed docs.
What RedFlag Is
A self-hosted update management platform for homelabs and small MSPs. Centralized visibility and control over software updates across Linux, Windows, and Docker — with a cryptographic supply chain gate that most commercial RMM tools don't attempt.
The Two Capability Tiers
Tier 1: Update Management
Agents register with a one-time token and a hardware fingerprint (TOFU). The server issues Ed25519-signed commands; agents verify signatures, check nonces, reject replays. Pull-based polling (5 min default, rapid mode available). Subsystem scanning across apt, dnf, winget, WUA, and Docker.
Packages move through a server-owned state machine (pending through installed or
failed) with typed transitions and guarded UPDATEs — no free-form string jumps. A
lifecycle orchestrator drives auto-advance and recovers stuck states.
Architecture docs:
- core/01-ethos — the five principles
- core/02-architecture-decisions — the twelve foundational choices
- security/02-authentication-stack — four-layer auth (reg tokens, JWT, refresh, machine binding)
- security/01-trust-boundaries — endpoint classification and middleware matrix
- flows/06-update-lifecycle — state machine, two execution paths, orchestrator
Tier 2: Supply Chain Gate
The differentiator. The server is the signing authority — it evaluates policy (OSV
vulnerability checks, package age, human approval) and mints an Ed25519-signed
capability token describing exactly one operation over a fully-resolved dependency
closure. A privileged, network-less Rust executor (helper/) verifies the signature
and every artifact hash before performing that one operation.
The approval gate is fail-closed: a known vulnerability anywhere in the resolved closure — top-level or transitive — blocks the token from being minted. The operator must override with a documented reason. The override waives the vulnerability judgment only; signing and hash verification have no skip path.
Auto-confirm shares the same ClosureCleared predicate as manual approval — the two
paths cannot drift on what counts as a clean closure.
Architecture docs:
- security/05-supply-chain-gate — the design of record: capability model, wire contract, load-bearing constraints, enforcement layers, trust chain, hash registry
docs/tasks/GATE-000-supply-chain-gate-plan.md— build status & implementation tracking (not design)
Tier 3: Break-Glass Sessions
When Tiers 1–3 (read, catalog actions, signed runbooks) can't cover the case — live
shell, desktop control, or an urgent pre-signed runbook triggered by detection — the
session broker provides a break-glass path. It is a separate privileged Rust binary
(redflag-broker), spawned on demand via the same sudo systemd-run pattern as the
helper, disposable, time-boxed, and audit-logged.
The broker cannot start without a minted, Ed25519-signed session grant specifying exactly what it may do. The agent verifies the grant and spawns the broker; after that the agent is out of the loop. The broker opens its own connection to the server, streams live I/O, hash-chains every command in a tamper-evident audit log, and exits when the grant expires.
Prerequisite: Tier 4 requires RBAC (operator-level role gating for grant minting). The design is complete but gated behind the RBAC substrate — a break-glass path without role-gated minting is just "anyone can get a root shell."
Architecture docs:
- components/06-session-broker — design of record: grant format, trust chain, audit trail, sequence diagram, scope variants
Process Explorer
On-demand /proc filesystem scanning for process inventory and drill-down detail.
Triggered when a user opens the Processes tab — no background broadcasting.
25+ fields per process (osquery parity) plus 7 related data types (open files,
sockets, pipes, environment keys, memory map, namespaces, listening ports).
Data collection caps are server-controlled via ProcessExplorerConfig (Settings →
Process Explorer) and delivered to agents on check-in. Listening ports use socket
inode correlation against /proc/net/tcp — not system-wide assignment.
Architecture docs:
- scanners/05-process-scanner — data model, collection, caps
- flows/07-process-scan — command-dispatch flow, API endpoints, schema
Architectural Boundaries
Agent is a Stateless Executor
The agent receives commands, executes them, and reports results. It does not track lifecycle states. The server owns every state transition. The agent's only autonomous decisions are: verify this signature, check this nonce, reject this replay.
Mutation Only Through the Helper
On capability-gated ecosystems (dnf, apt), the agent cannot run install commands
directly. All mutation flows through consumer.go → sudo systemd-run --pipe →
redflag-helper. The agent holds zero sudo for installs. Discovery (scan, dry-run,
hash-resolve) runs unprivileged through DiscoveryRunner.
Two Execution Paths
- Capability gate (dnf, apt): token minted at approval → agent polls for tokens → helper verifies + executes → agent reports receipt. No install command issued.
- Legacy command (docker, winget, windows_update): signed command → agent executes directly via type-asserted installer methods → reports via ReportLog.
The legacy path is a known gap — the gate design covers these ecosystems but implementation is deferred.
Six Load-Bearing Constraints
From security/05-supply-chain-gate.md — do not regress these:
- Sign the resolved closure, not the top-level package
- The signer lives off the web process (seam documented, not yet isolated)
- Verified-cache fallback, fail-closed only on change
- Verify keys, not servers
- Kernel stops are defense-in-depth, not a prerequisite
- No doctrinal knobs — signing required and forward-only are not configurable
Navigation
| Section | What It Describes |
|---|---|
| core | ETHOS principles, architectural decisions |
| components | Server, agent, web, helper, session broker — package structure and responsibilities |
| security | Trust boundaries, auth stack, machine binding, supply chain gate |
| verification | Ed25519 signing pipeline, agent verification, key rotation, replay protection |
| scanners | Per-ecosystem scanner behavior and integration points (incl. process scanner) |
| flows | Data flows — registration, command execution, upgrade, heartbeat, capability advertisement, update lifecycle |
| reference | File mappings, glossary |
Honest Gaps
- Gate policy visibility: the soak and age gates are live policies as of v0.2.6.2 (
supply_chain.*settings — see security/05-supply-chain-gate §4), but the dashboard doesn't yet surface their configuration; operators tune them blind. The live install-through-helper path completed e2e on 2026-06-05 - Closure transitivity split by platform: dnf/apt resolve via dry-run (full closure); npm/pypi still single-entry
- Signer in-process: key encapsulated in SigningService, minter is the only caller — but true process isolation not built
- Legacy ecosystems ungated: docker, winget, windows_update still direct-mutation
- Kernel enforcement inert: eBPF scaffold exists, not wired to the capability model
These are architectural gaps, not bugs. They define where the system's protection
boundary currently ends. Task tracking for closing them lives in docs/tasks/.
Last reviewed: 2026-06-10