173 lines
9.1 KiB
Markdown
173 lines
9.1 KiB
Markdown
# 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](core/01-ethos.md) — the five principles
|
||
- [core/02-architecture-decisions](core/02-architecture-decisions.md) — the twelve foundational choices
|
||
- [security/02-authentication-stack](security/02-authentication-stack.md) — four-layer auth (reg tokens, JWT, refresh, machine binding)
|
||
- [security/01-trust-boundaries](security/01-trust-boundaries.md) — endpoint classification and middleware matrix
|
||
- [flows/06-update-lifecycle](flows/06-update-lifecycle.md) — 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 the resolved artifact set the
|
||
agent reported. On dnf/apt, the top-level hash is mandatory; dependency hashes that
|
||
resolve are included, while unresolved dependencies can currently be omitted. A
|
||
privileged, short-lived Rust executor (`helper/`) validates the token version and time,
|
||
host binding, signature, and replay state before running one fixed argv plan with no
|
||
shell and a cleared environment.
|
||
|
||
The helper rehashes a closure entry when it points to a readable local file and refuses a
|
||
missing mirror artifact. Normal registry entries without local paths are not rehashed
|
||
helper-side, and the current transient unit retains host network access. Full closure
|
||
pinning, complete local byte custody, and network isolation remain the target boundary.
|
||
|
||
The approval gate is fail-closed over the set it checked: a known vulnerability in a
|
||
reported resolved entry — 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; it does not waive capability validation or local artifact verification.
|
||
|
||
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](security/05-supply-chain-gate.md) — 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](components/06-session-broker.md) — 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](scanners/05-process-scanner.md) — data model, collection, caps
|
||
- [flows/07-process-scan](flows/07-process-scan.md) — 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 --wait` with
|
||
token/result files → `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:
|
||
|
||
1. Sign the resolved closure, not the top-level package
|
||
2. The signer lives off the web process (seam documented, not yet isolated)
|
||
3. Verified-cache fallback, fail-closed only on change
|
||
4. Verify keys, not servers
|
||
5. Kernel stops are defense-in-depth, not a prerequisite
|
||
6. No doctrinal knobs — signing required and forward-only are not configurable
|
||
|
||
---
|
||
|
||
## Navigation
|
||
|
||
| Section | What It Describes |
|
||
|---------|-------------------|
|
||
| [core](core/) | ETHOS principles, architectural decisions |
|
||
| [components](components/) | Server, agent, web, helper, session broker — package structure and responsibilities |
|
||
| [security](security/) | Trust boundaries, auth stack, machine binding, supply chain gate |
|
||
| [verification](verification/) | Ed25519 signing pipeline, agent verification, key rotation, replay protection |
|
||
| [scanners](scanners/) | Per-ecosystem scanner behavior and integration points (incl. process scanner) |
|
||
| [flows](flows/) | Data flows — registration, command execution, upgrade, heartbeat, capability advertisement, update lifecycle |
|
||
| [reference](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](security/05-supply-chain-gate.md) §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 completeness**: dnf/apt require the top-level hash, but dependency hashes are best-effort and unresolved entries can be omitted; npm/pypi registry pinning remains single-entry
|
||
- **Registry artifact verification**: the helper rehashes local paths, but normal registry artifacts without a local path are not rehashed helper-side
|
||
- **Helper network isolation**: the current `systemd-run` unit retains host network access; complete local artifact custody and a private network boundary are not built
|
||
- **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-08-25*
|