osquery

package module
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Sep 23, 2021 License: MIT Imports: 13 Imported by: 5

README

basequery-go

basequery-go is a fork of osquery-go. This library can be used to write Golang extensions for basequery. This library was initially developed by Kolide and contributed to Osquery foundation.

Changes

  • This implementation supports the additional thrift extension manager method streamEvents().
  • ServerVersion option is added indicate version of the extension manager server (optional).
  • Extension manager client can be retrieved using GetClient() method.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CallFunc 

type CallFunc func(registry string, item string, req osquery.ExtensionPluginRequest) (*osquery.ExtensionResponse, error)

type CloseFunc 

type CloseFunc func()

type ExtensionManager 

type ExtensionManager interface {
	Close()
	Ping() (*osquery.ExtensionStatus, error)
	Call(registry, item string, req osquery.ExtensionPluginRequest) (*osquery.ExtensionResponse, error)
	Extensions() (osquery.InternalExtensionList, error)
	RegisterExtension(info *osquery.InternalExtensionInfo, registry osquery.ExtensionRegistry) (*osquery.ExtensionStatus, error)
	Options() (osquery.InternalOptionList, error)
	Query(sql string) (*osquery.ExtensionResponse, error)
	GetQueryColumns(sql string) (*osquery.ExtensionResponse, error)
	StreamEvents(name string, events osquery.ExtensionPluginResponse) (*osquery.ExtensionStatus, error)
	GetNodeKey() (string, error)
}

ExtensionManager is the interface for thrift bindings supported by basequery

type ExtensionManagerClient 

type ExtensionManagerClient struct {
	Client osquery.ExtensionManager
	// contains filtered or unexported fields
}

ExtensionManagerClient is a wrapper for the osquery Thrift extensions API.

func NewClient 

func NewClient(path string, timeout time.Duration) (*ExtensionManagerClient, error)

NewClient creates a new client communicating to osquery over the socket at the provided path. If resolving the address or connecting to the socket fails, this function will error.

func (*ExtensionManagerClient) Call 

func (c *ExtensionManagerClient) Call(registry, item string, request osquery.ExtensionPluginRequest) (*osquery.ExtensionResponse, error)

Call requests a call to an extension (or core) registry plugin.

func (*ExtensionManagerClient) Close 

func (c *ExtensionManagerClient) Close()

Close should be called to close the transport when use of the client is completed.

func (*ExtensionManagerClient) Extensions 

func (c *ExtensionManagerClient) Extensions() (osquery.InternalExtensionList, error)

Extensions requests the list of active registered extensions.

func (*ExtensionManagerClient) GetNodeKey added in v0.6.0 

func (c *ExtensionManagerClient) GetNodeKey() (string, error)

GetNodeKey returns TLS node key when enroll plugin is set to "tls".

func (*ExtensionManagerClient) GetQueryColumns 

func (c *ExtensionManagerClient) GetQueryColumns(sql string) (*osquery.ExtensionResponse, error)

GetQueryColumns requests the columns returned by the parsed query.

func (*ExtensionManagerClient) Options 

func (c *ExtensionManagerClient) Options() (osquery.InternalOptionList, error)

Options requests the list of bootstrap or configuration options.

func (*ExtensionManagerClient) Ping 

func (c *ExtensionManagerClient) Ping() (*osquery.ExtensionStatus, error)

Ping requests metadata from the extension manager.

func (*ExtensionManagerClient) Query 

func (c *ExtensionManagerClient) Query(sql string) (*osquery.ExtensionResponse, error)

Query requests a query to be run and returns the extension response. Consider using the QueryRow or QueryRows helpers for a more friendly interface.

func (*ExtensionManagerClient) QueryRow 

func (c *ExtensionManagerClient) QueryRow(sql string) (map[string]string, error)

QueryRow behaves similarly to QueryRows, but it returns an error if the query does not return exactly one row.

func (*ExtensionManagerClient) QueryRows 

func (c *ExtensionManagerClient) QueryRows(sql string) ([]map[string]string, error)

QueryRows is a helper that executes the requested query and returns the results. It handles checking both the transport level errors and the osquery internal errors by returning a normal Go error type.

func (*ExtensionManagerClient) RegisterExtension 

func (c *ExtensionManagerClient) RegisterExtension(info *osquery.InternalExtensionInfo, registry osquery.ExtensionRegistry) (*osquery.ExtensionStatus, error)

RegisterExtension registers the extension plugins with the osquery process.

func (*ExtensionManagerClient) StreamEvents 

func (c *ExtensionManagerClient) StreamEvents(name string, events osquery.ExtensionPluginResponse) (*osquery.ExtensionStatus, error)

StreamEvents sends a batch of events for a event'ed table.

type ExtensionManagerServer 

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

ExtensionManagerServer is an implementation of the full ExtensionManager API. Plugins can register with an extension manager, which handles the communication with the osquery process.

func NewExtensionManagerServer 

func NewExtensionManagerServer(name string, sockPath string, opts ...ServerOption) (*ExtensionManagerServer, error)

NewExtensionManagerServer creates a new extension management server communicating with osquery over the socket at the provided path. If resolving the address or connecting to the socket fails, this function will error.

func (*ExtensionManagerServer) Call 

func (s *ExtensionManagerServer) Call(ctx context.Context, registry string, item string, request osquery.ExtensionPluginRequest) (*osquery.ExtensionResponse, error)

Call routes a call from the osquery process to the appropriate registered plugin.

func (*ExtensionManagerServer) GetClient added in v0.2.0 

func (s *ExtensionManagerServer) GetClient() ExtensionManager

GetClient returns the extension manager client.

func (*ExtensionManagerServer) Ping 

func (s *ExtensionManagerServer) Ping(ctx context.Context) (*osquery.ExtensionStatus, error)

Ping implements the basic health check.

func (*ExtensionManagerServer) RegisterPlugin 

func (s *ExtensionManagerServer) RegisterPlugin(plugins ...Plugin)

RegisterPlugin adds one or more OsqueryPlugins to this extension manager.

func (*ExtensionManagerServer) Run 

func (s *ExtensionManagerServer) Run() error

Run starts the extension manager and runs until osquery calls for a shutdown or the osquery instance goes away.

func (*ExtensionManagerServer) Shutdown 

func (s *ExtensionManagerServer) Shutdown(ctx context.Context) error

Shutdown stops the server and closes the listening socket.

func (*ExtensionManagerServer) Start 

func (s *ExtensionManagerServer) Start() error

Start registers the extension plugins and begins listening on a unix socket for requests from the osquery process. All plugins should be registered with RegisterPlugin() before calling Start().

type ExtensionsFunc 

type ExtensionsFunc func() (osquery.InternalExtensionList, error)

type GetNodeKeyFunc added in v0.6.0 

type GetNodeKeyFunc func() (string, error)

type GetQueryColumnsFunc 

type GetQueryColumnsFunc func(sql string) (*osquery.ExtensionResponse, error)

type MockExtensionManager 

type MockExtensionManager struct {
	CloseFunc        CloseFunc
	CloseFuncInvoked bool

	PingFunc        PingFunc
	PingFuncInvoked bool

	CallFunc        CallFunc
	CallFuncInvoked bool

	ExtensionsFunc        ExtensionsFunc
	ExtensionsFuncInvoked bool

	RegisterExtensionFunc        RegisterExtensionFunc
	RegisterExtensionFuncInvoked bool

	OptionsFunc        OptionsFunc
	OptionsFuncInvoked bool

	QueryFunc        QueryFunc
	QueryFuncInvoked bool

	GetQueryColumnsFunc        GetQueryColumnsFunc
	GetQueryColumnsFuncInvoked bool

	StreamEventsFunc        StreamEventsFunc
	StreamEventsFuncInvoked bool

	GetNodeKeyFunc        GetNodeKeyFunc
	GetNodeKeyFuncInvoked bool
}

func (*MockExtensionManager) Call 

func (m *MockExtensionManager) Call(registry string, item string, req osquery.ExtensionPluginRequest) (*osquery.ExtensionResponse, error)

func (*MockExtensionManager) Close 

func (m *MockExtensionManager) Close()

func (*MockExtensionManager) Extensions 

func (m *MockExtensionManager) Extensions() (osquery.InternalExtensionList, error)

func (*MockExtensionManager) GetNodeKey added in v0.6.0 

func (m *MockExtensionManager) GetNodeKey() (string, error)

func (*MockExtensionManager) GetQueryColumns 

func (m *MockExtensionManager) GetQueryColumns(sql string) (*osquery.ExtensionResponse, error)

func (*MockExtensionManager) Options 

func (m *MockExtensionManager) Options() (osquery.InternalOptionList, error)

func (*MockExtensionManager) Ping 

func (m *MockExtensionManager) Ping() (*osquery.ExtensionStatus, error)

func (*MockExtensionManager) Query 

func (m *MockExtensionManager) Query(sql string) (*osquery.ExtensionResponse, error)

func (*MockExtensionManager) RegisterExtension 

func (m *MockExtensionManager) RegisterExtension(info *osquery.InternalExtensionInfo, registry osquery.ExtensionRegistry) (*osquery.ExtensionStatus, error)

func (*MockExtensionManager) StreamEvents 

func (m *MockExtensionManager) StreamEvents(name string, events osquery.ExtensionPluginResponse) (*osquery.ExtensionStatus, error)

type OptionsFunc 

type OptionsFunc func() (osquery.InternalOptionList, error)

type PingFunc 

type PingFunc func() (*osquery.ExtensionStatus, error)

type Plugin added in v0.7.0 

type Plugin interface {
	// Name is the name used to refer to the plugin (eg. the name of the
	// table the plugin implements).
	Name() string
	// RegistryName is which "registry" the plugin should be added to.
	// Valid names are ["config", "logger", "table"].
	RegistryName() string
	// Routes returns the detailed information about the interface exposed
	// by the plugin. See the example plugins for samples.
	Routes() osquery.ExtensionPluginResponse
	// Ping implements a health check for the plugin. If the plugin is in a
	// healthy state, StatusOK should be returned.
	Ping() osquery.ExtensionStatus
	// Call requests the plugin to perform its defined behavior, returning
	// a response containing the result.
	Call(context.Context, osquery.ExtensionPluginRequest) osquery.ExtensionResponse
	// Shutdown alerts the plugin to stop.
	Shutdown()
}

Plugin exposes the basequery Plugin interface.

type QueryFunc 

type QueryFunc func(sql string) (*osquery.ExtensionResponse, error)

type RegisterExtensionFunc 

type RegisterExtensionFunc func(info *osquery.InternalExtensionInfo, registry osquery.ExtensionRegistry) (*osquery.ExtensionStatus, error)

type ServerOption 

type ServerOption func(*ExtensionManagerServer)

ServerOption is function for setting extension manager server options.

func ServerPingInterval 

func ServerPingInterval(interval time.Duration) ServerOption

ServerPingInterval can be used to configure health check ping interval/frequency.

func ServerPrometheusPort added in v0.7.0 

func ServerPrometheusPort(port uint16) ServerOption

ServerPrometheusPort is used to specify the port on which prometheus metrics will be exposed. By default this is disabled (0). A positive integer port value should be specified to enable it.

func ServerTimeout 

func ServerTimeout(timeout time.Duration) ServerOption

ServerTimeout sets timeout duration for thrift socket.

func ServerVersion added in v0.2.0 

func ServerVersion(version string) ServerOption

ServerVersion can be used to specify the basequery SDK version.

type StreamEventsFunc 

type StreamEventsFunc func(name string, events osquery.ExtensionPluginResponse) (*osquery.ExtensionStatus, error)

Source Files

View all Source files

Directories

Path Synopsis
cmd
examples/call
examples/config
examples/distributed
examples/logger
examples/query
examples/table
gen
osquery
plugin
config
Package config creates an osquery configuration plugin.
 Package config creates an osquery configuration plugin.
distributed
Package distributed creates an osquery distributed query plugin.
 Package distributed creates an osquery distributed query plugin.
logger
Package logger creates an osquery logging plugin.
 Package logger creates an osquery logging plugin.
table
Package table creates an osquery table plugin.
 Package table creates an osquery table plugin.
Package transport provides Thrift TTransport and TServerTransport implementations for use on mac/linux (TSocket/TServerSocket) and Windows (custom named pipe implementation).
 Package transport provides Thrift TTransport and TServerTransport implementations for use on mac/linux (TSocket/TServerSocket) and Windows (custom named pipe implementation).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.