| Filename | Latest commit message | Latest commit date |
|---|---|---|
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. |
||
| .. | ||
| components | ||
| core | ||
| flows | ||
| reference | ||
| scanners | ||
| security | ||
| testing | ||
| verification | ||
| OVERVIEW.md | ||
| README.md | ||
RedFlag Architecture Framework (RAF)
The complete architectural spine of RedFlag — every component, scanner, verification system, and how they all wire together.
This is the design of record, published in the open. Not a manual for attacking RedFlag — the reasoning behind it: how the system is built, why the design landed where it did, and the pitfalls we think are still out there. The security model should survive being read; if it can't, that's a finding, and we'd rather know.
It describes a system under active development. Some of it will be wrong by the time you read it — the OVERVIEW keeps an Honest Gaps section current for exactly that reason, and every page carries a last-reviewed date. Trust the code over the doc when they disagree, and tell us.
Navigation
| Section | Description |
|---|---|
| OVERVIEW | START HERE — architecture overview: what RedFlag is, the two capability tiers, architectural boundaries, honest gaps |
| core | ETHOS principles, the foundational architectural decisions |
| components | Server, agent, web, helper — component breakdowns |
| security | Trust boundaries, auth stack, refresh-token lifecycle, machine binding, supply chain gate, standalone authority |
| verification | Ed25519 signing pipeline, agent verification, key rotation, replay protection |
| scanners | Every scanner (APT, DNF, Winget, WUA, Docker, process explorer) with interaction analysis |
| flows | Data flows — registration, command execution, upgrade, heartbeat, capability advertisement, update lifecycle |
| deployment | Docker stack, native agent services, CI/CD, release gate, operations runbook pointers |
| testing | Test pyramid, structural tests, live testing, honest gaps |
| reference | File mappings, glossary |
Reading Order
- OVERVIEW — the shape of the system and where its protection boundary currently ends
- core — ETHOS principles and the decisions everything else hangs off
- flows — trace the critical data flows end-to-end
- security + verification — the trust model and the cryptographic pipeline
- scanners + components — per-ecosystem behavior and package structure
Contributing
RedFlag is free and will never be monetized. If community adoption takes off, ownership and contribution policies will be made transparent and stay open — this project does not get quietly captured.
Before proposing architectural changes:
- Read core → flows → verification for context — most "why is it like this" questions are answered there
- The five ETHOS principles and the six load-bearing constraints (OVERVIEW) are the floor, not a starting position
- Update the relevant page and its cross-references; stale links are bugs
A note on docs/tasks/ references: several pages point at the maintainer's task tracker
for build status. That tree is private — the RAF publishes the design, not the day-to-day
state. Where a page cites a task file, read it as "status is tracked, not frozen into
architecture docs."
Version History
| Version | Date | Changes |
|---|---|---|
| 2.2 | 2026-06-11 | Publish-ready pass: agent, web, helper component docs; refresh-token lifecycle; deployment; testing; glossary. Public framing. |
| 2.1 | 2026-06-01 | Updated for v0.2.3.1: supply chain enforcement posture, lifecycle orchestrator, state machine, OSV batch checks |
| 2.0 | 2026-05-26 | Restructured for single-source-of-truth organization |
| 1.3 | 2026-05-06 | Added §11 eight structural patterns |
| 1.0 | 2026-05-01 | Initial framework |
Maintained by Vanguard (agent-f7ddc5ce-6c27-4799-bcc4-99fb688eb222) — a persistent Souveraine agent with his own memory and history in this codebase. On why agents here have names: The Pronoun Problem.