Documentation
¶
Overview ¶
Package nodeconfig validates and applies per-node osquery configuration overrides on top of an environment's configuration.
Index ¶
- Constants
- func FlagOptionConflicts(override string, configs ...string) []string
- func Merge(envConfig, override string) (string, error)
- func MergeFlags(envFlags, override string) (string, error)
- func ProtectedFlag(name string) bool
- func ProtectedOption(name string) bool
- func ValidEventID(id string) bool
- func ValidStage(kind, stage string) bool
- func ValidUpgrade(u types.OsctrldUpgrade) bool
- func ValidUpgradeReason(r string) bool
- func Validate(override string) error
- func ValidateFlagsOverride(override string) error
- type FlagsManager
- func (m *FlagsManager) Active(ctx context.Context, nodeUUID string, envID uint, now time.Time) (*FlagsOverride, error)
- func (m *FlagsManager) CountDown(now time.Time) (map[uint]int, error)
- func (m *FlagsManager) Delete(ctx context.Context, nodeUUID string) error
- func (m *FlagsManager) DeleteStatus(nodeUUID string) error
- func (m *FlagsManager) Get(nodeUUID string) (*FlagsOverride, error)
- func (m *FlagsManager) RecordFetch(nodeUUID string, envID uint, at time.Time, apply *types.OsctrldApplyStatus) error
- func (m *FlagsManager) RecordReport(nodeUUID string, envID uint, r types.OsctrldStatusRequest, at time.Time) ([]string, error)
- func (m *FlagsManager) Set(ctx context.Context, o FlagsOverride) (*FlagsOverride, error)
- func (m *FlagsManager) Status(nodeUUID string) (*OsctrldStatus, error)
- type FlagsOverride
- type Manager
- func (m *Manager) Active(ctx context.Context, nodeUUID string, envID uint, now time.Time) (*Override, error)
- func (m *Manager) Delete(ctx context.Context, nodeUUID string) error
- func (m *Manager) Get(nodeUUID string) (*Override, error)
- func (m *Manager) Set(ctx context.Context, o Override) (*Override, error)
- type OsctrldStatus
- type Override
Constants ¶
const ReportFreshness = 15 * time.Minute
ReportFreshness is how long an osctrld health report counts as current.
Variables ¶
This section is empty.
Functions ¶
func FlagOptionConflicts ¶
FlagOptionConflicts returns, sorted, the flag names of a flags override that are also keys of "options" in any of the given JSON configurations. Flags and options both set osquery options, so the same one in both is ambiguous. Configurations that are not valid JSON are ignored.
func Merge ¶
Merge deep-merges override on top of envConfig and returns the indented JSON. Objects merge key by key; any other override value (including arrays) replaces the environment's. An empty envConfig is treated as an empty object.
func MergeFlags ¶
MergeFlags applies a flags override to an environment flagfile. Each override flag replaces every environment line with the same name in place, keeping that line's dash prefix; flags the environment lacks are appended in override order. The output is deterministic for the same inputs.
func ProtectedFlag ¶
ProtectedFlag reports whether an osquery flag controls the connection to osctrl and so cannot be set by a node flags override.
func ProtectedOption ¶
ProtectedOption reports whether an osquery option controls the connection to osctrl and so cannot be set by a node override.
func ValidEventID ¶
ValidEventID reports whether id has the rollback event id format.
func ValidStage ¶
ValidStage reports whether stage is a known rollback stage for kind ("flags" or "extensions").
func ValidUpgrade ¶
func ValidUpgrade(u types.OsctrldUpgrade) bool
ValidUpgrade reports whether u is a well-formed osquery upgrade result.
func ValidUpgradeReason ¶
ValidUpgradeReason reports whether r is a known upgrade reason.
func Validate ¶
Validate checks that an override is a JSON object that is safe to merge: known sections are objects, no value is null and no protected option is set.
func ValidateFlagsOverride ¶
ValidateFlagsOverride checks that an override is a list of osquery flags, one per line, with no protected flag, no flag repeated and at least one flag. Blank lines and # comments are ignored.
Types ¶
type FlagsManager ¶
type FlagsManager struct {
// contains filtered or unexported fields
}
FlagsManager stores per-node flags overrides and osctrld status in SQL, with the same cache protocol as Manager in front of the overrides.
func NewFlagsManager ¶
NewFlagsManager migrates the tables. client may be nil, which disables the cache.
func (*FlagsManager) Active ¶
func (m *FlagsManager) Active(ctx context.Context, nodeUUID string, envID uint, now time.Time) (*FlagsOverride, error)
Active returns the node's flags override if it exists, belongs to envID and has not expired. It does not validate the stored flags; callers re-validate.
func (*FlagsManager) CountDown ¶
CountDown returns, per environment, the nodes whose fresh report says osqueryd is not running.
func (*FlagsManager) Delete ¶
func (m *FlagsManager) Delete(ctx context.Context, nodeUUID string) error
Delete hard-deletes the node's flags override, then caches its absence.
func (*FlagsManager) DeleteStatus ¶
func (m *FlagsManager) DeleteStatus(nodeUUID string) error
DeleteStatus hard-deletes the node's osctrld status.
func (*FlagsManager) Get ¶
func (m *FlagsManager) Get(nodeUUID string) (*FlagsOverride, error)
Get returns the node's flags override straight from SQL, or nil if there is none.
func (*FlagsManager) RecordFetch ¶
func (m *FlagsManager) RecordFetch(nodeUUID string, envID uint, at time.Time, apply *types.OsctrldApplyStatus) error
RecordFetch upserts the node's osctrld status. A nil apply keeps the previously reported apply fields.
func (*FlagsManager) RecordReport ¶
func (m *FlagsManager) RecordReport(nodeUUID string, envID uint, r types.OsctrldStatusRequest, at time.Time) ([]string, error)
RecordReport stores an osctrld health report. A kind (flags/extensions) with an invalid stage or event id is dropped, keeping its stored values; so is an invalid upgrade result. A rejected upgrade reports the kind "upgrade". It returns the kinds whose non-none event id was not seen before; the compare-and-set on the event id column counts an event once across replicas.
func (*FlagsManager) Set ¶
func (m *FlagsManager) Set(ctx context.Context, o FlagsOverride) (*FlagsOverride, error)
Set validates and upserts the flags override for o.NodeUUID, then caches it.
func (*FlagsManager) Status ¶
func (m *FlagsManager) Status(nodeUUID string) (*OsctrldStatus, error)
Status returns the node's osctrld status, or nil if it never fetched flags.
type FlagsOverride ¶
type FlagsOverride struct {
gorm.Model
NodeUUID string `gorm:"uniqueIndex:idx_node_flags_overrides_node_uuid;size:255"`
EnvironmentID uint `gorm:"index:idx_node_flags_overrides_env"`
Flags string
ExpiresAt *time.Time
UpdatedBy string
}
FlagsOverride is a per-node osquery flags override: flagfile lines merged over the environment flags osctrld fetches.
func (*FlagsOverride) Expired ¶
func (o *FlagsOverride) Expired(now time.Time) bool
Expired reports whether the override has an expiry that is not after now.
func (FlagsOverride) TableName ¶
func (FlagsOverride) TableName() string
TableName keeps the table name stable.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager stores per-node configuration overrides in SQL, with a Redis cache in front of the read path osctrl-tls takes on every osquery config request.
SQL is the source of truth. Set and Delete write the full state into the cache after the SQL commit (never delete the key); Active only refills a cache miss with setNX, so it can never overwrite a newer write.
func NewManager ¶
NewManager migrates the table. client may be nil, which disables the cache.
func (*Manager) Active ¶
func (m *Manager) Active(ctx context.Context, nodeUUID string, envID uint, now time.Time) (*Override, error)
Active returns the node's override if it exists, belongs to envID and has not expired. It does not validate the stored config; callers re-validate.
type OsctrldStatus ¶
type OsctrldStatus struct {
gorm.Model
NodeUUID string `gorm:"uniqueIndex:idx_osctrld_status_node_uuid;size:255"`
EnvironmentID uint
LastFetchedAt time.Time
ApplyResult string
ApplySHA256 string
ApplyError string
ApplyAt *time.Time
// Health report fields, written by RecordReport only.
OsqueryRunning *bool
DownSince *time.Time
ReportedAt *time.Time `gorm:"index"`
FlagsStage string `gorm:"default:''"`
ExtensionsStage string `gorm:"default:''"`
FlagsEventID string `gorm:"default:''"`
ExtensionsEventID string `gorm:"default:''"`
// Osquery upgrade result, written by RecordReport only.
UpgradeResult string `gorm:"default:''"`
UpgradeVersion string `gorm:"default:''"`
UpgradeReason string `gorm:"default:''"`
UpgradeRequestID string `gorm:"default:''"`
UpgradeEventID string `gorm:"default:''"`
UpgradeReportedAt *time.Time
// UpgradeEventAt is the server time UpgradeEventID was first recorded.
UpgradeEventAt *time.Time
}
OsctrldStatus is the last flags fetch by a node's osctrld and the result of its last flags apply, as reported by osctrld.
func (OsctrldStatus) TableName ¶
func (OsctrldStatus) TableName() string
TableName keeps the table name stable.
type Override ¶
type Override struct {
gorm.Model
NodeUUID string `gorm:"uniqueIndex;size:255"`
EnvironmentID uint `gorm:"index"`
Config string
ExpiresAt *time.Time
UpdatedBy string
}
Override is a per-node osquery configuration override.
Source Files