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.
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)# Generate the compile-time runtime-config header from plugin.toml.malbox_generate_runtime_config( MANIFEST ${CMAKE_CURRENT_SOURCE_DIR}/plugin.toml OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/generated/malbox_runtime_config.hpp)add_executable(my-plugin src/main.cpp ${MALBOX_GENERATED_HEADERS})target_include_directories(my-plugin PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/generated)target_link_libraries(my-plugin PRIVATE MalboxPluginSDK::MalboxPluginSDK)
The malbox_generate_runtime_config function invokes the malbox-codegen CLI (shipped with the SDK) to read your plugin.toml and emit a malbox_runtime_config.hpp header with constexpr values. The header is regenerated whenever plugin.toml changes.
#include <malbox/plugin.hpp>#include "malbox_runtime_config.hpp" // generated from plugin.tomlclass MyPlugin final : public malbox::Plugin {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::Task& task, const malbox::Context& ctx) override { auto sample = task.sample_bytes(); ctx.emit_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.push_result(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.plugin_type = malbox::PluginType::Guest; meta.state = malbox::PluginState::Ephemeral; meta.execution = malbox::ExecutionContext::Exclusive; malbox::run_guest_plugin( std::make_unique<MyPlugin>(), meta, malbox::generated::runtime_config);}
Your plugin subclasses malbox::Plugin and implements on_task at minimum. The on_start and on_stop lifecycle hooks are optional.For a host plugin, change the metadata and entry point:
Results are pushed to the daemon during on_task via ctx.push_result(). You can call it multiple times to stream results incrementally. There are three result types:
// JSON-encoded result (pass raw UTF-8 bytes)ctx.push_result(PluginResult::json("name", byte_span));// Raw binary resultctx.push_result(PluginResult::bytes("name", byte_span));// Reference a file on disk (runtime reads it)ctx.push_result(PluginResult::file("name", "/path/to/file"));
Each result name should match an entry in your plugin.toml under [results.*].
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:
When using ExecutionContext::Parallel, multiple on_task calls may execute concurrently. Protect shared mutable state with std::mutex or similar synchronization primitives. Health checks may also arrive on a different thread regardless of execution context.
Guest plugins that run inside a Windows analysis VM need to be cross-compiled. The Malbox devenv provides a MinGW toolchain and a CMake toolchain file for this:
This produces a statically linked .exe binary with no runtime DLL dependencies.
The MinGW toolchain file reads MINGW_LIB_PATH and MINGW_INCLUDE_PATH environment variables for library and header search paths. The Malbox devenv sets these automatically.
Guest plugin binaries must be deployed inside the analysis VM. Place them in the daemon’s plugin directory (so the daemon knows about them), then provision the binary into the VM:
