From 6e54b98fd25f6e77cc0b84e7a5249fe15c6bf7f7 Mon Sep 17 00:00:00 2001 From: Leonardo Grasso Date: Tue, 6 Sep 2022 18:28:30 +0200 Subject: [PATCH] update(sdk): bump plugin_info version (plugin API v2) This is temporary and required for testing purpose. Another bump should be expected before releasing v0.6.0. Signed-off-by: Leonardo Grasso --- Makefile | 2 +- pkg/sdk/plugin_api.h | 113 ++++++++++++++++++++++++++++--------------- 2 files changed, 74 insertions(+), 41 deletions(-) diff --git a/Makefile b/Makefile index 03db971..399cc44 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/pkg/sdk/plugin_api.h b/pkg/sdk/plugin_api.h index c0539a8..996a90b 100644 --- a/pkg/sdk/plugin_api.h +++ b/pkg/sdk/plugin_api.h @@ -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 @@ -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 { @@ -74,9 +75,9 @@ typedef struct // Required: yes // Return value: the API version string, in the following format: // "..", 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)(); @@ -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); // @@ -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); @@ -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 // @@ -161,14 +165,15 @@ typedef struct // Return value: a string with a version identifier, in the following format: // "..", 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 { // @@ -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); @@ -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); @@ -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 @@ -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); // @@ -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); // @@ -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 { // @@ -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: @@ -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)(); @@ -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;