docs: bind the supply-chain claims to the helper
This commit is contained in:
parent
14d4730c76
commit
c3037655cd
10 changed files with 194 additions and 128 deletions
|
|
@ -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*
|
||||
|
|
|
|||
Loading…
Reference in a new issue