Module falco_plugin::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::{InitInput, Plugin};
use falco_plugin::{extract_plugin, FailureReason, plugin};
use falco_plugin::extract::{
    EventInput,
    ExtractFieldInfo,
    ExtractFieldRequestArg,
    ExtractPlugin,
    field};
use falco_plugin::tables::TableReader;

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

impl MyExtractPlugin { // note this is not the trait implementation
    fn extract_sample(
        &mut self,
        _context: &mut (),
        _arg: ExtractFieldRequestArg,
        _input: &EventInput,
        _tables: &TableReader,
    ) -> 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
• FieldExtractInput
• FieldStorage
  Storage for extracted fields

Enums

• ExtractArgType
  The type of argument a field extractor expects
• ExtractFieldRequestArg
  The actual argument passed to the extractor function

Traits

• ExtractPlugin
  Support for field extraction plugins

Functions

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