Trait SourcePlugin

pub trait SourcePlugin: Plugin + SourcePluginExported {
    type Instance: SourcePluginInstance<Plugin = Self>;
    type Event<'a>: AnyEventPayload + TryFrom<&'a RawEvent<'a>>
       where Self: 'a;

    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<'_, Self::Event<'_>>,
    ) -> 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 plugin events (e.g. crate::event::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 plugin events (e.g. crate::event::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.

type Event<'a>: AnyEventPayload + TryFrom<&'a RawEvent<'a>> where Self: 'a

Event type handled by this plugin

The SDK does not enforce limits on the events generated, but you can make your life a bit easier in event_to_string by specifying the event type your plugin generates here. Events will be parsed into this type before being passed to the plugin, so you can work directly on the deserialized form and don’t need to worry about validating the events.

If an event fails this conversion, an error will be returned from the SDK and your string formatting code won’t be called.

If you don’t want any specific validation/conversion to be performed, specify the type as

type Event<'a> = falco_event::events::RawEvent<'a>;

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<'_, Self::Event<'_>>, ) -> 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