MVMRelay

Authenticated Command Execution for Isolated Windows Research VMs

MVMRelay provides authenticated remote command execution for isolated Windows research VMs without opening an RDP session. It creates temporary or persistent user accounts, executes commands under SYSTEM, Medium Integrity, or Low Integrity, cleans up ephemeral identities, and transfers selected research artifacts through the existing authenticated relay channel.

The project addresses a common limitation of QEMU Guest Agent workflows: qemu-ga executes commands as NT AUTHORITY\SYSTEM, while reverse engineering, security research, and malware analysis often require repeatable execution under constrained security contexts. MVMRelay automates that lifecycle without repeatedly creating users, switching contexts, and performing manual cleanup.

Project Documentation

• Deployment: portable Linux relay and Windows agent installation
• Configuration: server, agent, Compose, and environment settings
• Command reference: mvmctl, relay, agent, installer, and maintenance commands
• Operations: validation, upgrades, identity lifecycle, and recovery
• Diagnostics: debug modes and stable error codes
• Security architecture: trust boundaries and residual risks
• Native embedding: Rust APIs, Linux .so, Windows DLL, C headers, and lifecycle

---

What MVMRelay Does

• Routes authenticated commands from a local Linux control socket to a selected Windows VM.
• Executes commands as LocalSystem or through bounded Medium and Low Integrity identities.
• Supports interactive consoles, one-shot automation, cancellation, and remote deadlines.
• Creates, disables, expires, and removes ephemeral Windows accounts automatically.
• Pulls resumable, SHA-256-verified artifacts through the agent's existing outbound connection.
• Provides native Linux and Windows embedding surfaces for authorized host applications.
• Bounds frames, queues, retained output, concurrency, execution time, and account lifetime.

The relay does not expose a host shell, Docker API, or network-facing operator endpoint.

---

How It Works

A Windows LocalSystem service establishes one outbound mutual-TLS connection to a Linux relay host. Operators use mvmctl through a local mode-0660 Unix socket. The relay authenticates agents, correlates requests to a specific client and connection generation, and returns bounded output or verified artifact chunks over the same channel.

flowchart LR
operator["Operator<br/>mvmctl"] -->|"Mode-0660 Unix socket"| relay["Linux relay host<br/>mvmrelay-server"]
relay <-->|"Outbound mutual TLS<br/>Bounded relay protocol"| agent["Windows VM<br/>LocalSystem agent"]
agent -->|"Create bounded child"| command["SYSTEM, Medium, or Low<br/>Integrity command"]
command -->|"Output and artifact chunks"| agent

Loading

Component	Runs on	Purpose
mvmrelay-server	Linux relay host	Authenticates agents and routes bounded messages
libmvmrelay_server.so	Native Linux host	Embeds the same relay runtime in a larger service
mvmctl	Linux relay host	Uses the local administrative Unix socket
mvmrelay-agent.exe	Windows VM	Boot-start LocalSystem agent and command executor
mvmrelay_agent.dll	Native Windows host	Embeds the same agent runtime in an authorized host process

---

Security Boundary

• The relay binds an explicit administrator-selected VM-network address and rejects peers outside configured CIDRs.
• Mutual TLS authenticates both sides, and each client ID is pinned to its leaf-certificate SHA-256 fingerprint.
• The network listener accepts authenticated agents only. Operator access remains on the local Unix socket.
• Filesystem access is limited to pull-only reads of an explicit operator-selected regular file.
• Routing is scoped by client ID, request ID, and connection generation.
• Windows children use kill-on-close Job Objects.
• Temporary integrity identities are non-administrators, immediately disabled, and deleted on completion, expiry, or startup recovery.

Review the complete security architecture before deployment.

---

Requirements

• A Linux relay host with an isolated VM-network interface
• Docker Engine with Compose for the packaged relay deployment
• A stable Rust toolchain when building from source
• One or more Windows VMs for the agent service
• A private PKI with a unique client identity for each VM

---

Getting Started

The examples use 10.10.10.1/24 and client ID vm01. Replace them with your private VM network.

1) Build the Linux components

CARGO_BUILD_JOBS=1 cargo build --release -p mvmrelay-server -p mvmctl

2) Create the private PKI

scripts/init-pki.sh ./pki 10.10.10.1 mvmrelay.internal
scripts/issue-client.sh ./pki vm01

3) Configure the relay

Copy config/server.example.toml to an ignored runtime directory, set listen, allowed_agent_networks, and [clients.<id>], then place only these runtime certificates under its pki/ directory:

server.crt
server.key
client-ca.crt

Keep both CA private keys outside the container. Configure Compose from a private .env based on deploy/.env.example, then start the relay:

cp deploy/.env.example deploy/.env
docker compose -f deploy/compose.yaml up -d --build
target/release/mvmctl clients

4) Build and install the Windows agent

Build on a Windows Rust host:

cargo build --release -p mvmrelay-agent

Create the VM bundle described in Deployment, then install from elevated PowerShell:

.\Install-MVMRelay.ps1`-SourceDirectory .`-ClientId vm01 `-ServerAddress 10.10.10.1`-ServerName mvmrelay.internal

---

Operate

Interactive console:

$ mvmctl
mvmctl> use vm01
mvmctl>vm01[10.10.10.20]> system
mvmctl>vm01[10.10.10.20]>System> whoami /all
mvmctl>vm01[10.10.10.20]>System> :back
mvmctl>vm01[10.10.10.20]> low --ttl 300
mvmctl>vm01[10.10.10.20]>Low> :userinfo
mvmctl>vm01[10.10.10.20]>Low> :cmd
mvmctl>vm01[10.10.10.20]>Low>Cmd> whoami /all

Interactive commands have a bounded remote deadline. Pressing Ctrl+C requests cancellation of the exact command UUID in the selected VM, and the agent terminates that command's kill-on-close Job Object. Use :context powershell|cmd, :powershell, or :cmd to switch interpreters without changing identity.

One-shot automation:

mvmctl clients
mvmctl exec --client vm01 -- C:\Windows\System32\whoami.exe /all
mvmctl exec --client vm01 --ephemeral-integrity low --account-ttl 60 --timeout 30 -- C:\Windows\System32\whoami.exe /groups
mvmctl exec --client vm01 --powershell-file ./instrument.ps1
mvmctl pull --client vm01 --remote 'C:\dumps\kernel.dmp' --output ./kernel.dmp --resume

Artifact pulls use the agent's existing outbound mTLS connection and the relay's local Unix control socket. Chunks are compressed when beneficial, verified individually and end-to-end with SHA-256, and resumable from a remote-verified local partial prefix. No HTTP receiver or firewall change is involved.

See the command reference for every command, prompt directive, option, environment variable, limit, and exit status.