Fimeg/RedFlag
Watch
1
0
Fork
You've already forked RedFlag
 0
Code Releases Activity

docs: bind the supply-chain claims to the helper

Browse source
This commit is contained in:
Fimeg 2026-08-25 08:26:05 -04:00
commit c3037655cd
10 changed files with 194 additions and 128 deletions
Download patch file Download diff file Expand all files Collapse all files

34
RAF/OVERVIEW.md
View file

@ -39,14 +39,22 @@ lifecycle orchestrator drives auto-advance and recovers stuck states.
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.
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 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.
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.
@ -106,9 +114,9 @@ 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`.
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
@ -150,7 +158,9 @@ From `security/05-supply-chain-gate.md` — do not regress these:
## 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](security/05-supply-chain-gate.md) §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
- **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
@ -160,4 +170,4 @@ boundary currently ends. Task tracking for closing them lives in `docs/tasks/`.
---
*Last reviewed: 2026-06-10*
*Last reviewed: 2026-08-25*