Trait SourcePlugin

pub trait SourcePlugin: Plugin + SourcePluginExported {
    type Instance: SourcePluginInstance<Plugin = Self>;

    const EVENT_SOURCE: &'static CStr;
    const PLUGIN_ID: u32;

    // Required methods
    fn open(&mut self, params: Option<&str>) -> Result<Self::Instance, Error>;
    fn event_to_string(&mut self, event: &EventInput) -> Result<CString, Error>;

    // Provided methods
    fn list_open_params(&mut self) -> Result<&CStr, Error> { ... }
    fn close(&mut self, _instance: &mut Self::Instance) { ... }
}

Support for event sourcing plugins

Required Associated Constants

const EVENT_SOURCE: &'static CStr

Event source name

This string describes the event source. One notable event source name is syscall, for plugins collecting syscall information.

If the plugin defines both EVENT_SOURCE (as a non-empty string) and PLUGIN_ID (as a non-zero value), it will only be allowed to emit events of type PluginEvent with the plugin_id field matching PLUGIN_ID in the definition of this trait.

This constant must be a non-empty string if PLUGIN_ID is set.

const PLUGIN_ID: u32

Plugin ID

This is the unique ID of the plugin.

If the plugin defines both EVENT_SOURCE (as a non-empty string) and PLUGIN_ID (as a non-zero value), it will only be allowed to emit events of type PluginEvent with the plugin_id field matching PLUGIN_ID in the definition of this trait.

EVERY PLUGIN WITH EVENT SOURCING CAPABILITY IMPLEMENTING A SPECIFIC EVENT SOURCE MUST OBTAIN AN OFFICIAL ID FROM THE FALCOSECURITY ORGANIZATION, OTHERWISE IT WON’T PROPERLY COEXIST WITH OTHER PLUGINS.

Required Associated Types

type Instance: SourcePluginInstance<Plugin = Self>

Instance type

Each source plugin defines an instance type. The instance is the object responsible for actual generation of events. The plugin type mostly serves as a way to create and destroy instances.

Note: while there may be multiple instances for a particular plugin, there will be at most one at any given time.

Required Methods

fn open(&mut self, params: Option<&str>) -> Result<Self::Instance, Error>

Open a capture instance

This method receives the open parameter from Falco configuration and returns a new instance of the source plugin.

fn event_to_string(&mut self, event: &EventInput) -> Result<CString, Error>

Render an event to string

This string will be available as %evt.plugininfo in Falco rules. You may consider using the helpers from crate::strings to build the resulting CString.

Provided Methods

fn list_open_params(&mut self) -> Result<&CStr, Error>

List sample open parameters

Return a list of suggested open parameters supported by this plugin. Any of the values in the returned list are valid parameters for open().

The default implementation returns an empty string, but you can use crate::source::serialize_open_params and crate::source::OpenParam to build a description of what the SourcePlugin::open method expects.

Note: as of API version 3.4.0, this appears unused.

fn close(&mut self, _instance: &mut Self::Instance)

Close a capture instance

The default implementation does nothing, leaving all cleanup to the instance type’s Drop implementation, if any.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors