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 plugins with field extraction capability (https://github.com/falcosecurity/plugin-sdk-go/tree/main/examples/extractor), with event sourcing capability, (https://github.com/falcosecurity/plugin-sdk-go/tree/main/examples/source), and with both (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(ssPluginEvtInput 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 FieldEntryArg
• 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 (
	// A 64bit unsigned integer.
	FieldTypeUint64 uint32 = 8
	// A printable buffer of bytes, NULL terminated.
	FieldTypeCharBuf uint32 = 9
	// A relative time. Seconds * 10^9  + nanoseconds. 64bit.
	FieldTypeRelTime uint32 = 20
	// An absolute time interval. Seconds from epoch * 10^9  + nanoseconds. 64bit.
	FieldTypeAbsTime uint32 = 21
	// A boolean value, 4 bytes.
	FieldTypeBool uint32 = 25
	// Either an IPv4 or IPv6 address. The length indicates which one it is.
	FieldTypeIPAddr uint32 = 40
	// Either an IPv4 or IPv6 network. The length indicates which one it is.
	FieldTypeIPNet uint32 = 41
)

The full set of values that can be returned in the ftype member of ss_plugin_extract_field structs (ppm_events_public.h).

const DefaultBatchSize uint32 = 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(ssPluginEvtInput unsafe.Pointer) EventReader

NewEventReader wraps a pointer to a ss_plugin_event_input 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, the supported types are:
	//  - sdk.FieldTypeBool
	//  - sdk.FieldTypeUint64
	//  - sdk.FieldTypeCharBuf
	//  - sdk.FieldTypeRelTime
	//  - sdk.FieldTypeAbsTime
	//  - sdk.FieldTypeIPAddr
	//  - sdk.FieldTypeIPNet
	FieldType() uint32
	//
	// Field returns the name of the field for which the value extraction
	// is requested.
	Field() string
	//
	// ArgKey must be used when the field arg is a generic string (like a key
	// in a lookup operation). This field must have the `isKey` flag enabled.
	ArgKey() string
	//
	// ArgIndex must be used when the field arg is an index (0<=index<=2^64-1).
	// This field must have the `isIndex` flag enabled.
	ArgIndex() uint64
	//
	// ArgPresent clearly defines when an argument is valid or not.
	ArgPresent() bool
	//
	// IsList returns true if the field extracts lists of values.
	IsList() bool
	//
	// 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.
	//
	// Coherently to the FieldType of the extraction request, this function
	// panics if the passed value is not one of the following types (or slices
	// of them, in case IsList() returns true):
	//  - sdk.FieldTypeBool: bool
	//  - sdk.FieldTypeUint64: uint64
	//  - sdk.FieldTypeCharBuf: string
	//  - sdk.FieldTypeRelTime: time.Duration, *time.Duration
	//  - sdk.FieldTypeAbsTime: time.Time, *time.Time
	//  - sdk.FieldTypeIPAddr: net.IP, *net.IP
	//  - sdk.FieldTypeIPNet: net.IPNet, *net.IPNet
	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-friendly 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 {
	Name       string        `json:"name"`
	Type       string        `json:"type"`
	IsList     bool          `json:"isList"`
	Arg        FieldEntryArg `json:"arg"`
	Display    string        `json:"display"`
	Desc       string        `json:"desc"`
	Properties []string      `json:"properties"`
}

FieldEntry represents a single field entry that a plugin with field extraction capability can expose. Should be used when implementing plugin_get_fields().

type FieldEntryArg

type FieldEntryArg struct {
	IsRequired bool `json:"isRequired"`
	IsIndex    bool `json:"isIndex"`
	IsKey      bool `json:"isKey"`
}

FieldEntryArg describes the argument of a single field entry that an plugin with field extraction capability 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"`
	Separator string `json:"separator"`
}

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.
	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(evt EventReader) (string, error)
}

Stringer is an interface wrapping the basic String method. String takes an EventReader and produces a string representation describing its internal data. This is meant to be used in plugin_event_to_string(), where the event is provided by the framework and previouly produced by an invocation of plugin_next_batch() of this plugin.

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().