Skip to content

Commit

Permalink
update(sdk): bump plugin_info version (plugin API v2)
Browse files Browse the repository at this point in the history 
This is temporary and required for testing purpose. Another bump should be expected before releasing v0.6.0.

Signed-off-by: Leonardo Grasso <[email protected]>
  • Loading branch information
@leogr @poiana
leogr authored and poiana committed Sep 6, 2022
1 parent 4a87bc0 commit 6e54b98
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 41 deletions.
2 changes: 1 addition & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ SHELL := /bin/bash
GO ?= $(shell which go)
CURL ?= $(shell which curl)

FALCOSECURITY_LIBS_REVISION ?= 5b9c3ca9ae55800e774e1681a0c5e7d54ca89263
FALCOSECURITY_LIBS_REVISION ?= 000eb27573af74168510e4836330ff6958c3f355
FALCOSECURITY_LIBS_REPO ?= falcosecurity/libs
PLUGINLIB_URL=https://raw.githubusercontent.com/${FALCOSECURITY_LIBS_REPO}/${FALCOSECURITY_LIBS_REVISION}/userspace/plugin

Expand Down
113 changes: 73 additions & 40 deletions pkg/sdk/plugin_api.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@ extern "C" {


//
// API versions of this plugin engine
// API versions of this plugin framework
//
#define PLUGIN_API_VERSION_MAJOR 1
#define PLUGIN_API_VERSION_MAJOR 2
#define PLUGIN_API_VERSION_MINOR 0
#define PLUGIN_API_VERSION_PATCH 0

Expand Down Expand Up @@ -64,8 +64,9 @@ extern "C" {
// parameters) if not corresponding to plugin-allocated memory in the
// cases above. Plugins can safely use the passed memory during the execution
// of the exported functions.

//
// Plugins vtable
// Plugins API vtable
//
typedef struct
{
Expand All @@ -74,9 +75,9 @@ typedef struct
// Required: yes
// Return value: the API version string, in the following format:
// "<major>.<minor>.<patch>", e.g. "1.2.3".
// NOTE: to ensure correct interoperability between the engine and the plugins,
// NOTE: to ensure correct interoperability between the framework and the plugins,
// we use a semver approach. Plugins are required to specify the version
// of the API they run against, and the engine will take care of checking
// of the API they run against, and the framework will take care of checking
// and enforcing compatibility.
//
const char *(*get_required_api_version)();
Expand All @@ -103,17 +104,20 @@ typedef struct
const char *(*get_init_schema)(ss_plugin_schema_type *schema_type);

//
// Initialize the plugin and allocate its non-NULL state.
// Initialize the plugin and allocate its state.
// Required: yes
// Arguments:
// - config: a string with the plugin configuration. The format of the
// string is chosen by the plugin itself.
// - rc: pointer to a ss_plugin_rc that will contain the initialization result
// Return value: pointer to the plugin state that will be treated as opaque
// by the engine and passed to the other plugin functions.
// by the framework and passed to the other plugin functions.
// If rc is SS_PLUGIN_FAILURE, this function may return NULL or a state to
// later retrieve the error string.
//
//
// 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, if not after
// it has been disposed with destroy() first.
ss_plugin_t *(*init)(const char *config, ss_plugin_rc *rc);

//
Expand All @@ -129,7 +133,7 @@ typedef struct
//
// In cases where any other api function returns an error, the
// plugin should be prepared to return a human-readable error
// string with more context for the error. The plugin manager
// string with more context for the error. The framework
// calls get_last_error() to access that string.
//
const char *(*get_last_error)(ss_plugin_t *s);
Expand All @@ -143,13 +147,13 @@ typedef struct

//
// Return the descriptions of the plugin, which will be printed when displaying
// information about the plugin or its events.
// information about the plugin.
// Required: yes
//
const char *(*get_description)();

//
// Return a string containing contact info (url, email, twitter, etc) for
// Return a string containing contact info (url, email, etc) for
// the plugin authors.
// Required: yes
//
Expand All @@ -161,14 +165,15 @@ typedef struct
// Return value: a string with a version identifier, in the following format:
// "<major>.<minor>.<patch>", e.g. "1.2.3".
// This differs from the api version in that this versions the
// plugin itself, as compared to the plugin interface. When
// reading capture files, the major version of the plugin that
// generated events must match the major version of the plugin
// used to read events.
// plugin itself. Note, 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.
//
const char *(*get_version)();

// Sourcing capabilities related
// Event sourcing capability API
struct
{
//
Expand All @@ -180,33 +185,38 @@ typedef struct
uint32_t (*get_id)();

//
// Return a string describing the events generated by this plugin with event sourcing capabilities.
// Return a string representing the name of the event source generated
// by this plugin.
// Required: yes
// Example event sources would be strings like "syscall",
// "k8s_audit", etc. The source can be used by extractor
// plugins to filter the events they receive.
// Example event sources would be strings like "aws_cloudtrail",
// "k8s_audit", etc. The source can be used by plugins with event
// sourcing capabilities to filter the events they receive.
//
const char* (*get_event_source)();

//
// Open the source and start a capture (e.g. stream of events)
// Open the event source and start a capture (e.g. stream of events)
// Required: yes
// Arguments:
// - s: the plugin state returned by init()
// - params: the open parameters, as a string. The format is defined by the plugin
// itsef
// - params: the open parameters, as an opaque string.
// The string format is defined by the plugin itself
// - rc: pointer to a ss_plugin_rc that will contain the open result
// Return value: a pointer to the open context that will be passed to next_batch(),
// close(), event_to_string() and extract_fields.
// Return value: a pointer to the opened plugin instance that will be
// passed to next_batch(), close(), event_to_string()
// and extract_fields().
//
// 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, if not after it has been disposed with close() first.
ss_instance_t* (*open)(ss_plugin_t* s, const char* params, ss_plugin_rc* rc);

//
// Close a capture.
// Required: yes
// Arguments:
// - s: the plugin context, returned by init(). Can be NULL.
// - h: the capture context, returned by open(). Can be NULL.
// - s: the plugin state, returned by init(). Can be NULL.
// - h: the plugin instance, returned by open(). Can be NULL.
//
void (*close)(ss_plugin_t* s, ss_instance_t* h);

Expand All @@ -215,14 +225,21 @@ typedef struct
// Any of the values in the returned list are valid parameters for open().
// Required: no
// Return value: a string with the list of open params encoded as
// a json array.
// Each field entry is a json object with the following properties:
// "value": a string usable as an open() parameter.
// "desc": (optional) a string with a description of the parameter.
// a json array. Each field entry is a json object with the following
// properties:
// - "value": a string usable as an open() parameter.
// - "desc": (optional) a string with a description of the parameter.
// - "separator": (optional) a separator string, for when "value"
// represents multiple contatenated open parameters
// Example return value:
// [
// {"value": "resource1", "desc": "An example of openable resource"},
// {"value": "resource2", "desc": "Another example of openable resource"}
// {"value": "resource2", "desc": "Another example of openable resource"},
// {
// "value": "res1;res2;res3",
// "desc": "Some names",
// "separator": ";"
// }
// ]
const char* (*list_open_params)(ss_plugin_t* s, ss_plugin_rc* rc);

Expand All @@ -231,7 +248,7 @@ typedef struct
// Required: no
// Arguments:
// - progress_pct: 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
// and 10000 (100% of the data has been read). This encoding allows the framework to
// print progress decimals without requiring to deal with floating point numbers
// (which could cause incompatibility problems with some languages).
// Return value: a string representation of the read
Expand All @@ -245,6 +262,11 @@ typedef struct
// when possible, it's recommended as it provides valuable information to the
// user.
//
// 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.
const char* (*get_progress)(ss_plugin_t* s, ss_instance_t* h, uint32_t* progress_pct);

//
Expand All @@ -261,6 +283,11 @@ typedef struct
// and must not be deallocated or modified until the next call to
// event_to_string().
//
// 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.
const char* (*event_to_string)(ss_plugin_t *s, const ss_plugin_event *evt);

//
Expand All @@ -275,10 +302,15 @@ typedef struct
// next_batch() or close().
// Required: yes
//
// 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.
ss_plugin_rc (*next_batch)(ss_plugin_t* s, ss_instance_t* h, uint32_t *nevts, ss_plugin_event **evts);
};

// Extraction capability related
// Field extraction capability API
struct
{
//
Expand All @@ -305,9 +337,6 @@ typedef struct
// "type": one of "string", "uint64"
// "isList: (optional) If present and set to true, notes
// that the field extracts a list of values.
// "argRequired": [DEPRECATED, use "arg" property instead]
// (optional) If present and set to true, notes
// that the field requires an argument e.g. field[arg].
// "arg": (optional) if present, notes that the field can accept
// an argument e.g. field[arg]. More precisely, the following
// flags could be specified:
Expand All @@ -325,9 +354,8 @@ typedef struct
// "desc": a string with a description of the field
// Example return value:
// [
// {"type": "string", "name": "field1", "argRequired": true, "desc": "Describing field 1"}, [DEPRECATED 'argRequired' property]
// {"type": "uint64", "name": "field2", "desc": "Describing field 2"},
// {"type": "string", "name": "field3", "arg": {"isRequired": true, "isIndex": true,}, "desc": "Describing field 3"},
// {"type": "uint64", "name": "field1", "desc": "Describing field 1"},
// {"type": "string", "name": "field2", "arg": {"isRequired": true, "isIndex": true}, "desc": "Describing field 2"},
// ]
const char* (*get_fields)();

Expand All @@ -348,6 +376,11 @@ typedef struct
//
// Return value: A ss_plugin_rc with values SS_PLUGIN_SUCCESS or SS_PLUGIN_FAILURE.
//
// 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.
ss_plugin_rc (*extract_fields)(ss_plugin_t *s, const ss_plugin_event *evt, uint32_t num_fields, ss_plugin_extract_field *fields);
};
} plugin_api;
Expand Down

0 comments on commit 6e54b98

Please sign in to comment.