Module extract

Field extraction plugin support

Plugins with field extraction capability have the ability to extract information from events based on fields. For example, a field (e.g. proc.name) extracts a value (e.g. process name like nginx) from a syscall event. The plugin returns a set of supported fields, and there are functions to extract a value given an event and field. The plugin framework can then build filtering expressions (e.g. rule conditions) based on these fields combined with relational and/or logical operators.

For example, given the expression ct.name=root and ct.region=us-east-1, the plugin framework handles parsing the expression, calling the plugin to extract values for fields ct.name/ct.region for a given event, and determining the result of the expression. In a Falco output string like An EC2 Node was created (name=%ct.name region=%ct.region), the plugin framework handles parsing the output string, calling the plugin to extract values for fields, and building the resolved string, replacing the template field names (e.g. %ct.region) with values (e.g. us-east-1).

Plugins with this capability only focus on field extraction from events generated by other plugins or by the core libraries. They do not provide an event source but can extract fields from other event sources. The supported field extraction can be generic or be tied to a specific event source. An example is JSON field extraction, where a plugin might be able to extract fields from generic JSON payloads.

For your plugin to support field extraction, you will need to implement the extract::ExtractPlugin trait and invoke the extract_plugin macro, for example:

use std::ffi::{CStr, CString};
use anyhow::Error;
use falco_event::events::types::EventType;
use falco_plugin::base::{Metric, Plugin};
use falco_plugin::{extract_plugin, plugin};
use falco_plugin::extract::{
    EventInput,
    ExtractFieldInfo,
    ExtractPlugin,
    ExtractRequest,
    field};
use falco_plugin::tables::TablesInput;

struct MyExtractPlugin;
impl Plugin for MyExtractPlugin {
    // ...
}

impl MyExtractPlugin { // note this is not the trait implementation
    fn extract_sample(
        &mut self,
        _req: ExtractRequest<Self>,
    ) -> Result<CString, Error> {
        Ok(c"hello".to_owned())
    }
}

impl ExtractPlugin for MyExtractPlugin {
    const EVENT_TYPES: &'static [EventType] = &[]; // all event types
    const EVENT_SOURCES: &'static [&'static str] = &[]; // all event sources
    type ExtractContext = ();

    const EXTRACT_FIELDS: &'static [ExtractFieldInfo<Self>] = &[
        field("my_extract.sample", &Self::extract_sample),
    ];
}

plugin!(MyExtractPlugin);
extract_plugin!(MyExtractPlugin);

See the extract::ExtractPlugin trait documentation for details.

Structs

EventInput

An event from which additional data may be extracted

ExtractFieldInfo

A description of an extracted field

ExtractRequest

An extraction request

Traits

ExtractPlugin

Support for field extraction plugins

Functions

field

Wrap a function or method to make it usable as a field extractor