Provisioning

What are provisioners?

Provisioners handle post-allocation machine setup - installing packages, deploying guest plugins, running configuration scripts, and taking snapshots. After a provider allocates a machine, provisioning steps prepare it for analysis. Provisioners are transport-agnostic: each provisioner manages its own connectivity to the machine (WinRM, SSH, etc.). Like providers, provisioners register themselves at compile time using the inventory crate and can be developed independently.

Running provisioning

Provisioning is driven through the malbox CLI. Each invocation runs a single provisioning step against a machine via the daemon’s HTTP API (POST /v1/machines/{id}/provision).

malbox machine provision win10-dev \
  --provisioner ansible \
  --snapshot with-yara \
  --config '{"playbook": "playbooks/windows/provision.yml"}' \
  --plugins guest-windows-agent

Flag	Required	Description
`--provisioner`	Yes	Provisioner type (e.g. `"ansible"`).
`--snapshot`	No	Snapshot name to create after successful provisioning.
`--revert-to`	No	Snapshot to revert to before provisioning (defaults to `"base"`).
`--config`	No	Provisioner-specific config as JSON.
`--plugins`	No	Guest plugin names to deploy (resolved from the daemon’s plugin registry).

Machines can be referenced by name or numeric ID. If omitted, Malbox shows an interactive fuzzy selector. You can view provisioning history with:

malbox machine provision-history win10-dev

What happens during a provision step

The machine transitions to provisioning state (prevents concurrent provisioning)
The VM is reverted to the --revert-to snapshot (defaults to "base") for a clean starting state
The VM is started and the daemon waits for the management service (WinRM on port 5986 for Windows, SSH on port 22 for Linux) to become reachable
The provisioner runs (e.g. Ansible executes the playbook)
The VM is stopped
If --snapshot was specified, a provider-level snapshot is taken and recorded in the database
The machine transitions back to ready

Multi-step provisioning

To build up a machine in layers, run multiple provision commands, each snapshotting after completion. Later steps can use --revert-to to start from a previous step’s snapshot:

# Step 1: Configure auto-login, snapshot as "configured"
malbox machine provision win10-dev \
  --provisioner ansible \
  --config '{"playbook": "playbooks/windows/provision.yml", "extra_vars": {"skip_plugins": "true"}}' \
  --snapshot configured

# Step 2: Deploy guest plugins on top of the configured snapshot
malbox machine provision win10-dev \
  --provisioner ansible \
  --revert-to configured \
  --config '{"playbook": "playbooks/windows/provision.yml", "extra_vars": {"skip_autologin": "true"}}' \
  --plugins guest-windows-agent \
  --snapshot ready

Architecture

The provisioner system follows the same pattern as providers:

Provisioner trait - defines the contract all provisioners must implement: an async provision(context) method and a name() method.
ProvisionerMetadata - registered at compile time via the inventory crate. Contains the provisioner name and a factory function.
ProvisionContext - passed to the provisioner with the machine’s network endpoint (IP, platform) and the step’s TOML config.
ProvisionResult - returned by the provisioner with a status (Success or Failed) and optional output text.

Provisioners are looked up by name at runtime using create_provisioner(name, config).

Supported provisioners

Ansible

The built-in Ansible provisioner runs Ansible playbooks against allocated machines. It auto-generates dynamic inventory when needed and injects plugin metadata as extra variables.

Configuration

Field	Type	Default	Description
`playbook`	`string`	(required)	Path to the Ansible playbook to execute. Must exist on disk.
`inventory`	`string`	`"dynamic"`	Inventory source. Set to `"dynamic"` to auto-generate a temporary inventory with the machine IP, or provide a path to a static inventory file.
`extra_vars`	`table`	`{}`	Extra variables passed to `ansible-playbook --extra-vars`.
`plugins`	`table`	`{}`	Plugin entries resolved by the daemon. Each key is a plugin name with `binary`, `manifest`, and `port` fields.
`timeout`	`integer`	`1800`	Timeout in seconds for the `ansible-playbook` process.
`ansible_bin`	`string`	`"ansible-playbook"`	Path to the `ansible-playbook` binary.

Dynamic inventory

When inventory = "dynamic" (the default), the provisioner generates a temporary inventory file containing the machine’s IP address. For Windows machines, it automatically adds WinRM connection variables:

[malbox]
192.168.1.50 ansible_connection=winrm ansible_winrm_transport=ntlm ansible_winrm_server_cert_validation=ignore ansible_port=5986 ansible_user=Administrator ansible_password=packer

For Linux machines, only the IP is added (SSH is the default connection).

Guest plugin injection

When plugins are specified (either via --plugins on the CLI or guest_plugins in the pipeline), the Ansible provisioner resolves each plugin’s plugin.toml manifest. It then injects a guest_plugins extra variable as a JSON array. Each entry includes:

{
  "name": "my-plugin",
  "binary": "/path/to/plugin.exe",
  "toml": "/path/to/plugin.toml",
  "port": 50051,
  "paths": {
    "sample_dir": "C:\\malbox\\samples",
    "artifact_dir": "C:\\malbox\\artifacts",
    "stash_dir": "C:\\malbox\\stash",
    "log_dir": "C:\\malbox\\logs"
  }
}

The paths are resolved from the plugin’s [runtime.paths] in plugin.toml, so playbooks can create the correct directories on the guest without hardcoding paths.

Bundled playbooks

Malbox ships a modular provision.yml playbook for Windows that composes two steps:

Auto-login configuration - configures the sandbox user for interactive sample execution
Guest plugin deployment - copies plugin binaries and manifests, creates runtime directories, sets up scheduled tasks to start plugins on login

Each sub-step can be skipped via extra variables (skip_plugins, skip_autologin):

# Plugins only (auto-login already configured):
malbox machine provision win10-dev \
  --provisioner ansible \
  --config '{"playbook": "playbooks/windows/provision.yml", "extra_vars": {"skip_autologin": "true"}}' \
  --plugins guest-windows-agent \
  --snapshot with-plugins

Next steps

Read about Providers for machine allocation
Read about Packer for building machine images

Getting Started

Plugin System

Machinery

Task Management

Contributing

What are provisioners?

Running provisioning

What happens during a provision step

Multi-step provisioning

Architecture

Supported provisioners

Ansible

Configuration

Dynamic inventory

Guest plugin injection

Bundled playbooks

Next steps

​What are provisioners?

​Running provisioning

​What happens during a provision step

​Multi-step provisioning

​Architecture

​Supported provisioners

​Ansible

​Configuration

​Dynamic inventory

​Guest plugin injection

​Bundled playbooks

​Next steps

What are provisioners?

Running provisioning

What happens during a provision step

Multi-step provisioning

Architecture

Supported provisioners

Ansible

Configuration

Dynamic inventory

Guest plugin injection

Bundled playbooks

Next steps