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

6.8 KiB
Raw Blame History

Start Here: RedFlag Architecture Overview

Version: v0.2.8.0 (June 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 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)

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

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