Documentation
¶
Overview ¶
Package securitymaintenance evaluates public security advisories locally and coordinates installation-owned update drivers. Advisory metadata never grants release, migration, shell or deployment authority.
Index ¶
- Constants
- Variables
- type AbortRestorer
- type Advisory
- type Affected
- type Catalog
- type Decision
- type Driver
- type Engine
- type Enrollment
- type Feed
- type GateProver
- type Impact
- type Mode
- type Observation
- type Operation
- type Policy
- type Preparation
- type Reconciler
- type Severity
- type Status
- type Store
- type Target
Constants ¶
const CatalogFormat = "hikyo.security-catalog/v1"
const MaxCatalogBytes = 4 << 20
const MaxCatalogLifetime = 90 * 24 * time.Hour
MaxCatalogLifetime bounds the payload only. Freshness comes from the much shorter TUF timestamp expiry, which also bounds client eligibility.
const MaxRolloutMinutes = 10080
const ReplacementUndone = "the replacement did not complete; the earlier release is serving again and the security fix is not applied"
ReplacementUndone is the status text after the source was put back, whether the target reported an abort or ran out of time.
const StatusFormat = securitystatus.Format
Variables ¶
var ErrNotStarted = errors.New("security application did not take effect")
ErrNotStarted may be returned only by a trusted local driver that refused before any workload mutation, or that proved the exact source image is serving again after its target stopped before the database was written. Other execution failures retain recovery pins. Its text becomes the status detail, so it must hold for both cases.
var ErrPastFinalGate = errors.New("the target passed the final gate; a person decides whether it stays")
ErrPastFinalGate keeps the pin: a target that is healthy at its release may have served.
var ErrProtectionGap = errors.New("applicable security advisories remain unremediated")
ErrProtectionGap makes a known unremediated advisory fail the scheduled unit, so ordinary host monitoring sees it without any project telemetry.
var ErrRolledBack = errors.New(ReplacementUndone)
ErrRolledBack accompanies ErrSourceRestored when the target had written and the fenced snapshot was restored: nothing was "refused before the database changed".
var ErrSourceRestored = errors.New("the source was interrupted and is serving again")
ErrSourceRestored accompanies ErrNotStarted when a driver stopped the source and proved it serving again. Unlike a refusal before any mutation, that cost an outage, so it counts toward the retry limit.
Functions ¶
This section is empty.
Types ¶
type AbortRestorer ¶
type AbortRestorer interface {
RestoreAborted(ctx context.Context, aborted Observation, operation Operation) error
}
AbortRestorer is implemented by drivers that can put the source back after its target reported that it stopped before writing the database, or, with an observation that does not report it, after the operation's deadline passed without the target proving healthy. It returns ErrNotStarted once the exact source is observed serving untouched again; any other result keeps the recovery pins, and a later run asks again.
type Affected ¶
type Affected struct {
Profile releaseidentity.Profile `json:"profile"`
Introduced string `json:"introduced,omitempty"`
Fixed string `json:"fixed"`
Platforms []string `json:"platforms"`
// Empty covers both delivery forms; image-only component advisories must
// not apply to a native installation of the same application release.
Delivery string `json:"delivery,omitempty"`
}
Affected is a half-open SemVer interval within a release trust profile. Empty Introduced means the beginning of that profile; Fixed is exclusive.
type Catalog ¶
type Catalog struct {
Format string `json:"format"`
Sequence uint64 `json:"sequence"`
IssuedAt time.Time `json:"issued_at"`
ExpiresAt time.Time `json:"expires_at"`
Advisories []Advisory `json:"advisories"`
Targets []Target `json:"targets"`
}
func DecodeCatalog ¶
DecodeCatalog is structural validation, not authentication. Production calls it only on a fixed target authenticated by the maintained TUF client.
type Decision ¶
type Decision struct {
Applicable []string `json:"applicable"`
Target *Target `json:"target,omitempty"`
Blocked string `json:"blocked,omitempty"`
// Urgent records that the selected target fixes an urgent applicable advisory.
Urgent bool `json:"urgent,omitempty"`
}
func Select ¶
func Select(c Catalog, installed releaseidentity.Identity, platform string, p Policy, now time.Time) (Decision, error)
Select chooses the newest nonwithdrawn target covering every applicable advisory at the configured severity, or failing that the one fixing the most, because a remaining unfixed advisory must not hold back a critical fix. Artifact and route verification remain mandatory in the driver.
type Engine ¶
type Engine struct {
RequireRuntimeDigest bool
Store *Store
Feed Feed
Driver Driver
Platform string
ImageDelivery bool
Policy Policy
Now func() time.Time
// OperationTimeout is how long a replacement may stay unfinished before a later
// run has the driver roll it back to the source. Zero never rolls back by time.
OperationTimeout time.Duration
}
func (*Engine) Enroll ¶
Enroll is an explicit local operator action. Merely running a checker or changing a configuration flag can never adopt a populated installation.
func (*Engine) Reconcile ¶
Reconcile is the explicit local exit from a state that blocks every later update: abandoning a pinned operation, or accepting a restored installation. confirm must name what is being given up, so it cannot be run by rote, and the installation must be healthy, so it cannot bypass an owner's recovery fence.
type Enrollment ¶
type GateProver ¶
GateProver is implemented by drivers that can show, without the target answering, that the target has not crossed the final gate. Without such proof an unobservable target is never stopped by the deadline.
type Impact ¶
type Impact struct {
Restart bool `json:"restart"`
Features bool `json:"features"`
Schema bool `json:"schema"`
API bool `json:"api"`
Configuration bool `json:"configuration"`
Maintenance bool `json:"maintenance"`
}
Impact describes the reviewed change, independently of advisory severity. Drivers additionally measure schema/maintenance impact from signed routes.
type Observation ¶
type Observation struct {
Platform string `json:"platform"`
Engine releaseidentity.Engine `json:"engine"`
Identity releaseidentity.Identity `json:"identity"`
StagedTarget releaseidentity.Identity `json:"staged_target,omitzero"`
Image string `json:"image"`
RuntimeImageSHA256 releaseidentity.Digest `json:"runtime_image_sha256,omitempty"`
Instance string `json:"instance"`
Generation int64 `json:"generation"`
RestoreEpoch int64 `json:"restore_epoch"`
Incarnation string `json:"incarnation"`
Phase string `json:"phase"`
Maintenance bool `json:"maintenance"`
Ready bool `json:"ready"`
RouteSHA256 releaseidentity.Digest `json:"route_sha256,omitempty"`
RequiresMaintenance bool `json:"requires_maintenance"`
SchemaChanges bool `json:"schema_changes"`
// AbortedBeforeMutation: the target image reports that it stopped before the
// live database was written, and the other fields describe the untouched source.
AbortedBeforeMutation bool `json:"aborted_before_mutation,omitempty"`
}
func (Observation) Healthy ¶
func (o Observation) Healthy() bool
func (Observation) Validate ¶
func (o Observation) Validate() error
type Operation ¶
type Operation struct {
RequireRuntimeDigest bool `json:"require_runtime_digest"`
Target Target `json:"target"`
Source Observation `json:"source"`
RouteSHA256 releaseidentity.Digest `json:"route_sha256"`
StartedAt time.Time `json:"started_at"`
}
type Policy ¶
type Policy struct {
Mode Mode `json:"mode"`
Channel updatecheck.Channel `json:"channel"`
Pin string `json:"pin,omitempty"`
// UpgradeClass is patch, minor, or compatible. Compatible still requires an
// independently authenticated exact route; it does not infer SemVer safety.
UpgradeClass string `json:"upgrade_class"`
AllowMaintenance bool `json:"allow_maintenance"`
MinimumSeverity Severity `json:"minimum_severity"`
// A zero-length window permits any time. Nonzero windows use UTC minutes.
WindowStartMinute int `json:"window_start_minute"`
WindowDurationMinutes int `json:"window_duration_minutes"`
// A verified fix at or above UrgentSeverity need not wait for the window.
// Empty means windows always apply. Pins, upgrade classes, maintenance
// consent, signatures and recovery fences bind regardless of severity.
UrgentSeverity Severity `json:"urgent_severity,omitempty"`
}
func DefaultPolicy ¶
func DefaultPolicy() Policy
type Preparation ¶
type Preparation struct {
Target releaseidentity.Identity
Source Observation
Image string
RouteSHA256 releaseidentity.Digest
Impact Impact
}
Preparation is evidence from a local driver that independently authenticates artifacts and stages every route hop. A feed label is never this evidence.
type Reconciler ¶
type Reconciler interface {
Reconcile(context.Context, Observation) error
}
Reconciler is implemented by drivers holding their own recovery journal.
type Status ¶
type Status struct {
Policy *Policy `json:"policy,omitempty"`
Format string `json:"format"`
Enrollment *Enrollment `json:"enrollment,omitempty"`
Phase string `json:"phase"`
Reason string `json:"reason,omitempty"`
CatalogSequence uint64 `json:"catalog_sequence"`
CatalogSHA256 releaseidentity.Digest `json:"catalog_sha256,omitempty"`
LastAttempt time.Time `json:"last_attempt,omitzero"`
LastVerified time.Time `json:"last_verified,omitzero"`
KnownUntil time.Time `json:"known_until,omitzero"`
Applicable []string `json:"applicable"`
CoverageThrough string `json:"coverage_through,omitempty"`
Coverage []string `json:"coverage"`
CoveredComponents []string `json:"covered_components"`
Selected *Target `json:"selected,omitempty"`
Running *Observation `json:"running,omitempty"`
// RunningWithdrawn: the authenticated catalog of the latest run withdraws the
// running release. The coordinator then refuses to adopt it as its own.
RunningWithdrawn bool `json:"running_withdrawn,omitempty"`
Operation *Operation `json:"operation,omitempty"`
// Action names the exact local command that leaves a state needing an operator.
Action string `json:"action,omitempty"`
// Detail keeps the cause of the latest failure, so status explains it alone.
Detail string `json:"detail,omitempty"`
// Retry bounds repeated failure on one target; a different target resets it.
RetryTarget *releaseidentity.Identity `json:"retry_target,omitempty"`
RetryAttempts int `json:"retry_attempts,omitempty"`
RetryAfter time.Time `json:"retry_after,omitzero"`
// RetryDisruptive counts the failed attempts at RetryTarget that reached the
// workload. A failure before that point costs no availability and only backs off.
RetryDisruptive int `json:"retry_disruptive,omitempty"`
RetryCause string `json:"retry_cause,omitempty"`
}
func (Status) ProtectionGap ¶
ProtectionGap distinguishes a stuck installation from one waiting for an expected local or published schedule.
func (Status) Public ¶
func (s Status) Public() securitystatus.Public
Public is the subset of Status the serving application may show. It leaves out the operation record and every recovery fence. Action is passed through whole because an administrator needs the exact command, and its confirmation value (a manifest digest or a recovery incarnation) is not a credential. Detail is the failure text and can echo arbitrary tool output, so it is scrubbed and bounded.
type Store ¶
type Store struct {
// PublicStatusFile, when set, receives the public subset after every save.
PublicStatusFile string
// contains filtered or unexported fields
}
func NewStoreOnVolume ¶
NewStoreOnVolume is NewStore for a directory inside a mounted volume whose root the platform may leave group-writable (a Kubernetes fsGroup); see localsocket.
func NewStoreOnWorldWritableVolume ¶
NewStoreOnWorldWritableVolume is NewStoreOnVolume for an operator who explicitly accepted a volume root any local user can write; see localsocket.
type Target ¶
type Target struct {
BeforeMutation func() error `json:"-"`
PolicyFile string `json:"-"`
PolicySHA256 releaseidentity.Digest `json:"-"`
// EligibilityUntil is local execution context derived from verified feed
// expiry. It is never accepted from or serialized into advisory metadata.
EligibilityUntil time.Time `json:"-"`
Identity releaseidentity.Identity `json:"identity"`
Platforms []string `json:"platforms"`
Image string `json:"image,omitempty"`
RuntimeImageSHA256 releaseidentity.Digest `json:"runtime_image_sha256,omitempty"`
Fixes []string `json:"fixes"`
CoverageThrough string `json:"coverage_through,omitempty"`
Impact Impact `json:"impact"`
Withdrawn bool `json:"withdrawn"`
AvailableAt time.Time `json:"available_at,omitzero"`
RolloutMinutes int `json:"rollout_minutes,omitempty"`
}