Help us shape the future of Go! Take the 2026 Go Developer Survey

osqueryversions

package
v0.6.1 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package osqueryversions stores the osquery versions osctrl can roll out and the SHA-256 of each official package.

Index

Constants

View Source
const (
	ReasonNoTarget             = "no_target"
	ReasonAheadOfTarget        = "ahead_of_target"
	ReasonNoDigestForTarget    = "no_digest_for_target"
	ReasonNoDigestForInstalled = "no_digest_for_installed"
	ReasonUnsupportedPlatform  = "unsupported_platform"
	ReasonRolloutPending       = "rollout_pending"
	ReasonRolloutPaused        = "rollout_paused"
)

Reasons Resolve gives for not upgrading; "" means upgrade.

View Source
const (
	RolloutRunning   = "running"
	RolloutPaused    = "paused"
	RolloutCompleted = "completed"
	RolloutAborted   = "aborted"
)

Rollout states. "completed" is only ever an effective state of a running row.

View Source
const RolloutStageWait = 2 * time.Hour

RolloutStageWait is how long each stage stays open before the next one.

Variables

View Source
var ErrInUse = errors.New("osquery version is in use by a target or pin")

ErrInUse is returned when a change would break a target or pin referencing a version.

View Source
var ErrInvalid = errors.New("invalid osquery version input")

ErrInvalid is returned for invalid versions or entries.

View Source
var ErrNotFound = errors.New("osquery version not found")

ErrNotFound is returned when a version has no library entries.

View Source
var ErrRolloutState = errors.New("rollout is not in a state that allows this")

ErrRolloutState is returned when the rollout state does not allow a change.

View Source
var RolloutStages = [4]uint32{100, 1000, 5000, 10000}

RolloutStages are the stage shares in basis points (1%, 10%, 50%, 100%).

Functions

func Bucket

func Bucket(envID uint, version, nodeUUID string) uint32

Bucket maps a node to a stable position in [0, 10000) for a rollout.

func CleanHost

func CleanHost(s string) string

CleanHost makes a host-reported name safe to store and log: it drops control and other non-printable runes (newlines, tabs, ...) and cuts to 255 runes.

func Compare

func Compare(a, b string) (int, error)

Compare returns -1, 0 or 1 comparing versions part by part; a missing part counts as 0. It errors when either version is invalid.

func ComputeThresholds

func ComputeThresholds(envID uint, version string, uuids []string) [4]uint32

ComputeThresholds returns the stage thresholds for the given hosts: a host is eligible at stage i iff Bucket < thresholds[i]. Stage 1 has at least one host.

func HostName

func HostName(names ...string) string

HostName returns the first of the names that is non-empty once cleaned.

func NodePlatformSupported

func NodePlatformSupported(platform string) bool

NodePlatformSupported is the one rule for whether a stored node platform is part of upgrades, shared by thresholds, progress, the behind gauge and the node API. Windows is supported; an empty or unknown platform keeps counting (it is unsupported only if listed above), case-insensitive.

func SupportedNodePlatformSQL

func SupportedNodePlatformSQL(column string) string

SupportedNodePlatformSQL is NodePlatformSupported as a WHERE fragment on the given platform column, for the raw queries of packages that cannot be imported here.

func ValidEntry

func ValidEntry(platform, arch, format, sha256 string) error

ValidEntry checks that the platform, arch and format are a supported combination and that sha256 is 64 lowercase hex characters.

func ValidVersion

func ValidVersion(v string) bool

ValidVersion reports whether v is a 2 to 4 part numeric version with parts of at most 6 digits (so at most 27 characters, within the size-32 column).

Types

type DigestEntry

type DigestEntry struct {
	ID        uint      `gorm:"primaryKey" json:"-"`
	Version   string    `gorm:"uniqueIndex:idx_osq_digest;size:32" json:"version"`
	Platform  string    `gorm:"uniqueIndex:idx_osq_digest;size:16" json:"platform"`
	Arch      string    `gorm:"uniqueIndex:idx_osq_digest;size:16" json:"arch"`
	Format    string    `gorm:"uniqueIndex:idx_osq_digest;size:16" json:"format"`
	SHA256    string    `gorm:"size:64" json:"sha256"`
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
}

DigestEntry is the SHA-256 of one official osquery package (a version, for one platform, arch and format). It is the GORM model and the exchange type.

func (DigestEntry) TableName

func (DigestEntry) TableName() string

TableName keeps the table name stable independent of the struct name.

type EnvTarget

type EnvTarget struct {
	gorm.Model
	EnvironmentID uint   `gorm:"uniqueIndex:idx_osq_env_target_env"`
	Version       string `gorm:"size:32"`
	RequestID     string `gorm:"size:32"`
	UpdatedBy     string
}

EnvTarget is the osquery version an environment is rolled out to. RequestID changes on every set so osctrld can tell a re-set from a repeat.

func (EnvTarget) TableName

func (EnvTarget) TableName() string

TableName keeps the table name stable.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager is the source of truth for the osquery version library, shared by osctrl-api and osctrl-tls through SQL.

func NewManager

func NewManager(db *gorm.DB) (*Manager, error)

NewManager migrates the library tables and returns a manager.

func (*Manager) AbortRollout

func (m *Manager) AbortRollout(envID uint, by string, now time.Time) (*Rollout, error)

AbortRollout aborts a running or paused rollout and clears the environment target in the same transaction. Pins are kept.

func (*Manager) ClearEnvTarget

func (m *Manager) ClearEnvTarget(envID uint) (bool, error)

ClearEnvTarget removes the environment's target and reports whether one was set.

func (*Manager) CountBehind

func (m *Manager) CountBehind(now time.Time, fresh time.Duration) (map[uint]int, error)

CountBehind returns, per environment id, the nodes with an osctrld report newer than fresh whose stored osquery version is lower than their effective target: an unexpired pin of the same environment, else the environment's target. Nodes without a target, with an unparseable version or on an unsupported platform (see NodePlatformSupported) are not counted. The table names are those of the nodes and osctrld status models, which this package must not import.

func (*Manager) CountPaused

func (m *Manager) CountPaused() (map[uint]int, error)

CountPaused returns environment id -> 1 for every environment whose latest rollout row (highest id) is stored as paused. One bounded query: at most maxRolloutRows rows are kept per environment.

func (*Manager) DeleteNodeRecords

func (m *Manager) DeleteNodeRecords(nodeUUID string) error

DeleteNodeRecords removes everything stored for a node; used by node deletion.

func (*Manager) DeletePin

func (m *Manager) DeletePin(nodeUUID string) (bool, error)

DeletePin removes the node's pin and reports whether one was set.

func (*Manager) DeleteVersion

func (m *Manager) DeleteVersion(version string) error

DeleteVersion removes every digest of a version. It returns ErrInUse when a target or an unexpired pin references it and ErrNotFound when it has no rows.

func (*Manager) GetEntries

func (m *Manager) GetEntries(version string) ([]DigestEntry, error)

GetEntries returns the digests of a version.

func (*Manager) GetEnvTarget

func (m *Manager) GetEnvTarget(envID uint) (*EnvTarget, error)

GetEnvTarget returns the environment's target, or nil when none is set.

func (*Manager) GetPin

func (m *Manager) GetPin(nodeUUID string) (*NodePin, error)

GetPin returns the node's pin (expired or not), or nil when none is set.

func (*Manager) GetRollout

func (m *Manager) GetRollout(envID uint) (*Rollout, error)

GetRollout returns the environment's latest rollout, or nil when none exists.

func (*Manager) ListVersions

func (m *Manager) ListVersions() ([]VersionView, error)

ListVersions returns every version, newest first, with its digests.

func (*Manager) PauseRollout

func (m *Manager) PauseRollout(envID uint, requestID, host, reason string, eventAt, now time.Time) (bool, error)

PauseRollout pauses the running rollout of request requestID, freezing its effective stage. eventAt is the server time the rollback was first recorded: a rollback that happened before the rollout was last resumed never pauses it (the host keeps re-reporting it). It returns false when no running rollout matches or the rollback is older than the last resume.

func (*Manager) Progress

func (m *Manager) Progress(r Rollout, now time.Time) (RolloutProgress, error)

Progress counts the environment's hosts against the rollout at now. Hosts on an unsupported platform (NodePlatformSupported, the same rule as the thresholds' host set) are left out entirely: they are never eligible or waiting, nor listed when rolled back. Windows hosts count. The table names are those of the nodes and osctrld status models, which this package must not import.

func (*Manager) PutEntries

func (m *Manager) PutEntries(version string, entries []DigestEntry, by string) error

PutEntries validates all entries and then upserts them, per (version, platform, arch, format), in one transaction.

func (*Manager) Resolve

func (m *Manager) Resolve(in ResolveInput, now time.Time) (Resolution, error)

Resolve decides what a node should do: the unexpired pin wins over the environment target. Versions are matched by exact string, as stored.

func (*Manager) ResumeRollout

func (m *Manager) ResumeRollout(envID uint, by string, now time.Time) (*Rollout, error)

ResumeRollout resumes a paused rollout at its frozen stage and restarts that stage's wait.

func (*Manager) SetEnvTarget

func (m *Manager) SetEnvTarget(envID uint, version, by string) (*EnvTarget, error)

SetEnvTarget sets the environment's target to a library version with a new request id. It does NOT start or replace a rollout: API code must use SetEnvTargetRollout.

func (*Manager) SetEnvTargetRollout

func (m *Manager) SetEnvTargetRollout(envID uint, version, by string, uuids []string, now time.Time) (*EnvTarget, *Rollout, error)

SetEnvTargetRollout sets the environment target like SetEnvTarget and starts a rollout for it, aborting any active one, in one transaction.

func (*Manager) SetPin

func (m *Manager) SetPin(nodeUUID string, envID uint, version string, expiresAt *time.Time, by string) (*NodePin, error)

SetPin pins a node to a library version. expiresAt, when set, must be in the future. Changing only the expiry of a pin of the same environment keeps its request id, so osctrld does not retry a version the host rejected; any other call, including an identical re-save (how an operator retries), gets a new request id.

func (*Manager) VersionNames

func (m *Manager) VersionNames() ([]string, error)

VersionNames returns the versions that have library entries, oldest first, without digests or in-use queries.

type NodePin

type NodePin struct {
	gorm.Model
	NodeUUID      string `gorm:"uniqueIndex:idx_osq_node_pin_uuid;size:255"`
	EnvironmentID uint   `gorm:"index:idx_osq_node_pin_env"`
	Version       string `gorm:"size:32"`
	RequestID     string `gorm:"size:32"`
	UpdatedBy     string
	ExpiresAt     *time.Time
}

NodePin overrides the environment target for one node, optionally until ExpiresAt.

func (NodePin) Expired

func (p NodePin) Expired(now time.Time) bool

Expired reports whether the pin has an expiry that is not after now.

func (NodePin) TableName

func (NodePin) TableName() string

TableName keeps the table name stable.

type Ref

type Ref struct {
	Version string `json:"version"`
	SHA256  string `json:"sha256"`
}

Ref is a version with the SHA-256 of its package.

type Resolution

type Resolution struct {
	Reason, Source, RequestID string
	Target, Previous          *Ref
}

Resolution is the answer for one node. Target and Previous are set only when Reason is "".

type ResolveInput

type ResolveInput struct {
	EnvironmentID                                      uint
	NodeUUID, Platform, Arch, Format, InstalledVersion string
}

ResolveInput is what a node reports plus its identity.

type RolledBackHost

type RolledBackHost struct {
	Host, Reason string
	At           time.Time
}

RolledBackHost is a host that rejected the rollout's version.

type Rollout

type Rollout struct {
	gorm.Model
	EnvironmentID uint   `gorm:"uniqueIndex:idx_osq_rollout_env_req"`
	RequestID     string `gorm:"uniqueIndex:idx_osq_rollout_env_req;size:32"`
	Version       string `gorm:"size:32"`
	State         string `gorm:"size:16"`
	Stage         int
	StageOpenedAt time.Time
	// Thresholds is the JSON of the [4]uint32 bucket thresholds.
	Thresholds   string `gorm:"size:96"`
	CreatedBy    string
	PausedHost   string
	PausedReason string
	PausedAt     *time.Time
	ResumedBy    string
	ResumedAt    *time.Time
	AbortedBy    string
	AbortedAt    *time.Time
}

Rollout is the staged rollout of an environment target. The effective stage is a pure function of the row and the clock, so no background job exists.

func (Rollout) EffectiveStage

func (r Rollout) EffectiveStage(now time.Time) int

EffectiveStage is the 0-based stage open at now.

func (Rollout) EffectiveState

func (r Rollout) EffectiveState(now time.Time) string

EffectiveState is the stored state, or completed once a running rollout reached the last stage.

func (Rollout) Eligible

func (r Rollout) Eligible(bucket uint32, now time.Time) bool

Eligible reports whether a host with this bucket may upgrade at now.

func (Rollout) NextStageAt

func (r Rollout) NextStageAt(now time.Time) *time.Time

NextStageAt is when the next stage opens, or nil unless running and not at the last stage.

func (Rollout) NodeStage

func (r Rollout) NodeStage(bucket uint32) int

NodeStage is the 0-based stage that first includes a host with this bucket, or -1 when the thresholds are invalid.

func (Rollout) TableName

func (Rollout) TableName() string

TableName keeps the table name stable.

type RolloutCounts

type RolloutCounts struct{ Eligible, Upgraded, Waiting, RolledBack int }

RolloutCounts are the host counts of a rollout.

type RolloutProgress

type RolloutProgress struct {
	Rollout         Rollout
	State           string
	Stage           int
	NextStageAt     *time.Time
	Counts          RolloutCounts
	RolledBackHosts []RolledBackHost
}

RolloutProgress is a rollout with its effective state and host counts.

type VersionView

type VersionView struct {
	Version string        `json:"version"`
	Entries []DigestEntry `json:"entries"`
	// InUse is set when a target or an unexpired pin references the version.
	InUse bool `json:"in_use"`
}

VersionView is a library version with its digests.

Jump to

Keyboard shortcuts

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