Content
# winbox
Run Windows pentest tools from Kali. Transparently.
winbox manages a headless Windows Server Core 2022 VM via QEMU/KVM. Type `winbox exec SharpHound.exe -c All -d corp.local` on your Kali box and it Just Works — the VM starts automatically, runs the command, and prints the output.
## Quick Demo
```console
$ winbox setup -y # one-time: builds the VM (~20 min)
$ winbox tools add Rubeus.exe SharpHound.exe # drop in your tools
$ winbox exec Rubeus.exe kerberoast /domain:corp.local
[*] VM is off, starting...
[+] VM ready
[*] Running: Rubeus.exe kerberoast /domain:corp.local
______ _
(_____ \ | |
_____) )_ _| |__ _____ _ _ ___
| __ /| | | | _ \| ___ | | | |/___)
| | \ \| |_| | |_) ) ____| |_| |___ |
|_| |_|____/|____/|_____)____/(___/
...
$ winbox exec --bg --log Seatbelt.exe -group=all # run in background
[+] Job 1 started (PID 4532)
$ winbox shell # SYSTEM shell with full PTY
PS C:\Windows\system32>
```
## Features
- **Transparent execution** — run `.exe` files as if they were native Kali commands
- **Auto-start** — VM boots on demand, use `winbox suspend` to save state
- **Shared filesystem** — `~/.winbox/shared/tools/` maps to `Z:\tools\` in Windows via VirtIO-FS
- **One-shot upload & MSI** — `winbox upload` stages files on Z:\, `winbox msi` installs an MSI and cleans up
- **Background jobs** — `--bg` for long-running tools, `--log` for persistent output
- **Interactive shells** — ConPTY SYSTEM shell with resize support, or SSH into PowerShell
- **Network integration** — VM traffic is NAT'd through Kali; push DNS, manage hosts file, join AD domains
- **Snapshots** — save and restore VM state (auto-shuts VM down, bare `winbox snapshot` lists)
- **AV toggle** — disable/enable Windows Defender on demand (`winbox av disable/enable`)
- **AppLocker** — enable AppLocker with default rules for bypass testing
- **Autologin** — persistent Administrator auto-login that survives reboots on Server 2022
- **Network isolation** — disconnect/reconnect VM NIC while keeping host-VM channels alive
- **Malware detonation lab** — `winbox capture` (host-side pcap on the bridge — prefers `dumpcap`, which Kali's Wireshark package lets the `wireshark` group run without root, falling back to `tcpdump` otherwise), `winbox sinkhole` (zero-dependency DNS sinkhole that answers every C2 lookup with the bridge IP and logs the domain, plus optional INETSim fake services), and `winbox detonate check` (read-only preflight that refuses to go green unless the guest genuinely can't reach the internet). See [docs/malware-detonation.md](docs/malware-detonation.md)
- **binfmt_misc** — register `.exe` so you can run `./SharpHound.exe` directly from Kali
- **MCP server** — 54 tools that expose the VM to AI agents (Claude Code) for assisted vulnerability research, including Defender enable/disable/status, a session-based named-pipe broker, and a long-running hypervisor-level kernel debug session
- **Hypervisor-level kernel debug** — `winbox kdbg` drives QEMU's gdbstub from outside the VM via a long-running session daemon, pure-Python RSP client, PDB-backed symbol cache, EPROCESS/module walkers, hardware breakpoints by default (Z1/DRs, KVM-virtualized — invisible to PatchGuard and `GetThreadContext`; `--mode auto` falls back to software 0xCC where the 4 DR slots run out, but note HVCI blocks software breakpoints on Windows 11), conditional breakpoints (server-side predicates), and CR3-switching memory reads (PPL-resistant, EDR-invisible)
- **VNC display** via virt-manager (`winbox vnc`) — plain VGA, no clipboard/resize
- **x64dbg in the guest** — bundled in setup, extracted to `C:\Tools\x64dbg`, both x32 and x64 on PATH
- **Python in the guest** — Python 3.13 installed during setup (pip, PATH, py.exe launcher) for MCP-driven research
- **No VM internet needed for setup** — all tools and dependencies are staged from the host side
## Prerequisites
Install on Kali (most are pre-installed):
```bash
sudo apt install qemu-system-x86 qemu-utils libvirt-daemon-system virtinst \
libguestfs-tools virtiofsd p7zip-full genisoimage sshpass wget
```
Required:
- `qemu-system-x86_64`, `qemu-img`, `virsh`, `virt-install`, `virt-customize`
- `7z` (p7zip-full)
- `virtiofsd` (at `/usr/libexec/virtiofsd` or on PATH)
- `/dev/kvm` (hardware virtualization must be enabled)
- `mkisofs` or `genisoimage`
- `wget`
- `default` libvirt network (active)
Optional:
- `sshpass` — auto-auth for `winbox ssh` (falls back to manual password entry)
- `virt-manager` — required for `winbox vnc` (VM display — plain VNC, no clipboard/resize)
## Installation
```bash
git clone https://github.com/totekuh/winbox.git
cd winbox
pip install -e .
```
Then build the VM (downloads the eval ISO + VirtIO drivers):
```bash
winbox iso download # ~4.7 GB, supports resume
winbox setup -y # builds and provisions the VM
```
### Choosing the guest OS
`winbox setup` builds **Windows Server 2022** by default. Pass `--os win11` to build
**Windows 11 Enterprise (Evaluation)** instead:
```bash
winbox setup --os win11 -y # build Windows 11 instead of Server 2022
```
The choice is build-time and there is one VM at a time — switching OS means
`winbox destroy -y` then `winbox setup --os <other> -y`. Setup records the choice as
`VM_OS=` in `~/.winbox/config`, so every later command (`status`, `av`, `exec`, the
MCP server) resolves the same profile as the VM on disk; you can also set that key
yourself to change the default for a bare `winbox setup`. The right ISO is downloaded
automatically for the selected OS (or pass `--iso <path>` to use your own).
Notes for Win11:
- No TPM / Secure Boot required — setup injects the `LabConfig` bypass keys so the
install proceeds on plain UEFI. `--desktop` is Server-only and rejected for Win11.
- Win11 needs a 64 GB system drive and the standard UEFI layout (larger ESP + MSR
partition); setup handles both automatically (the disk is grown to 64 GB and the
Windows partition lands on partition 3).
- **Defender:** Win11 client ships with Tamper Protection on, which normally blocks
the registry-based disable. Setup clears it in the offline registry hive before
first boot so Defender can be turned off during provisioning. This is best-effort
(Defender's cloud component can re-arm it on a networked boot); `winbox av status`
reports the Tamper-Protection state, and `winbox av disable` refuses honestly rather
than falsely reporting success if TP is still on.
- If Microsoft rotates the eval ISO's download link, the auto-download fails loudly;
grab the ISO manually and pass `--iso <path>`.
## Commands
`winbox --help` groups commands into seven sections:
```
VM Lifecycle setup provision up down suspend destroy status snapshot restore vnc
Execute eventlogs exec shell ssh jobs msi
Files tools upload iso
Network net dns hosts domain
Target applocker autologin av (bidirectional — flip on to test bypass tools)
Malware Analysis capture detonate sinkhole (detonation lab — capture C2, sinkhole DNS, preflight)
Integrations binfmt kdbg mcp office
```
Each command supports `--help` for its own flags and subcommands.
## Usage
### Executing Commands
```bash
winbox exec whoami
winbox exec ipconfig /all
winbox exec Rubeus.exe kerberoast /domain:corp.local
winbox exec --timeout 300 SharpHound.exe -c All # --timeout must come BEFORE the command
```
The VM starts automatically if it's not running.
### Background Jobs
Long-running tools can run in the background:
```bash
winbox exec --bg Seatbelt.exe -group=all # output buffered in guest agent memory
winbox exec --bg --log Certify.exe find /vulnerable # output redirected to log files (tail -f)
winbox jobs list # check status
winbox jobs output <job-id> # print output
winbox jobs kill <job-id> # kill a running job
```
With `--log`, output files are at `~/.winbox/shared/loot/.jobs/<id>.stdout` and `.stderr`.
### Interactive Shells
```bash
winbox shell # ConPTY reverse shell — runs as SYSTEM, supports terminal resize
winbox ssh # SSH into PowerShell (auto-auth via sshpass)
```
### Managing Tools
Tools placed in the shared directory are available at `Z:\tools\` in the VM and automatically on PATH:
```bash
winbox tools add Rubeus.exe SharpHound.exe Certify.exe
winbox tools list
winbox tools remove Rubeus.exe
```
### One-shot Uploads and MSI Installs
For files that shouldn't live permanently in the tools dir:
```bash
winbox upload payload.exe # stage at Z:\payload.exe
winbox upload payload.exe C:\Windows\Temp\p.exe # also copy into the VM path
winbox msi VMware-tools.msi ADDLOCAL=ALL /norestart # extra args pass through to msiexec
```
Both stage through the VirtIO-FS share and clean up on failure. `winbox msi` treats exit code 3010 (reboot required) as success.
### Event Logs
Query Windows event logs from inside the VM. Useful right after running a tool to see what Defender / Sysmon / Security audit logged in response.
```bash
winbox eventlogs # Security log, last 1h, max 100 (CSV)
winbox eventlogs --since 5m --max 20 # last 5 minutes
winbox eventlogs --log "Microsoft-Windows-Sysmon/Operational" # Sysmon channel
winbox eventlogs --log Security --id 4624 --id 4625 --since 1d
winbox eventlogs --level Error --since 1d --json | jq '.[0]'
winbox eventlogs --since 1h | csvgrep -c Id -m 4624 # pipe into csvkit
```
Default output is CSV (RFC 4180, fields `Time,Log,Level,Id,Provider,Message`). `--json` emits the raw `Get-WinEvent` JSON. Status messages go to stderr so stdout stays clean for piping. Newlines/tabs in Message are flattened to ` | ` so each event is exactly one CSV row. `--log` is repeatable for multi-channel queries; `--id` is repeatable and OR'd inside the filter.
Clear channels (destructive, prompts for confirmation unless `-y`):
```bash
winbox eventlogs clear --log Security # one channel
winbox eventlogs clear --log Security --log System -y # multiple
winbox eventlogs clear --all -y # nuke (read-only / system-protected channels are skipped)
```
### Network
```bash
# Isolation
winbox net isolate # disconnect VM from network (host-VM channels stay up)
winbox net connect # reconnect VM to network
winbox net status # show link state
# DNS
winbox dns view # show DNS on Kali and VM
winbox dns set 10.10.10.2 # set VM DNS nameserver
winbox dns sync # push Kali's resolv.conf nameservers to VM
# Hosts file
winbox hosts view
winbox hosts add 10.10.10.5 dc01.corp.local
winbox hosts set 10.10.10.5 dc01.corp.local # idempotent — replaces existing entry
winbox hosts delete dc01.corp.local
# Active Directory
winbox domain join corp.local --ns 10.10.10.2 --user admin
# password is prompted interactively
winbox domain leave
```
### VM Lifecycle
```bash
winbox up # start or resume
winbox up --reboot # graceful shutdown + start in one command
winbox down # graceful shutdown
winbox suspend # save state to disk (instant resume)
winbox status # state, IP, disk usage, tool/loot counts
winbox destroy -y # delete VM and all storage (clears jobs.json too)
winbox provision # re-run provisioning script
```
### Snapshots
```bash
winbox snapshot # list existing snapshots
winbox snapshot pre-attack # create named snapshot (auto-shuts VM down first)
# ... do your thing ...
winbox restore pre-attack # revert to clean state
```
### Office Installation
For testing macro-based payloads, install Office on a Desktop Experience VM:
```bash
winbox setup --desktop -y # build VM with Desktop Experience
winbox autologin enable # enable auto-login as Administrator (persistent across reboots)
winbox office # install Word, Excel, PowerPoint with macros enabled
```
Requires a Microsoft 365 subscription. Macros are enabled (VBAWarnings=1) for Word, Excel, and PowerPoint.
### Persistent Autologin
```bash
winbox autologin enable # writes all 6 Winlogon+PasswordLess keys Server 2022 needs
winbox autologin status
winbox autologin disable
```
Unlike the old 3-key approach, this actually survives reboots on Server 2022 (which otherwise silently wipes `DefaultPassword` on first boot without `ForceAutoLogon=1` and the `PasswordLess\Device\DevicePasswordLessBuildVersion=0` gate).
### AppLocker
Test application whitelisting bypass techniques:
```bash
winbox applocker enable # enable AppLocker with default rules (Exe, Script, MSI, Appx)
winbox applocker status # show enforcement status
winbox applocker disable # disable AppLocker, clear policy, reboot
```
### Antivirus (Windows Defender)
```bash
winbox av disable # disable Defender completely (reboot required — WinDefend is PPL)
winbox av status # show Defender/AMSI protection status
winbox av enable # re-enable Defender + AMSI (adds QEMU GA/VirtIO-FS exclusions)
```
### Transparent .exe Execution (binfmt_misc)
Register a binfmt_misc handler so `.exe` files run through winbox automatically:
```bash
sudo winbox binfmt enable
./SharpHound.exe -c All # runs via winbox exec
sudo winbox binfmt disable
winbox binfmt status
```
### MCP Server (AI-assisted vulnerability research)
winbox exposes an MCP server so AI agents (Claude Code, etc.) can interact with the Windows VM directly — run Python code, send IOCTLs to drivers, query/set registry, list processes, talk to named pipes.
**Install:**
```bash
pip install -e '.[mcp]'
```
**Add to Claude Code:**
```bash
claude mcp add winbox -- winbox mcp
```
**Available tools (54):**
User-mode primitives:
| Tool | Description |
|------|-------------|
| `python(code)` | Execute Python code in the VM (ctypes, winreg, COM, WMI — full Win32 access) |
| `ioctl(device, code, input_hex, output_size)` | Send DeviceIoControl to a driver — no ctypes boilerplate |
| `reg_query(key, value?)` | Query registry key or value |
| `reg_set(key, value, data, value_type)` | Set registry value (creates key if needed) |
| `reg_delete(key, value?)` | Delete registry value or entire key tree |
| `ps(filter?)` | List processes with PID, name, path, memory usage (JSON) |
| `upload(src, dst?)` | Upload file from Kali to VM via VirtIO-FS (optionally copy to dst inside VM) |
| `file_copy(src, dst)` | Copy file within the VM (DLL sideloading, staging binaries) |
| `mem_read(pid, address, length)` | Read memory from a process (enables SeDebugPrivilege, address as hex string, 1MB cap) |
| `service_start(name)` | Start a Windows service |
| `service_stop(name)` | Stop a Windows service |
| `net_isolate()` | Disconnect VM from network (host-VM channels stay up) |
| `net_connect()` | Reconnect VM to network (restarts adapter, renews DHCP) |
| `net_unplug()` | Full air-gap (link down via virsh) |
| `eventlogs(log?, since?, ids?, provider?, level?, max_events?)` | Query Windows event logs via Get-WinEvent (returns JSON array; CLI defaults to CSV) |
| `eventlogs_clear(log?, all_logs?, confirm)` | Clear event channels via wevtutil cl. `confirm=True` required (destructive). |
Defender:
| Tool | Description |
|------|-------------|
| `av_status(timeout?)` | Report Defender/AMSI protection state (Get-MpComputerStatus + Get-MpPreference) |
| `av_enable()` | Re-enable Defender real-time protection, AMSI, and behavior monitoring |
| `av_disable(confirm)` | Disable Defender completely — sets GP registry keys then reboots the VM. `confirm=True` required. |
Named pipes:
| Tool | Description |
|------|-------------|
| `pipe_list(filter?)` | Enumerate named pipes matching a pattern (JSON array) |
| `pipe_info(name)` | JSON: DACL/SDDL, mode, buffer sizes, max instances for a pipe |
| `pipe_connect(name, access?)` | One-shot pipe handle open; returns result or Win32 error |
| `pipe_open(name, access)` | Start a session — spawns a detached broker in the VM that holds the handle open |
| `pipe_send(session_id, data_hex)` | WriteFile through the session broker |
| `pipe_recv(session_id, size, timeout?)` | ReadFile through the session broker |
| `pipe_close(session_id)` | Close session + taskkill the broker |
Hypervisor-level kernel debug (via QEMU gdbstub + HMP, EDR-invisible):
*Stateless walks and symbol management — work against the live VM without an attached session:*
| Tool | Description |
|------|-------------|
| `kdbg_start(port?, any_interface?)` | Start the gdbstub listener |
| `kdbg_stop()` | Stop the gdbstub listener |
| `kdbg_status(port?)` | Show stub state + reachability |
| `kdbg_symbols_load()` | Pull ntoskrnl.exe out, fetch PDB from msdl, persist symbols + struct layouts to `~/.winbox/symbols/` |
| `kdbg_user_symbols_load(name, vm_path)` | Same flow for an arbitrary user-mode binary (per-process PDB) |
| `kdbg_sym(name, search?, limit?, rva?)` | Resolve `mod!sym` to VA or RVA; substring search supported |
| `kdbg_struct(type_name, field?, module?)` | Dump full struct layout or one field offset |
| `kdbg_ps()` | Walk `PsActiveProcessHead` (JSON: pid, dtb, eprocess, name) |
| `kdbg_lm()` | Walk `PsLoadedModuleList` (JSON: base, size, name) |
| `kdbg_user_lm(pid)` | Walk `PEB.Ldr` for one process — modules actually loaded in target |
| `kdbg_read_va(pid, address, length)` | CR3-switching arbitrary-process read; works against PPL targets (1MB cap, hex bytes) |
| `kdbg_base_refresh()` | Re-resolve nt load base after ASLR reboot |
*Session daemon — long-running debug session (attach once, drive across many tool calls):*
| Tool | Description |
|------|-------------|
| `kdbg_attach(pid, port?)` | Fork the session daemon and attach to a target process. VM keeps running; bps stay armed until detach |
| `kdbg_detach()` | Tear down the session and leave the VM running |
| `kdbg_session()` | Show current daemon state (target pid, attach time, bp count, halted vs running) |
| `kdbg_bp(target, mode?, condition?)` | Install a bp. `mode="hw"` (default; Z1/DR — invisible to PatchGuard + `GetThreadContext`, 4 slots/vCPU), `mode="soft"` (0xCC patch — unlimited but PG-visible), or `mode="auto"` (hw first, soft on slot exhaustion). **On Windows 11 use `hw`/`auto`: HVCI blocks the software 0xCC patch.** Optional `condition` is a server-side predicate evaluated on each fire (regs, `[reg+off]` qword reads, `==/!=/</<=/>/>=`, `&&`/`||`) |
| `kdbg_bps()` | List installed bps with hit/skip/error counters |
| `kdbg_rm(bp_id)` | Remove an installed bp |
| `kdbg_cont(timeout?)` | Resume; block until next stop in target's CR3 set (KPTI-aware: kernel + user PML4) |
| `kdbg_step()` | Single-instruction step on the firing vCPU |
| `kdbg_interrupt()` | Halt a running cont via raw `\x03` on the RSP socket |
| `kdbg_resume()` | Resume without waiting (fire-and-forget) |
| `kdbg_regs()` | Dump GPRs + control regs from the firing vCPU |
| `kdbg_stack(n?)` | Hex-dump the top `n` qwords of the current stack |
| `kdbg_bt(depth?)` | Symbolicated backtrace (cross-module, with C++ demangling via `llvm-undname`) |
| `kdbg_mem(va, length?, decode?)` | Read in target's CR3 (CR3-masquerade); `decode` modes for hex/utf8/utf16/disasm |
| `kdbg_write_mem(va, hex)` | Write into target's CR3 (used for buffer-swap / agent-driven MITM workflows) |
| `kdbg_disasm(va, length?)` | Capstone disassembly at a target VA |
The `pipe_open` + `pipe_send`/`recv`/`close` family uses a persistent broker process per session (spawned as DETACHED_PROCESS | CREATE_NO_WINDOW inside the VM). IPC happens via `cmd.json`/`result.json` files on the VirtIO-FS share, so there's no VM round-trip on the polling path. This matters for protocols where a write on one handle must be answered on the same handle (stateless `send`/`recv` open fresh handles and never see each other's messages).
**Requires** Python installed in the VM — this is now done automatically as part of `winbox setup`.
## Architecture
```
Kali Linux
├── winbox CLI (Python/Click)
│ ├── virtio-serial ──────> QEMU Guest Agent (command execution, VM management)
│ ├── VirtIO-FS ──────────> ~/.winbox/shared/ <=> Z:\ in VM
│ ├── SSH ────────────────> OpenSSH Server (interactive PowerShell)
│ └── TCP listener ───────< ConPTY reverse shell (SYSTEM, resizable PTY)
│
└── Windows Server Core 2022 (headless QEMU/KVM, plain VNC display)
├── QEMU Guest Agent ← primary exec channel
├── VirtioFsSvc (WinFsp) ← auto-mounts Z:\ on boot
├── OpenSSH Server ← interactive sessions
├── Python 3.13 ← required for MCP Python/ioctl/mem_read tools
├── x64dbg (C:\Tools\x64dbg) ← in-VM user-mode debugger
├── Defender disabled ← no AV interference
├── Firewall disabled ← no port blocking
└── NAT via libvirt ← reaches anything Kali can reach
```
**Four channels:**
- **Guest Agent** (virtio-serial) — command execution for `winbox exec`, VM management
- **VirtIO-FS** — shared filesystem, zero-copy via shared memory
- **SSH** — interactive PowerShell sessions (`winbox ssh`)
- **ConPTY** — SYSTEM-level interactive shell with full PTY (`winbox shell`)
## Configuration
Override defaults in `~/.winbox/config` (shell-style `KEY=VALUE`):
```bash
# VM resources
VM_NAME=winbox
VM_RAM=4096 # MB
VM_CPUS=4
VM_DISK=30 # GB
# Network
HOST_IP=192.168.122.1
# Credentials
VM_USER=Administrator
VM_PASSWORD=WinboxP@ss123
# Paths
WINBOX_DIR=~/.winbox
VIRTIO_ISO_URL=https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso
```
## Filesystem Layout
```
~/.winbox/
├── config # user config overrides (optional)
├── jobs.json # background job state (cleared on winbox destroy)
├── .setup.lock # fcntl lock — serializes concurrent winbox setup
├── id_ed25519 / .pub # SSH keypair (generated during setup)
├── disk.qcow2 # VM disk image
├── iso/
│ ├── SERVER_EVAL_x64FRE_en-us.iso # Windows Server 2022 eval ISO
│ ├── virtio-win.iso # VirtIO drivers
│ ├── OpenSSH-Win64.zip # bundled OpenSSH
│ ├── winfsp.msi # WinFsp installer
│ ├── virtiofs.exe # VirtIO-FS service binary
│ ├── python-3.13.13-amd64.exe # Python 3.13 installer for the guest
│ ├── x64dbg.zip # x64dbg snapshot (extracted to C:\Tools\x64dbg)
│ └── unattend.img # built during setup
├── captures/ # winbox capture — host-side pcaps
│ ├── capture-<ts>.pcap
│ └── capture.pid # pidfile for the running capture
├── sinkhole/ # winbox sinkhole — DNS sinkhole state
│ ├── queries.log # captured C2 domains (tab-sep)
│ ├── sinkhole.pid
│ └── inetsim.conf # written by `sinkhole inetsim`
└── shared/ # VirtIO-FS share <=> Z:\ in VM
├── tools/ # your pentest tools
├── .msi/ # staging dir for winbox msi (cleaned up per-run)
└── loot/ # output directory
└── .jobs/ # background job log files
```
## Testing
```bash
pytest # unit + coverage tests, no VM required
pytest -m integration # live end-to-end suite, drives the real VM
```
A bare `pytest` deselects everything marked `integration`, so it never touches a
VM you are using.
The live suite (`tests/test_e2e_live.py`) exercises every CLI command and every
MCP tool against whichever image `~/.winbox/config` points at, and is written to
pass on **both** `server2022` and `win11` — where the two genuinely differ
(Tamper Protection, Server Core's smaller service set, the Python payload) it
asserts the profile-appropriate behavior instead of skipping.
`tests/e2e_manifest.py` records how each command and tool is covered — live, or
excluded with a stated reason — and `tests/test_e2e_coverage.py` checks that
manifest against the real click tree and MCP registry. Adding a command or tool
fails the build until you say how it gets exercised, which is what keeps "we
test everything" a claim you can verify rather than one that quietly rots.
To validate a change across both images:
```bash
winbox setup --os server2022 -y && pytest -m integration
winbox setup --os win11 -y && pytest -m integration
```
## License
MIT
