Module falco_plugin::source
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 std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::thread::JoinHandle;
use anyhow::Error;
use falco_event::events::Event;
use falco_plugin::base::{InitInput, Plugin};
use falco_plugin::{EventInputExt, FailureReason, plugin, source_plugin};
use falco_plugin::source::{
EventBatch,
EventInput,
PluginEvent,
SourcePlugin,
SourcePluginInstance};
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§
- A helper that enables writing into CStrings
- An object that describes a batch of events
- Information about capture progress
Enums§
- Specification of open parameters for a source plugin instance
Traits§
- Support for event sourcing plugins
- An open instance of a source plugin
Functions§
- Serialize the open parameter specification