{"id":47827851,"url":"https://github.com/totekuh/winbox","last_synced_at":"2026-04-29T17:01:09.697Z","repository":{"id":348603492,"uuid":"1198919700","full_name":"totekuh/winbox","owner":"totekuh","description":"Transparent Windows execution proxy for Kali — run Windows pentest tools via a headless QEMU/KVM VM","archived":false,"fork":false,"pushed_at":"2026-04-01T22:21:49.000Z","size":238,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-02T09:44:13.627Z","etag":null,"topics":["cli","hacking","kali","kali-linux","kvm","offensive-security","pentest","python","qemu","red-team","security","virtualization","windows","windows-vm"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/totekuh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T22:19:08.000Z","updated_at":"2026-04-01T22:21:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/totekuh/winbox","commit_stats":null,"previous_names":["totekuh/winbox"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/totekuh/winbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totekuh%2Fwinbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totekuh%2Fwinbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totekuh%2Fwinbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totekuh%2Fwinbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/totekuh","download_url":"https://codeload.github.com/totekuh/winbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totekuh%2Fwinbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31374051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","hacking","kali","kali-linux","kvm","offensive-security","pentest","python","qemu","red-team","security","virtualization","windows","windows-vm"],"created_at":"2026-04-03T20:01:58.282Z","updated_at":"2026-04-25T21:05:00.684Z","avatar_url":"https://github.com/totekuh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# winbox\n\nRun Windows pentest tools from Kali. Transparently.\n\nwinbox 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.\n\n## Quick Demo\n\n```console\n$ winbox setup -y                                    # one-time: builds the VM (~20 min)\n$ winbox tools add Rubeus.exe SharpHound.exe         # drop in your tools\n$ winbox exec Rubeus.exe kerberoast /domain:corp.local\n[*] VM is off, starting...\n[+] VM ready\n[*] Running: Rubeus.exe kerberoast /domain:corp.local\n\n   ______        _\n  (_____ \\      | |\n   _____) )_   _| |__  _____ _   _  ___\n  |  __  /| | | |  _ \\| ___ | | | |/___)\n  | |  \\ \\| |_| | |_) ) ____| |_| |___ |\n  |_|   |_|____/|____/|_____)____/(___/\n  ...\n\n$ winbox exec --bg --log Seatbelt.exe -group=all     # run in background\n[+] Job 1 started (PID 4532)\n$ winbox shell                                       # SYSTEM shell with full PTY\nPS C:\\Windows\\system32\u003e\n```\n\n## Features\n\n- **Transparent execution** — run `.exe` files as if they were native Kali commands\n- **Auto-start** — VM boots on demand, use `winbox suspend` to save state\n- **Shared filesystem** — `~/.winbox/shared/tools/` maps to `Z:\\tools\\` in Windows via VirtIO-FS\n- **One-shot upload \u0026 MSI** — `winbox upload` stages files on Z:\\, `winbox msi` installs an MSI and cleans up\n- **Background jobs** — `--bg` for long-running tools, `--log` for persistent output\n- **Interactive shells** — ConPTY SYSTEM shell with resize support, or SSH into PowerShell\n- **Network integration** — VM traffic is NAT'd through Kali; push DNS, manage hosts file, join AD domains\n- **Snapshots** — save and restore VM state (auto-shuts VM down, bare `winbox snapshot` lists)\n- **AV toggle** — disable/enable Windows Defender on demand (`winbox av disable/enable`)\n- **AppLocker** — enable AppLocker with default rules for bypass testing\n- **Autologin** — persistent Administrator auto-login that survives reboots on Server 2022\n- **Network isolation** — disconnect/reconnect VM NIC while keeping host-VM channels alive\n- **binfmt_misc** — register `.exe` so you can run `./SharpHound.exe` directly from Kali\n- **MCP server** — 31 tools that expose the VM to AI agents (Claude Code) for assisted vulnerability research, including a session-based named-pipe broker and hypervisor-level kernel debug\n- **Hypervisor-level kernel debug** — `winbox kdbg` drives QEMU's gdbstub from outside the VM, with PDB-backed symbol cache, EPROCESS/module walkers, and CR3-switching memory reads (PPL-resistant, EDR-invisible)\n- **VNC display** via virt-manager (`winbox vnc`) — plain VGA, no clipboard/resize\n- **x64dbg in the guest** — bundled in setup, extracted to `C:\\Tools\\x64dbg`, both x32 and x64 on PATH\n- **Python in the guest** — Python 3.13 installed during setup (pip, PATH, py.exe launcher) for MCP-driven research\n- **No VM internet needed for setup** — all tools and dependencies are staged from the host side\n\n## Prerequisites\n\nInstall on Kali (most are pre-installed):\n\n```bash\nsudo apt install qemu-system-x86 qemu-utils libvirt-daemon-system virtinst \\\n    libguestfs-tools virtiofsd p7zip-full genisoimage sshpass wget\n```\n\nRequired:\n- `qemu-system-x86_64`, `qemu-img`, `virsh`, `virt-install`, `virt-customize`\n- `7z` (p7zip-full)\n- `virtiofsd` (at `/usr/libexec/virtiofsd` or on PATH)\n- `/dev/kvm` (hardware virtualization must be enabled)\n- `mkisofs` or `genisoimage`\n- `wget`\n- `default` libvirt network (active)\n\nOptional:\n- `sshpass` — auto-auth for `winbox ssh` (falls back to manual password entry)\n- `virt-manager` — required for `winbox vnc` (VM display — plain VNC, no clipboard/resize)\n\n## Installation\n\n```bash\ngit clone https://github.com/totekuh/winbox.git\ncd winbox\npip install -e .\n```\n\nThen build the VM (downloads Windows Server 2022 eval ISO + VirtIO drivers):\n\n```bash\nwinbox iso download          # ~4.7 GB, supports resume\nwinbox setup -y              # builds and provisions the VM\n```\n\n## Commands\n\n`winbox --help` groups commands into six sections:\n\n```\nVM Lifecycle   setup  up  down  suspend  destroy  status  snapshot  restore  provision\nExecute        exec  shell  ssh  vnc  jobs  msi  eventlogs  kdbg\nFiles          tools  upload  iso\nNetwork        net  dns  hosts  domain\nTarget         av  applocker  autologin     (bidirectional — flip on to test bypass tools)\nIntegrations   binfmt  mcp  office\n```\n\nEach command supports `--help` for its own flags and subcommands.\n\n## Usage\n\n### Executing Commands\n\n```bash\nwinbox exec whoami\nwinbox exec ipconfig /all\nwinbox exec Rubeus.exe kerberoast /domain:corp.local\nwinbox exec --timeout 300 SharpHound.exe -c All     # --timeout must come BEFORE the command\n```\n\nThe VM starts automatically if it's not running.\n\n### Background Jobs\n\nLong-running tools can run in the background:\n\n```bash\nwinbox exec --bg Seatbelt.exe -group=all             # output buffered in guest agent memory\nwinbox exec --bg --log Certify.exe find /vulnerable   # output redirected to log files (tail -f)\nwinbox jobs list                                      # check status\nwinbox jobs output \u003cjob-id\u003e                           # print output\nwinbox jobs kill \u003cjob-id\u003e                             # kill a running job\n```\n\nWith `--log`, output files are at `~/.winbox/shared/loot/.jobs/\u003cid\u003e.stdout` and `.stderr`.\n\n### Interactive Shells\n\n```bash\nwinbox shell                 # ConPTY reverse shell — runs as SYSTEM, supports terminal resize\nwinbox ssh                   # SSH into PowerShell (auto-auth via sshpass)\n```\n\n### Managing Tools\n\nTools placed in the shared directory are available at `Z:\\tools\\` in the VM and automatically on PATH:\n\n```bash\nwinbox tools add Rubeus.exe SharpHound.exe Certify.exe\nwinbox tools list\nwinbox tools remove Rubeus.exe\n```\n\n### One-shot Uploads and MSI Installs\n\nFor files that shouldn't live permanently in the tools dir:\n\n```bash\nwinbox upload payload.exe                         # stage at Z:\\payload.exe\nwinbox upload payload.exe C:\\Windows\\Temp\\p.exe   # also copy into the VM path\n\nwinbox msi VMware-tools.msi ADDLOCAL=ALL /norestart   # extra args pass through to msiexec\n```\n\nBoth stage through the VirtIO-FS share and clean up on failure. `winbox msi` treats exit code 3010 (reboot required) as success.\n\n### Event Logs\n\nQuery Windows event logs from inside the VM. Useful right after running a tool to see what Defender / Sysmon / Security audit logged in response.\n\n```bash\nwinbox eventlogs                                              # Security log, last 1h, max 100 (CSV)\nwinbox eventlogs --since 5m --max 20                          # last 5 minutes\nwinbox eventlogs --log \"Microsoft-Windows-Sysmon/Operational\" # Sysmon channel\nwinbox eventlogs --log Security --id 4624 --id 4625 --since 1d\nwinbox eventlogs --level Error --since 1d --json | jq '.[0]'\nwinbox eventlogs --since 1h | csvgrep -c Id -m 4624           # pipe into csvkit\n```\n\nDefault 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.\n\nClear channels (destructive, prompts for confirmation unless `-y`):\n\n```bash\nwinbox eventlogs clear --log Security                       # one channel\nwinbox eventlogs clear --log Security --log System -y       # multiple\nwinbox eventlogs clear --all -y                             # nuke (read-only / system-protected channels are skipped)\n```\n\n### Network\n\n```bash\n# Isolation\nwinbox net isolate           # disconnect VM from network (host-VM channels stay up)\nwinbox net connect           # reconnect VM to network\nwinbox net status            # show link state\n\n# DNS\nwinbox dns view              # show DNS on Kali and VM\nwinbox dns set 10.10.10.2    # set VM DNS nameserver\nwinbox dns sync              # push Kali's resolv.conf nameservers to VM\n\n# Hosts file\nwinbox hosts view\nwinbox hosts add 10.10.10.5 dc01.corp.local\nwinbox hosts set 10.10.10.5 dc01.corp.local   # idempotent — replaces existing entry\nwinbox hosts delete dc01.corp.local\n\n# Active Directory\nwinbox domain join corp.local --ns 10.10.10.2 --user admin\n# password is prompted interactively\nwinbox domain leave\n```\n\n### VM Lifecycle\n\n```bash\nwinbox up                    # start or resume\nwinbox up --reboot           # graceful shutdown + start in one command\nwinbox down                  # graceful shutdown\nwinbox suspend               # save state to disk (instant resume)\nwinbox status                # state, IP, disk usage, tool/loot counts\nwinbox destroy -y            # delete VM and all storage (clears jobs.json too)\nwinbox provision             # re-run provisioning script\n```\n\n### Snapshots\n\n```bash\nwinbox snapshot              # list existing snapshots\nwinbox snapshot pre-attack   # create named snapshot (auto-shuts VM down first)\n# ... do your thing ...\nwinbox restore pre-attack    # revert to clean state\n```\n\n### Office Installation\n\nFor testing macro-based payloads, install Office on a Desktop Experience VM:\n\n```bash\nwinbox setup --desktop -y    # build VM with Desktop Experience\nwinbox autologin enable      # enable auto-login as Administrator (persistent across reboots)\nwinbox office                # install Word, Excel, PowerPoint with macros enabled\n```\n\nRequires a Microsoft 365 subscription. Macros are enabled (VBAWarnings=1) for Word, Excel, and PowerPoint.\n\n### Persistent Autologin\n\n```bash\nwinbox autologin enable      # writes all 6 Winlogon+PasswordLess keys Server 2022 needs\nwinbox autologin status\nwinbox autologin disable\n```\n\nUnlike 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).\n\n### AppLocker\n\nTest application whitelisting bypass techniques:\n\n```bash\nwinbox applocker enable      # enable AppLocker with default rules (Exe, Script, MSI, Appx)\nwinbox applocker status      # show enforcement status\nwinbox applocker disable     # disable AppLocker, clear policy, reboot\n```\n\n### Antivirus (Windows Defender)\n\n```bash\nwinbox av disable            # disable Defender completely (reboot required — WinDefend is PPL)\nwinbox av status             # show Defender/AMSI protection status\nwinbox av enable             # re-enable Defender + AMSI (adds QEMU GA/VirtIO-FS exclusions)\n```\n\n### Transparent .exe Execution (binfmt_misc)\n\nRegister a binfmt_misc handler so `.exe` files run through winbox automatically:\n\n```bash\nsudo winbox binfmt enable\n./SharpHound.exe -c All      # runs via winbox exec\nsudo winbox binfmt disable\nwinbox binfmt status\n```\n\n### MCP Server (AI-assisted vulnerability research)\n\nwinbox 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.\n\n**Install:**\n\n```bash\npip install -e '.[mcp]'\n```\n\n**Add to Claude Code:**\n\n```bash\nclaude mcp add winbox -- winbox mcp\n```\n\n**Available tools (33):**\n\nUser-mode primitives:\n\n| Tool | Description |\n|------|-------------|\n| `python(code)` | Execute Python code in the VM (ctypes, winreg, COM, WMI — full Win32 access) |\n| `ioctl(device, code, input_hex, output_size)` | Send DeviceIoControl to a driver — no ctypes boilerplate |\n| `reg_query(key, value?)` | Query registry key or value |\n| `reg_set(key, value, data, value_type)` | Set registry value (creates key if needed) |\n| `reg_delete(key, value?)` | Delete registry value or entire key tree |\n| `ps(filter?)` | List processes with PID, name, path, memory usage (JSON) |\n| `upload(src, dst?)` | Upload file from Kali to VM via VirtIO-FS (optionally copy to dst inside VM) |\n| `file_copy(src, dst)` | Copy file within the VM (DLL sideloading, staging binaries) |\n| `mem_read(pid, address, length)` | Read memory from a process (enables SeDebugPrivilege, address as hex string, 1MB cap) |\n| `service_start(name)` | Start a Windows service |\n| `service_stop(name)` | Stop a Windows service |\n| `net_isolate()` | Disconnect VM from network (host-VM channels stay up) |\n| `net_connect()` | Reconnect VM to network (restarts adapter, renews DHCP) |\n| `net_unplug()` | Full air-gap (link down via virsh) |\n| `eventlogs(log?, since?, ids?, provider?, level?, max_events?)` | Query Windows event logs via Get-WinEvent (returns JSON array; CLI defaults to CSV) |\n| `eventlogs_clear(log?, all_logs?, confirm)` | Clear event channels via wevtutil cl. `confirm=True` required (destructive). |\n\nNamed pipes:\n\n| Tool | Description |\n|------|-------------|\n| `pipe_list(filter?)` | Enumerate named pipes matching a pattern (JSON array) |\n| `pipe_info(name)` | JSON: DACL/SDDL, mode, buffer sizes, max instances for a pipe |\n| `pipe_connect(name, access?)` | One-shot pipe handle open; returns result or Win32 error |\n| `pipe_open(name, access)` | Start a session — spawns a detached broker in the VM that holds the handle open |\n| `pipe_send(session_id, data_hex)` | WriteFile through the session broker |\n| `pipe_recv(session_id, size, timeout?)` | ReadFile through the session broker |\n| `pipe_close(session_id)` | Close session + taskkill the broker |\n\nHypervisor-level kernel debug (via QEMU gdbstub + HMP, EDR-invisible):\n\n| Tool | Description |\n|------|-------------|\n| `kdbg_start(port?, any_interface?)` | Start the gdbstub listener |\n| `kdbg_stop()` | Stop the gdbstub listener |\n| `kdbg_status(port?)` | Show stub state + reachability |\n| `kdbg_symbols_load(module?, from_ghidra?, base?)` | Pull ntoskrnl.exe out, fetch PDB from msdl, persist symbols + struct layouts to `~/.winbox/symbols/` |\n| `kdbg_sym(name, search?, limit?, rva?)` | Resolve `mod!sym` to VA or RVA; substring search supported |\n| `kdbg_struct(type_name, field?, module?)` | Dump full struct layout or one field offset |\n| `kdbg_ps()` | Walk `PsActiveProcessHead` (JSON: pid, dtb, eprocess, name) |\n| `kdbg_lm()` | Walk `PsLoadedModuleList` (JSON: base, size, name) |\n| `kdbg_read_va(pid, address, length)` | CR3-switching arbitrary-process read; works against PPL targets (1MB cap, hex bytes) |\n| `kdbg_base_refresh()` | Re-resolve nt load base after ASLR reboot |\n\nThe `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).\n\n**Requires** Python installed in the VM — this is now done automatically as part of `winbox setup`.\n\n## Architecture\n\n```\nKali Linux\n├── winbox CLI (Python/Click)\n│   ├── virtio-serial ──────\u003e QEMU Guest Agent (command execution, VM management)\n│   ├── VirtIO-FS ──────────\u003e ~/.winbox/shared/ \u003c=\u003e Z:\\ in VM\n│   ├── SSH ────────────────\u003e OpenSSH Server (interactive PowerShell)\n│   └── TCP listener ───────\u003c ConPTY reverse shell (SYSTEM, resizable PTY)\n│\n└── Windows Server Core 2022 (headless QEMU/KVM, plain VNC display)\n    ├── QEMU Guest Agent          ← primary exec channel\n    ├── VirtioFsSvc (WinFsp)      ← auto-mounts Z:\\ on boot\n    ├── OpenSSH Server            ← interactive sessions\n    ├── Python 3.13               ← required for MCP Python/ioctl/mem_read tools\n    ├── x64dbg (C:\\Tools\\x64dbg)  ← in-VM user-mode debugger\n    ├── Defender disabled         ← no AV interference\n    ├── Firewall disabled         ← no port blocking\n    └── NAT via libvirt           ← reaches anything Kali can reach\n```\n\n**Four channels:**\n- **Guest Agent** (virtio-serial) — command execution for `winbox exec`, VM management\n- **VirtIO-FS** — shared filesystem, zero-copy via shared memory\n- **SSH** — interactive PowerShell sessions (`winbox ssh`)\n- **ConPTY** — SYSTEM-level interactive shell with full PTY (`winbox shell`)\n\n## Configuration\n\nOverride defaults in `~/.winbox/config` (shell-style `KEY=VALUE`):\n\n```bash\n# VM resources\nVM_NAME=winbox\nVM_RAM=4096          # MB\nVM_CPUS=4\nVM_DISK=30           # GB\n\n# Network\nHOST_IP=192.168.122.1\n\n# Credentials\nVM_USER=Administrator\nVM_PASSWORD=WinboxP@ss123\n\n# Paths\nWINBOX_DIR=~/.winbox\nVIRTIO_ISO_URL=https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso\n```\n\n## Filesystem Layout\n\n```\n~/.winbox/\n├── config                              # user config overrides (optional)\n├── jobs.json                           # background job state (cleared on winbox destroy)\n├── .setup.lock                         # fcntl lock — serializes concurrent winbox setup\n├── id_ed25519 / .pub                   # SSH keypair (generated during setup)\n├── disk.qcow2                          # VM disk image\n├── iso/\n│   ├── SERVER_EVAL_x64FRE_en-us.iso    # Windows Server 2022 eval ISO\n│   ├── virtio-win.iso                  # VirtIO drivers\n│   ├── OpenSSH-Win64.zip               # bundled OpenSSH\n│   ├── winfsp.msi                      # WinFsp installer\n│   ├── virtiofs.exe                    # VirtIO-FS service binary\n│   ├── python-3.13.13-amd64.exe        # Python 3.13 installer for the guest\n│   ├── x64dbg.zip                      # x64dbg snapshot (extracted to C:\\Tools\\x64dbg)\n│   └── unattend.img                    # built during setup\n└── shared/                             # VirtIO-FS share \u003c=\u003e Z:\\ in VM\n    ├── tools/                          # your pentest tools\n    ├── .msi/                           # staging dir for winbox msi (cleaned up per-run)\n    └── loot/                           # output directory\n        └── .jobs/                      # background job log files\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftotekuh%2Fwinbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftotekuh%2Fwinbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftotekuh%2Fwinbox/lists"}