securitymaintenance

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MPL-2.0 Imports: 25 Imported by: 0

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

View Source
const CatalogFormat = "hikyo.security-catalog/v1"
View Source
const MaxCatalogBytes = 4 << 20
View Source
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.

View Source
const MaxRolloutMinutes = 10080
View Source
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.

View Source
const StatusFormat = securitystatus.Format

Variables

View Source
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.

View Source
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.

View Source
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.

View Source
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".

View Source
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.

View Source
var ErrStateUnavailable = errors.New("maintenance state is unavailable; preserve existing recovery evidence")

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 Advisory

type Advisory struct {
	ID         string     `json:"id"`
	Summary    string     `json:"summary"`
	Severity   Severity   `json:"severity"`
	Components []string   `json:"components"`
	Affected   []Affected `json:"affected"`
	Withdrawn  bool       `json:"withdrawn"`
}

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

func DecodeCatalog(raw []byte, now time.Time) (Catalog, error)

DecodeCatalog is structural validation, not authentication. Production calls it only on a fixed target authenticated by the maintained TUF client.

func (Catalog) FixesFor

func (c Catalog) FixesFor(target Target) []string

FixesFor lists every active advisory within the target's profile, delivery and platforms that the target is not affected by, so an authored target cannot leave out a fix that it actually contains, nor claim one for another artifact.

func (Catalog) Validate

func (c Catalog) Validate(now time.Time) error

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 Driver

type Driver interface {
	Observe(context.Context) (Observation, error)
	Prepare(context.Context, Target) (Preparation, error)
	Apply(context.Context, Target) error
}

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

func (e *Engine) Enroll(ctx context.Context) (Status, error)

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

func (e *Engine) Reconcile(ctx context.Context, confirm string) (Status, error)

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.

func (*Engine) RunOnce

func (e *Engine) RunOnce(ctx context.Context, apply bool) (Status, error)

RunOnce performs a bounded check. apply=false never stages artifacts or changes a workload. apply=true still requires prior explicit enrollment and eligible local policy. Failures never stop an otherwise admitted service.

type Enrollment

type Enrollment struct {
	Instance     string    `json:"instance"`
	Incarnation  string    `json:"incarnation"`
	RestoreEpoch int64     `json:"restore_epoch"`
	ConsentedAt  time.Time `json:"consented_at"`
}

type Feed

type Feed interface {
	Refresh(context.Context) (securityfeed.Document, error)
}

type GateProver

type GateProver interface {
	NoFinalGate(ctx context.Context, operation Operation) (bool, error)
}

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 Mode

type Mode string
const (
	Automatic Mode = "automatic"
	Manual    Mode = "manual"
	Offline   Mode = "offline"
)

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

func (Policy) Validate

func (p Policy) Validate() error

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 Severity

type Severity string
const (
	Low      Severity = "low"
	Moderate Severity = "moderate"
	High     Severity = "high"
	Critical Severity = "critical"
)

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

func (s Status) ProtectionGap() bool

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 NewStore

func NewStore(directory string) (*Store, error)

func NewStoreOnVolume

func NewStoreOnVolume(directory, volume string) (*Store, error)

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

func NewStoreOnWorldWritableVolume(directory, volume string) (*Store, error)

NewStoreOnWorldWritableVolume is NewStoreOnVolume for an operator who explicitly accepted a volume root any local user can write; see localsocket.

func (*Store) Load

func (s *Store) Load() (result Status, returnErr error)

func (*Store) Save

func (s *Store) Save(state Status) (returnErr error)

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"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL