Fimeg/RedFlag
Watch
1
0
Fork
You've already forked RedFlag
 0
Code Releases Activity
RedFlag/RAF/OVERVIEW.md

9.1 KiB
Raw Blame History

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:

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 — 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:

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:

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