Creating a C++ plugin

Getting started

Create a new repository from the C++ plugin template by clicking Use this template on GitHub. Clone your new repository and rename the project in CMakeLists.txt and plugin.toml to match your plugin name.The template gives you a working plugin with CMake configuration, a plugin.toml manifest, example source code, and CI already set up.

Prerequisites

C++20 compiler (GCC 11+, Clang 13+, or MSVC 2019 16.10+)
CMake 3.20+

Project structure

`CMakeLists.txt`

cmake_minimum_required(VERSION 3.20)
project(my-plugin LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(MalboxPluginSDK REQUIRED)

add_executable(my-plugin src/main.cpp)
target_link_libraries(my-plugin PRIVATE MalboxPluginSDK::MalboxPluginSDK)

`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.

`src/main.cpp`

#include <malbox/plugin.hpp>

class MyPlugin final : public malbox::HostPlugin {
public:
    void on_start(const std::unordered_map<std::string, std::string>& config) override {
        // Called once before tasks arrive. Use config for initialization.
    }

    void on_task(const malbox::Context& ctx) override {
        auto sample = ctx.task().sample_bytes();
        ctx.progress(0.5, "analyzing");

        // ... perform analysis ...

        std::string json = R"({"status": "clean"})";
        auto data = std::span<const uint8_t>{
            reinterpret_cast<const uint8_t*>(json.data()),
            json.size()
        };
        ctx.results().push(malbox::PluginResult::json("my_result", data));
    }

    void on_stop() override {
        // Called once on shutdown. Clean up resources.
    }
};

int main() {
    malbox::PluginMeta meta{};
    meta.name        = "my-plugin";
    meta.version     = "0.1.0";
    meta.description = "My analysis plugin";
    meta.authors     = "Your Name";
    meta.state       = malbox::PluginState::Ephemeral;
    meta.execution   = malbox::ExecutionContext::Exclusive;

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

Handler methods

Override virtual methods on the malbox::HostPlugin base class:

Method	Signature	Required
`on_task`	`(const Context&) -> void`	No (default no-op)
`on_start`	`(const std::unordered_map<std::string, std::string>&) -> void`	No
`on_stop`	`() -> void`	No
`health_check`	`() -> HealthStatus`	No
`on_event`	`(const Event&) -> void`	No

Pushing results

Results are pushed to the daemon via the ResultSink obtained from ctx.results(). You can call push methods multiple times to stream results incrementally:

// Using PluginResult objects
ctx.results().push(PluginResult::json("name", byte_span));
ctx.results().push(PluginResult::bytes("name", byte_span));
ctx.results().push(PluginResult::file("name", "/path/to/file"));

// Or use the convenience methods on ResultSink directly:
ctx.results().push_json("name", byte_span);
ctx.results().push_bytes("name", byte_span);
ctx.results().push_file("name", "/path/to/file");

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.

#include <malbox/report.hpp>

using namespace malbox::report;

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

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

Handling errors

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>

if (something_wrong) {
    throw malbox::Error{malbox::ErrorKind::Unknown, "analysis failed: corrupt sample"};
}

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

Subscribing to events

Override on_event to react to system-wide or plugin lifecycle events:

void on_event(const malbox::Event& event) override {
    if (event.tag() == malbox::EventTag::PluginResultAvailable) {
        auto source = event.source();
        auto name = event.result_name();
    }
}

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

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.

Build

Linux

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

cmake -B build -DCMAKE_PREFIX_PATH=/path/to/malbox-plugin-sdk/dist
cmake --build build

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.

Installation

Plugin Development

Creating a C++ plugin

Getting started

Prerequisites

Project structure

`CMakeLists.txt`

`plugin.toml`

`src/main.cpp`

Handler methods

Pushing results

Reports

Handling errors

Subscribing to events

Thread safety

Build

Linux

Deploy

Examples

​Getting started

​Prerequisites

​Project structure

​CMakeLists.txt

​plugin.toml

​src/main.cpp

​Handler methods

​Pushing results

​Reports

​Handling errors

​Subscribing to events

​Thread safety

​Build

​Linux

​Deploy

​Examples

Getting started

Prerequisites

Project structure

`CMakeLists.txt`

`plugin.toml`

`src/main.cpp`

Handler methods

Pushing results

Reports

Handling errors

Subscribing to events

Thread safety

Build

Linux

Deploy

Examples