Creating a Rust plugin

Step-by-step guide to building analysis plugins in Rust using the Malbox Plugin SDK

Getting started

Create a new repository from the Rust plugin template by clicking Use this template on GitHub. Clone your new repository and rename the project in Cargo.toml and plugin.toml to match your plugin name.

The template gives you a working plugin with Cargo configuration, a plugin.toml manifest, a build.rs, example source code, and CI already set up.

Prerequisites

• Rust toolchain (stable, 2024 edition)

Project structure

Cargo.toml

[package]
name = "my-plugin"
version = "0.1.0"
edition = "2024"

[dependencies]
malbox-plugin-sdk = { path = "path/to/malbox-plugin-sdk", features = ["host"] }
serde = { version = "1", features = ["derive"] }

plugin.toml

Every plugin needs a plugin.toml manifest alongside its binary. This tells the daemon how to manage your plugin.

[plugin]
name = "my-plugin"
version = "0.1.0"
description = "My analysis plugin"
authors = ["Your Name"]
type = "guest"                    # or "host"

[runtime]
state = "ephemeral"               # or "persistent", "scoped"
execution = "exclusive"           # or "sequential", "parallel", "unrestricted"
port = 50051                      # gRPC listen port (default: 50051)
log_filter = "info"               # tracing filter (default: "info")
analysis_timeout = 300            # max analysis time in seconds (default: 300)

[runtime.paths]
sample_dir       = "C:\\malbox\\samples"      # where daemon pushes the sample
artifact_dir     = "C:\\malbox\\artifacts"    # where plugin writes output (auto-collected)
stash_dir        = "C:\\malbox\\stash"        # internal result stash spillover
log_dir          = "C:\\malbox\\logs"         # SDK-internal log overflow files
external_log_dir = "C:\\malbox\\ext-logs"     # external tool/driver logs (auto-collected)

[runtime.stash]
threshold_bytes = 1048576
ttl_secs = 120

# Event subscriptions (host plugins only)
[events]
subscribe = ["other-plugin"]

[results.my_result]
description = "What this result contains"
user_visible = true
display_name = "My Result"
render = "json"

See the Plugin Configuration Reference for the full field list, defaults, and validation rules.

build.rs

The build.rs ensures cargo re-runs the proc-macro when plugin.toml changes:

fn main() {
    println!("cargo:rerun-if-changed=plugin.toml");
}

src/main.rs

The SDK uses attribute macros to wire your plugin into the runtime. You annotate your struct and impl block instead of manually implementing traits.

extern crate malbox_plugin_sdk as malbox;

use malbox::prelude::*;

#[malbox::host_plugin]
struct MyPlugin;

#[malbox::handlers]
impl MyPlugin {
    #[malbox::on_start]
    fn init(&self) -> Result<()> {
        info!("Plugin ready - waiting for tasks");
        Ok(())
    }

    #[malbox::on_task]
    fn process(&self, ctx: &Context) -> Result<()> {
        let sample = ctx.task().sample_bytes()?;
        ctx.progress(0.5, "analyzing")?;

        // ... perform analysis ...

        ctx.results().push(PluginResult::json("my_result", &serde_json::json!({
            "status": "clean"
        }))?)?;
        Ok(())
    }

    #[malbox::on_stop]
    fn shutdown(&self) -> Result<()> {
        info!("Plugin shutting down");
        Ok(())
    }
}

The #[malbox::handlers] macro scans your impl block for annotated methods and generates the necessary trait implementations. Your method names can be anything you like - the attributes determine their role.

Handler methods

Attribute	Signature	Required
#[malbox::on_task]	fn(&self, ctx: &Context) -> Result<()>	No (default no-op)
#[malbox::on_start]	fn(&self) -> Result<()> or fn(&self, config: T) -> Result<()>	No
#[malbox::on_stop]	fn(&self) -> Result<()>	No
#[malbox::health_check]	fn(&self) -> HealthStatus	No
#[malbox::on_event(EventVariant)]	fn(&self) -> Result<()> or fn(&self)	No

When on_start takes a typed parameter, the macro deserializes the raw HashMap<String, String> config into that type automatically.

Pushing results

Results are pushed to the daemon via ctx.results(). You can call push methods multiple times to stream results incrementally. There are three result types:

ctx.results().push(PluginResult::json("name", &my_struct)?)?;
ctx.results().push(PluginResult::bytes("name", raw_data))?;
ctx.results().push(PluginResult::file("name", "/path/to/file"))?;

json() returns Result<PluginResult> (serialization can fail), while bytes() and file() return PluginResult directly.

Each result name should match an entry in your plugin.toml under [results.*].

Reports

For structured analysis output with verdicts, indicators, TTPs, and frontend-renderable sections, use the ReportBuilder to construct a Report and push it as a result. Reports support:

• Verdicts with classification (clean/suspicious/malicious/unknown), confidence, and score
• Indicators (IOCs) with open-vocabulary types like sha256, ipv4, domain
• TTPs referencing MITRE ATT&CK techniques
• Artifact references linking to sibling PluginResult entries
• Presentation sections with typed blocks (markdown, tables, code, hex dumps, graphs, timelines, and more)

See the results and reports reference for the complete type catalog, or the SDK reference for builder API methods.

use malbox::types::report::{ReportBuilder, Classification, Confidence, Indicator};

let report = ReportBuilder::new("my-plugin", "0.1.0")
    .summary("Analysis complete")
    .verdict(Classification::Malicious, Some(85), Some(Confidence::High))
    .indicator(Indicator::new("sha256", "abc123..."))
    .section("overview", "Overview", |s| {
        s.markdown("Found malicious indicators")
    })
    .build();

ctx.results().push(report.into_plugin_result()?)?;

Handling errors

The SDK uses its own Result<T> type aliased to std::result::Result<T, SdkError>. Handler methods return Result<()> and can use ? to propagate errors naturally.

#[malbox::on_task]
fn process(&self, ctx: &Context) -> Result<()> {
    let sample = ctx.task().sample_bytes()?;

    if sample.is_empty() {
        return Err(SdkError::Plugin("empty sample".into()));
    }

    ctx.results().push(PluginResult::json("result", &"ok")?)?;
    Ok(())
}

Subscribing to events

Declare subscriptions in the [events] section of your plugin.toml, then use #[malbox::on_event(...)] in your handler impl to react to specific event variants:

# plugin.toml
[events]
subscribe = ["string-extractor", "network-analyzer"]

#[malbox::handlers]
impl MyPlugin {
    #[malbox::on_event(TaskCompleted)]
    fn on_task_done(&self) -> Result<()> {
        info!("A task completed");
        Ok(())
    }

    #[malbox::on_event(PluginResultAvailable)]
    fn on_upstream_result(&self) -> Result<()> {
        info!("An upstream plugin produced a result");
        Ok(())
    }
}

Event handlers are called with no arguments (the event metadata is matched internally by the macro). Handlers can optionally return Result<()>.

See the Events Reference for the full list of available events.

Holding state

Your plugin struct can hold fields. For concurrent access with ExecutionContext::Parallel, wrap mutable state in Mutex or similar:

#[malbox::host_plugin]
struct MyPlugin {
    cache: Mutex<HashMap<String, String>>,
}

Thread safety

When using ExecutionContext::Parallel, multiple on_task calls may execute concurrently. Protect shared mutable state with Mutex, RwLock, or atomic types. Health checks may also arrive on a different thread regardless of execution context.

Testing

The SDK provides a testkit feature for writing unit tests without a running daemon. Enable it in your Cargo.toml:

[dev-dependencies]
malbox-plugin-sdk = { path = "path/to/malbox-plugin-sdk", features = ["host", "testkit"] }

This gives you Context::test_new() to create a mock context for testing handler logic.

Build

Linux

Host plugins always target Linux (they run on the daemon machine). Guest plugins targeting a Linux guest VM also use this.

cargo build --release

Deploy

Place the compiled binary and plugin.toml in a subdirectory of the daemon’s plugin directory. The daemon discovers plugins automatically on startup.

~/.config/malbox/plugins/

my-host-plugin-bin

plugin.toml

Examples

See the example plugins on GitHub.