Malbox provides configuration options for controlling how plugins operate. Both the plugin system itself and individual plugins can be configured to fit specific use cases and requirements. All plugin configuration lives in plugin.toml, a manifest file that sits alongside the plugin binary.
Plugin types
Plugins can run either on the host system or inside a sandboxed (guest) environment:
| Type | Transport | Lifecycle | Use case |
|---|
| Host | iceoryx2 IPC (shared memory) | Can persist across tasks | Analysis that needs host-level access or long-lived state (ML models, signature databases) |
| Guest | gRPC | Terminated with sandbox after each task | Analysis inside a VM that monitors the sample at runtime (ETW, syscall tracing) |
HostPlugin trait with on_task, on_start, on_stop, on_event, and health_check handlers. Guest plugins implement the GuestPlugin trait with on_start, on_stop, execute_sample, and health_check handlers.
Execution contexts
Execution contexts define how plugins coordinate with each other during task execution:
| Context | Description |
|---|
exclusive | Only one instance runs at a time across the entire daemon. Use when the plugin holds a global lock or exclusive resource. |
sequential | Tasks are dispatched one at a time, in order. The plugin processes tasks serially but the daemon can run other plugins concurrently. |
parallel | Multiple tasks may run concurrently within this plugin. Your handlers must be thread-safe (Mutex, RwLock, atomics). |
unrestricted | No constraints on concurrency or ordering. Use when the plugin is fully stateless. |
execution in the [runtime] section of plugin.toml:
[runtime]
execution = "parallel"
State management
State management controls how plugins maintain data across their lifecycle:
| Mode | Description |
|---|
persistent | Stays running between tasks. The process is started once and reused. Host plugins only. Good for keeping ML models or signature databases loaded in memory. |
ephemeral | Spun up per task and torn down immediately after. Each task gets a clean plugin process. The default for guest plugins. |
scoped | Lives for the duration of an analysis scope (e.g. a batch of related tasks). Requires a [scope] section defining which plugins and task types share the scope. |
scoped state is not yet implemented. Plugins configured with state = "scoped" will fail to start.
state in the [runtime] section of plugin.toml:
[runtime]
state = "persistent"
Runtime configuration
Guest plugins carry their runtime settings in the [runtime] section of their plugin.toml. The SDK bakes these values into the plugin binary at build time. Host plugins have the same [runtime] section, but the daemon reads it at registry scan time rather than baking it into the binary.
Key runtime settings include paths (sample directory, artifact directory, stash directory), stash behavior (threshold and TTL), analysis timeout, log filter, and auto-collection configuration for artifacts and external logs.
To change a runtime setting, edit plugin.toml and rebuild the plugin (guest) or restart the daemon (host). See the plugin configuration reference for the full field list, defaults, and validation rules.
Custom plugin settings
Beyond system-level configuration, you can expose custom settings. The daemon passes a HashMap<String, String> config map to the plugin’s on_start handler. In Rust host plugins, the #[malbox::handlers] macro can automatically deserialize this map into a typed struct if your on_start method takes a typed parameter.
Event subscriptions
Host plugins can subscribe to other plugins’ event channels via the [events] section in plugin.toml. This enables reactive analysis pipelines where plugins chain off each other’s output. See Event Hooks for details.
[events]
subscribe = ["string-extractor"]
Guest plugins do not support event subscriptions.
Reference
For complete specifications, all available options, and validation rules, see the plugin configuration reference. 
