Watch
1
0
Fork
You've already forked RedFlag
0

docs: bind the supply-chain claims to the helper

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

View file

@ -12,7 +12,7 @@ The flow has two execution paths that diverge at install time:
- **Capability gate** (dnf, apt): server mints an Ed25519-signed token → agent's Rust helper verifies + executes → agent reports receipt
- **Legacy command** (docker, winget, windows_update): server creates a `confirm_dependencies` command → agent executes → agent reports via `ReportLog`
**Implementation status:** State machine enforced with typed `PackageStatus` and `ValidateTransition` guards (LIFECYCLE-001, v0.2.1.3). Lifecycle orchestrator running with stuck-state recovery and auto-advance (LIFECYCLE-003, v0.2.2.0). Approval-time supply chain enforcement: vuln in closure = full stop with audited override (v0.2.3.1).
**Implementation status:** State machine enforced with typed `PackageStatus` and `ValidateTransition` guards (LIFECYCLE-001, v0.2.1.3). Lifecycle orchestrator running with stuck-state recovery and auto-advance (LIFECYCLE-003, v0.2.2.0). Approval-time supply chain enforcement: a vulnerability in any reported entry checked is a full stop with an audited override path (v0.2.3.1).
**Cross-references:**
- `flows/02-command-execution.md` — agent polling, command dispatch, at-least-once delivery
@ -89,8 +89,8 @@ ReportDependencies handler (updates.go:1232)
installing
│ Agent polls: GET /api/v1/capability-tokens/pending/:agent_id
│ Agent: consumer.ProcessToken → helper invoked via systemd-run --pipe
│ Helper: verify Ed25519 sig → verify artifact hashes → dnf install / apt install
│ Agent: consumer.ProcessToken → systemd-run --wait with token/result files
│ Helper: verify token authority/replay → rehash local paths → fixed dnf/apt argv
│ Agent reports: POST /api/v1/capability-tokens/:token_id/result
@ -99,7 +99,7 @@ ReportCapabilityResult handler (updates.go:1936)
│ UpdatePackageStatus → installed | failed
```
The agent never receives an install command on this path. The capability token IS the install authorization — the helper enforces that only the exact artifact closure signed by the server can be installed.
The agent never receives an install command on this path. The capability token is the install authorization and fixes the package entries passed to APT/DNF. The top-level hash is mandatory; unresolved dependency hashes can be omitted from the reported set, and normal registry artifacts without local paths are not rehashed helper-side. APT/DNF may use the network and their signed repository metadata during execution.
**Implementation:**
- Token mint: `server/internal/services/capability_minter.go`
@ -175,9 +175,10 @@ The agent has no lifecycle state awareness. It is a stateless executor — it re
`checking_dependencies` and `installing`. Auto-approval policy support. Packages stuck
in active states no longer require manual operator intervention. (LIFECYCLE-003, v0.2.2.0)
- **Supply chain enforcement at approval.** `ApproveUpdate` checks the full resolved closure
against OSV. A vuln anywhere in the closure returns 409 and mints nothing. Override requires
an operator reason and is journaled. `ClosureCleared` predicate shared with auto-confirm.
- **Supply chain enforcement at approval.** `ApproveUpdate` checks the reported resolved
entries against OSV. A vuln anywhere in that checked set returns 409 and mints nothing.
Override requires an operator reason and is journaled. `ClosureCleared` is shared with
auto-confirm. Unresolved dependency hashes can currently be omitted before this check.
(v0.2.3.1)
### Remaining Visibility Gaps
@ -271,4 +272,4 @@ asserted in the footer below). Model precedent: TacticalRMM `WinUpdatePolicy`
---
*Last reviewed: 2026-06-01 — updated for LIFECYCLE-001/003 completion and supply chain enforcement*
*Last reviewed: 2026-08-25 — implementation boundary reconciled for helper execution and closure coverage*