table

Documentation

Overview

Package table creates an osquery table plugin.

Index

• type ColumnDefinition
• type ColumnOptions
• type ColumnType
• type Constraint
• type ConstraintList
• type GenerateRowsImpl
• type InsertRowImpl
• type Operator
• type Option
  • func GenerateRows(generate GenerateRowsImpl) Option
  • func InsertRow(insert InsertRowImpl) Option
  • func UpdateRow(update UpdateRowImpl) Option
• type Plugin
  • func NewPlugin(name string, rowDefinition RowDefinition, options ...Option) (*Plugin, error)
  • func (t *Plugin) Call(ctx context.Context, request osquery.ExtensionPluginRequest) (response osquery.ExtensionResponse)
  • func (t *Plugin) Name() string
  • func (t *Plugin) Ping() osquery.ExtensionStatus
  • func (t *Plugin) RegistryName() string
  • func (t *Plugin) Routes() osquery.ExtensionPluginResponse
  • func (t *Plugin) Shutdown()
• type QueryContext
• type RowDefinition
• type RowID
• type UpdateRowImpl

Types

type ColumnDefinition

type ColumnDefinition struct {
	Name    string
	Type    ColumnType
	Options ColumnOptions
}

ColumnDefinition defines the relevant information for a column in a table plugin. Both values are mandatory. Prefer using the *Column helpers to create ColumnDefinition structs.

type ColumnOptions

type ColumnOptions uint8

ColumnOptions is an enum of the osquery column options.

const (
	// Default/no options.
	ColumnOptionDefault ColumnOptions = 0
	// Treat this column as a primary key.
	ColumnOptionIndex ColumnOptions = 1
	// This column MUST be included in the query predicate.
	ColumnOptionRequired ColumnOptions = 2
	/*
		 	 * @brief This column is used to generate additional information.
			 *
			 * If this column is included in the query predicate, the table will generate
			 * additional information. Consider the browser_plugins or shell history
			 * tables: by default they list the plugins or history relative to the user
			 * running the query. However, if the calling query specifies a UID explicitly
			 * in the predicate, the meaning of the table changes and results for that
			 * user are returned instead.
	*/
	ColumnOptionAdditional ColumnOptions = 4
	/*
		* @brief This column can be used to optimize the query.
		*
		* If this column is included in the query predicate, the table will generate
		* optimized information. Consider the system_controls table, a default filter
		* without a query predicate lists all of the keys. When a specific domain is
		* included in the predicate then the table will only issue syscalls/lookups
		* for that domain, greatly optimizing the time and utilization.
		*
		 * This optimization does not mean the column is an index.
	*/
	ColumnOptionOptimized ColumnOptions = 8
	// This column should be hidden from '*” selects.
	ColumnOptionHidden ColumnOptions = 16
)

The following operators are dfined in osquery tables.h.

type ColumnType

type ColumnType string

ColumnType is a strongly typed representation of the data type string for a column definition. The named constants should be used.

const (
	ColumnTypeText       ColumnType = "TEXT"
	ColumnTypeInteger    ColumnType = "INTEGER"
	ColumnTypeBigInt     ColumnType = "BIGINT"
	ColumnUnsignedBigInt ColumnType = "UNSIGNED BIGINT"
	ColumnTypeDouble     ColumnType = "DOUBLE"
	ColumnTypeBlob       ColumnType = "BLOB"
)

The following column types are defined in osquery tables.h.

type Constraint

type Constraint struct {
	Operator   Operator
	Expression string
}

Constraint contains both an operator and an expression that are applied as constraints in the query.

type ConstraintList

type ConstraintList struct {
	Affinity    ColumnType
	Constraints []Constraint
}

ConstraintList contains the details of the constraints for the given column.

type GenerateRowsImpl

type GenerateRowsImpl func(ctx context.Context, queryContext QueryContext) ([]RowDefinition, error)

type InsertRowImpl

type InsertRowImpl func(ctx context.Context, row RowDefinition) (rowID RowID, err error)

type Operator

type Operator int

Operator is an enum of the osquery operators.

const (
	OperatorEquals              Operator = 2
	OperatorGreaterThan         Operator = 4
	OperatorLessThanOrEquals    Operator = 8
	OperatorLessThan            Operator = 16
	OperatorGreaterThanOrEquals Operator = 32
	OperatorMatch               Operator = 64
	OperatorLike                Operator = 65
	OperatorGlob                Operator = 66
	OperatorRegexp              Operator = 67
	OperatorUnique              Operator = 1
)

The following operators are dfined in osquery tables.h.

type Option

type Option func(*Plugin)

func GenerateRows

func GenerateRows(generate GenerateRowsImpl) Option

GenerateRows allows you to provide a function that is used by OSQuery to fulfill SELECT SQL statements.

Your Generate function is passed a set of constraints (representing any WHERE clauses in the query). These are optional to do anything with: the OSQuery SQLite engine will do its own filtering but they can be useful as optimisations or for taking arguments.

func InsertRow

func InsertRow(insert InsertRowImpl) Option

InsertRow allows you to provide a function that is used by OSQuery to fulfill INSERT SQL statements. Your Insert function must return a RowID.

func UpdateRow

func UpdateRow(update UpdateRowImpl) Option

UpdateRow allows you to provide a function that is used by OSQuery to fulfill UPDATE SQL statements. OSQuery first calls your GenerateRows function to find rows that should be updated and then calls UpdateRow once per row.

If your provided RowDefinition has a field of type RowID then this is the value passed to your update function. If not, you are passed an index into the array returned from GenerateRows. It is *strongly* recommended to use a RowID

type Plugin

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

func NewPlugin

func NewPlugin(name string, rowDefinition RowDefinition, options ...Option) (*Plugin, error)

func (*Plugin) Call

func (t *Plugin) Call(ctx context.Context, request osquery.ExtensionPluginRequest) (response osquery.ExtensionResponse)

func (*Plugin) Name

func (t *Plugin) Name() string

func (*Plugin) Ping

func (t *Plugin) Ping() osquery.ExtensionStatus

func (*Plugin) RegistryName

func (t *Plugin) RegistryName() string

func (*Plugin) Routes

func (t *Plugin) Routes() osquery.ExtensionPluginResponse

func (*Plugin) Shutdown

func (t *Plugin) Shutdown()

type QueryContext

type QueryContext struct {
	// Constraints is a map from column name to the details of the
	// constraints on that column.
	Constraints map[string]ConstraintList
}

QueryContext contains the constraints from the WHERE clause of the query, that can optionally be used to optimize the table generation. Note that the osquery SQLite engine will perform the filtering with these constraints, so it is not mandatory that they be used in table generation.

type RowDefinition

type RowDefinition interface{}

type RowID

type RowID uint64

type UpdateRowImpl

type UpdateRowImpl func(ctx context.Context, rowID RowID, row RowDefinition) error