falco_plugin/extract/

mod.rs

//! # Field extraction plugin support
//!
//! Plugins with field extraction capability can 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 [`ExtractPlugin`]
//! trait and invoke the [`extract_plugin`](crate::extract_plugin) macro, for example:
//!
//! ```
//! use std::ffi::{CStr, CString};
//! use anyhow::Error;
//! use falco_event::events::RawEvent;
//! 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 {
//!     // ...
//! #    const NAME: &'static CStr = c"sample-plugin-rs";
//! #    const PLUGIN_VERSION: &'static CStr = c"0.0.1";
//! #    const DESCRIPTION: &'static CStr = c"A sample Falco plugin that does nothing";
//! #    const CONTACT: &'static CStr = c"you@example.com";
//! #    type ConfigType = ();
//! #
//! #    fn new(input: Option<&TablesInput>, config: Self::ConfigType)
//! #        -> Result<Self, anyhow::Error> {
//! #        Ok(MyExtractPlugin)
//! #    }
//! #
//! #    fn set_config(&mut self, config: Self::ConfigType) -> Result<(), anyhow::Error> {
//! #        Ok(())
//! #    }
//! #
//! #    fn get_metrics(&mut self) -> impl IntoIterator<Item=Metric> {
//! #        []
//! #    }
//! }
//!
//! 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 {
//!     type Event<'a> = RawEvent<'a>;
//!     type ExtractContext = ();
//!
//!     const EXTRACT_FIELDS: &'static [ExtractFieldInfo<Self>] = &[
//!         field("my_extract.sample", &Self::extract_sample),
//!     ];
//! }
//!
//! plugin!(MyExtractPlugin);
//! extract_plugin!(MyExtractPlugin);
//! ```
//!
//! See the [`ExtractPlugin`] trait documentation for details.

use crate::base::Plugin;
use crate::extract::wrappers::ExtractPluginExported;
use crate::tables::LazyTableReader;
use falco_event::events::{AnyEventPayload, RawEvent};
use falco_plugin_api::{ss_plugin_extract_field, ss_plugin_extract_value_offsets};
use std::any::TypeId;
use std::collections::BTreeMap;
use std::ffi::{CStr, CString};
use std::ops::Range;
use std::sync::Mutex;

mod extractor_fn;
mod fields;
mod schema;
#[doc(hidden)]
pub mod wrappers;

pub use crate::event::EventInput;
pub use schema::{field, ExtractFieldInfo};

/// An invalid range (not supported)
///
/// This is used when an extractor that does not support ranges is used together with extractors
/// that do, and range extraction is requested. Due to the design of the Falco plugin API,
/// there must be a range for all the fields (or none of them), so we fill out the missing ranges
/// with this value.
///
/// **Note**: you should not use this value in plugins yourself. If an extractor returns data that is
/// not corresponding to any particular byte offset in the plugin payload, it should set the range
/// to [`UNSPECIFIED_RANGE`].
#[allow(clippy::reversed_empty_ranges)]
pub const INVALID_RANGE: Range<usize> = 1..0;

/// An unspecified range (computed data)
///
/// Use this range to indicate that the extracted value does not correspond to any specific
/// byte range in the event (for example, it was calculated based on the event data).
pub const UNSPECIFIED_RANGE: Range<usize> = 0..0;

/// The offset in the event where a plugin event payload starts
///
/// Since the event payload is at a fixed offset, you can add this value
/// to the start of an extracted field within the payload to get the offset
/// from the start of the event.
///
/// 26 bytes for the event header, plus 2*4 bytes for the parameter lengths,
/// plus 4 bytes for the plugin ID.
const PLUGIN_EVENT_PAYLOAD_OFFSET: usize = falco_plugin_api::PLUGIN_EVENT_PAYLOAD_OFFSET as usize;

/// Range extraction request/response
#[derive(Debug, Eq, PartialEq)]
pub enum ExtractByteRange {
    /// Range extraction was not requested
    NotRequested,

    /// Range extraction was requested but not performed
    ///
    /// This value is set upon entry to the extractor function. The function may replace the value
    /// with [`ExtractByteRange::Found`] if it supports finding byte ranges. If the extractor does
    /// not support byte ranges, it can ignore this value completely and leave it unchanged.
    Requested,

    /// Range extraction finished successfully
    ///
    /// Note that for fields extracted from the plugin event data field, you will probably want
    /// to construct this value using [`ExtractByteRange::in_plugin_data`].
    Found(Range<usize>),
}

impl ExtractByteRange {
    /// Create a range pointing into a plugin event data field
    ///
    /// This is a helper for the common case of returning offsets inside the data field
    /// of a plugin event. It simply shifts the provided range by 38 bytes (26 header bytes,
    /// 2*4 length bytes, 4 plugin id bytes) to make the resulting range relative to the full
    /// event buffer.
    pub fn in_plugin_data(range: Range<usize>) -> Self {
        Self::Found(
            PLUGIN_EVENT_PAYLOAD_OFFSET + range.start..PLUGIN_EVENT_PAYLOAD_OFFSET + range.end,
        )
    }
}

/// An extraction request
#[derive(Debug)]
pub struct ExtractRequest<'c, 'e, 'r, 't, P: ExtractPlugin> {
    /// A context instance, potentially shared between extractions
    pub context: &'c mut P::ExtractContext,

    /// The event being processed
    pub event: &'e EventInput<'r, P::Event<'r>>,

    /// An interface to access tables exposed from Falco core and other plugins
    ///
    /// See [`crate::tables`] for details.
    pub table_reader: &'t LazyTableReader<'t>,

    /// Offset of extracted data in event payload
    ///
    /// If set to [`ExtractByteRange::Requested`], and the plugin supports it, replace this
    /// with a [`ExtractByteRange::Found`] containing the byte range containing the extracted value,
    /// *within the whole event buffer*. In the typical case of a range inside the plugin event
    /// data, you can use the [`ExtractByteRange::in_plugin_data`] helper.
    ///
    /// If the data is computed (not directly coming from any byte range in the event), use
    /// [`UNSPECIFIED_RANGE`] instead.
    ///
    /// **Note**: range support is optional, and this field can be ignored.
    pub offset: &'c mut ExtractByteRange,
}

/// Support for field extraction plugins
pub trait ExtractPlugin: Plugin + ExtractPluginExported + Sized
where
    Self: 'static,
{
    /// # Event type to perform extractions on
    ///
    /// 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 [`EventInput::event`],
    /// which you can propagate directly to the caller.
    ///
    /// If you don't want any specific validation/conversion to be performed, specify the type as
    /// ```
    /// type Event<'a> = falco_event::events::RawEvent<'a>;
    /// ```
    type Event<'a>: AnyEventPayload + TryFrom<&'a RawEvent<'a>>;

    /// The extraction context
    ///
    /// It might be useful if your plugin supports multiple fields, and they all share some common
    /// preprocessing steps. Instead of redoing the preprocessing for each field, intermediate
    /// results can be stored in the context for subsequent extractions (from the same event).
    ///
    /// If you do not need a context to share between extracting fields of the same event, use `()`
    /// as the type.
    ///
    /// Since the context is created using the [`Default`] trait, you may prefer to use an Option
    /// wrapping the actual context type:
    ///
    /// ```ignore
    /// impl ExtractPlugin for MyPlugin {
    ///     type ExtractContext = Option<ActualContext>;
    ///     // ...
    /// }
    ///
    /// impl MyPlugin {
    ///     fn make_context(&mut self, ...) -> ActualContext { /* ... */ }
    ///
    ///     fn extract_field_one(
    ///         &mut self,
    ///         req: ExtractContext<Self>) -> ... {
    ///         let context = req.context.get_or_insert_with(|| self.make_context(...));
    ///
    ///         // use context
    ///     }
    /// }
    /// ```
    type ExtractContext: Default + 'static;

    /// The actual list of extractable fields
    ///
    /// An extraction method is a method with the following signature:
    /// ```ignore
    /// use anyhow::Error;
    /// use falco_plugin::extract::{EventInput, ExtractFieldRequestArg, ExtractRequest};
    /// use falco_plugin::tables::TableReader;
    ///
    /// fn extract_sample(
    ///     &mut self,
    ///     req: ExtractRequest<Self>,
    ///     arg: A, // optional
    /// ) -> Result<R, Error>;
    ///
    /// ```
    /// where `R` is one of the following types or a [`Vec`] of them:
    /// - [`u64`]
    /// - [`bool`]
    /// - [`CString`]
    /// - [`std::time::SystemTime`]
    /// - [`std::time::Duration`]
    /// - [`std::net::IpAddr`]
    /// - [`falco_event::types::IpNet`]
    ///
    /// and `A` is the argument to the field extraction:
    ///
    /// | Argument declaration | `field` lookup | `field[5]` lookup | `field[foo]` lookup |
    /// |----------------------|----------------|-------------------|---------------------|
    /// | _missing_            | valid          | -                 | -                   |
    /// | `arg: u64`           | -              | valid             | -                   |
    /// | `arg: Option<u64>`   | valid          | valid             | -                   |
    /// | `arg: &CStr`         | -              | -                 | valid               |
    /// | `arg: Option<&CStr>` | valid          | -                 | valid               |
    ///
    /// `req` is the extraction request ([`ExtractRequest`]), containing the context in which
    /// the plugin is doing the work.
    ///
    /// To register extracted fields, add them to the [`ExtractPlugin::EXTRACT_FIELDS`] array, wrapped via [`crate::extract::field`]:
    /// ```
    /// use std::ffi::CStr;
    /// use falco_event::events::RawEvent;
    /// use falco_plugin::anyhow::Error;
    /// use falco_plugin::base::Plugin;
    /// use falco_plugin::extract::{
    ///     field,
    ///     ExtractFieldInfo,
    ///     ExtractPlugin,
    ///     ExtractRequest};
    ///# use falco_plugin::{extract_plugin, plugin};
    /// use falco_plugin::tables::TablesInput;
    ///
    /// struct SampleExtractPlugin;
    ///
    /// impl Plugin for SampleExtractPlugin {
    ///      const NAME: &'static CStr = c"dummy";
    ///      const PLUGIN_VERSION: &'static CStr = c"0.0.0";
    ///      const DESCRIPTION: &'static CStr = c"test plugin";
    ///      const CONTACT: &'static CStr = c"rust@localdomain.pl";
    ///      type ConfigType = ();
    ///
    ///      fn new(_input: Option<&TablesInput>, _config: Self::ConfigType) -> Result<Self, Error> {
    ///          Ok(Self)
    ///      }
    /// }
    ///
    /// impl SampleExtractPlugin {
    ///     fn extract_sample(
    ///         &mut self,
    ///         _req: ExtractRequest<Self>,
    ///     ) -> Result<u64, Error> {
    ///         Ok(10u64)
    ///     }
    ///
    ///     fn extract_arg(
    ///         &mut self,
    ///         _req: ExtractRequest<Self>,
    ///         arg: u64,
    ///     ) -> Result<u64, Error> {
    ///         Ok(arg)
    ///     }
    /// }
    ///
    /// impl ExtractPlugin for SampleExtractPlugin {
    ///     type ExtractContext = ();
    ///     type Event<'a> = RawEvent<'a>;
    ///     const EXTRACT_FIELDS: &'static [ExtractFieldInfo<Self>] = &[
    ///         field("sample.always_10", &Self::extract_sample),
    ///         field("sample.arg", &Self::extract_arg)
    ///     ];
    /// }
    ///
    ///# plugin!(SampleExtractPlugin);
    ///# extract_plugin!(SampleExtractPlugin);
    /// ```
    const EXTRACT_FIELDS: &'static [ExtractFieldInfo<Self>];

    /// Generate the field schema for the Falco plugin framework
    ///
    /// The default implementation inspects all fields from [`Self::EXTRACT_FIELDS`] and generates
    /// a JSON description in the format expected by the framework.
    ///
    /// You probably won't need to provide your own implementation.
    fn get_fields() -> &'static CStr {
        static FIELD_SCHEMA: Mutex<BTreeMap<TypeId, CString>> = Mutex::new(BTreeMap::new());

        let ty = TypeId::of::<Self>();
        let mut schema_map = FIELD_SCHEMA.lock().unwrap();
        // Safety:
        //
        // we only generate the string once and never change or delete it
        // so the pointer should remain valid for the static lifetime
        // hence the dance of converting a reference to a raw pointer and back
        // to erase the lifetime
        unsafe {
            CStr::from_ptr(
                schema_map
                    .entry(ty)
                    .or_insert_with(|| {
                        let schema = serde_json::to_string_pretty(&Self::EXTRACT_FIELDS)
                            .expect("failed to serialize extraction schema");
                        CString::new(schema.into_bytes())
                            .expect("failed to add NUL to extraction schema")
                    })
                    .as_ptr(),
            )
        }
    }

    /// Perform the actual field extraction
    ///
    /// The default implementation creates an empty context and loops over all extraction
    /// requests, invoking the relevant function to actually generate the field value.
    ///
    /// You probably won't need to provide your own implementation.
    fn extract_fields<'a>(
        &'a mut self,
        event_input: &EventInput<'a, Self::Event<'a>>,
        table_reader: &LazyTableReader,
        fields: &mut [ss_plugin_extract_field],
        offsets: Option<&mut ss_plugin_extract_value_offsets>,
        storage: &'a bumpalo::Bump,
    ) -> Result<(), anyhow::Error> {
        let mut context = Self::ExtractContext::default();

        let (mut offset_vec, mut length_vec) = if offsets.is_some() {
            (
                Some(bumpalo::collections::Vec::with_capacity_in(
                    fields.len(),
                    storage,
                )),
                Some(bumpalo::collections::Vec::with_capacity_in(
                    fields.len(),
                    storage,
                )),
            )
        } else {
            (None, None)
        };

        let mut any_offsets = false;

        for req in fields {
            let info = Self::EXTRACT_FIELDS
                .get(req.field_id as usize)
                .ok_or_else(|| anyhow::anyhow!("field index out of bounds"))?;

            let mut offset = if offsets.is_some() {
                ExtractByteRange::Requested
            } else {
                ExtractByteRange::NotRequested
            };

            let request = ExtractRequest::<Self> {
                context: &mut context,
                event: event_input,
                table_reader,
                offset: &mut offset,
            };

            info.func.call(self, req, request, storage)?;

            if let (Some(offsets_vec), Some(lengths_vec)) =
                (offset_vec.as_mut(), length_vec.as_mut())
            {
                let range = match offset {
                    ExtractByteRange::Found(range) => {
                        any_offsets = true;
                        range
                    }
                    _ => INVALID_RANGE,
                };
                offsets_vec.push(range.start as u32);
                lengths_vec.push(range.end.wrapping_sub(range.start) as u32);
            }
        }

        fn pointer_to_vec<T>(v: &Option<bumpalo::collections::Vec<T>>) -> *mut T {
            match v {
                None => std::ptr::null_mut(),
                Some(v) => v.as_ptr().cast_mut(),
            }
        }

        if let Some(offsets) = offsets {
            if any_offsets {
                offsets.start = pointer_to_vec(&offset_vec);
                offsets.length = pointer_to_vec(&length_vec);
            }
        }

        Ok(())
    }
}