Documentation
¶
Index ¶
- Constants
- Variables
- func Exists(name string) bool
- func GroupByPhase() map[string][]string
- func IsCustomDeclaration(overrides map[string]any) bool
- func List() []string
- func ListByPhase(phase string) []string
- type Option
- type OptionTOML
- type Preset
- type PresetTOML
- type PresetsFile
- type PromotionDecision
Constants ¶
const PromotionCooldown = 14 * 24 * time.Hour
PromotionCooldown is how long a newly published version must have been publicly available before the catalogue promotes it. The monitor runs weekly, so this is roughly two cycles.
It is deliberately not a user-facing setting: the policy governs cidx's own catalogue, not the projects that use cidx, which pin whatever they want in their own cidx.toml (guardrail 5). Shortening the window is a decision to argue for in a commit, not to bury in a config file.
Variables ¶
var GlobalRegistry map[string]Preset
GlobalRegistry contains all built-in presets Loaded from presets.yaml (dev) or embedded data (production)
Functions ¶
func GroupByPhase ¶
GroupByPhase returns presets grouped by phase
func IsCustomDeclaration ¶
IsCustomDeclaration reports whether the given override section declares a brand-new container (image field present) rather than overriding an existing preset. Used by validator and runner to decide between preset-override semantics and custom-container semantics.
func ListByPhase ¶
ListByPhase returns presets filtered by phase
Types ¶
type Option ¶
type Option struct {
Type string `yaml:"type" toml:"type"` // string, bool, int, array
Default any `yaml:"default" toml:"default"` // Default value
Description string `yaml:"description" toml:"description"` // Help text
EnvVar string `yaml:"env_var" toml:"env_var"` // Maps to environment variable
CommandFlag string `yaml:"command_flag" toml:"command_flag"` // Maps to command flag
}
Option defines a configurable parameter for a preset
type OptionTOML ¶
type OptionTOML struct {
Type string `toml:"type"`
Default interface{} `toml:"default"`
Description string `toml:"description"`
CommandFlag string `toml:"command_flag"`
EnvVar string `toml:"env_var"`
}
OptionTOML represents an option in TOML format
type Preset ¶
type Preset struct {
Name string `yaml:"name" toml:"name"`
Phase string `yaml:"phase" toml:"phase"`
Image string `yaml:"image" toml:"image"`
Description string `yaml:"description,omitempty" toml:"description,omitempty"` // Usage notes and constraints, shown by `preset info`
Hardened bool `yaml:"hardened,omitempty" toml:"hardened,omitempty"` // Uses Docker Hardened Image (dhi.io)
Command string `yaml:"command" toml:"command"`
Entrypoint []string `yaml:"entrypoint" toml:"entrypoint"`
Workdir string `yaml:"workdir" toml:"workdir"`
Volumes []string `yaml:"volumes" toml:"volumes"`
Env map[string]string `yaml:"env" toml:"env"`
ConfigFiles []string `yaml:"config_files" toml:"config_files"`
Options map[string]Option `yaml:"options" toml:"options"`
RequireCI bool `yaml:"require_ci" toml:"require_ci"` // Requires CI environment
LocalBehavior string `yaml:"local_behavior" toml:"local_behavior"` // draft, no-push, dry-run, disabled
Privileged bool `yaml:"privileged,omitempty" toml:"privileged,omitempty"` // Requires root privileges (skip user mapping)
PullPolicy string `yaml:"pull_policy,omitempty" toml:"pull_policy,omitempty"` // always, if-not-present, never (default: env-based)
Timeout string `yaml:"timeout,omitempty" toml:"timeout,omitempty"` // duration string (e.g., "5m", "45m"), default: 30m
}
Preset defines a complete tool configuration with sensible defaults
func PresetFromOverrides ¶
PresetFromOverrides constructs a Preset from a custom container declaration in cidx.toml. A declaration is a `[containers.NAME]` section that has an `image` field present — that signals a brand-new container, not an override of a known preset. The returned Preset is filled from the overrides map; fields absent from the map keep their zero value.
This implements the user-facing contract documented in examples/cidx-complete.toml (custom containers section) and closes #142.
type PresetTOML ¶
type PresetTOML struct {
Name string `toml:"name"`
Phase string `toml:"phase"`
Image string `toml:"image"`
Description string `toml:"description"`
Hardened bool `toml:"hardened"`
Command string `toml:"command"`
Entrypoint []string `toml:"entrypoint"`
Workdir string `toml:"workdir"`
Volumes []string `toml:"volumes"`
Env map[string]string `toml:"env"`
ConfigFiles []string `toml:"config_files"`
Options map[string]OptionTOML `toml:"options"`
RequireCI bool `toml:"require_ci"`
LocalBehavior string `toml:"local_behavior"`
Privileged bool `toml:"privileged"`
PullPolicy string `toml:"pull_policy"`
Timeout string `toml:"timeout"`
}
PresetTOML represents a preset in TOML format
type PresetsFile ¶
type PresetsFile struct {
Presets map[string]PresetTOML `toml:"presets"`
}
PresetsFile represents the structure of presets.toml
type PromotionDecision ¶ added in v2.2.0
type PromotionDecision struct {
// Promote reports whether the candidate may replace the running image.
Promote bool
// Reason states why. Always set, for promotions as much as for holds — a
// candidate held for another week has to say so somewhere, or the policy
// silently swallows it.
Reason string
// WaivedFor names the vulnerabilities that bought the candidate its way
// past the cooldown. Empty when no waiver was needed, so a promotion never
// claims a waiver that did nothing.
WaivedFor []string
// AgeDays is how long the candidate has been public, in whole days. Nil
// when the registry gave no date.
AgeDays *int
}
PromotionDecision is the verdict on one candidate version, in the words the workflow summary and the promotion PR print verbatim.
func EvaluatePromotion ¶ added in v2.2.0
func EvaluatePromotion(published, now time.Time, affectingUs []string) PromotionDecision
EvaluatePromotion applies the cooldown and its exception to one candidate.
published is when the candidate became publicly available; the zero time means the registry would not say. affectingUs are the HIGH/CRITICAL vulnerabilities already recorded against the image the catalogue runs today.
An undatable candidate is held. That mirrors rule 1's treatment of an unresolvable digest: the promotion is skipped rather than taken on an assumption, and the reason is reported so it does not vanish quietly.
The exception then overrides the hold — for a young candidate and an undatable one alike. Waiting out a date that will never arrive would just leave a known vulnerability in place, and deliberately running a known-vulnerable image to guard against a hypothetical one is the worse trade. A candidate that has served the cooldown claims no waiver: it did not need one.
Source Files