osquery

Documentation

Index

• Constants
• func ConfigFromDB(db *bbolt.DB) (string, error)
• func IdentifierFromDB(db *bbolt.DB) (string, error)
• func NodeKeyFromDB(db *bbolt.DB) (string, error)
• type Decorators
• type DiffResults
• type Extension
  • func NewExtension(client service.KolideService, db *bbolt.DB, opts ExtensionOpts) (*Extension, error)
  • func (e *Extension) Enroll(ctx context.Context) (string, bool, error)
  • func (e *Extension) GenerateConfigs(ctx context.Context) (map[string]string, error)
  • func (e *Extension) GetQueries(ctx context.Context) (*distributed.GetQueriesResult, error)
  • func (e *Extension) LogString(ctx context.Context, typ logger.LogType, logText string) error
  • func (e *Extension) RequireReenroll(ctx context.Context)
  • func (e *Extension) SetQuerier(client Querier)
  • func (e *Extension) Shutdown()
  • func (e *Extension) Start()
  • func (e *Extension) WriteResults(ctx context.Context, results []distributed.Result) error
• type ExtensionOpts
• type OsqueryConfig
• type OsqueryDistributedQueryResults
• type OsqueryPlatform
  • func DetectPlatform() (OsqueryPlatform, error)
• type OsqueryResultLog
• type OsqueryStatusLog
• type PackContent
• type Packs
• type Querier
• type Queries
• type QueryContent
• type Rows

Constants

const (

	// the bucket which we push values into from server-backed tables, like kolide_target_membership
	ServerProvidedDataBucket = "server_provided_data"
)

Functions

func ConfigFromDB

func ConfigFromDB(db *bbolt.DB) (string, error)

ConfigFromDB returns the device config from a local bolt DB

func IdentifierFromDB

func IdentifierFromDB(db *bbolt.DB) (string, error)

IdentifierFromDB returns the built-in launcher identifier from the config bucket. The function is exported to allow for building the kolide_launcher_identifier table.

func NodeKeyFromDB

func NodeKeyFromDB(db *bbolt.DB) (string, error)

NodeKeyFromDB returns the device node key from a local bolt DB

Types

type Decorators

type Decorators struct {
	Load     []string            `json:"load,omitempty"`
	Always   []string            `json:"always,omitempty"`
	Interval map[string][]string `json:"interval,omitempty"`
}

Decorators is the format of the decorator configuration in an osquery config

type DiffResults

type DiffResults struct {
	Added   Rows `json:"added"`
	Removed Rows `json:"removed"`
}

DiffResults is the format of osquery log results when --log_result_event is set to false

type Extension

type Extension struct {
	NodeKey string
	Opts    ExtensionOpts
	// contains filtered or unexported fields
}

Extension is the implementation of the osquery extension methods. It handles both the communication with the osquery daemon and the Kolide server.

func NewExtension

func NewExtension(client service.KolideService, db *bbolt.DB, opts ExtensionOpts) (*Extension, error)

NewExtension creates a new Extension from the provided service.KolideService implementation. The background routines should be started by calling Start().

func (*Extension) Enroll

func (e *Extension) Enroll(ctx context.Context) (string, bool, error)

Enroll will attempt to enroll the host using the provided enroll secret for identification. If the host is already enrolled, the existing node key will be returned. To force re-enrollment, use RequireReenroll.

func (*Extension) GenerateConfigs

func (e *Extension) GenerateConfigs(ctx context.Context) (map[string]string, error)

GenerateConfigs will request the osquery configuration from the server. If retrieving the configuration from the server fails, the locally stored configuration will be returned. If that fails, this method will return an error.

func (*Extension) GetQueries

func (e *Extension) GetQueries(ctx context.Context) (*distributed.GetQueriesResult, error)

GetQueries will request the distributed queries to execute from the server.

func (*Extension) LogString

func (e *Extension) LogString(ctx context.Context, typ logger.LogType, logText string) error

LogString will buffer logs from osquery into the local BoltDB store. No immediate action is taken to push the logs to the server (that is handled by the log publishing thread).

func (*Extension) RequireReenroll

func (e *Extension) RequireReenroll(ctx context.Context)

RequireReenroll clears the existing node key information, ensuring that the next call to Enroll will cause the enrollment process to take place.

func (*Extension) SetQuerier

func (e *Extension) SetQuerier(client Querier)

SetQuerier sets an osquery client on the extension, allowing the extension to query the running osqueryd instance.

func (*Extension) Shutdown

func (e *Extension) Shutdown()

Shutdown should be called to cleanup the resources and goroutines associated with this extension.

func (*Extension) Start

func (e *Extension) Start()

Start begins the goroutines responsible for background processing (currently just the log buffer flushing routine). It should be shut down by calling the Shutdown() method.

func (*Extension) WriteResults

func (e *Extension) WriteResults(ctx context.Context, results []distributed.Result) error

WriteResults will publish results of the executed distributed queries back to the server.

type ExtensionOpts

type ExtensionOpts struct {
	// EnrollSecret is the (mandatory) enroll secret used for
	// enrolling with the server.
	EnrollSecret string
	// MaxBytesPerBatch is the maximum number of bytes that should be sent in
	// one batch logging request. Any log larger than this will be dropped.
	MaxBytesPerBatch int
	// LoggingInterval is the interval at which logs should be flushed to
	// the server.
	LoggingInterval time.Duration
	// Clock is the clock that should be used for time based operations. By
	// default it will be a normal realtime clock, but a mock clock can be
	// passed with clock.NewMockClock() for testing purposes.
	Clock clock.Clock
	// Logger is the logger that the extension should use. This is for
	// logging about the launcher, and not for logging osquery results.
	Logger log.Logger
	// MaxBufferedLogs is the maximum number of logs to buffer before
	// purging oldest logs (applies per log type).
	MaxBufferedLogs int
	// RunDifferentialQueriesImmediately allows the client to execute a new query the first time it sees it,
	// bypassing the scheduler.
	RunDifferentialQueriesImmediately bool
}

ExtensionOpts is options to be passed in NewExtension

type OsqueryConfig

type OsqueryConfig struct {
	Options    map[string]interface{} `json:"options"`
	Decorators Decorators             `json:"decorators,omitempty"`
	Packs      Packs                  `json:"packs,omitempty"`
}

OsqueryConfig is a struct that can be serialized into a valid osquery config using Go's JSON tooling

type OsqueryDistributedQueryResults

type OsqueryDistributedQueryResults map[string][]map[string]string

OsqueryDistributedQueryResults represents the format of the results of an osquery distributed query

type OsqueryPlatform

type OsqueryPlatform string

OsqueryPlatform is the specific type assigned to osquery platform strings

const (
	Unknown OsqueryPlatform = "unknown"
	Windows OsqueryPlatform = "windows"
	Darwin  OsqueryPlatform = "darwin"
	Linux   OsqueryPlatform = "linux"
)

func DetectPlatform

func DetectPlatform() (OsqueryPlatform, error)

DetectPlatform returns the runtime platform, or an error if the runtime platform cannot be sufficiently detected.

type OsqueryResultLog

type OsqueryResultLog struct {
	Name           string `json:"name"`
	HostIdentifier string `json:"hostIdentifier"`
	UnixTime       int    `json:"unixTime"`
	CalendarTime   string `json:"calendarTime"`
	Epoch          int    `json:"epoch"`
	Counter        int    `json:"counter"`
	// Columns stores the columns of differential queries
	Columns map[string]string `json:"columns,omitempty"`
	// Snapshot stores the rows and columns of snapshot queries
	Snapshot    []map[string]string `json:"snapshot,omitempty"`
	DiffResults *DiffResults        `json:"diffResults,omitempty"`
	Action      string              `json:"action,omitempty"`
	Decorations map[string]string   `json:"decorations,omitempty"`
}

OsqueryResultLog is the format of an osquery result log (ie: a differential or snapshot query)

type OsqueryStatusLog

type OsqueryStatusLog struct {
	Severity    string            `json:"severity"`
	Filename    string            `json:"filename"`
	Line        string            `json:"line"`
	Message     string            `json:"message"`
	Version     string            `json:"version"`
	Decorations map[string]string `json:"decorations"`
}

OsqueryStatusLog is the format of an osquery status log

type PackContent

type PackContent struct {
	Platform  string   `json:"platform,omitempty"`
	Version   string   `json:"version,omitempty"`
	Shard     uint     `json:"shard,omitempty"`
	Discovery []string `json:"discovery,omitempty"`
	Queries   Queries  `json:"queries"`
}

PackContent is the format of an osquery query pack

type Packs

type Packs map[string]PackContent

Packs is a helper which represents the format of a list of osquery query packs

type Querier

type Querier interface {
	Query(sql string) ([]map[string]string, error)
}

Querier allows querying osquery.

type Queries

type Queries map[string]QueryContent

Queries is a helper which represents the format of a set of queries in a pack

type QueryContent

type QueryContent struct {
	Query       string  `json:"query"`
	Description string  `json:"description,omitempty"`
	Interval    uint    `json:"interval"`
	Platform    *string `json:"platform,omitempty"`
	Version     *string `json:"version,omitempty"`
	Snapshot    *bool   `json:"snapshot,omitempty"`
	Removed     *bool   `json:"removed,omitempty"`
	Shard       *uint   `json:"shard,omitempty"`
}

QueryContent is the format of a query stanza in an osquery configuration

type Rows

type Rows []map[string]string

Rows is a type often used to represent osquery query results