HID-Shell

A headless shell payload that rides the Vandal agent's vendor HID interface. It spawns a local OS shell and pumps stdin/stdout over 64-byte raw HID reports — no network path, no console window on the host, nothing written to disk.

Getting started GitHub

Core concepts

Everything you need to understand what HID-Shell does and how it moves bytes.

Raw-HID transport

Speaks the Vandal vendor HID interface (usage page 0xFF00) with 64-byte reports — no TCP, UDP, or any other network protocol on the host.

Headless shell bridge

Spawns cmd.exe (Windows, hidden console) or an interactive /bin/sh on a PTY (POSIX) and streams bytes both ways until the agent sends BYE.

Device disambiguation

Probes every vendor-page HID device with a HELLO/HELLO_ACK exchange so it opens the real Vandal agent, not an RGB controller or gaming dongle.

Single-threaded pump

An event loop that alternates short non-blocking reads from the HID link and the child shell, fragments output into frames, and pings for liveness.

Reference

Authoritative reference derived directly from the source tree.

Wire protocol

Frame layout, CTRL subtypes, OS identifiers, versioning, lifecycle, flow control and sequence numbers.

API reference

Every exported procedure, type and constant across protocol, transport_hid, shell_child and pump.

Building

Docker cross-toolchain, local Nim builds, and the opt-in fully-static macOS binary.

Deploying to an agent

Download, verify and upload the three payloads to a Vandal agent's /payloads/ volume.