Module source

Expand description

§Event sourcing support

Plugins with event sourcing capability provide a new event source and make it available to libscap and libsinsp. They have the ability to “open” and “close” a stream of events and return those events to the plugin framework. They also provide a plugin ID, which is globally unique and is used in capture files. Event sources provided by plugins with this capability are tied to the events they generate and can be used by plugins with field extraction capabilities and within Falco rules. For your plugin to support event sourcing, you will need to implement the source::SourcePlugin trait and invoke the source_plugin macro, for example:

use std::ffi::{CStr, CString};
use anyhow::Error;
use falco_event::events::Event;
use falco_plugin::base::{Metric, Plugin};
use falco_plugin::{plugin, source_plugin};
use falco_plugin::source::{
    EventBatch,
    EventInput,
    PluginEvent,
    SourcePlugin,
    SourcePluginInstance};
use falco_plugin::tables::TablesInput;
use falco_plugin_api::ss_plugin_event_input;

struct MySourcePlugin;

impl Plugin for MySourcePlugin {
    // ...
}

struct MySourcePluginInstance;

impl SourcePlugin for MySourcePlugin {
    type Instance = MySourcePluginInstance;
    const EVENT_SOURCE: &'static CStr = c"my-source-plugin";
    const PLUGIN_ID: u32 = 0; // we do not have one assigned for this example :)

    fn open(&mut self, params: Option<&str>) -> Result<Self::Instance, Error> {
        // we do not use the open parameters in this example
        Ok((MySourcePluginInstance))
    }

    fn event_to_string(&mut self, event: &EventInput) -> Result<CString, Error> {
        // a string representation for our event; just copy out the whole event data
        // (it's an ASCII string); please note we need the copy because we need to add
        // a NUL terminator to convert the byte buffer to a C string

        // get the raw event
        let event = event.event()?;
        // parse the fields into a PluginEvent
        let plugin_event = event.load::<PluginEvent>()?;

        // take a copy of the event data (it's in an Option because we never know if events
        // have all the fields, and it's important to handle short events for backwards
        // compatibility).
        let data = plugin_event.params.event_data.map(|e| e.to_vec()).unwrap_or_default();

        // convert the data to a CString and return it
        Ok(CString::new(data)?)
    }
}

impl SourcePluginInstance for MySourcePluginInstance {
    type Plugin = MySourcePlugin;

    fn next_batch(&mut self, plugin: &mut Self::Plugin, batch: &mut EventBatch)
    -> Result<(), Error> {
        let event = Self::plugin_event(b"hello, world");
        batch.add(event)?;

        Ok(())
    }}

plugin!(MySourcePlugin);
source_plugin!(MySourcePlugin);

Structs§

EventBatch: An object that describes a batch of events
EventInput: An event from which additional data may be extracted
PluginEvent
ProgressInfo: Information about capture progress

Enums§

OpenParam: Specification of open parameters for a source plugin instance

Traits§

SourcePlugin: Support for event sourcing plugins
SourcePluginInstance: An open instance of a source plugin

Functions§