C++ - Malbox Docs

Complete API reference for the Malbox C++20 Plugin SDK. For a step-by-step walkthrough, see the Creating a C++ Plugin guide.

Plugin Base Class

Every plugin subclasses malbox::Plugin and implements on_task at minimum. All other methods have default no-op implementations.

#include <malbox/plugin.hpp>

class MyPlugin final : public malbox::Plugin {
    std::vector<PluginResult> on_task(const Task& task, const Context& ctx) override;
};

Lifecycle Methods

`on_task` (required)

Called for each assigned analysis task. This is where your analysis logic lives.

virtual std::vector<PluginResult> on_task(const Task& task, const Context& ctx) = 0;

task

const Task&

required

Handle to the current task. Provides access to the sample and task configuration. Non-owning, do not store.

ctx

const Context&

required

Runtime communication handle for emitting progress, warnings, and events. Non-owning, do not store.

return

std::vector<PluginResult>

One or more analysis results. Each result name should match a [results.*] entry in your plugin.toml.

`on_start`

Called once before any tasks arrive. Use for initialization.

virtual void on_start(const std::unordered_map<std::string, std::string>& config);

config

const std::unordered_map<std::string, std::string>&

Key-value configuration map from the daemon and plugin.toml settings.

`on_stop`

Called once on shutdown. Clean up resources here.

virtual void on_stop();

`health_check`

Called periodically by the runtime to check plugin health.

virtual HealthStatus health_check();

return

HealthStatus

A struct with ready (bool) and reason (string) fields.

Event Handlers

Override these to react to system events. All are optional and default to no-ops. See the Events Reference for the full list of events in each category.

`on_daemon_event`

Triggered by system-wide events such as shutdown or configuration reload.

virtual void on_daemon_event(DaemonEvent event, const Context& ctx);

event

DaemonEvent

required

The daemon event that occurred (DaemonShutdown or ConfigReloaded).

ctx

const Context&

required

Runtime communication handle.

`on_task_event`

Triggered by task lifecycle events (created, starting, completed, failed).

virtual void on_task_event(TaskEvent event, const TaskEventPayload& payload, const Context& ctx);

event

TaskEvent

required

The task event that occurred.

payload

const TaskEventPayload&

required

Contains the task_id of the affected task.

ctx

const Context&

required

Runtime communication handle.

`on_plugin_event`

Triggered by plugin process events (started, stopped, result produced).

virtual void on_plugin_event(PluginEvent event, const PluginEventPayload& payload, const Context& ctx);

event

PluginEvent

required

The plugin event that occurred.

payload

const PluginEventPayload&

required

Contains the plugin_id of the affected plugin.

ctx

const Context&

required

Runtime communication handle.

`on_sample_event`

Triggered by sample processing events (started, stopped, result produced).

virtual void on_sample_event(SampleEvent event, const SampleEventPayload& payload, const Context& ctx);

event

SampleEvent

required

The sample event that occurred.

payload

const SampleEventPayload&

required

Contains the sample_id of the affected sample.

ctx

const Context&

required

Runtime communication handle.

Task

Provides access to the current analysis task. Task is a non-owning handle, valid only during the on_task callback. Do not store it.

`id()`

int32_t id();

return

int32_t

Unique identifier for this task.

`sample_path()`

std::string sample_path();

return

std::string

Absolute path to the sample on disk.

`sample_bytes()`

Reads the entire sample file into memory. Throws malbox::Error on I/O failure.

std::vector<uint8_t> sample_bytes();

return

std::vector<uint8_t>

The raw bytes of the sample file.

`config()`

std::unordered_map<std::string, std::string> config();

return

std::unordered_map<std::string, std::string>

All configuration key-value pairs for this task.

`config_value()`

std::optional<std::string> config_value(const std::string& key);

key

const std::string&

required

The configuration key to look up.

return

std::optional<std::string>

The value if found, or std::nullopt.

Context

Used to communicate with the runtime during task execution. Context is a non-owning handle, valid only during the callback. Do not store it.

`emit_progress()`

Reports task progress to the runtime.

void emit_progress(double fraction, const std::string& message);

fraction

double

required

Progress value clamped to [0.0, 1.0].

message

const std::string&

required

Human-readable status message (e.g. "scanning signatures").

`warn()`

Attaches a warning message to the task report.

void warn(const std::string& message);

message

const std::string&

required

The warning message to attach.

`emit_event()`

Emits a raw system event. This is an advanced escape hatch for custom event routing.

void emit_event(Event event, Payload payload);

event

Event

required

The event to emit.

payload

Payload

required

The event payload.

PluginResult

Returned from on_task to report analysis findings. Each result name should correspond to a [results.*] entry in your plugin.toml.

`PluginResult::json()`

Creates a JSON-encoded result from raw UTF-8 bytes.

static PluginResult json(const std::string& name, std::span<const uint8_t> data);

name

const std::string&

required

Result identifier matching a [results.*] key in plugin.toml.

data

std::span<const uint8_t>

required

Raw UTF-8 encoded JSON bytes.

`PluginResult::bytes()`

Creates a raw binary result.

static PluginResult bytes(const std::string& name, std::span<const uint8_t> data);

name

const std::string&

required

Result identifier matching a [results.*] key in plugin.toml.

data

std::span<const uint8_t>

required

Raw binary data.

`PluginResult::file()`

Creates a result referencing a file on disk. The runtime reads the file contents.

static PluginResult file(const std::string& name, const std::string& path);

name

const std::string&

required

Result identifier matching a [results.*] key in plugin.toml.

path

const std::string&

required

Absolute filesystem path to the result file.

PluginMeta

Metadata passed to the runtime at startup. All string fields must be null-terminated string literals with static lifetime.

name

const char*

required

Plugin identifier. Must be alphanumeric with - and _ only.

version

const char*

required

Semver version string (e.g. "0.1.0").

description

const char*

Human-readable description. Nullable.

authors

const char*

required

Author name(s).

plugin_type

PluginType

required

PluginType::Host or PluginType::Guest.

state

PluginState

required

PluginState::Persistent, PluginState::Ephemeral, or PluginState::Scoped.

execution

ExecutionContext

required

ExecutionContext::Exclusive, Sequential, Parallel, or Unrestricted.

Enums

PluginType
PluginState
ExecutionContext

Value	Description
`PluginType::Guest`	Runs inside a VM/container, communicates via gRPC
`PluginType::Host`	Runs on the daemon machine, communicates via IPC

Value	Description
`PluginState::Persistent`	Stays running between tasks
`PluginState::Ephemeral`	Spawned per task, torn down after
`PluginState::Scoped`	Lives for a batch of related tasks

Value	Description
`ExecutionContext::Exclusive`	Only one instance runs across the entire daemon
`ExecutionContext::Sequential`	Tasks dispatched one at a time, in order
`ExecutionContext::Parallel`	Multiple tasks may run concurrently
`ExecutionContext::Unrestricted`	No constraints on concurrency or ordering

Runtime Entry Points

malbox::run_guest_plugin(std::make_unique<MyPlugin>(), meta);

Both functions block until the runtime shuts down. They throw malbox::Error on failure.

plugin

std::unique_ptr<Plugin>

required

Owning pointer to your plugin instance.

Error Handling

Plugin methods can throw malbox::Error to signal failures. The SDK catches exceptions at the FFI boundary and reports them to the runtime.

#include <malbox/error.hpp>

throw malbox::Error(-1, "analysis failed: corrupt sample");

code

int32_t

required

Numeric error code. Use -1 for generic failures.

message

const char*

required

Human-readable error description.

SDK methods (like task.sample_bytes()) also throw malbox::Error on failure.

Thread Safety

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

Headers

Header	Contents
`malbox/plugin.hpp`	Umbrella header (include this one)
`malbox/error.hpp`	`malbox::Error` exception class
`malbox/types.hpp`	Enums, `PluginMeta`, `HealthStatus`
`malbox/events.hpp`	Event types and payloads
`malbox/task.hpp`	`malbox::Task` wrapper
`malbox/context.hpp`	`malbox::Context` wrapper
`malbox/result.hpp`	`malbox::PluginResult`
`malbox/handlers.hpp`	`malbox::Plugin` base class
`malbox/runtime.hpp`	Entry points and trampolines

Configuration

Plugin SDK

​Plugin Base Class

​Lifecycle Methods

​on_task (required)

​on_start

​on_stop

​health_check

​Event Handlers

​on_daemon_event

​on_task_event

​on_plugin_event

​on_sample_event

​Task

​id()

​sample_path()

​sample_bytes()

​config()

​config_value()

​Context

​emit_progress()

​warn()

​emit_event()

​PluginResult

​PluginResult::json()

​PluginResult::bytes()

​PluginResult::file()

​PluginMeta

​Enums

​Runtime Entry Points

​Error Handling

​Thread Safety

​Headers

Plugin Base Class

Lifecycle Methods

`on_task` (required)

`on_start`

`on_stop`

`health_check`

Event Handlers

`on_daemon_event`

`on_task_event`

`on_plugin_event`

`on_sample_event`

Task

`id()`

`sample_path()`

`sample_bytes()`

`config()`

`config_value()`

Context

`emit_progress()`

`warn()`

`emit_event()`

PluginResult

`PluginResult::json()`

`PluginResult::bytes()`

`PluginResult::file()`

PluginMeta

Enums

Runtime Entry Points

Error Handling

Thread Safety

Headers