Documentation Index
Fetch the complete documentation index at: https://docs.malbox.app/llms.txt
Use this file to discover all available pages before exploring further.
This page documents all plugin configuration options. For conceptual information, see Plugin Configuration.
Plugin Types
| Type | Description |
|---|
| Guest | Executes within sandboxed environments (VMs, containers). Terminated with sandbox after task completion. |
| Host | Executes directly on the host system with full resource access. Can persist across multiple tasks. |
Execution Contexts
| Context | Description |
|---|
| Exclusive | Plugin runs alone, no other plugins execute simultaneously |
| Sequential | Plugins run one at a time in defined order |
| Parallel | Compatible plugins run concurrently |
| Unrestricted | No coordination required, can run alongside any plugin |
State Management
| Mode | Description |
|---|
| Persistent | Persists across tasks, host plugins only |
| Ephemeral | Fresh state per task, no persistence |
| Scoped | Selective sharing with specific plugins or tasks |
Runtime Configuration
The [runtime] section in plugin.toml controls how the guest plugin runtime behaves. All values are baked into the plugin binary at compile time.
[runtime]
state = "ephemeral" # or "persistent", "scoped"
execution = "exclusive" # or "sequential", "parallel", "unrestricted"
port = 50051
log_filter = "info"
[runtime.paths]
sample_dir = "/tmp/malbox/samples"
artifact_dir = "/tmp/malbox/artifacts"
stash_dir = "/tmp/malbox/stash"
log_dir = "/tmp/malbox/logs"
external_log_dir = "/tmp/malbox/ext-logs"
[runtime.stash]
threshold_bytes = 1048576
ttl_secs = 120
[runtime.auto_collect.artifacts]
enabled = true
include = ["**/*"]
exclude = []
max_file_size = 52428800
[runtime.auto_collect.external_logs]
enabled = true
include = ["**/*"]
exclude = []
max_file_size = 52428800
state and execution are required. All other fields are optional with sensible defaults.
| Field | Type | Required | Default | Description |
|---|
state | string | Yes | - | Plugin state management mode ("ephemeral", "persistent", or "scoped"). |
execution | string | Yes | - | Execution context ("exclusive", "sequential", "parallel", or "unrestricted"). |
port | u16 | No | 50051 | gRPC listen port. Must be >= 1024. Guest plugins only. |
log_filter | string | No | "info" | Tracing directive string (same syntax as tracing_subscriber::EnvFilter). Examples: "info", "debug", "info,hyper=warn". |
[runtime.paths]
| Field | Type | Default (unix) | Default (windows) | Description |
|---|
sample_dir | string | /tmp/malbox/samples | C:\malbox\samples | Where the daemon pushes the sample for analysis. |
artifact_dir | string | /tmp/malbox/artifacts | C:\malbox\artifacts | Where the plugin writes output artifacts. Auto-collected after task execution. |
stash_dir | string | /tmp/malbox/stash | C:\malbox\stash | Internal result stash spillover directory. |
log_dir | string | /tmp/malbox/logs | C:\malbox\logs | SDK-internal log overflow files directory. |
external_log_dir | string | /tmp/malbox/ext-logs | C:\malbox\ext-logs | External log files from kernel drivers or other tools. Auto-collected after task execution. |
[runtime.stash]
| Field | Type | Default | Description |
|---|
threshold_bytes | integer | 1048576 (1 MiB) | Result payloads larger than this are spilled to disk via the result stash. Must be >= 4096. |
ttl_secs | integer | 120 | How long stashed result entries are kept before TTL sweep reclaims them. Must be >= 1. |
[runtime.auto_collect]
Controls automatic file collection from artifact_dir and external_log_dir after each task completes. Files in these directories are streamed back to the daemon as results without the plugin needing to send them explicitly via push_result.
For artifacts, files that were already sent explicitly (via ctx.push_result(PluginResult::file(...))) or marked via ctx.mark_collected() are skipped to avoid duplicates. External logs are always collected without dedup.
[runtime.auto_collect.artifacts]
| Field | Type | Default | Description |
|---|
enabled | bool | true | Whether to auto-collect files from artifact_dir. |
include | string[] | ["**/*"] | Glob patterns for files to include. |
exclude | string[] | [] | Glob patterns for files to exclude. |
max_file_size | integer | 52428800 (50 MiB) | Files larger than this are skipped. |
[runtime.auto_collect.external_logs]
| Field | Type | Default | Description |
|---|
enabled | bool | true | Whether to auto-collect files from external_log_dir. |
include | string[] | ["**/*"] | Glob patterns for files to include. |
exclude | string[] | [] | Glob patterns for files to exclude. |
max_file_size | integer | 52428800 (50 MiB) | Files larger than this are skipped. |
Changing any runtime setting requires rebuilding the plugin.The daemon validates the [runtime] section when scanning plugin manifests.Plugins with invalid values (e.g., a relative sample_dir or a port below 1024) are marked Invalid in the registry and will not be started.
