Falco – Falco Plugins

Docs: Falco Plugins API Reference

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

This page documents the functions that make up the Falco plugins API. In most cases, you will not need to implement these functions directly. There are Go and C++ SDKs that provide an easier-to-use interface for plugin authors.

At a high level, the API functions are grouped as follows:

Functions that are commons to all plugins
Functions that implement one specific capability

The C header files plugin_api.h numerate all the API functions and associated structs/types as they are used by the plugins framework. The whole plugin API and the loader used in Falco are implemented in C in a standalone module located inside falcosecurity/libs/userspace/plugin, and can be imported and reused in other projects using the falcosecurity plugin system (e.g. we have a plugin loader written in Go developed on top of the C one).

Remember, however, that from the perspective of the plugin, each function name has a prefix plugin_ e.g. plugin_get_required_api_version, plugin_get_name, etc.

Since Falco v0.33.0, some function symbols of the plugin API started supporting concurrent invocations from multiple threads. If not explicitly specified in each symbol's API reference, the plugin API assumes that functions are invoked always from the same thread with no concurrency.

Plugin API Versioning

The current version of the plugin API is 3.6.0.

The plugin API is a formal contract between the framework and the plugins, and it is versioned using semantic versioning. The framework exposes the plugin API version it supports, and each plugin expresses a required plugin API version. If the version required by a plugin does not pass the semantic check with the one supported by the framework, then the plugin cannot be loaded. See the section about plugin_get_required_api_version for more details.

Conventions

The following conventions apply for all of the below API functions:

Every function that returns a const char* must return a null-terminated C string.
All string values returned across the API are considered owned by the plugin and must remain valid for use by the plugin framework. Specifically, this means:
- For demographic functions like plugin_get_name, plugin_get_description, the returned strings must remain valid until the plugin is destroyed.
- When returning events via plugin_next_batch, both the array of structs and the data payloads inside each struct must remain valid until the next call to plugin_next_batch.
- When returning extracted string values via plugin_extract_fields, every extracted string must remain valid until the next call to plugin_extract_fields.
For every function that returns an error, the plugin should save a meaningful error string that the framework can retrieve via a call to plugin_get_last_error.

Inversion of Control and Callbacks to the Plugin's Owner

All functions from the plugin API define functionalities that the plugin offers to the framework. In the default execution path, the plugin is always the "passive" actor, with the framework being the orchestrator determining when and how often a given plugin function gets invoked.

The plugin API also supports an occasional inversion of control in which plugins can actively invoke functions exposed by the framework that owns it. For those cases, the execution flow generally proceeds as follows. First, the framework invokes a function exported by the plugin according its supported version of the plugin API. As one of the function arguments the framework passes to the plugin a vtable struct allocated and owned by the framework itself, containing one or more function pointers referring to code functions of the framework that the plugin is allowed to invoke. Permissions about retaining such function pointers inside the plugin's state after the execution of the plugin API symbol may vary depending on the API symbol itself and its related capabilities. Alongside the function pointers, the framework also provides the plugin with a ss_plugin_owner_t* opaque handle, which the plugin must pass to the framework's functions. The opaque handle represents an instance of the plugin's owner, which is an abstract component that the framework allocates for managing the plugin's requests. If the framework passes one of the function pointers defined in the vtable structs as NULL, then the plugin must assume that the related piece of functionality is not supported by the framework in that context. Plugins must always check whether the function pointers passed by the framework are NULL or not.

An example of functionality provided in the form of inversion of control is the access to state tables. The C++ example below shows how a plugin can interact with its owner during the execution of its init function. In this case, the plugin iterates over the list of state tables registered in the framework and catches errors arising during the invocations of the owner's callbacks:

extern "C" ss_plugin_t* plugin_init(const ss_plugin_init_input* in, ss_plugin_rc* rc)
{
 *rc = SS_PLUGIN_SUCCESS;
 my_plugin *ret = new my_plugin();

 if (!in || !in->tables)
 {
 *rc = SS_PLUGIN_FAILURE;
 ret->lasterr = "access to the state tables is not supported by the owner";
 return ret;
 }

 uint32_t ntables = 0;
 auto tables = in->tables->list_tables(in->owner, &ntables);
 if (!tables)
 {
 *rc = SS_PLUGIN_FAILURE;
 ret->lasterr = "can't list state tables: " + std::string(in->get_owner_last_error(in->owner));
 return ret;
 }

 for (uint32_t i = 0; i < ntables; i++)
 {
 auto& ti = tables[i];
 printf("table='%s', key_type=%d\n", ti.name, ti.key_type);
 }

 return ret;
}

Logging

Another functionality that makes use of inversion of control is logging.

The framework provides a log function during the plugin initialization, which the plugin can use to invoke the framework-provided logger at any time during the plugin life-cycle.

The following C++ example shows how a plugin can retain the owner's handle and the log function to invert control and invoke the framework logger:

struct my_plugin
{
 ss_plugin_owner_t* owner;
 ss_plugin_log_fn_t log;
};

extern "C" ss_plugin_t* plugin_init(const ss_plugin_init_input* in, ss_plugin_rc* rc)
{
 *rc = SS_PLUGIN_SUCCESS;
 my_plugin *ret = new my_plugin();

 ret->log = in->log_fn;
 ret->owner = in->owner;

 ret->log(ret->owner, NULL, "initializing plugin...", SS_PLUGIN_LOG_SEV_INFO);

 return ret;
}

extern "C" void plugin_destroy(ss_plugin_t* s)
{
 my_plugin *ps = (my_plugin *) s;
 ps->log(ps->owner, NULL, "destroying plugin...", SS_PLUGIN_LOG_SEV_INFO);

 delete ((my_plugin *) s);
}

The signature of the log function is:

void log(ss_plugin_owner_t* owner, const char* component, const char* msg, ss_plugin_log_severity sev);

where owner is the handle of the owner, component is a string representing the plugin's component name that is invoking the logger (falls back to the plugin name when NULL), msg is the log message and sev is the log severity as defined in API.

Common Plugin API

get_required_api_version

const char* plugin_get_required_api_version() [Required: yes]

This function returns a string containing a semver version number e.g. "3.0.0", reflecting the version of the plugin API framework that this plugin requires. This is different than the version of the plugin itself, and should only have to change when the plugin API changes.

This is the first function the framework calls when loading a plugin. If the returned value is not semver-compatible with the version of the plugin API framework, the plugin will not be loaded.

For example, if the code implementing the plugin framework has version 1.1.0, and a plugin's plugin_get_required_api_version function returns 1.0.0, the plugin API is compatible and the plugin will be loaded. If the code implementing the plugin framework has version 3.0.0, and a plugin's plugin_get_required_api_version function returns 1.0.0, the API is not compatible and the plugin will not be loaded.

get_{name,description,contact,version}

const char* plugin_get_name() [Required: yes]
const char* plugin_get_description() [Required: yes]
const char* plugin_get_contact() [Required: yes]
const char* plugin_get_version() [Required: yes]

These functions all return an C string, with memory owned by the plugin, that describe the plugin:

plugin_get_name: Return the name of the plugin.
plugin_get_description: Return a short description of the plugin.
plugin_get_contact: Return a contact url/email/twitter account for the plugin authors.
plugin_get_version: Return the version of the plugin itself.

For get_version, note that increasing the major version signals breaking changes in the plugin implementation but must not change the serialization format of the event data. For example, events written in pre-existing capture files must always be readable by newer versions of the plugin.

init

ss_plugin_t* plugin_init(const ss_plugin_init_input *input, ss_plugin_rc *rc) [Required: yes]

This function passes plugin-level configuration to the plugin to create its plugin-level state. The plugin then returns a pointer to that state, as a ss_plugin_t * handle. The handle is never examined by the plugin framework and is never freed. It is only provided as the argument to later API functions.

When managing plugin-level state, keep the following in mind:

It is the plugin's responsibility to allocate plugin state (memory, open files, etc) and free that state later in plugin_destroy.
The plugin state should be the only location for state (e.g. no globals, no per-thread state). Although unlikely, the framework may choose to call plugin_init multiple times for the same plugin, and this should be supported by the plugin.
The returned rc value should be SS_PLUGIN_SUCCESS (0) on success, SS_PLUGIN_FAILURE (1) on failure.
On failure, make sure to return a meaningful error message in the next call to plugin_get_last_error.
On failure, plugins can decide whether to return an allocated state or not. In the first case, the plugin framework will use the allocated state to retrieve the failure error with plugin_get_last_error, and will then free the state with plugin_destroy. In the second case, plugin_destroy will not be called and the plugin framework will return a generic error.

The format of the config string is entirely determined by the plugin author, and by default is passed unchanged from Falco/the application using the plugin framework to the plugin. However, semi-structured formats like JSON/YAML are preferable to free-form text. In those cases, the plugin author can provide a schema describing the config string contents by implementing the optional get_init_schema function. If so, the init function can assume the passed-in configuration string to always be well-formed, and can avoid performing any error handling. The plugin framework will take care of automatically parsing it against the provided schema and generating ad-hoc errors accordingly. Please refer to the documentation of get_init_schema for more details.

If a non-NULL ss_plugin_t* state is returned, then subsequent invocations of init must not return the same ss_plugin_t * value again, unless it has been disposed with destroy first.

destroy

void plugin_destroy(ss_plugin_t *s) [Required: yes]

This function frees any resources held in the ss_plugin_t struct. Afterwards, the handle should be considered destroyed and no further API functions will be called with that handle.

get_last_error

const char* plugin_get_last_error(ss_plugin_t* s) [Required: yes]

This function is called by the framework after a prior call returned an error. The plugin should return a meaningful error string providing more information about the most recent error.

get_init_schema

const char* plugin_get_init_schema(ss_plugin_schema_type* schema_type) [Required: no]

This function returns a schema that describes the configuration to be passed to init during plugin initialization. The return value is a C string, with memory owned by the plugin, representing the configuration schema. The type of schema returned is compliant with the ss_plugin_schema_type enumeration, and is written inside the schema_type output argument.

Although this function is non-required, it is common to implement it due to the benefits it brings. If get_init_schema is correctly implemented, the init function can assume the passed-in configuration string to always be well-formed. The plugin framework will take care of automatically parsing it against the provided schema and generating ad-hoc errors accordingly. This also serves as a piece of documentation for users about how the plugin needs to be configured.

Currently, the plugin framework only supports the JSON Schema format, which is represented by the SS_PLUGIN_SCHEMA_JSON enum value. If a plugin defines a JSON Schema, the framework will require the init configuration string to be a valid json-formatted string.

Writing the dummy enum value SS_PLUGIN_SCHEMA_NONE inside schema_type is equivalent to avoiding implementing the get_init_schema function itself, which ends up with the framework treating the init configuration as an opaque string with no additional checks.

set_config

ss_plugin_rc plugin_set_config(ss_plugin_t* s, const ss_plugin_set_config_input* i) [Required: no]

Sets a new plugin configuration when provided by the framework. The new configuration is provided by config as a string in ss_plugin_set_config_input* i.

This function should return:

SS_PLUGIN_SUCCESS (0) if the config is accepted
SS_PLUGIN_FAILURE (1) if the config is rejected

If rejected, the plugin should provide context in the string returned by get_last_error() before returning.

get_metrics

ss_plugin_metric* plugin_get_metrics(ss_plugin_t* s, uint32_t* num_metrics) [Required: no]

This function returns the pointer to the first element of an array containing plugin-provided custom metrics.

Each element of the array is a ss_plugin_metric which is defined in the plugin API as follows:

typedef struct ss_plugin_metric
{
 const char* name; //Opaque string representing the metric name.
 ss_plugin_metric_type type; // Metric type, indicates whether the metric value is monotonic or non-monotonic.
 ss_plugin_metric_value value; // Metric numeric value.
 ss_plugin_metric_value_type value_type; // Metric value data type, e.g. `uint64_t`.
} ss_plugin_metric;

Each metric defines its own name, value, type (monotonic or non-monotonic) and value type (data type of its numeric value).

The argument num_metrics is a return argument and must be set to the length of the array before returning. It can be set to 0 if no metrics are provided.

Event Sourcing Capability API

get_id

uint32_t plugin_get_id() [Required: varies]

This should return the event ID allocated to your plugin. During development and before receiving an official event ID, you can use the "Test" value of 999.

This function is required if get_event_source is defined and returns a non-empty string, otherwise it is considered optional. Returning zero is equivalent to not implementing the function. If the plugin has a non-zero ID and a non-empty event source, then its next_batch function is allowed to only return events of plugin type (code 322) with its own plugin ID and event source.

get_event_source

const char* plugin_get_event_source() [Required: varies]

This function returns a C string, with memory owned by the plugin, containing the plugin's event source. This event source is used for:

Associating Falco rules with plugin events--A Falco rule with a source: gizmo property will run on all events returned by the gizmo plugin's next_batch function.
Linking together plugins with field extraction capability and plugins with event sourcing capability. The first can list a given event source like gizmo in its get_extract_event_sources function, and they will get an opportunity to extract fields from all events returned by the "gizmo" plugin.
Ensuring that only one plugin at a time is loaded for a given source.

When defining a source, make sure it accurately describes the events from your plugin (e.g. use aws_cloudtrail for AWS CloudTrail events, not json or logs) and doesn't overlap with the source of any other plugin with event sourcing capability.

The only time where duplicate sources make sense are when a group of plugins can use a standard data format for a given event. For example, plugins might extract k8s_audit events from multiple cloud sources like gcp, azure, aws, etc. If they all format their events as json objects that have identical formats as one could obtain by using K8s Audit hooks, then it would make sense for the plugins to use the same source.

This function is required if get_id is defined and returns a non-zero ID, otherwise it is considered optional. Returning an empty string is equivalent to not implementing the function. If the plugin has a non-zero ID and a non-empty event source, then its next_batch function is allowed to only return events of plugin type (code 322) with its own plugin ID and event source.

open

ss_instance_t* plugin_open(ss_plugin_t* s, const char* params, int32_t* rc) [Required: yes]

This function is called to "open" a stream of events. The interpretation of a stream of events is up to the plugin author, but think of plugin_init as initializing the plugin software, and plugin_open as configuring the software to return events. Using a streaming audio analogy, plugin_init turns on the app, and plugin_open starts a streaming audio channel.

The same general guidelines apply for plugin_open as do for plugin_init:

All state related to sourcing a stream of events should be in the returned ss_instance_t pointer.
Return 0 on success, 1 on error. Be ready to return an error via plugin_get_last_error on error.
The plugin should support concurrent open sessions at once. Unlike plugin-level state, it's very likely that the plugin framework might call plugin_open multiple times for a given plugin.
On error, do not return any instance struct, as the plugin framework will not call plugin_close.

If a non-NULL ss_instance_t* instance is returned, then subsequent invocations of open must not return the same ss_instance_t* value again, unless it has been disposed with close first.

close

void plugin_close(ss_plugin_t* s, ss_instance_t* h) [Required: yes]

This function closes a stream of events previously started via a call to plugin_open. Afterwards, the stream should be considered closed and the framework will not call plugin_next_batch/plugin_extract_fields with the same ss_instance_t pointer.

next_batch

int32_t plugin_next_batch(ss_plugin_t* s, ss_instance_t* h, uint32_t *nevts, ss_plugin_event ***evts) [Required: yes]

This function is used to return a set of next events to the plugin framework, given a plugin state and open instance.

*evts should be updated to an allocated contiguous array of ss_plugin_event pointers. The memory for the structs array is owned by the plugin and should be held until the next call to plugin_next_batch. *nevts should be updated with the number of events returned.

An event is represented by a ss_plugin_event struct, which observes the same format of the libscap event block specification.

This function should return:

SS_PLUGIN_SUCCESS (0) on success
SS_PLUGIN_FAILURE (1) on failure
SS_PLUGIN_TIMEOUT (-1) on non-error but there are no events to return.
SS_PLUGIN_EOF (6) when the stream of events is complete.

If the plugin receives a SS_PLUGIN_FAILURE, it will close the stream of events by calling plugin_close.

If a plugin implements a specific event source (get_id is non-zero and get_event_source is non-empty), then, it is only allowed to produce events of type plugin (code 322) containing its own plugin ID (as returned by get_id). In such a case, when an event contains a zero plugin ID, the framework automatically sets the plugin ID of the event to the one of the plugin. If a plugin does not implement a specific event source, it is allowed to produce events of any of the types supported by the libscap specific.

SS_PLUGIN_TIMEOUT should be returned whenever no events can be returned immediately. This ensures that the plugin framework is not stalled waiting for a response from plugin_next_batch. When the framework receives a SS_PLUGIN_TIMEOUT, it will keep the stream of events open and call plugin_next_batch again later.

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. The value of the ss_plugin_event*** output parameter must be uniquely attached to the ss_instance_t* parameter value. The pointer must not be shared across multiple distinct ss_instance_t* values.

get_progress

const char* plugin_get_progress(ss_plugin_t* s, ss_instance_t* h, uint32_t* progress_pct) [Required: no]

If the plugin exports this function, the framework will periodically call it after open to return how much of the event stream has been read. If a plugin does not provide a bounded stream of events (for example, events coming from a file or other source that has an ending), it should not export this function.

If not exported, the plugin framework will not print meaningful process indicators while processing event streams.

When called, the progress_pct pointer should be updated with the read progress, as a number between 0 (no data has been read) and 10000 (100% of the data has been read). This encoding allows the engine to print progress decimals without requiring to deal with floating point numbers (which could cause incompatibility problems with some languages).

The return value is an string representation of the read progress, with the memory owned by the plugin. This might include the progress percentage combined with additional context added by the plugin. The plugin can return NULL. In this case, the framework will use the progress_pct value instead.

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. If the returned pointer is non-NULL, then it must be uniquely attached to the ss_instance_t* parameter value. The pointer must not be shared across multiple distinct ss_instance_t* values.

event_to_string

const char* plugin_event_to_string(ss_plugin_t *s, const ss_plugin_event_input *evt) [Required: no]

This function is used to return a printable representation of an event. The memory is owned by the plugin and can be freed on the next call to plugin_event_to_string. It is used in filtering/output expressions as the built-in field evt.plugininfo. Even if implemented, this function is ignored if a plugin does not implement a specific event source (get_id is undefined or returns zero, and get_event_source is undefined or returns an empty string).

The string representation should be on a single line and contain important information about the event. It is not necessary to return all information from the event. Simply return the most important fields/properties of the event that provide a useful default representation.

Here is an example output, from the cloudtrail plugin:

us-east-1 masters.some-demo.k8s.local s3 GetObject Size=0 URI=s3://some-demo-env/some-demo.k8s.local/backups/etcd/events/control/etcd-cluster-created

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. If the returned pointer is non-NULL, then it must be uniquely attached to the ss_plugin_t* parameter value. The pointer must not be shared across multiple distinct ss_plugin_t* values.

list_open_params

const char* plugin_list_open_params(ss_plugin_t* s, ss_plugin_rc* rc) [Required: no]

This function returns a list of suggested values that are valid parameters for the open plugin function. Although non-required, this function is useful to instruct users about potential valid parameters for opening a stream of events. Implementing this function also brings additional usage documentation for the plugin, and allows makes it more usable with automated tools.

The returned value is a json string, with memory owned by the plugin, which contains an array of objects. Each object describes one suggested value for the open function. Here's an example:

[
 {"value": "resource1", "desc": "An example of openable resource"},
 {"value": "resource2", "desc": "Another example of openable resource"}
 {
 "value": "res1;res2;res3",
 "desc": "Some names",
 "separator": ";"
 }
]

Each object has the following properties:

value: a string usable as a parameter for open
desc: (optional) a string with that describes the meaning of value.
separator: (optional) a string representing a separator string in case value represents a list of concatenated values. This can be used by plugins to specify an open param that represents more than one source, in which case they can be separated by the separator substring. It's a plugin responsibility to specify the separator string.

Field Extraction Capability API

get_fields

const char* plugin_get_fields() [Required: yes]

This function should return the set of fields supported by the plugin. Remember, a field is a name (e.g. proc.name) that can extract a value (e.g. nginx) from an event (e.g. a syscall event involving a process). The return value is a string whose memory is owned by the plugin. The string is json formatted and contains an array of objects. Each object describes one field. Here's an example:

[
 {"type": "string", "name": "gizmo.field1", "arg": {"isRequired": true, "isKey": true}, "desc": "Describing field 1"},
 {"type": "uint64", "name": "gizmo.field2", "desc": "Describing field 2", properties: ["hidden"]}
]

Each object has the following properties:

type: one of "string", "uint64", "bool", "reltime", "abstime", "ipaddr", "ipnet"
name: a string with a name for the field. By convention, this is a dot-separated path of names. Use a consistent first name e.g. "ct.xxx" to help filter authors associate the field with a given plugin.
isList: (optional) If present and set to true, notes that the field extracts a list of values. Fields of this kind can only be used with the in and intersects filtering operators. For list fields, extracting single values means extracting lists of length equal to 1.
arg: (optional) if present, notes that the field can accept an argument e.g. field[arg]. More precisely, the following flags could be specified:
- isRequired: if true, the argument is required.
- isIndex: if true, the field is numeric.
- isKey: if true, the field is a string. If isRequired is true, one between isIndex and isKey must be true, to specify the argument type. If isRequired is false, but one between isIndex and isKey is true, the argument is allowed but not required.
display: (optional) If present, a string that will be used to display the field instead of the name. Used in tools like wireshark.
desc: a string with a short description of the field. This will be used in help output so be concise and descriptive.
properties: (optional) If present, an array of additional properties that apply to the field. The value is an array of strings that can be one of the following:
- hidden: Do not display the field when using programs like falco --list to list the set of supported fields.
- conversation: This field is applicable for use in wireshark conversations, and denotes that the field represents one half of a "conversation" that can be shown in the conversations or endpoints view.
- info: Also applicable for use in wireshark, and denotes that it should be appended to the "info" column in the wireshark event list.

When defining fields, keep the following guidelines in mind:

Field names should generally have the plugin name/event source as the first component, and usually have one or two additional components. For example, gizmo.pid is preferred over gizmo.process.id.is. If a plugin has a moderately large set of fields, using components to group fields may make sense (e.g. cloudtrail.s3.bytes.in and cloudtrail.s3.bytes.out).
Fields should be idempotent: for a given event, the value for a field should be the same regardless of when/where the event was generated.
Fields should be neutral: define fields that extract properties of the event (e.g. "source ip address") rather than judgements (e.g. "source ip address is associated with a botnet").

extract_fields

int32_t plugin_extract_fields(ss_plugin_t *s, const ss_plugin_event_input *evt, const ss_plugin_field_extract_input* in) [Required: yes]

This function is used to return the value for one or more field names that were returned in plugin_get_fields. The framework provides an event and an input containing an array of ss_plugin_extract_field structs. Each struct has one field name/type, and the plugin fills in each struct with the corresponding value for that field.

The format of the ss_plugin_extract_field struct is the following:

// The noncontiguous numbers are to maintain equality with underlying
// falcosecurity/libs types.
typedef enum ss_plugin_field_type
{
 // A 64bit unsigned integer.
 FTYPE_UINT64 = 8,
 // A printable buffer of bytes, NULL terminated
 FTYPE_STRING = 9,
 // A relative time. Seconds * 10^9 + nanoseconds. 64bit.
 FTYPE_RELTIME = 20,
 // An absolute time interval. Seconds from epoch * 10^9 + nanoseconds. 64bit.
 FTYPE_ABSTIME = 21,
 // A boolean value, 4 bytes.
 FTYPE_BOOL = 25,
 // Either an IPv4 or IPv6 address. The length indicates which one it is.
 FTYPE_IPADDR = 40,
 // Either an IPv4 or IPv6 network. The length indicates which one it is.
 // The field encodes only the IP address, so this differs from FTYPE_IPADDR,
 // from the way the framework perform runtime checks and comparisons.
 FTYPE_IPNET = 41,
}ss_plugin_field_type;

typedef struct ss_plugin_extract_field
{
 union {
 const char** str;
 uint64_t* u64;
 uint32_t* u32;
 ss_plugin_bool* boolean;
 ss_plugin_byte_buffer* buf;
 } res;
 uint64_t res_len;

 uint32_t field_id;
 const char* field;
 const char* arg_key;
 uint64_t arg_index;
 bool arg_present;
 uint32_t ftype;
 bool flist;
} ss_plugin_extract_field;

For each struct, the plugin fills in field_id/field/arg/ftype with the field. field_id is the index into the original list of fields returned by plugin_get_fields, and allows for faster mapping to a plugin's set of fields. The plugin should fill in res_len and res with a pointer to an array of values of appropriate type for the field, depending on the field type ftype. If the field type is FTYPE_STRING, res should be updated to point to an string with the string value, with memory owned by the plugin. The plugin should retain this memory until the next call to plugin_extract_fields.

If res_len is set to zero, the plugin framework assumes that res is undefined and will not use it. Setting a res_len value grater than 1 is allowed only for fields for which isList is defined as true.

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. The value of the ss_plugin_extract_field* output parameter must be uniquely attached to the ss_plugin_t* parameter value. The pointer must not be shared across multiple distinct ss_plugin_t* values.

get_extract_event_sources

const char* plugin_get_extract_event_sources() [Required: no]

This function allows the plugin to restrict the kinds of events where the plugin's extract_fields method will be called. Valid event source names are the ones returned by the get_event_source function of plugins with event sourcing capability, or syscall for indicating support to non-plugin events. The return value should be a string containing a json array of compatible event sources, with memory owned by the plugin. Here's an example:

["aws_cloudtrail", "gcp_cloudtrail"]

This implies that the plugin can potentially extract values from events that have a source aws_cloudtrail or gcp_cloudtrail.

This function is optional. If the plugin does not export this function or if it returns an empty array (or NULL), then if the plugin has sourcing capability, and implements a specific event source, it will only receive events matching its event source, otherwise the framework will assume the plugin can receive events from all event sources.

get_extract_event_types

uint16_t* plugin_get_extract_event_types(uint32_t* numtypes) [Required: no]

This function allows the plugin to restrict the kinds of events where the plugin's extract_fields method will be called. The return value is an array of integers representing the event types that the plugin is capable of processing for field extraction. Events with types that are not present in the returned list will not be received by the plugin. The event types follow the enumeration from the libscap specific.

This function is optional. If the plugin does not export this function or if it returns an empty array (or NULL), the plugin will receive every event type if the result of get_extract_event_sources (either default or custom) is compatible with the syscall event source, otherwise the plugin will only receive events of plugin type (code 322).

Event Parsing Capability API

parse_event

ss_plugin_rc plugin_parse_event(ss_plugin_t *s, const ss_plugin_event_input *evt, const ss_plugin_event_parse_input* in) [Required: yes]

Receives an event from the current capture and parses its content. The plugin is guaranteed to receive an event at most once, after any operation related the event sourcing capability, and before any other operation related to the field extraction capability. The returned rc value should be SS_PLUGIN_SUCCESS (0) on success, SS_PLUGIN_FAILURE (1) on failure.

The framework provides an event and an input. The event pointer is allocated and owner by the framework, and it is not guaranteed that to refer to the same memory or data returned by the last next_batch call (in case the same plugin also supports the event sourcing capability). The input is a vtable containing callbacks towards the plugin's owner that can be used by the plugin for performing read/write operations on state tables not owned by itself, for which it obtained accessors at initialization time. The plugin does not need to go through this vtable in order to read and write from a table it owns.

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. The value of the ss_plugin_event_parse_input* output parameter must be uniquely attached to the ss_plugin_t* parameter value. The pointer must not be shared across multiple distinct ss_plugin_t* values.

get_parse_event_sources

const char* plugin_get_parse_event_sources() [Required: no]

This function allows the plugin to restrict the kinds of events where the plugin's parse_event method will be called. Valid event source names are the ones returned by the get_event_source function of plugins with event sourcing capability, or syscall for indicating support to non-plugin events. The return value should be a string containing a json array of compatible event sources, with memory owned by the plugin.

get_parse_event_types

uint16_t* plugin_get_parse_event_types(uint32_t* numtypes) [Required: no]

This function allows the plugin to restrict the kinds of events where the plugin's parse_event method will be called. The return value is an array of integers representing the event types that the plugin is capable of processing for field extraction. Events with types that are not present in the returned list will not be received by the plugin. The event types follow the enumeration from the libscap specific.

This function is optional. If the plugin does not export this function or if it returns an empty array (or NULL), the plugin will receive every event type if the result of get_parse_event_sources (either default or custom) is compatible with the syscall event source, otherwise the plugin will only receive events of plugin type (code 322).

Async Events Capability API

get_async_event_sources

const char* plugin_get_async_event_sources() [Required: no]

The return value should be a string containing a json array of compatible event sources, with memory owned by the plugin. The list describes the event sources for which this plugin is capable of injecting async events in the event stream of a capture.

This function is optional. If the plugin does not export this function or if it returns an empty array (or NULL), then the async events produced by a plugin will be injected in the event stream of any source.

get_async_events

const char* plugin_get_async_events() [Required: yes]

Return a string describing the name list of all asynchronous events that this plugin is capable of pushing into a live event stream. The framework can reject async events produced by a plugin if their name is not on the name list returned by this function. The return value should be a string containing a json array of compatible event sources, with memory owned by the plugin.

set_async_event_handler

ss_plugin_rc plugin_set_async_event_handler(ss_plugin_t* s, ss_plugin_owner_t* owner, const ss_plugin_async_event_handler_t handler) [Required: yes]

Sets a function handler that allows the plugin to send events asynchronously to its owner during a live event capture. The handler is a thread-safe function that can be invoked concurrently by multiple threads. The asynchronous events must be encoded as an async event type (code 402) as for the libscap specific. The returned rc value should be SS_PLUGIN_SUCCESS (0) on success, SS_PLUGIN_FAILURE (1) on failure.

The memory of events sent to the async event handler function must be owned by the plugin and is not retained by the owner after the event handler returns. The async event handler function is defined as follows:

// Function handler used by plugin for sending asynchronous events to the
// Falcosecurity libs during a live event capture. The asynchronous events
// must be encoded as an async event type (code 402) as for the libscap specific.
// The function returns SS_PLUGIN_SUCCESS in case of success, or
// SS_PLUGIN_FAILURE otherwise. If a non-NULL char pointer is passed for
// the "err" argument, it will be filled with an error message string
// in case the handler function returns SS_PLUGIN_FAILURE. The error string
// has a max length of PLUGIN_MAX_ERRLEN (termination char included) and its
// memory must be allocated and owned by the plugin.
typedef ss_plugin_rc (*ss_plugin_async_event_handler_t)(ss_plugin_owner_t* o, const ss_plugin_event *evt, char* err);

The plugin can start sending async events through the passed-in handler right from the moment this function is invoked. set_async_event_handler can be invoked multiple times during the lifetime of a plugin. In that case, the registered function handler remains valid up until the next invocation of set_async_event_handler on the same plugin, after which the new handler set must replace any already-set one. If the handler is set to a NULL function pointer, the plugin is instructed about disabling or stopping the production of async events. If a NULL handler is set, and an asynchronous job has been started by the plugin before, the plugin should stop the job and wait for it to be finished before returning from this function. Although the event handler is thread-safe and can be invoked concurrently, this function is still invoked by the framework sequentially from the same thread.

The C++ example below shows how an async event handler can be correctly used from an asynchronous thread with proper start and stop conditions:

typedef struct my_plugin
{
 std::thread async_thread;
 std::atomic<bool> async_thread_run;
} my_plugin;

extern "C" ss_plugin_t* plugin_init(const ss_plugin_init_input* in, ss_plugin_rc* rc)
{
 my_plugin *ret = new my_plugin();
 ret->async_thread_run = false;
 *rc = SS_PLUGIN_SUCCESS;
 return ret;
}

extern "C" void plugin_destroy(ss_plugin_t* s)
{
 // stop the async thread if it's running
 my_plugin *ps = (my_plugin *) s;
 if (ps->async_thread_run)
 {
 ps->async_thread_run = false;
 if (ps->async_thread.joinable())
 {
 ps->async_thread.join();
 }
 }
 delete ps;
}

...

extern "C" ss_plugin_rc plugin_set_async_event_handler(ss_plugin_t* s, ss_plugin_owner_t* owner, const ss_plugin_async_event_handler_t handler)
{
 my_plugin *ps = (my_plugin *) s;

 // stop the async thread if it's running
 if (ps->async_thread_run)
 {
 ps->async_thread_run = false;
 if (ps->async_thread.joinable())
 {
 ps->async_thread.join();
 }
 }

 // if an handler is provided, launch an async worker
 if (handler)
 {
 ps->async_thread_run = true;
 ps->async_thread = std::thread([ps, owner, handler]()
 {
 char err[PLUGIN_MAX_ERRLEN];
 while (ps->async_thread_run;)
 {
 ss_plugin_event* evt = ps->do_some_work();
 if (handler(owner, evt, err) != SS_PLUGIN_SUCCESS)
 {
 // report the error somehow
 }
 }
 });
 }

 return SS_PLUGIN_SUCCESS;
}

Async events encode a plugin ID that defines its event source. However, this value is set by the framework when the async event is received, and is set to the ID associated to the plugin-defined event source currently open during a live capture, or zero in case of the syscall event source. The event source assigned by the framework to the async event can only be among the ones compatible with the list returned by get_async_event_sources.

Async events encode a string representing their event name, which is used for runtime matching and define the encoded data payload. Plugins are allowed to only send async events with one of the names expressed in the list returned by get_async_events. The name of an async event acts as a contract on the encoding of the data payload of all async events with the same name.

Libscap Event Block Specification

Libscap, the Falcosecurity libs component responsible of event captures and control, proposes and supports a specification that regulates the way system, kernel, and plugin events are encoded. The same specification also defines the encoding of SCAP capture files, that can be used by the Falcosecurity libs to record and replay event streams. In the specification, events are defined as a specific block type of the pcap-ng file format. All the event types and the associated parameters supported by libscap are defined by the libscap's event table. The plugin API fully shares and observes the libscap's event definitions, and uses them for both reading and writing events from/to the framework.

As for the libscap specific, an event is represented as a contiguous region of memory composed by a header and a list of parameters appended to it, in the form of:

// | evt header | len param 1 (2B/4B) | ... | len param N (2B/4B) | data param 1 | ... | data param N |
typedef struct ss_plugin_event {
 uint64_t ts; /* timestamp, in nanoseconds from epoch */
 uint64_t tid; /* the tid of the thread that generated this event */
 uint32_t len; /* the event len, including the header */
 uint16_t type; /* the event type */
 uint32_t nparams; /* the number of parameters of the event */
} ss_plugin_event;

The event header is composed of:

ts: the event timestamp, in nanoseconds since the epoch. Can be (uint64_t)-1, in which case the framework will automatically fill the event time with the current time.
tid: the tid of the thread that generated this event. Can be (uint64_t)-1 in case no thread is specified, such as when generating a plugin event (type code 322).
len: the event len, including the header
type: the code of the event, as per the ones supported by the libscap specific. This dictates the number and kind of parameters, and whether the length is encoded as a 2 bytes or 4 bytes integer.
nparams: the number of parameters of the event

Further and more formal documentation will be available in the future...

State Tables API

In the plugin framework, state tables are simple key-value mappings representing a piece of state owned by a component of the Falcosecurity libs or defined by a plugin. The plugin API declares formal abstract definitions for state tables and provides means for plugins to access the state owned by other components of the framework, define and own their own state, and make it accessible externally. In this context, a component of the framework is an abstract entity that could represent a given piece of machinery within the Falco libraries or any other plugin loaded at runtime.

Basic Concepts

A state table is a key-value map that can be used for storing pieces of state within the plugin framework. State tables are an abstract concept, and the plugin API does not enforce any specific implementation. Instead, the API specifies interface boundaries in the form of C virtual tables of methods representing the behavior of state tables. This allows the plugin API to remain flexible, abstract, and multi-language by nature. The model by which state tables work is defined by the notions of ownership, registration, and discovery.

Every state table must have an owner, which is responsible of managing the table's memory and of implementing all the functions of the state tables API. Owners can either be plugins or any of the other actors that are part of the Falcosecurity libraries. For example, libsinsp is the owner of the threads table, which is a key-value store where the key is a thread ID of a Linux machine and the value is a set of information describing a Linux thread. Plugins can access the threads table of libsinsp for retrieving thread information given a thread ID, reading and writing the info fields, extending the info with additional metadata, and do much more. However, plugins are never responsible of managing the memory and the implementation of the threads table, as it is owned by libsinsp only. Instead, plugins can do the same by defining their own stateful components and implementing the required interface functions to register them as "state tables". Stateful components must be registered in the framework in order to be considered "state tables". Libsinsp, which owns the plugins loaded at runtime, also holds a "table registry" that is the source of truth for all the state tables known at runtime. Once a state table is registered in the table registry, it is discoverable by all the actors and plugins running in the context of the same Falcosecurity libs instance.

The way plugins can interact with state tables is through discovery and the usage of accessors. At initialization time (in the init function), plugins are provided interface functions that allow them to list all the state tables available at runtime and obtaining "accessors" for later usage. An accessor is an opaque pointers obtained at initialization time and that can be used later (e.g. when parsing an event or when extracting a field) for accessing a given table or the fields of its entries. Considering the example of the threads table, in its init function a given plugin could obtain an accessor to the table and to some of the fields of each thread info (such as the pid or the comm) and store them in its plugin state. Later, when extracting a field, the same plugin would be available to query the threads table for a given thread ID (perhaps obtained by reading the event payload of a syscall) by using the table accessor, and then reading the pid of the obtained thread by using the field accessor.

Inherently, the plugin API also enable plugins to define their own state tables and register them in the table registry. Once that's done, the registered state table will be visible to all other plugins just like the threads table, without knowing nor caring about which actor is owning it. The state table owned by the plugin will be discoverable through the table registry by the plugin itself too. However, plugins owning a given table are not forced to go through the state tables interface in order to operate on it (conversely, this could also be the less efficient choice). Plugins can implement their own state as they prefer, whereas the purpose of the state tables interface is solely to make that state available to other actors in the framework. Coherently, table owners can also decide "how much" of a table they want the other components to have visibility of. For example, libsinsp can access more info and functionalities on the threads table than what it makes available through the state table interface, which is also natural considering that its implementation is hidden and can be arbitrary.

The set of state tables made available by a given plugin or Falcosecurity libs actor, and the set of fields and operations available for each of those table, take part of the semantic versioned UX contract of that plugin or actor. For example, removing a given table or table field from libsinsp can be considered a breaking change that must reflected by the version number of the Falcosecurity libs. The same applies for the version of each plugin and the state tables declared by them.

Access and Consistency

State tables are dynamic structures. Each table is defined by a given key type, which can be any of the types supported by the ss_plugin_state_type enumeration. Then, the each key-value mappings contained in the table are referred to as table entries. Each entry has a specific set of information fields, which is shared across all the entries of the same table. Each field is named and has a specific type. The set of fields for the entries of a given table is defined dynamically at runtime and can be extended by different actors. For example, libsinsp populates the threads table with a given set of information fields for each table's entry (representing a given thread info), and plugins can read and write the value of those fields by obtaining accessors for those. However, plugins also have the opportunity of defining new fields inside the threads table, with a new unique name and a specific type, and libsinsp will be responsible of hosting that new piece of information for each thread and make it available to all actors in the framework. The same can happen for tables defined by any plugin.

Given that state tables can get modified by different actors at runtime, there has to be a deterministic disambiguation about consistency of table edits and visibility of those changes. The plugin API implements this by guaranteeing a deterministic and non-changing total ordering of all the actors in the system. Considering a given ordering, an actor will have visibility only over the changes applied by actors coming before it in the given ordering. In the Falcosecurity libs and the plugin framework, the guaranteed order is the one by which plugins are loaded at runtime. The first actor in the order is always libsinsp itself, which means that all plugins will always see all the table modifications authored by libsinsp at a given point in time. Then, plugins are ordered by following their loading order at runtime. This means that if Plugin B is loaded in Falco after Plugin A, then Plugin B will see all the table changes performed by Plugin A at runtime, but not the contrary (however, they'll both have visibility over the changes performed by libsinsp). As such the plugins loading order in Falco can be functionally relevant.

Subtables and complex data types

The plugin framework supports a special table field type which is the table type. Table entries can use this field to store the handle to another table, which means each entry can have its own subtables.

For example, the threads table has a field named file_descriptors. This field allows accessing the file descriptor table of every thread, making it possible to access useful information about a specific open file descriptor like file name, pid, and much more.

This also unlocks the ability for tables to store/access arrays, maps or even more complex data types. The plugin can "wrap" the complex type in a table by implementing the interface functions for that type, allowing the complex data types to be stored as a subtable.

Obtaining Accessors

Before performing any operation over state tables, plugins must first obtain accessors for each of them. This can happen only at initialization time through a vtable that is passed only to the init plugin function. The vtable allows plugins to discover all the tables registered in the framework, get accessors for them, and register their own tables. Once an accessor is obtained, plugins must maintain it up until they are destroyed, and use it during functions related to specific capabilities (e.g. field extraction, event parsing). The vtable passed to init is reported below.

// Vtable for controlling and the fields for the entries of a state table.
// This allows discovering the fields available in the table, defining new ones,
// and obtaining accessors usable at runtime for reading and writing the fields'
// data from each entry of a given state table.
typedef struct
{
 // Returns a pointer to an array containing info about all the fields
 // available in the entries of the table. nfields will be filled with the number
 // of elements of the returned array. The array's memory is owned by the
 // tables's owner. Returns NULL in case of error.
 ss_plugin_table_fieldinfo* (*list_table_fields)(ss_plugin_table_t* t, uint32_t* nfields);
 //
 // Returns an opaque pointer representing an accessor to a data field
 // present in all entries of the table, given its name and type.
 // This can later be used for read and write operations for all entries of
 // the table. The pointer is owned by the table's owner.
 // Returns NULL in case of issues (including when the field is not defined
 // or it has a type different than the specified one).
 ss_plugin_table_field_t* (*get_table_field)(ss_plugin_table_t* t, const char* name, ss_plugin_state_type data_type);
 //
 // Defines a new field in the table given its name and data type,
 // which will then be available in all entries contained in the table.
 // Returns an opaque pointer representing an accessor to the newly-defined
 // field. This can later be used for read and write operations for all entries of
 // the table. The pointer is owned by the table's owner.
 // Returns NULL in case of issues (including when a field is defined multiple
 // times with different data types).
 ss_plugin_table_field_t* (*add_table_field)(ss_plugin_table_t* t, const char* name, ss_plugin_state_type data_type);
} ss_plugin_table_fields_vtable;

typedef struct
{
 // Returns a pointer to an array containing info about all the tables
 // registered in the plugin's owner. ntables will be filled with the number
 // of elements of the returned array. The array's memory is owned by the
 // plugin's owner. Returns NULL in case of error.
 ss_plugin_table_info* (*list_tables)(ss_plugin_owner_t* o, uint32_t* ntables);
 //
 // Returns an opaque accessor to a state table registered in the plugin's
 // owner, given its name and key type. Returns NULL if an case of error.
 ss_plugin_table_t* (*get_table)(ss_plugin_owner_t* o, const char* name, ss_plugin_state_type key_type);
 //
 // Registers a new state table in the plugin's owner. Returns
 // SS_PLUGIN_SUCCESS in case of success, and SS_PLUGIN_FAILURE otherwise.
 // The state table is owned by the plugin itself, and the input will be used
 // by other actors of the plugin's owner to interact with the state table.
 ss_plugin_rc (*add_table)(ss_plugin_owner_t* o, const ss_plugin_table_input* in);
 //
 // Vtable for controlling operations related to fields on the state tables
 // registered in the plugin's owner.
 ss_plugin_table_fields_vtable fields;
} ss_plugin_init_tables_input;

Obtaining subtables accessors

Obtaining table accessors is a bit different for subtables.

Table accessors can be only obtained at initialization time, however tables may be empty at this time, which means subtables may not yet exist. The solution to this problem is to create a table entry just to get its subtables.

Please note that this newly created entry is temporary and it should be used only at initialization time to obtain subtable accessors.

The following example shows how to obtain accessors for the file descriptor subtable:

struct plugin_state
{
 ss_plugin_table_t* thread_table;
 ss_plugin_table_field_t* table_field_fdtable;
 ss_plugin_table_field_t* table_field_fdtable_name;
};

static ss_plugin_t* plugin_init(const ss_plugin_init_input* in, ss_plugin_rc* rc)
{
 plugin_state *ret = new plugin_state();

 // get the accessor to the threads table
 ret->thread_table = in->tables->get_table(in->owner, "threads", ss_plugin_state_type::SS_PLUGIN_ST_INT64);

 // get an accessor to the subtable field
 ret->table_field_fdtable = in->tables->fields.get_table_field(ret->thread_table, "file_descriptors", ss_plugin_state_type::SS_PLUGIN_ST_TABLE);

 // create a new table entry
 auto entry = in->tables->writer_ext->create_table_entry(ret->thread_table);

 // read the subtable handle from the new entry
 ss_plugin_state_data data;
 in->tables->reader_ext->read_entry_field(ret->thread_table, entry, ret->table_field_fdtable, &data);
 auto fdtable = data.table;

 //obtain the accessor to one of the subtable fields
 ret->table_field_fdtable_name = in->tables->fields_ext->get_table_field(fdtable, "name", ss_plugin_state_type::SS_PLUGIN_ST_STRING);

 //destroy the temporary entry
 in->tables->writer_ext->destroy_table_entry(ret->thread_table, entry);
}

Accessing Tables

After obtaining accessors for all the tables and fields a given plugin is interested into, they can be used for performing operations over tables at runtime. Table operations are split in the two "reading" and "writing" categories, each having their own vtable and set of functions. The "reader" and the "writer" vtables are passed to the interested plugin functions for different capabilities, depending on their scope. For example, the extract_fields function of the field extraction capability gets passed the state tables reader vtable, whereas the parse_event function of the event parsing capability has access to both the reader and writer vtables. This enforces users to only apply state tables modifications at event parsing time, leaving field extraction a "stateless" code path. The reader and writer vtables and their respective functions are reported below.

// Vtable for controlling a state table for read operations.
typedef struct
{
 // Returns the table's name, or NULL in case of error.
 // The returned pointer is owned by the table's owner.
 const char* (*get_table_name)(ss_plugin_table_t* t);
 //
 // Returns the number of entries in the table, or ((uint64_t) -1) in
 // case of error.
 uint64_t (*get_table_size)(ss_plugin_table_t* t);
 //
 // Returns an opaque pointer to an entry present in the table at the given
 // key, or NULL in case of issues (including if no entry is found at the
 // given key). The returned pointer is owned by the table's owner.
 ss_plugin_table_entry_t* (*get_table_entry)(ss_plugin_table_t* t, const ss_plugin_state_data* key);
 //
 // Reads the value of an entry field from a table's entry.
 // The field accessor must be obtained during plugin_init().
 // The read value is stored in the "out" parameter.
 // Returns SS_PLUGIN_SUCCESS if successful, and SS_PLUGIN_FAILURE otherwise.
 ss_plugin_rc (*read_entry_field)(ss_plugin_table_t* t, ss_plugin_table_entry_t* e, const ss_plugin_table_field_t* f, ss_plugin_state_data* out);
} ss_plugin_table_reader_vtable;

// Vtable for controlling a state table for write operations.
typedef struct
{
 // Erases all the entries of the table.
 // Returns SS_PLUGIN_SUCCESS if successful, and SS_PLUGIN_FAILURE otherwise.
 ss_plugin_rc (*clear_table)(ss_plugin_table_t* t);
 //
 // Erases an entry from a table at the given key.
 // Returns SS_PLUGIN_SUCCESS if successful, and SS_PLUGIN_FAILURE otherwise.
 ss_plugin_rc (*erase_table_entry)(ss_plugin_table_t* t, const ss_plugin_state_data* key);
 //
 // Creates a new entry that can later be added to the same table it was
 // created from. The entry is represented as an opaque pointer owned
 // by the plugin. Once obtained, the plugin can either add the entry
 // to the table through add_table_entry(), or destroy it through
 // destroy_table_entry(). Returns an opaque pointer to the newly-created
 // entry, or NULL in case of error.
 ss_plugin_table_entry_t* (*create_table_entry)(ss_plugin_table_t* t);
 //
 // Destroys a table entry obtained by from previous invocation of create_table_entry().
 void (*destroy_table_entry)(ss_plugin_table_t* t, ss_plugin_table_entry_t* e);
 //
 // Adds a new entry to a table obtained by from previous invocation of
 // create_table_entry() on the same table. The entry is inserted in the table
 // with the given key. If another entry is already present with the same key,
 // it gets replaced. After insertion, table will be come the owner of the
 // entry's pointer. Returns an opaque pointer to the newly-added table's entry,
 // or NULL in case of error.
 ss_plugin_table_entry_t* (*add_table_entry)(ss_plugin_table_t* t, const ss_plugin_state_data* key, ss_plugin_table_entry_t* entry);
 //
 // Updates a table's entry by writing a value for one of its fields.
 // The field accessor must be obtained during plugin_init().
 // The written value is read from the "in" parameter.
 // Returns SS_PLUGIN_SUCCESS if successful, and SS_PLUGIN_FAILURE otherwise.
 ss_plugin_rc (*write_entry_field)(ss_plugin_table_t* t, ss_plugin_table_entry_t* e, const ss_plugin_table_field_t* f, const ss_plugin_state_data* in);
} ss_plugin_table_writer_vtable;

Accessing subtables

Subtables handles can be obtained just like any other field, by reading the table type field of an entry.

After obtaining subtables handles and fields accessors, accessing subtables is the same as accessing regular tables.

The following example shows how to access fields from the file_descriptors subtable from one of the entries of the threads table:

ss_plugin_rc plugin_parse_event(ss_plugin_t *s, const ss_plugin_event_input *ev, const ss_plugin_event_parse_input* in)
{
 plugin_state *ps = (plugin_state *) s;
 ss_plugin_state_data tmp;

 // get an entry from the thread table
 tmp.s64 = ev->evt->tid;
 ss_plugin_table_entry_t* thread_entry = in->table_reader_ext->get_table_entry(ps->thread_table, &tmp);

 // read the file_descriptors field from the entry
 in->table_reader_ext->read_entry_field(ps->thread_table, thread_entry, ps->table_field_fdtable, &tmp);
 ss_plugin_table_t* fdtable = tmp.table;

 // get an entry from the file descriptors table of the previously read thread
 tmp.s64 = 0;
 ss_plugin_table_entry_t* fd_entry = in->table_reader_ext->get_table_entry(fdtable, &tmp);

 // read a field from the entry in the file descriptors table
 in->table_reader_ext->read_entry_field(fdtable, fd_entry, ps->table_field_fdtable_name, &tmp);
}

Registering State Tables

On top of accessing tables owned by the framework or other plugins, each plugin can also make part (or all) of its state available to other actors in the framework in the form of state tables. In this case, the plugin is responsible of providing all the necessary vtables and their respective functions, just like the Falcosecurity libraries do for the tables owned by them (e.g. the threads table). Plugins have total freedom towards how the table is actually implemented, as long as they respect the API functions in the vtables and they own all the memory related to the table and its entries. Plugins also have the freedom of not supporting some of the functions of the vtables, however they are not allowed to pass NULL-pointing function references. The struct by which plugins register their state table and the related vtable functions is reported below.

// Plugin-provided input passed to the add_table() callback of
// ss_plugin_init_tables_input, that can be used by the plugin to inform its
// owner about one of the state tables owned by the plugin. The plugin
// is responsible of owning all the memory pointed by this struct and
// of implementing all the API functions. These will be used by other
// plugins loaded by the falcosecurity libraries to interact with the state
// of a given plugin to implement cross-plugin state access.
typedef struct
{
 // The name of the state table.
 const char* name;
 //
 // The type of the sta table's key.
 ss_plugin_state_type key_type;
 //
 // A non-NULL opaque pointer to the state table.
 // This will be passed as parameters to all the callbacks defined below.
 ss_plugin_table_t* table;
 //
 // Vtable for controlling read operations on the state table.
 ss_plugin_table_reader_vtable reader;
 //
 // Vtable for controlling write operations on the state table.
 ss_plugin_table_writer_vtable writer;
 //
 // Vtable for controlling operations related to fields on the state table.
 ss_plugin_table_fields_vtable fields;
} ss_plugin_table_input;

Thread-safety and Reproducibility

State access is not thread-safe. Operations related to either discovery, reading, or writing, must all be executed in the synchronous context and within the thread in which the framework invokes the given plugin function that is capable of accessing tables. For example, plugins are only allowed to read from a table during the execution of extract_fields or parse_event, but they are not allowed to launch an asynchronous thread that reuses the same accessors to read from a table after any of those functions have returned.

Also, the previous sections imply that state tables can be operated on during the execution of various plugin functions, but that however only the parse_event function of the event parsing capability can perform write operations. This is by purpose and design due to the architecture of the Falcosecurity libraries themselves.

There may be use cases when the state update results of some asynchronous job and computation. For example, the Falcosecurity libraries implement the container metadata enrichment support by connecting to one or more container runtime sockets and fetching information asynchronously using a separate thread of the main event processing loop. In those cases, state updates must still happen synchronously. The async events capability is the strategy provided by the plugin framework. With that, plugins are provided with a thread-safe callback that they can use to inject asynchronous events in the currently-open event stream, and the framework will guarantee those events to be later received by functions such as parse_event or extract_fields just like any other events. Plugins can only safely utilize asynchronously-obtained information for state updates and field extraction through this messaging-like communication mode.

An additional effect of injecting asynchronous events in an event stream is that they can so be recorded in SCAP capture files, thus being reproducible when reading events later from that capture files. By having the asynchronous information recorded in the event stream, the event parsing and field extraction plugin functions will be able to work just like in live capture mode by also making all the state transitions reproducible and deterministic.

Docs: Falco Plugins Go SDK Walkthrough

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

The Go SDK provides prebuilt constructs and definitions that help developing plugins by abstracting all the complexities related to the bridging between the C and the Go runtimes. The Go SDK takes care of satisfying all the plugin framework requirements without having to deal with the low-level details, by also optimizing the most critical code paths.

The SDK allows developers to choose either from a low-level set of abstractions, or from a more high-level set of packages designed for simplicity and ease of use. The best way to approach the Go SDK is to start by importing a few high-level packages, which is enough to satisfy the majority of use cases.

This section documents the Go SDK at a high-level, please refer to the official Go SDK documentation for deeper details.

Architecture of the Go SDK

Since Falcosecurity plugins run in a C runtime, the Go SDK has been designed to abstract most of the complexity related to writing C-compliant code acceptable by the plugin framework, so that developers can focus on writing Go code only.

At a high level, the SDK is on top of three fundamental packages with different levels of abstractions:

Package sdk is a container for all the basic types, definitions, and helpers that are reused across all the SDK parts.
Package sdk/symbols contains prebuilt implementations for all the C symbols that plugins must export to be accepted by the framework. The prebuilt C symbols are divided in many subpackages, so that each of them can be imported individually to opt-in/opt-out each symbol.
Package sdk/plugins provide high-level definition and base types for implementing plugin capabilities. This uses sdk/symbols internally and takes care of importing all the prebuilt C symbols required each plugin capability respectively. This is the main entrypoint for developers to write plugins in Go.

Two additional packages ptr and cgo are used internally to simplify and optimize the state management and the usage of C-allocated memory pointers.

For some use cases, developers can consider using the SDK layers selectively. This is meaningful only if developers wish to manually write part of the low-level C details of the framework in their plugins, but still want to use some parts of the SDK. However, this is discouraged if not for advanced use cases only. Developers are encouraged to use the sdk/plugins to build Falcosecurity plugins, which is easier to use and will have less frequent breaking changes.

Further details can be found in the documentation of each package: sdk, sdk/symbols, and sdk/plugins.

Getting Started

The SDK is built on top of a set of minimal composable interfaces describing the behavior of plugins and plugin instances. As such, developing plugins is as easy as defining a struct type representing the plugin itself, ensuring that the mandatory interface methods are defined on it, and then registering it to the SDK.

To use the Go SDK, all you need to import are the sdk and sdk/plugins packages. The first contains all the core types and definitions used across the rest of the SDK packages, whereas the latter contains built-in constructs to develop plugins. The subpackages sdk/plugins/source and sdk/plugins/extractor contain specialized definitions for the event sourcing and the field extraction capabilities respectively.

The dummy plugin, documented in the next sections, is a simple example that helps understand how to start writing Go plugins with this SDK. The SDK also provides a set of base examples to get you started with plugin development.

Defining a Plugin with Field Extraction Capability

In the Go SDK, a plugin with field extraction capability is a type implementing the following interface:

// sdk/plugins/extractor
type Plugin interface {
 ...
 Info() *sdk.Info
 Init(config string) error
 Fields() []sdk.FieldEntry
 Extract(req sdk.ExtractRequest, evt sdk.EventReader) error
}

Info() returns all the info about the plugin. The returned plugins.Info struct should be filled in by the plugin author and contains fields such as the plugin ID, name, description, etc.

Init() method is called to initialize a plugin when the framework allocates it. A user-defined configuration string is passed by the framework. This is where the plugin can initialize its internal state and acquire all the resources it needs.

Fields() returns an array of sdk.FieldEntry representing all the fields supported by a plugin for extraction. The order of the fields is relevant, as their index is used as an identifier during extraction.

Extract() extracts the value of one of the supported fields from a given event passed in by the framework. The sdk.ExtractRequest argument should be used to set the extracted value.

Optional Interfaces

type Destroyer interface {
 Destroy()
}

type InitSchema interface {
 InitSchema() *SchemaInfo
}

Plugins with field extraction capability can optionally implement the sdk.Destroyer interface. In that case, Destroy() will be called when the plugin gets destroyed and can be used to release any allocated resource. they can also also optionally implement the sdk.InitSchema interface. In that case, InitSchema() will be used to to return a schema describing the data expected to be passed as a configuration during the plugin initialization. This follows the semantics documented for get_init_schema. Currently, the schema must follow the JSON Schema specific, which in Go can also be easily auto-generated with external packages (e.g. alecthomas/jsonschema).

Defining a Plugin with Event Sourcing Capability

In the Go SDK, a plugin with event sourcing capability must specify two types, one of the plugin itself and one for the plugin instances, implementing the following interfaces respectively:

// sdk/plugins/source
type Plugin interface {
 ...
 Info() *sdk.Info
 Init(config string) error
 Open(params string) (Instance, error)
}

// sdk/plugins/source
type Instance interface {
 ...
 NextBatch(pState PluginState, evts EventWriters) (int, error)
}

The source.Plugin interface has many functions in common with extractor.Plugin.

Open() creates a new plugin instance to open a new stream of events. The framework provides the user-defined open parameters to customize the event source. The return value must implement the source.Instance interface, and its lifecycle ends when the event stream is closed.

The source.Instance interface represents plugin instances for an opened event stream, and has one mandatory method and a few optional ones.

NextBatch creates a new batch of events to be pushed in the event stream. The SDK provides a pre-allocated batch to write events into, in order to manage the used memory optimally.

Optional Interfaces

type Destroyer interface {
 Destroy()
}

type Closer interface {
 Close()
}

type InitSchema interface {
 InitSchema() *SchemaInfo
}

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

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

type Stringer interface {
 String(evt sdk.EventReader) (string, error)
}

Plugins with event sourcing capabilities can optionally implement the sdk.Destroyer and sdk.InitSchema interfaces, just like mentioned in the section above.

Additionally, they can also implement the sdk.OpenParams interface. If requested by the application, the framework may call OpenParams() before opening the event stream to obtains some suggested values that would valid parameters for Open(). For more details, see the documentation of list_open_params.

Plugin instances can optionally implement the sdk.Closer, sdk.Progresser, and sdk.Stringer interfaces. If sdk.Closer is implemented, the Close() method is called while closing the event stream and can be used to release the resources used by the plugin instance. If sdk.Progresser is implemented, the Progress() method is called by the SDK when the framework requests progress data about the event stream of the plugin instance. Progress() must return a float64 with a value between 0 and 1 representing the current progress percentage, and a string representation of the same progress value. If sdk.Stringer is implemented, the String() method must return a string representation of an event created by the plugin, which is used by the framework as an extraction value of the evt.plugininfo field. The string representation should be on a single line and contain important information about the event.

Best Practices and Go SDK Prebuilts for Source Instances

Although the Go SDK gives developers high control and flexibility, in the general case implementing the sdk.NextBatcher interface is not trivial. Custom definitions of source.Instance require developers to be mindful of the following while implementing the NextBatch() function:

It should return as fast as possible and should try to fill-up event batch up to its maximum capacity
Listen for a timeout of few milliseconds and return the batch in its current state once the timeout is expired
Conceive the case in which Close() is called before NextBatch() has returned. This can potentially happen if the plugin framework receives signals such as SIGINT or SIGTERM
Minimize the number of memory allocations
Keep returning sdk.ErrEOF after returning it the first time

Considering the above, the SDK provides prebuilt implementations of source.Instance that satisfy a broad range of use cases, so that developers need to define their own type only if they have advanced or custom requirements.

// sdk/plugins/source

func NewPullInstance(pull source.PullFunc, options ...func(*<unexported-type>)) (source.Instance, error)

func NewPushInstance(evtC <-chan source.PushEvent, options ...func(*<unexported-type>)) (source.Instance, error)

source.NewPullInstance and source.NewPushInstance are two constructors for SDK-provided source.Instance implementations that cover the following use cases:

Pull Model: for when the event source can be implemented sequentially and the time required to generate a sequence of event is deterministic. This is implemented with a functional design, where the passed-in callback is expected to be non-suspensive and to return quickly
Push Model: for when the event source can be suspensive and there is no time guarantee regarding when an event gets produced. For instance, this applies for all event sources that generate events from webhook events. Given the event-driven nature of this use case, this is implemented by passing event data in the form of byte slices through a channel

The prebuilt source.Instances can be configured in the function constructors by using the Go options pattern. The SDK provides options for configuring and overriding all the default values:

// sdk/plugins/source

func WithInstanceContext(ctx context.Context) func(*<unexported-type>)

func WithInstanceTimeout(timeout time.Duration) func(*<unexported-type>)

func WithInstanceClose(close func()) func(*<unexported-type>)

func WithInstanceBatchSize(size uint32) func(*<unexported-type>)

func WithInstanceEventSize(size uint32) func(*<unexported-type>)

func WithInstanceProgress(progress func() (float64, string)) func(*<unexported-type>)

Here's an example of how the Pull Model prebuilt can be used to implement an event source:

func (m *MyPlugin) Open(params string) (source.Instance, error) {
 counter := uint64(0)
 pull := func(ctx context.Context, evt sdk.EventWriter) error {
 counter++
 if err := gob.NewEncoder(evt.Writer()).Encode(counter); err != nil {
 return err
 }
 evt.SetTimestamp(uint64(time.Now().UnixNano()))
 return nil
 }
 return source.NewPullInstance(pull)
}

Registering a Plugin in the SDK

After defining proper types for the plugin, the only thing remaining is to register it in the SDK so that it can be used in the plugin framework.

// sdk/plugins
type FactoryFunc func() plugins.Plugin

// sdk/plugins
func SetFactory(plugins.FactoryFunc)

// sdk/plugins/extractor
func Register(extractor.Plugin)

// sdk/plugins/source
func Register(source.Plugin)

The newly created plugin type need to be registered to the SDK in a Go init function and through the plugins.SetFactory() function. plugins.FactoryFunc is a function type that is used by the SDK to create plugins when requested by the plugin framework. Then, the source.Register() and extractor.Register() functions should be invoked inside the body of plugins.FactoryFunc functions to implement the event sourcing and the field extraction capabilities respectively.

The defined plugin types are expected to implement a given set of methods. Compilation will fail at the Register() functions if any of the required methods is not defined. Developers are encouraged to compose their structs with plugins.BasePlugin, and source.BaseInstance, which provide prebuilt boilerplate for many of those methods. In this way, developers just need to focus on implementing the few plugin-specific methods remaining.

Besides the interface requirements, the defined types can contain arbitrary fields and methods. State variable that must be maintained during the plugin lifecycle (or in the lifecycle of an opened event stream) must be contained in the defined types. In this way, the SDK can guarantee that the state variables are not disposed by the garbage collector.

Interacting with Events

Generating new events, and extracting field values from them, are the hottest path in the plugin framework and can happen at a very high rate. For this reason, the Go SDK optimizes the memory usage as much as possible, avoiding reallocations and copies wherever possible. Internally, this sometimes means reading and writing on C-allocated memory from Go code directly, which is efficient but also very unsafe and can lead to unstable code.

As such, the SDK provides the two sdk.EventReader and sdk.EventWriter interfaces, which enable developers to safely read and write from events while still fully leveraging the underlying memory optimizations. sdk.EventReader gives a read-only view of an event, with accessor methods for all the internal fields, and sdk.EventWriter does the same in read-only mode.

type EventReader interface {
 EventNum() uint64
 Timestamp() uint64
 Reader() io.ReadSeeker
}

type EventWriter interface {
 SetTimestamp(value uint64)
 Writer() io.Writer
}

Event data can either be read or written through the standard io.SeekReader and io.Writer interfaces, returned by the Reader() and Writer() methods respectively. The SDK hides behind these interfaces all the safety and optimization mechanisms.

For plugins with event sourcing capability, a reusable batch of sdk.EventWriters is automatically allocated in each plugin source instance after the Open() method returns. This slab-allocator creates reusable event data by using the default sdk.DefaultBatchSize and sdk.DefaultEvtSize constants. Developers can override the automatic allocation to define batches of arbitrary sizes in the Open() method, by calling the SetEvents() method on the newly opened plugin instance before returning it. The reusable event batch can be created with the sdk.NewEventWriters function, that takes the event data size and batch size as arguments.

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

Note that the size of the reusable event batch defines the maximum size of each event batch created by the plugin in NextBatch.

Compiling Plugins

After successfully writing a plugin, all you need is to compile it. Go allows compiling binaries as a C-compliant shared library with the -buildmode=c-shared flag. The build command will be something looking like:

go build -buildmode=c-shared -o <outname>.so *.go

The SDK takes care of generating all the required C exported functions that the plugin framework needs to load the plugin. Once built, your plugin is ready to be used in the Falcosecurity plugin system.

Example Go Plugin: `dummy`

This section walks through the implementation of the dummy. This plugin returns events that are just a number value that increases with each event generated. Each increase is 1 plus a random "jitter" value that ranges from [0:jitter]. The jitter value is provided as configuration to the plugin in plugin_init. The starting value and the maximum number of events are provided as open parameters to the plugin in plugin_open.

This will show how the above API functions are actually used in a functional plugin. The source code for this plugin can be found at dummy.go.

Initial Imports

package main

import (
 ...

 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/extractor"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"
)

Importing the sdk and sdk/plugins packages is the first step for developing a Falcosecurity plugin in Go. The sdk package contains all the core types and definitions used across the other packages of the SDK. The sdk/plugins package contains prebuilt constructs for defining new plugins.

The sdk/plugins/source and sdk/plugins/extractor packages are required to register the event sourcing and field extraction capabilities. dummy implements both of them.

The Go module falcosecurity/plugin-sdk-go has its own documentation, which gives deeper insights about the internal architecture of the SDK.

Defining the Plugin

In the Go SDK, plugins are defined by a set of composable tiny interfaces. To define a new plugin, the first step is to define a new struct type representing the plugin itself, and then register it to the SDK. Plugins with event sourcing capability, like dummy, must define an additional type representing the opened instance of the plugin event stream.

type PluginConfig struct {
 // This reflects potential internal state for the plugin. In
 // this case, the plugin is configured with a jitter.
 Jitter uint64 `json:"jitter" jsonschema:"description=A random amount added to the sample of each event (Default: 10)"`
}

type Plugin struct {
 plugins.BasePlugin
 // Will be used to randomize samples
 rand *rand.Rand
 // Contains the init configuration values
 config PluginConfig
}

type PluginInstance struct {
 source.BaseInstance
 // Copy of the init params from plugin_open()
 initParams string
 // The number of events to return before EOF
 maxEvents uint64
 // A count of events returned. Used to count against maxEvents.
 counter uint64
 // A semi-random numeric value, derived from this value and
 // jitter. This is put in every event as the data property.
 sample uint64
}

func init() {
 plugins.SetFactory(func() plugins.Plugin {
 p := &Plugin{}
 source.Register(p)
 extractor.Register(p)
 return p
 })
}

Plugin Info

An Info() method is needed to return a data struct containing all the plugin info. Info() is a required method for the defined plugin struct type. This plugin defined its info as a set of constants for simplicity, but it's not a requirement.

const (
 PluginID uint32 = 3
 PluginName = "dummy"
 PluginDescription = "Reference plugin for educational purposes"
 PluginContact = "github.com/falcosecurity/plugins"
 PluginVersion = "0.4.0"
 PluginEventSource = "dummy"
)

...

func (m *Plugin) Info() *plugins.Info {
 return &plugins.Info{
 ID: PluginID,
 Name: PluginName,
 Description: PluginDescription,
 Contact: PluginContact,
 Version: PluginVersion,
 RequiredAPIVersion: PluginRequiredApiVersion,
 EventSource: PluginEventSource,
 }
}

...

Initializing/Destroying the Plugin

The mandatory Init() method serves as an initialization entrypoint for plugins. This is where the user-defined configuration string is passed in by the framework. The internal state of the plugin should be initialized at this level. An error can be returned to abort the plugin initialization.

Defining the Destroy() method is optional but can be useful if some resource needs to be released before the plugin gets destroyed. The InitSchema() method is optional too, but it allows the framework to parse the init config automatically, thus avoiding the need of doing it manually inside Init().

// Set the config default values.
func (p *PluginConfig) setDefault() {
 p.Jitter = 10
}

// This returns a schema representing the configuration expected by the
// plugin to be passed to the Init() method. Defining InitSchema() allows
// the framework to automatically validate the configuration, so that the
// plugin can assume that it to be always be well-formed when passed to Init().
func (p *Plugin) InitSchema() *sdk.SchemaInfo {
 // We leverage the jsonschema package to autogenerate the
 // JSON Schema definition using reflection from our config struct.
 reflector := jsonschema.Reflector{
 // all properties are optional by default
 RequiredFromJSONSchemaTags: true,
 // unrecognized properties don't cause a parsing failures
 AllowAdditionalProperties: true,
 }
 if schema, err := reflector.Reflect(&PluginConfig{}).MarshalJSON(); err == nil {
 return &sdk.SchemaInfo{
 Schema: string(schema),
 }
 }
 return nil
}

// Since this plugin defines the InitSchema() method, we can assume
// that the configuration is pre-validated by the framework and
// always well-formed according to the provided schema.
func (m *Plugin) Init(cfg string) error {
 // initialize state
 m.rand = rand.New(rand.NewSource(time.Now().UnixNano()))
 // The format of cfg is a json object with a single param
 // "jitter", e.g. {"jitter": 10}
 // Empty configs are allowed, in which case the default is used.
 // Since we provide a schema through InitSchema(), the framework
 // guarantees that the config is always well-formed json.
 m.config.setDefault()
 json.Unmarshal([]byte(cfg), &m.config)
 return nil
}

func (m *Plugin) Destroy() {
 // nothing to do here
}

Opening/Closing a Stream of Events

A plugin instance is created when the plugin event stream is opened, which can happen more than once during the plugin lifecycle. Plugins with event sourcing capability are required to define an Open() method that creates a returns a new plugin instance. This is where the framework passes in the user-defined open parameters string.

The plugin instance type returned by Open() can define an optional Close() method bundling any additional deinitialization logic to run while closing the event stream.

func (m *Plugin) Open(prms string) (source.Instance, error) {
 // The format of params is a json object with two params:
 // - "start", which denotes the initial value of sample
 // - "maxEvents": which denotes the number of events to return before EOF.
 // Example:
 // {"start": 1, "maxEvents": 1000}
 var obj map[string]uint64
 err := json.Unmarshal([]byte(prms), &obj)
 if err != nil {
 return nil, fmt.Errorf("params %s could not be parsed: %v", prms, err)
 }
 if _, ok := obj["start"]; !ok {
 return nil, fmt.Errorf("params %s did not contain start property", prms)
 }

 if _, ok := obj["maxEvents"]; !ok {
 return nil, fmt.Errorf("params %s did not contain maxEvents property", prms)
 }

 return &PluginInstance{
 initParams: prms,
 maxEvents: obj["maxEvents"],
 counter: 0,
 sample: obj["start"],
 }, nil
}

func (m *PluginInstance) Close() {
 // nothing to do here
}

Returning new Events

New events are generated in batch by the NextBatch function. The function is mandatory for plugins with event sourcing capability and must be defined as a method of the plugin instance struct type. The pState argument is the plugin struct type initialized in Init(), passed in by the framework for ease of access. The plugin state is passed as an instance of the sdk.PluginState interface, so a manual cast is required to access the internal state variables defined in the struct type.

The evts parameter is a sdk-managed batch of events to be used for creating new events. For that, the SDK uses a slab allocator and reuses the same event batch at every iteration to improve performance. The length of the evts list represents the maximum size of each event batch. Each element of the batch is an instance of sdk.EventWriter that provides handy methods to write the event info and data. Event data can be written with the Go io.Writer interface.

If an error is returned, the SDK returns a failure to the framework and invalidates the current batch. The special errors sdk.ErrTimeout and sdk.ErrEOF have a special meaning, and are used to either advise the framework that no new events are currently available, or that the event stream is terminated.

func (m *PluginInstance) NextBatch(pState sdk.PluginState, evts sdk.EventWriters) (int, error) {
 // Return EOF if reached maxEvents
 if m.counter >= m.maxEvents {
 return 0, sdk.ErrEOF
 }

 // access the plugin state
 plugin := pState.(*Plugin)

 var n int
 var evt sdk.EventWriter
 for n = 0; m.counter < m.maxEvents && n < evts.Len(); n++ {
 evt = evts.Get(n)
 m.counter++

 // Increment sample by 1, also add a jitter of [0:jitter]
 m.sample += 1 + uint64(plugin.rand.Int63n(int64(plugin.config.Jitter+1)))

 // The representation of a dummy event is the sample as a string.
 str := strconv.Itoa(int(m.sample))

 // It is not mandatory to set the Timestamp of the event (it
 // would be filled in by the framework if set to uint_max),
 // but it's a good practice.
 evt.SetTimestamp(uint64(time.Now().UnixNano()))

 _, err := evt.Writer().Write([]byte(str))
 if err != nil {
 return 0, err
 }
 }
 return n, nil
}

Printing Events As Strings

Plugins with event sourcing capability can optionally have a String() method to format the contents of events created with a previous call to NextBatch(). The event data is readable through an instance of sdk.EventReader provided by the SDK. Internally, this allows safe memory access and an optimal reusage of the same buffer to maximize the performance of hot framework paths.

func (m *Plugin) String(evt sdk.EventReader) (string, error) {
 evtBytes, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 return "", err
 }
 evtStr := string(evtBytes)

 // The string representation of an event is a json object with the sample
 return fmt.Sprintf("{\"sample\": \"%s\"}", evtStr), nil
}

Defining Fields

This dummy plugin has field extraction capability and exports 3 fields:

dummy.value: the value in the event, as a uint64
dummy.strvalue: the value in the event, as a string
dummy.divisible: this field takes an argument and returns 1 if the value in the event is divisible by the argument (a numeric divisor). For example, if the value was 12, dummy.divisible[3] would return 1 for that event.

The Fields() method returns a slice of sdk.FieldEntry representing all the supported fields.

func (m *Plugin) Fields() []sdk.FieldEntry {
 return []sdk.FieldEntry{
 {
 Type: "uint64",
 Name: "dummy.divisible",
 Desc: "Return 1 if the value is divisible by the provided divisor, 0 otherwise",
 Arg: sdk.FieldEntryArg{IsRequired: true, IsKey: true},
 },
 {
 Type: "uint64",
 Name: "dummy.value",
 Desc: "The sample value in the event",
 },
 {
 Type: "string",
 Name: "dummy.strvalue",
 Desc: "The sample value in the event, as a string",
 },
 }
}

Extracting Fields

The Extract method extracts all of the supported fields. The req parameter allows accessing all the info regarding the field request, such as the field id or name, and the optional user-passed argument. The evt parameter is an interface that helps reading the event info and data.

The extracted field value must be set through the SetValue method of sdk.ExtractRequest. Returning from Extract without calling SetValue will signal the SDK that the requested field is not present in the given event.

func (m *Plugin) Extract(req sdk.ExtractRequest, evt sdk.EventReader) error {
 evtBytes, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 return err
 }
 evtStr := string(evtBytes)
 evtVal, err := strconv.Atoi(evtStr)
 if err != nil {
 return err
 }
 switch req.FieldID() {
 case 0: // dummy.divisible
 divisor, err := strconv.Atoi(req.ArgKey())
 if err != nil {
 return fmt.Errorf("argument to dummy.divisible %s could not be converted to number", req.ArgKey())
 }
 if evtVal%divisor == 0 {
 req.SetValue(uint64(1))
 } else {
 req.SetValue(uint64(0))
 }
 case 1: // dummy.value
 req.SetValue(uint64(evtVal))
 case 2: // dummy.strvalue
 req.SetValue(evtStr)
 default:
 return fmt.Errorf("no known field: %s", req.Field())
 }
 return nil
}

Running the Plugin

This plugin can be configured in Falco by adding the following to falco.yaml file:

plugins:
 - name: dummy
 library_path: /tmp/my-plugins/dummy/libdummy.so
 init_config:
 jitter: 10
 open_params: '{"start": 1, "maxEvents": 20}'

## Optional
load_plugins: [dummy]

This simple rule prints a Falco alert any time the event number is between 0 and 10, and the sample value is divisible by 3:

- rule: My Dummy Rule
 desc: My Desc
 condition: evt.num > 0 and evt.num < 10 and dummy.divisible[3] = 1
 output: A dummy event | event=%evt.plugininfo sample=%dummy.value sample_str=%dummy.strvalue num=%evt.num
 priority: INFO
 source: dummy

Here's what it looks like when run:

$ ./falco -r ../falco-files/dummy_rules.yaml -c ../falco-files/falco.yaml
Wed Feb 2 16:26:35 2022: Falco version 0.31.0 (driver version 319368f1ad778691164d33d59945e00c5752cd27)
Wed Feb 2 16:26:35 2022: Falco initialized with configuration file ../falco-files/falco.yaml
Wed Feb 2 16:26:35 2022: Loading plugin (dummy) from file /tmp/my-plugins/dummy/libdummy.so
Wed Feb 2 16:26:35 2022: Loading rules from file ../rules/dummy_rules.yaml:
Wed Feb 2 16:26:35 2022: Starting internal webserver, listening on port 8765
16:26:35.527827816: Notice A dummy event (event={"sample": "6"} sample=6 sample_str=6 num=1)
16:26:35.527829658: Notice A dummy event (event={"sample": "18"} sample=18 sample_str=18 num=3)
16:26:35.527831048: Notice A dummy event (event={"sample": "33"} sample=33 sample_str=33 num=8)
Events detected: 3
Rule counts by severity:
INFO: 3
Triggered rules by rule name:
My Dummy Rule: 3
Syscall event drop monitoring:
- event drop detected: 0 occurrences
- num times actions taken: 0

Falco – Falco Plugins

Docs: Falco Plugins API Reference

Introduction

Plugin API Versioning

Conventions

Inversion of Control and Callbacks to the Plugin's Owner

Logging

Common Plugin API

get_required_api_version

get_{name,description,contact,version}

init

destroy

get_last_error

get_init_schema

set_config

get_metrics

Event Sourcing Capability API

get_id

get_event_source

open

close

next_batch

get_progress

event_to_string

list_open_params

Field Extraction Capability API

get_fields

extract_fields

get_extract_event_sources

get_extract_event_types

Event Parsing Capability API

parse_event

get_parse_event_sources

get_parse_event_types

Async Events Capability API

get_async_event_sources

get_async_events

set_async_event_handler

Libscap Event Block Specification

State Tables API

Basic Concepts

Access and Consistency

Subtables and complex data types

Obtaining Accessors

Obtaining subtables accessors

Accessing Tables

Accessing subtables

Registering State Tables

Thread-safety and Reproducibility

Docs: Falco Plugins Go SDK Walkthrough

Introduction

Architecture of the Go SDK

Getting Started

Defining a Plugin with Field Extraction Capability

Optional Interfaces

Defining a Plugin with Event Sourcing Capability

Optional Interfaces

Best Practices and Go SDK Prebuilts for Source Instances

Registering a Plugin in the SDK

Interacting with Events

Compiling Plugins

Example Go Plugin: dummy

Initial Imports

Defining the Plugin

Plugin Info

Initializing/Destroying the Plugin

Opening/Closing a Stream of Events

Returning new Events

Printing Events As Strings

Defining Fields

Extracting Fields

Running the Plugin

Example Go Plugin: `dummy`