@adamkadaban/crucible

crucible

Build, snapshot, and control isolated Windows analysis VMs from Linux MCP agents.

Crucible provisions a Windows analysis VM on QEMU/KVM, installs debugger tooling and a small mTLS guest agent, then exposes VM control through a CLI and MCP server.

Use it for local malware-analysis and Windows debugging workflows where you control the host. Do not treat it as a hard containment boundary against VM escapes or host-kernel bugs.

Quick Start

Requirements:

• Linux host with KVM access.
• QEMU, OVMF, swtpm, socat, and xorriso.
• Local Windows installer ISO, virtio-win ISO, and virtio guest tools installer.

Debian / Ubuntu baseline:

sudo apt install qemu-system-x86 qemu-utils ovmf swtpm socat xorriso

Install the CLI:

npm install -g @adamkadaban/crucible
crucible doctor

Create a config, edit the media paths, and provision:

crucible config init
crucible provision
crucible guest health
crucible snapshot list

The first provision usually takes 12-18 minutes and creates a clean-base snapshot. Restore that snapshot before each new analysis session.

MCP Server

Run the MCP server over stdio:

crucible mcp --stdio

Use the setup helpers instead of hand-editing client config:

crucible setup opencode
crucible setup claude
crucible setup codex --print
crucible setup copilot --print

Example opencode config:

{
  "mcp": {
    "crucible": {
      "enabled": true,
      "type": "local",
      "command": ["crucible", "mcp", "--stdio"]
    }
  }
}

Common Commands

crucible --help
crucible version
crucible update --dry-run
crucible vm status
crucible vm credentials
printf %s "$VM_PASSWORD" | crucible vm paste --stdin
crucible vm view --dry-run
crucible snapshot restore clean-base
crucible network status

crucible vm credentials prints generated Windows account credentials from host-only secret files. Treat that output as sensitive. Use crucible vm paste --stdin to paste passwords into the focused VM window without putting the secret itself in shell history.

Source Checkout

Use a source checkout only when developing Crucible itself:

git clone https://github.com/Adamkadaban/crucible.git
cd crucible
scripts/check-host.sh
nvm install
corepack enable pnpm
pnpm install --frozen-lockfile
pnpm build

From source, use pnpm crucible ... instead of the global binary.

Safety

• Keep the default network mode isolated unless guest egress is intentional.
• Never mount host home directories, SSH agents, browser profiles, cloud credentials, or repository roots into the guest.
• Keep malware samples and generated artifacts outside Git and outside synced personal folders.
• Treat generated secrets, autounattend files, dumps, pcaps, and snapshots as local-only artifacts.
• Stop and restore clean-base after each sample unless you are intentionally continuing the same investigation.

See SECURITY.md for reporting and containment guidance.

Documentation

• docs/install.md - detailed install and first provision.
• docs/provisioning.md - provisioning stages, realism mode, and E2E scope.
• docs/qemu.md - QEMU command shape and lifecycle state.
• docs/network-isolation.md - isolated, NAT, and capture modes.
• docs/protocol.md - guest agent mTLS HTTP API.
• docs/debugger.md - CDB-backed debugger workflows.
• docs/malware-analysis-sop.md - operating procedure.
• docs/teardown.md - cleanup boundaries.
• docs/threat-model.md - assumptions and non-goals.

Development

pnpm check
pnpm e2e
pnpm e2e:live  # opt-in; requires local Windows media and live VM config

cd guest-agent
go test ./...
go build ./...

License

MIT