sdk

Documentation

Overview

Package sdk provides definitions and constructs for developers that would like to write Falcosecurity Plugins (https://falco.org/docs/plugins/) in Go.

Before using this package, review the developer's guide (https://falco.org/docs/plugins/developers_guide/) which fully documents the API and provides best practices for writing plugins. The developer's guide includes a walkthrough (https://falco.org/docs/plugins/developers_guide/#example-go-plugin-dummy) of a plugin written in Go that uses this package.

For a quick start, you can refer to the provided examples of extractor plugin (https://github.com/falcosecurity/plugin-sdk-go/tree/main/examples/extractor), source plugin (https://github.com/falcosecurity/plugin-sdk-go/tree/main/examples/source), and source plugin with extraction (https://github.com/falcosecurity/plugin-sdk-go/tree/main/examples/full).

This SDK is designed to be layered with different levels of abstraction:

1. The "sdk/plugins" package provide high-level constructs to easily develop plugins in a Go-friendly way, by abstracting all the low-level details of the plugin framework and by avoiding the need of useless boilerplate code. This package is the way to go for developers to start building plugins.

2. The "sdk/symbols" package provide prebuilt implementations for all the C symbols that need to be exported by the plugin in order to be accepted by the framework. The prebuilt symbols handle all the complexity of bridging the C symbols and the Go runtime. Each subpackage is not internal, and can be used by advanced plugin developers to achieve a custom usage of the SDK symbols. This option is a strongly discouraged, as plugins must generally be developed using the more high-level constructs of the "sdk/plugins" package. This package is also used internally, and may be subject to more frequent breaking changes.

3. The "sdk" package provides basic definitions and constructs necessary to develop plugins. The SDK describes the behavior of plugins as a set of minimal and composable interfaces, to be used flexibly in other packages.

Index

• Constants
• Variables
• type Closer
• type Destroyer
• type EventReader
  • func NewEventReader(ssPluginEvt unsafe.Pointer) EventReader
• type EventWriter
• type EventWriters
  • func NewEventWriters(size, dataSize int64) (EventWriters, error)
• type Events
• type ExtractRequest
• type ExtractRequestPool
  • func NewExtractRequestPool() ExtractRequestPool
• type ExtractRequests
• type Extractor
• type FieldEntry
• type InitSchema
• type InstanceState
• type LastError
• type LastErrorBuffer
• type NextBatcher
• type OpenParam
• type OpenParams
• type OpenParamsBuffer
• type PluginState
• type ProgressBuffer
• type Progresser
• type SchemaInfo
• type StringBuffer
• type Stringer
• type StringerBuffer

Constants

const (
	SSPluginSuccess      int32 = 0
	SSPluginFailure      int32 = 1
	SSPluginTimeout      int32 = -1
	SSPluginEOF          int32 = 2
	SSPluginNotSupported int32 = 3
)

Functions that return or update a rc (e.g. plugin_init, plugin_open) should return one of these values.

const (
	TypeSourcePlugin    uint32 = 1
	TypeExtractorPlugin uint32 = 2
)

One of these values should be returned by plugin_get_type().

const (
	ParamTypeNone             uint32 = 0
	ParamTypeInt8             uint32 = 1
	ParamTypeInt16            uint32 = 2
	ParamTypeInt32            uint32 = 3
	ParamTypeInt64            uint32 = 4
	ParamTypeUintT8           uint32 = 5
	ParamTypeUint16           uint32 = 6
	ParamTypeUint32           uint32 = 7
	ParamTypeUint64           uint32 = 8
	ParamTypeCharBuf          uint32 = 9  // A printable buffer of bytes, NULL terminated
	ParamTypeByteBuf          uint32 = 10 // A raw buffer of bytes not suitable for printing
	ParamTypeErrno            uint32 = 11 // this is an INT64, but will be interpreted as an error code
	ParamTypeSockaddr         uint32 = 12 // A sockaddr structure, 1byte family + data
	ParamTypeSocktuple        uint32 = 13 // A sockaddr tuple,1byte family + 12byte data + 12byte data
	ParamTypeFd               uint32 = 14 // An fd, 64bit
	ParamTypePid              uint32 = 15 // A pid/tid, 64bit
	ParamTypeFdlist           uint32 = 16 // A list of fds, 16bit count + count * (64bit fd + 16bit flags)
	ParamTypeFspath           uint32 = 17 // A string containing a relative or absolute file system path, null terminated
	ParamTypeSyscallId        uint32 = 18 // A 16bit system call ID. Can be used as a key for the g_syscall_info_table table.
	ParamTypeSigYype          uint32 = 19 // An 8bit signal number
	ParamTypeRelTime          uint32 = 20 // A relative time. Seconds * 10^9  + nanoseconds. 64bit.
	ParamTypeAbsTime          uint32 = 21 // An absolute time interval. Seconds from epoch * 10^9  + nanoseconds. 64bit.
	ParamTypePort             uint32 = 22 // A TCP/UDP prt. 2 bytes.
	ParamTypeL4Proto          uint32 = 23 // A 1 byte IP protocol type.
	ParamTypeSockfamily       uint32 = 24 // A 1 byte socket family.
	ParamTypeBool             uint32 = 25 // A boolean value, 4 bytes.
	ParamTypeIpv4Addr         uint32 = 26 // A 4 byte raw IPv4 address.
	ParamTypeDyn              uint32 = 27 // Type can vary depending on the context. Used for filter fields like evt.rawarg.
	ParamTypeFlags8           uint32 = 28 // this is an UINT8, but will be interpreted as 8 bit flags.
	ParamTypeFlags16          uint32 = 29 // this is an UINT16, but will be interpreted as 16 bit flags.
	ParamTypeFlags32          uint32 = 30 // this is an UINT32, but will be interpreted as 32 bit flags.
	ParamTypeUid              uint32 = 31 // this is an UINT32, MAX_UINT32 will be interpreted as no value.
	ParamTypeGid              uint32 = 32 // this is an UINT32, MAX_UINT32 will be interpreted as no value.
	ParamTypeDouble           uint32 = 33 // this is a double precision floating point number.
	ParamTypeSigSet           uint32 = 34 // sigset_t. I only store the lower UINT32 of it
	ParamTypeCharBufArray     uint32 = 35 // Pointer to an array of strings, exported by the user events decoder. 64bit. For internal use only.
	ParamTypeCharBufPairArray uint32 = 36 // Pointer to an array of string pairs, exported by the user events decoder. 64bit. For internal use only.
	ParamTypeIpv4Net          uint32 = 37 // An IPv4 network.
	ParamTypeIpv6Addr         uint32 = 38 // A 16 byte raw IPv6 address.
	ParamTypeIpv6Net          uint32 = 39 // An IPv6 network.
	ParamTypeIpAddr           uint32 = 40 // Either an IPv4 or IPv6 address. The length indicates which one it is.
	ParamTypeIpNet            uint32 = 41 // Either an IPv4 or IPv6 network. The length indicates which one it is.
	ParamTypeMode             uint32 = 42 // a 32 bit bitmask to represent file modes.
	ParamTypeFsRelPath        uint32 = 43 // A path relative to a dirfd.
	ParamTypeMax              uint32 = 44 // array size
)

The full set of values that someday might be returned in the ftype member of ss_plugin_extract_field structs. For now, only ParamTypeUint64/ParamTypeCharBuf are used.

const DefaultBatchSize = 128

DefaultBatchSize is the default number of events in the EventWriters interface used by the SDK.

const DefaultEvtSize uint32 = 256 * 1024

DefaultEvtSize is the default size for the data payload allocated for each event in the EventWriters interface used by the SDK.

Variables

var ErrEOF = errors.New("eof")

ErrEOF is the error returned by next_batch when no new events are available.

var ErrTimeout = errors.New("timeout")

ErrTimeout is the error returned by next_batch when no new events are available for the current batch, but may be available in the next one.

Types

type Closer

type Closer interface {
	Close()
}

Closer is an interface wrapping the basic Destroy method. Close deinitializes the resources opened or allocated by a plugin instance. This is meant to be used in plugin_close() to release the resources owned by a plugin instance. The behavior of Close after the first call is undefined.

type Destroyer

type Destroyer interface {
	Destroy()
}

Destroyer is an interface wrapping the basic Destroy method. Destroy deinitializes the resources opened or allocated by a plugin. This is meant to be used in plugin_destroy() to release the plugin's resources. The behavior of Destroy after the first call is undefined.

type EventReader

type EventReader interface {
	// EventNum returns the number assigned to the event by the framework.
	EventNum() uint64
	//
	// Timestamp returns the timestamp of the event.
	Timestamp() uint64
	//
	// Reader returns an instance of io.ReadSeeker that points to the
	// event data. This is the only way to read from the event data.
	//
	// This method returns an instance of io.ReadSeeker to leave the door
	// open for seek-related optimizations, which could be useful in the
	// field extraction use case.
	Reader() io.ReadSeeker
}

EventReader can be used to represent events passed by the framework to the plugin. This interface is meant to be used during extraction.

Data inside an event can only be accessed in read-only mode through the io.Reader interface returned by the Reader method.

func NewEventReader

func NewEventReader(ssPluginEvt unsafe.Pointer) EventReader

NewEventReader wraps a pointer to a ss_plugin_event C structure to create a new instance of EventReader. It's not possible to check that the pointer is valid. Passing an invalid pointer may cause undefined behavior.

type EventWriter

type EventWriter interface {
	// Writer returns an instance of io.Writer that points to the
	// event data. This is the only way to write inside the event data.
	//
	// Each invocation of Writer clears the event data and sets its
	// size to zero. As such, consequent invocations of Writer can
	// potentially return two distinct instances of io.Writer, and
	// any data written inside the event would be erased.
	Writer() io.Writer
	//
	// SetTimestamp sets the timestamp of the event.
	SetTimestamp(value uint64)
}

EventWriter can be used to represent events produced by a plugin. This interface is meant to be used in the next/next_batch.

Data inside an event can only be accessed in write-only mode through the io.Writer interface returned by the Writer method.

Instances of this interface should be retrieved through the Get method of sdk.EventWriters.

type EventWriters

type EventWriters interface {
	// Get returns an instance of sdk.EventWriter at the eventIndex
	// position inside the list.
	Get(eventIndex int) EventWriter
	//
	// Len returns the size of the list, namely the number of events
	// it contains. Using Len coupled with Get allows iterating over
	// all the events of the list.
	Len() int
	//
	// ArrayPtr return an unsafe pointer to the underlying C array of
	// ss_plugin_event. The returned pointer should only be used for
	// read tasks or for being passed to the plugin framework.
	// Writing in the memory pointed by this pointer is unsafe and might
	// lead to non-deterministic behavior.
	ArrayPtr() unsafe.Pointer
	//
	// Free deallocates any memory used by the list that can't be disposed
	// through garbage collection. The behavior of Free after the first call
	// is undefined.
	Free()
}

EventWriters represent a list of sdk.EventWriter to be used inside plugins. This interface hides the complexities related to the internal representation of C strutures and to the optimized memory management. Internally, this wraps an array of ss_plugin_event C structs that are compliant with the symbols and APIs of the plugin framework. The underlying C array can be accessed through the ArrayPtr method as an unsafe.Pointer. Manually writing inside the C array might break the internal logic of sdk.EventWriters and lead to undefined behavior.

This is intended to be used as a slab memory allocator. EventWriters are supposed to be stored inside the plugin instance state to avoid useless reallocations, and should be used to create plugin events and write their data. Unlike slices, the events contained in the list can only be accessed by using the Get and Len methods to enforce safe memory accesses. Ideally, the list is meant to be large enough to contain the maximum number of events that the plugin is capable of producing with plugin_next_batch.

func NewEventWriters

func NewEventWriters(size, dataSize int64) (EventWriters, error)

NewEventWriters creates a new instance of sdk.EventWriters. The size argument indicates the length of the list, which is the amount of events contained. Then dataSize argument indicates the maximum data size of each event.

type Events

type Events interface {
	// Events returns the list of reusable EventWriters.
	Events() EventWriters
	//
	// SetEvents sets the list of reusable EventWriters.
	SetEvents(events EventWriters)
}

Events is an interface wrapping the basic Events and SetEvents methods. This is meant to be used as a standard container for a resusable list of EventWriters to be used in plugin_next_batch().

type ExtractRequest

type ExtractRequest interface {
	// FieldID returns id of the field, as of its index in the list of fields
	// returned by plugin_get_fields
	FieldID() uint64
	//
	// FieldType returns the type of the field for which the value extraction
	// is requested. For now, only sdk.ParamTypeUint64 and
	// sdk.ParamTypeCharBuf are supported.
	FieldType() uint32
	//
	// Field returns the name of the field for which the value extraction
	// is requested.
	Field() string
	//
	// Arg returns the argument passed for the requested field. An empty string
	// is returned if no argument is specified.
	Arg() string
	//
	// SetValue sets the extracted value for the requested field.
	//
	// The underlying type of v must be compatible with the field type
	// associated to this extract request (as the returned by FieldType()),
	// otherwise SetValue will panic.
	SetValue(v interface{})
	//
	// SetPtr sets a pointer to a ss_plugin_extract_field C structure to
	// be wrapped in this instance of ExtractRequest.
	SetPtr(unsafe.Pointer)
}

ExtractRequest represents an high-level abstraction that wraps a pointer to a ss_plugin_extract_field C structure, providing methods for accessing its fields in a go-friently way.

type ExtractRequestPool

type ExtractRequestPool interface {
	// Get returns an instance of ExtractRequest at the requestIndex
	// position inside the pool. Indexes can be non-contiguous.
	Get(requestIndex int) ExtractRequest
	//
	// Free deallocates any memory used by the pool that can't be disposed
	// through garbage collection. The behavior of Free after the first call
	// is undefined.
	Free()
}

ExtractRequestPool represents a pool of reusable ExtractRequest objects. Each ExtractRequest can be reused by calling its SetPtr method to wrap a new ss_plugin_extract_field C structure pointer.

func NewExtractRequestPool

func NewExtractRequestPool() ExtractRequestPool

NewExtractRequestPool returns a new empty ExtractRequestPool.

type ExtractRequests

type ExtractRequests interface {
	ExtractRequests() ExtractRequestPool
	SetExtractRequests(ExtractRequestPool)
}

type Extractor

type Extractor interface {
	Extract(req ExtractRequest, evt EventReader) error
}

Extractor is an interface wrapping the basic Extract method. Extract is meant to be used in plugin_extract_fields() to extract the value of a single field from a given event data.

type FieldEntry

type FieldEntry struct {
	Type        string   `json:"type"`
	Name        string   `json:"name"`
	ArgRequired bool     `json:"argRequired"`
	Display     string   `json:"display"`
	Desc        string   `json:"desc"`
	Properties  []string `json:"properties"`
}

FieldEntry represents a single field entry that an extractor plugin can expose. Should be used when implementing plugin_get_fields().

type InitSchema

type InitSchema interface {
	InitSchema() *SchemaInfo
}

InitSchema is an interface wrapping the basic InitSchema method. InitSchema is meant to be used in plugin_get_init_schema() to return a schema describing the data expected to be passed as a configuration during the plugin initialization. The schema must follow the JSON Schema specific: https://json-schema.org/. A nil return value is interpreted as the absence of a schema, and the init configuration will not be pre-validated by the framework. If JSON Schema is returned, the init configuration will be expected to be a json-formatted string. If so, the init() function can assume the configuration to be well-formed according to the returned schema, as the framework will perform a pre-validation before initializing the plugin.

type InstanceState

type InstanceState interface {
}

InstanceState represents the state of a plugin instance created with plugin_open().

type LastError

type LastError interface {
	// LastError returns the last error occurred in the plugin.
	LastError() error
	//
	// SetLastError sets the last error occurred in the plugin.
	SetLastError(err error)
}

LastError is a compasable interface wrapping the basic LastError and SetLastError methods. This is meant to be used as a standard container for the last error catched during the execution of a plugin.

type LastErrorBuffer

type LastErrorBuffer interface {
	LastErrorBuffer() StringBuffer
}

LastErrorBuffer is an interface wrapping the basic LastErrorBuffer method. LastErrorBuffer returns a StringBuffer meant to be used as buffer for plugin_get_last_error().

type NextBatcher

type NextBatcher interface {
	NextBatch(pState PluginState, evts EventWriters) (int, error)
}

NextBatcher is an interface wrapping the basic NextBatch method. NextBatch is meant to be used in plugin_next_batch() to create a batch of new events altogether.

The pState argument represents the plugin state, whereas the evt argument is an EventWriters representing list the to-be created events. The size of the event list dictates the expected size of the batch.

NextBatch can set a timestamp for the to-be created events with the SetTimestamp method of the EventWriter interface. If not set manually, the framework will set a timestamp automatically. NextBatch must be consistent in setting timestamps: either it sets it for every event, or for none.

NextBatch returns the number of events created in the batch, which is always <= evts.Len(), and a nil error if the call is successful. ErrTimeout can be returned to indicate that no new events are currently available for the current batch, but that they can be available in future calls to NextBatch. ErrEOF can be returned to indicate that no new events will be available. After returning ErrEOF once, subsequent calls to NextBatch must be idempotent and must keep returning ErrEOF. If the returned error is non-nil, the batch of events is discarded.

type OpenParam

type OpenParam struct {
	Value string `json:"value"`
	Desc  string `json:"desc"`
}

OpenParam represents a valid parameter for plugin_open().

type OpenParams

type OpenParams interface {
	OpenParams() ([]OpenParam, error)
}

OpenParams is an interface wrapping the basic OpenParams method. OpenParams is meant to be used in plugin_list_open_params() to return a list of suggested parameters that would be accepted as valid arguments for plugin_open().

type OpenParamsBuffer

type OpenParamsBuffer interface {
	OpenParamsBuffer() StringBuffer
}

OpenParamsBuffer is an interface wrapping the basic OpenParamsBuffer method. OpenParamsBuffer returns a StringBuffer meant to be used as buffer for plugin_list_open_params().

type PluginState

type PluginState interface {
}

PluginState represents the state of a plugin returned by plugin_init().

type ProgressBuffer

type ProgressBuffer interface {
	ProgressBuffer() StringBuffer
}

ProgressBuffer is an interface wrapping the basic ProgressBuffer method. ProgressBuffer returns a StringBuffer meant to be used as buffer for plugin_get_progress().

type Progresser

type Progresser interface {
	Progress(pState PluginState) (float64, string)
}

Progresser is an interface wrapping the basic Progress method. Progress is meant to be used in plugin_get_progress() to optionally notify the framework about the current event creation progress. Progress returns a float64 representing the normalized progress percentage such that 0 <= percentage <= 1, and a string representation of the same percentage value.

type SchemaInfo

type SchemaInfo struct {
	Schema string
}

SchemaInfo represent a schema describing a structured data type. Should be used when implementing plugin_get_init_schema().

type StringBuffer

type StringBuffer interface {
	// Write writes a Go string inside the buffer, converting it to a C-like
	// null-terminated string. Implementations of this interface must handle
	// the case in which the buffer is not large enough to host the converted
	// string.
	Write(string)
	//
	// String returns a Go string obtained by converting the C-like string
	// currently stored in the buffer. If the buffer is empty, an empty string
	// is returned.
	String() string
	//
	// CharPtr returns an unsafe pointer to the underlying C-allocated
	// char* buffer. Freeing the returned pointer by any sort of deallocator
	// (C.free or similars) can lead to undefined behavior.
	CharPtr() unsafe.Pointer
	//
	// Free deallocates the underlying C-allocated buffer. The behavior of Free
	// after the first call is undefined.
	Free()
}

StringBuffer represents a buffer for C-allocated null-terminated strings in a Go-friendly way. Unlike the C.CString function, this interface helps convert a Go string in a C-like one by always reusing the same buffer. Implementations of this interface must take care of allocating the underlying C buffer.

type Stringer

type Stringer interface {
	String(in io.ReadSeeker) (string, error)
}

Stringer is an interface wrapping the basic String method. String takes a io.ReadSeeker byte input and produces a string representation describing its internal data. This is meant to be used in plugin_event_to_string(), where the byte input represents event data provided by the framework and previouly produced by the plugin_next_batch().

type StringerBuffer

type StringerBuffer interface {
	StringerBuffer() StringBuffer
}

StringerBuffer is an interface wrapping the basic StringerBuffer method. StringerBuffer returns a StringBuffer meant to be used as buffer for plugin_event_to_string().