Falco 插件 SDK

此包提供了一个框架用于编写 Falco 插件。有几种类型的插件可用。了解更多关于 Falco 插件和插件类型的信息，请参阅 Falco 插件文档。

动态链接插件

分发 Falco 插件的典型方式是构建一个共享库。要构建一个作为共享库的插件，您需要

1. 在 [lib] 部分中指定 crate_type = ["dylib"],
2. 调用与您的插件实现的功能相对应的所有 宏。

所有插件都必须实现基本插件特质（见 base），以及至少一种插件能力。

注意：由于 Falco 插件 API 的结构，每个共享库中只能有一个插件，尽管该插件可以实施多种能力，如以下所述。

静态链接插件

在某些情况下，您可能更喜欢将插件静态链接到您的应用程序中。这会稍微改变接口（而不是使用预定义的符号名称，您可以通过直接传递 falco_plugin_api::plugin_api 结构到 sinsp::register_plugin）来注册您的插件）。

对于静态链接的插件，您需要

1. 在 [lib] 部分中指定 crate_type = ["staticlib"],
2. 导出插件 API，例如以下名称

use std::ffi::CStr;
use falco_plugin::base::{InitInput, Plugin};
use falco_plugin::base::PluginApi;
use falco_plugin::FailureReason;

// define the type holding the plugin state
struct DummyPlugin;

// implement the base::Plugin trait
impl Plugin for DummyPlugin {
    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"[email protected]";
    type ConfigType = ();

    fn new(input: &InitInput, config: Self::ConfigType)
        -> Result<Self, FailureReason> {
        Ok(DummyPlugin)
    }

    fn set_config(&mut self, config: Self::ConfigType) -> Result<(), anyhow::Error> {
        Ok(())
    }
}

#[no_mangle]
pub static DUMMY_PLUGIN_API: falco_plugin_api::plugin_api =
    PluginApi::<DummyPlugin>::PLUGIN_API;

注意：由于实现限制，每个静态库中只能有一个插件，尽管该插件可以实施多种能力，如以下所述。这种限制对于静态库来说比共享库更痛苦（因为您可以在静态库中有意义地发送多个插件），并且可能会在未来取消。

事件来源插件

源插件用于生成事件。实现分为两部分

1. 在插件类型上实现 source::SourcePlugin，主要用于创建插件实例
2. 实现 source::SourcePluginInstance 的类型，该类型负责实际的事件生成

为了注册您的插件的事件源功能，将其传递给 source_plugin! 宏。

查看 samples/source_plugin.rs 了解示例实现。

字段提取插件

字段提取插件为规则匹配和规则输出添加额外的字段。每个字段都有一个名称、类型和一个返回实际提取数据的函数或方法。通过实现 extract::ExtractPlugin 特性来创建提取插件。

查看 samples/extract_plugin.rs 了解示例实现。

事件解析插件

事件解析插件在每个事件（除了一些过滤）上被调用，并且可以用来在事件之间保持一些状态，例如为提取插件或源插件返回数据。通过实现 parse::ParsePlugin 并用插件类型调用 parse_plugin! 来创建。

查看 samples/parse_plugin.rs 了解示例实现。

异步事件插件

异步事件插件可用于在主事件循环之外注入事件，例如从单独的线程。通过实现 async_event::AsyncEventPlugin 并用插件类型调用 async_event_plugin! 来创建。

查看 samples/async_plugin.rs 了解示例实现。