4.4 KiB
4.4 KiB
Glossary
The vocabulary of RedFlag, in one place. Terms link to their design-of-record pages.
| Term | Meaning |
|---|---|
| Agent | Stateless Go executor on each managed host. Polls, verifies, executes, reports. Never decides. components/02-agent |
| Capability token | Ed25519-signed grant describing exactly one operation over the artifact entries it carries. Every carried name/version/hash is signed; the current dnf/apt set can omit a dependency whose hash did not resolve. Minted at approval, executed once. security/05-supply-chain-gate |
| Closure (dependency closure) | The artifact set reported from a package-manager dry-run. The target is the full named package plus every transitive dependency; today the top-level hash is mandatory while unresolved dependency hashes can be omitted. |
| Closure hash | Canonical hash over the closure, embedded in the token's signed message. Computed byte-identically in Go (server) and Rust (helper) — the cross-language contract. |
| Discovery vs. mutation | Discovery (scan, dry-run, hash-resolve) runs unprivileged through DiscoveryRunner. Mutation happens only through the helper on gated ecosystems. The agent cannot install. |
| Doctrine / doctrinal | A guarantee with no configuration knob: signing-required, forward-only versioning, no verification skip path. If it's doctrine, there is nothing to misconfigure. core/01-ethos |
| Drift detection | Knowing what should be installed vs. what is, and bridging the gap into update packages. |
| ETHOS | The five principles every change is held to: errors are history, no unauthenticated endpoints, assume failure, idempotency, no marketing fluff in logs. core/01-ethos |
| Fail-closed | When a required check fails, the operation doesn't happen: bad token version/time/host/signature/replay state denies, a missing or mismatched mirror artifact denies, and an unknown vulnerability state blocks under configured policy. A normal registry entry without a local path is not currently a required helper-side rehash. |
| Family revocation | Refresh tokens form a lineage (family_id); replaying a stale token burns the entire family loudly. Theft is detected, not coexisted with. security/03-refresh-tokens |
| Forward-only | No downgrades. Versions move forward; the release gate enforces it; there is no override. |
| Helper | The privileged, short-lived Rust executor — the only RedFlag mutation path on gated ecosystems. It uses fixed argv and a cleared environment; its current transient unit is not network-isolated. components/04-helper |
| Legacy command path | Direct signed-command execution for docker / winget / windows_update — ecosystems the capability gate doesn't cover yet. A documented gap, not a feature. OVERVIEW |
| Machine binding | Hardware fingerprint registered at enrollment and checked on every authenticated request, including token renewal. A stolen config.json is inert elsewhere. security/04-machine-binding |
| Nonce | Per-command signed value with a 10-minute window; agents track executed nonces and reject replays. verification/04-replay-protection |
| OSV | OSV.dev, the open vulnerability database. Queried for discovered packages and for the resolved entries reported after dry-run; verdicts persist and gate approval. An unresolved dependency omitted from that report is not checked by this path. |
| RAF | This document tree — the RedFlag Architecture Framework, the design of record. What the system is, not what's currently on the task list. |
| Soak gate / age gate | Time-based supply-chain policies: minimum package age before approval (Shai-Hulud defense) and a version soak window before install. Policies, not doctrine — configurable, with enforcement modes. security/05-supply-chain-gate |
| TOFU | Trust-on-first-use: the agent caches the server's public key at first connect and verifies everything after against the cached roster, by key_id. verification/03-key-rotation |
| Two execution paths | Capability gate (dnf, apt — token + helper) and legacy command (everything else, for now). OVERVIEW |
Last reviewed: 2026-08-25