RAF: full docs pass — components, flows, security, scanners, reference, testing, verification, overview
This commit is contained in:
Fimeg
parent
565baa0819
commit
a19dcf4f14
34 changed files with 5085 additions and 28 deletions
141
RAF/OVERVIEW.md
Normal file
141
RAF/OVERVIEW.md
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
# 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:**
|
||||
- [[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)
|
||||
|
||||
### 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:
|
||||
|
||||
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*
|
||||
Loading…
Reference in a new issue