Documentation
¶
Overview ¶
Package extensions stores osquery extension binaries, their assignments to environments and nodes, and the status osctrld reports for them.
Index ¶
- Constants
- Variables
- func ValidName(name string) bool
- func ValidPlatform(platform, arch string) bool
- func ValidSHA256(s string) bool
- type EnvExtension
- type Extension
- type ExtensionChunk
- type ExtensionFile
- type ExtensionView
- type Manager
- func (m *Manager) AssignEnv(envID, extID uint, by string) error
- func (m *Manager) AssignNode(nodeUUID string, envID, extID uint, expiresAt *time.Time, by string) (*NodeExtension, error)
- func (m *Manager) Create(ext Extension) (*Extension, error)
- func (m *Manager) Delete(id uint) error
- func (m *Manager) DeleteFile(extID uint, platform, arch string) error
- func (m *Manager) DeleteNode(nodeUUID string) error
- func (m *Manager) EffectiveSet(envID uint, nodeUUID, platform, arch string, now time.Time) ([]types.OsctrldExtensionEntry, error)
- func (m *Manager) EnvExtensions(envID uint) ([]Extension, error)
- func (m *Manager) FileSize(sha string) (int64, error)
- func (m *Manager) Get(id uint) (*Extension, error)
- func (m *Manager) InEnvSet(envID uint, sha string) (bool, error)
- func (m *Manager) List() ([]ExtensionView, error)
- func (m *Manager) NodeAssignments(nodeUUID string) ([]NodeExtension, error)
- func (m *Manager) NodeStatuses(nodeUUID string) ([]NodeExtensionStatus, error)
- func (m *Manager) PutFile(ctx context.Context, extID uint, platform, arch, filename string, r io.Reader, ...) (*ExtensionFile, error)
- func (m *Manager) RecordStatus(nodeUUID string, envID uint, s []types.OsctrldExtensionStatus, at time.Time) error
- func (m *Manager) StreamFile(ctx context.Context, sha string, w io.Writer) (int64, error)
- func (m *Manager) UnassignEnv(envID, extID uint) error
- func (m *Manager) UnassignNode(nodeUUID string, extID uint) error
- func (m *Manager) Update(id uint, desc, version string, commandExec *bool, by string) (*Extension, error)
- type NodeExtension
- type NodeExtensionStatus
Constants ¶
const ( // MaxFileSize is the largest extension binary accepted. MaxFileSize = 64 << 20 // ChunkSize is the size of each stored chunk (the last one may be shorter). ChunkSize = 1 << 20 )
const ( ResultOK = "ok" ResultRejected = "rejected" ResultRemoved = "removed" ResultKept = "kept" )
Results osctrld reports: ok and rejected for an install or update, removed and kept for a removal that worked or failed.
Variables ¶
var ( ErrInvalid = errors.New("invalid extension input") ErrNotFound = errors.New("extension not found") ErrDuplicate = errors.New("extension name already exists") ErrAssigned = errors.New("extension is assigned") ErrKept = errors.New("extension is still on a host that could not remove it") ErrTooLarge = errors.New("extension file is too large") ErrEmpty = errors.New("extension file is empty") ErrTruncated = errors.New("extension file upload was cut short") ErrCommandExecution = errors.New("command-execution extensions can only be assigned to nodes") ErrNotCommandExecution = errors.New("only command-execution extensions can be assigned to nodes") )
Functions ¶
func ValidPlatform ¶
ValidPlatform reports whether platform and arch are in the allowed set.
func ValidSHA256 ¶
ValidSHA256 reports whether s is a lowercase hex SHA-256.
Types ¶
type EnvExtension ¶
type EnvExtension struct {
gorm.Model
EnvironmentID uint `gorm:"uniqueIndex:idx_ext_env"`
ExtensionID uint `gorm:"uniqueIndex:idx_ext_env"`
CreatedBy string
}
EnvExtension assigns an ordinary extension to an environment.
type Extension ¶
type Extension struct {
gorm.Model
Name string `gorm:"uniqueIndex:idx_ext_name;size:64"`
Description string
Version string `gorm:"size:64"`
CommandExecution bool
CreatedBy string
UpdatedBy string
}
Extension is an osquery extension in the library. All rows in this package are hard-deleted.
type ExtensionChunk ¶
type ExtensionChunk struct {
ID uint
SHA256 string `gorm:"index:idx_ext_chunk_sha;size:64"`
Seq int
Data []byte
}
ExtensionChunk is one ChunkSize piece of a file's content, keyed by the whole file's SHA-256 so identical files share chunks. Data maps to longblob (MySQL), bytea (Postgres) and blob (SQLite); do not add a size tag below 64 KiB.
type ExtensionFile ¶
type ExtensionFile struct {
gorm.Model
ExtensionID uint `gorm:"uniqueIndex:idx_ext_file_platform"`
Platform string `gorm:"uniqueIndex:idx_ext_file_platform;size:16"`
Arch string `gorm:"uniqueIndex:idx_ext_file_platform;size:16"`
Size int64
SHA256 string `gorm:"index:idx_ext_file_sha;size:64"`
Filename string
UpdatedBy string
}
ExtensionFile is the binary of an extension for one platform and arch.
type ExtensionView ¶
type ExtensionView struct {
Extension
Files []ExtensionFile
EnvAssignments int64
NodeAssignments int64
}
ExtensionView is a library entry with its files and assignment counts.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is the source of truth for extensions, shared by osctrl-api and osctrl-tls through SQL.
func NewManager ¶
NewManager migrates the extension tables and returns a manager.
func (*Manager) AssignNode ¶
func (m *Manager) AssignNode(nodeUUID string, envID, extID uint, expiresAt *time.Time, by string) (*NodeExtension, error)
AssignNode assigns a command-execution extension to one node, creating or updating its environment and expiry.
func (*Manager) Delete ¶
Delete removes an unassigned extension, its files, the statuses reported for its name and the chunks no other file uses. A command-execution extension a host reported as kept is refused with ErrKept.
func (*Manager) DeleteFile ¶
DeleteFile removes the binary for platform and arch and its chunks unless another file uses them.
func (*Manager) DeleteNode ¶
DeleteNode removes the node's assignments and statuses.
func (*Manager) EffectiveSet ¶
func (m *Manager) EffectiveSet(envID uint, nodeUUID, platform, arch string, now time.Time) ([]types.OsctrldExtensionEntry, error)
EffectiveSet returns what a node should run: the environment's extensions plus the node's unexpired assignments in that environment, each with its file for platform and arch (darwin falls back to universal). Extensions without a matching file are skipped. URL is left for the caller to fill.
func (*Manager) EnvExtensions ¶
EnvExtensions returns the extensions assigned to an environment, by name.
func (*Manager) InEnvSet ¶
InEnvSet reports whether sha is a file of an extension assigned to the environment or, unexpired, to any node in it. It gates downloads.
func (*Manager) List ¶
func (m *Manager) List() ([]ExtensionView, error)
List returns the library sorted by name, with files and assignment counts.
func (*Manager) NodeAssignments ¶
func (m *Manager) NodeAssignments(nodeUUID string) ([]NodeExtension, error)
NodeAssignments returns the node's assignments, expired ones included.
func (*Manager) NodeStatuses ¶
func (m *Manager) NodeStatuses(nodeUUID string) ([]NodeExtensionStatus, error)
NodeStatuses returns the node's last reported statuses, by name.
func (*Manager) PutFile ¶
func (m *Manager) PutFile(ctx context.Context, extID uint, platform, arch, filename string, r io.Reader, by string) (*ExtensionFile, error)
PutFile stores the extension binary for platform and arch from r, replacing any previous one. The content is hashed and written chunk by chunk inside a transaction, so an oversize or failed upload stores nothing.
func (*Manager) RecordStatus ¶
func (m *Manager) RecordStatus(nodeUUID string, envID uint, s []types.OsctrldExtensionStatus, at time.Time) error
RecordStatus stores what osctrld reported, one row per node and extension name. Entries with an invalid name, SHA-256 or result, or naming an extension not in the library, are dropped; errors are capped at 1 KiB.
func (*Manager) StreamFile ¶
StreamFile writes the content with this SHA-256 to w one chunk at a time, so at most one chunk is in memory and no connection is held while writing.
func (*Manager) UnassignEnv ¶
UnassignEnv removes an extension from an environment, or returns ErrNotFound when it was not assigned.
func (*Manager) UnassignNode ¶
UnassignNode removes a node assignment and the node's status for that extension, so a later assignment never shows a stale status; a kept status is evidence the extension is still there and stays. It returns ErrNotFound when there was no assignment.
func (*Manager) Update ¶
func (m *Manager) Update(id uint, desc, version string, commandExec *bool, by string) (*Extension, error)
Update changes the description, version and, while the extension is not assigned anywhere, whether it is a command-execution extension. Switching command execution off is refused with ErrKept while a host reports it kept.
type NodeExtension ¶
type NodeExtension struct {
gorm.Model
NodeUUID string `gorm:"uniqueIndex:idx_ext_node;size:255"`
ExtensionID uint `gorm:"uniqueIndex:idx_ext_node"`
EnvironmentID uint `gorm:"index:idx_ext_node_env"`
ExpiresAt *time.Time
CreatedBy string
}
NodeExtension assigns a command-execution extension to one node.
type NodeExtensionStatus ¶
type NodeExtensionStatus struct {
gorm.Model
NodeUUID string `gorm:"uniqueIndex:idx_ext_status;size:255"`
Name string `gorm:"uniqueIndex:idx_ext_status;size:64"`
EnvironmentID uint
SHA256 string
Result string
Error string
At *time.Time
ReportedAt time.Time
}
NodeExtensionStatus is the last status osctrld reported for an extension.
Source Files