| Filename | Latest commit message | Latest commit date |
|---|---|---|
320ad46e00
Cut 2 adds a verify-envelope path beside the closure-token executor. The helper parses an envelope, binds it to the independently provisioned agent identity, validates time and lifetime bounds, selects the trusted key, verifies the signed contract, checks backend payload shape, and then refuses with backend_not_migrated. Every path emits an unsigned MutationReceipt. No backend executes, no replay slot is consumed, and no artifact-custody claim is made until the first existing backend migrates. |
||
| .. | ||
| 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.