8.5 KiB
Warlock's Stave
A lightweight, zero-allocation reverse engineering telemetry hub written in Rust. The library crate is stave-core.
Warlock's Stave compiles to a single dynamic system library (libstave_core.so, stave_core.dll, libstave_core.dylib) that exposes a stateless, C-compatible FFI and JNI interface. It is designed as a permanent analysis engine that communicates via standardized data pipelines, independent of any specific host UI or windowing toolkit.
License: AGPL-3.0-only
What It Does
Warlock's Stave receives raw instruction execution frames from a host debugger or emulator, runs them through an analysis pipeline, and returns structured JSON-Lines telemetry. The host application (a disassembler, a GUI, a headless pipeline) renders the results.
It handles IPC transport automatically: Unix domain sockets on bare metal, TCP loopback in containers, and named-pipe-to-Unix-socket translation for compatibility-layer environments.
Core Engine
Branch Prediction (Branch Evaluator)
Decodes x86/x64 instructions via iced-x86 and evaluates conditional branches against the current EFLAGS register before the hardware commits. Supports JE, JNE, JG, JL, JMP, and CALL mnemonics. The decoder enforces a strict 15-byte clamp to prevent out-of-bounds reads on unmapped memory pages.
Hexagonal Heatmap Timeline
Maps execution flow onto an axial hexagonal grid using f64-precision pixel raycasting. Each hex cell tracks hit count, I/O activity, breakpoint status, and semantic markers (loop, disk, network). The grid supports four filter toggles (Alt+L/B/D/N) to isolate specific activity types.
Dictionary Scanner & Signature Database
A linear pattern-matching engine with two layers: a built-in hunting dictionary (HTTP/HTTPS URLs, anti-debug APIs, Base64 alphabets, PE headers) and a pluggable signature database designed to accept YARA-compatible and ClamAV-compatible backends via the ExternalScannerProvider trait.
Tri-Tier Scope Engine
Classifies each execution frame at three analytical levels:
- Global: Cross-references, export footprints, file entropy.
- Local: Active function block boundaries from symbol tables.
- Micro: Predicted implicit register and memory side-effects before execution.
Mirror Illusion Diff Engine
Section-aware binary comparison that aligns two files by ELF/PE section boundaries rather than raw byte offsets. This prevents code shifts from compiler changes from shattering the comparison. Operates on 16-byte grid lines with per-byte modified/identical status.
State Decay System
Mutation highlights (registers flash red, memory bytes flash yellow) carry a configurable TTL counter that decrements each frame. Highlights fade smoothly back to the base theme color, communicating recent changes without permanent visual clutter.
Self-Assembling IPC
Automatically detects the host environment at startup and selects the best transport:
| Environment | Transport |
|---|---|
| Bare metal (Linux) | Unix domain socket (/tmp/stave_bridge_ipc.sock) |
| Container (Docker, Podman, Kubernetes) | TCP loopback (127.0.0.1:21860) with TCP_NODELAY |
| Compatibility layer (Wine, Proton) | Named pipe (mapped to Unix socket by the translation bridge) |
Visualization
The immediate-mode UI (egui 0.27.0) renders a 4-quarter workspace at a target 60 FPS:
| Quarter | Content |
|---|---|
| Top panel | Hexagonal heatmap grid with pixel-raycaster mouse tracking |
| Q1 (bottom-left) | Disassembly stream from iced-x86 decoding |
| Q2 (bottom-right) | Register matrix with mutation highlighting + branch prediction outcome |
| Q3 (bottom-left, below Q1) | Dual-pane hex/ASCII data viewport |
| Q4 (bottom-right, below Q2) | Telemetry overlay: firmware alerts, IPC evasion status, entropy sparklines |
The UI is isolated from the core engine by design. It consumes computed data structures and renders them. The engine has zero dependencies on window layout toolkits.
Security Analysis
Shellcode Sentinel
Monitors runtime memory segment permissions via /proc/<pid>/maps. Detects transitions that indicate shellcode injection:
- Execute added to writable page (RW- to RWX, or R-- to R-X)
- Write added to executable page (R-X to RWX)
- Execute removed (RWX to RW-, possibly post-exploitation cleanup)
Fires timed alerts that the UI renders as flashing warnings.
Polymorphic IPC Evasion Detection
Audits processes for communication channel switching patterns. A process that drops its standard IPC connection while simultaneously creating unnamed pipes triggers an evasion alert. Includes Shannon entropy analysis for detecting encrypted channel activity.
Firmware Analysis
Audits UEFI NVRAM variables for entries not belonging to known firmware vendors, and examines ACPI table entries for non-standard tables that could indicate bootkit persistence.
Kernel Telemetry
- Linux: eBPF kprobe on
sys_enter_connectvia aya, capturing outbound connection events with PID and network namespace. - Windows: Real-time ETW trace session for system event telemetry.
Plugin System
Warlock's Stave is not locked into a single frontend. Three integration paths are provided:
C/C++ FFI (x64dbg / Wine)
A compiled plugin DLL (warlock_bridge.dp64) that hooks the debugger's step event callback, captures the current instruction context, and forwards it to the IPC daemon over a named pipe. See bridges/stave_stub.cpp.
JNI (Java-based disassemblers)
A Java class (WarlockStaveBridge) that allocates a DirectByteBuffer, passes it to the native library with zero-copy overhead, and receives JSON telemetry in return. See bridges/WarlockStaveBridge.java.
Direct Library Link
Any application that can call C FFI functions can link against libstave_core directly. The public API consists of four functions:
void* initialize_warlock_stave();
const char* stave_ingest_frame(void* ctx, const uint8_t* buf, size_t len, uint64_t rip, uint32_t eflags);
void free_stave_string(const char* str);
void destroy_warlock_stave(void* ctx);
Run cargo doc --open for full rustdoc with safety documentation.
Future Work
- Hotkey-driven action HUD (F1-F10, Alt+L/B/D/N, Ctrl+G/T/Z) — currently documented but not wired to the egui event loop.
- Struct overlay parser for casting C-style struct definitions onto the hex viewport.
- Inline micro-assembler for patching opcodes directly from the UI.
- External scanner provider implementations (YARA-rust, ClamAV FFI).
- IPC response channel (currently sends structured analysis back to the host but the response path needs architecture decisions).
- Render-loop caching for firmware/IPC telemetry queries (currently queried every frame).
- macOS Endpoint Security Framework consumer.
Project Structure
stave-core/
├── Cargo.toml
├── build.sh
├── LICENSE
├── README.md
├── QuickStart.md
├── THIRD_PARTY_NOTICES.md
├── .gitignore
├── .editorconfig
├── .cargo/
│ └── config.toml
├── src/
│ ├── lib.rs # Core engine, FFI, JNI, all analysis modules
│ ├── ebpf.rs # Linux eBPF kernel tracing (aya)
│ ├── windows_etw.rs # Windows ETW telemetry
│ ├── polymorphic_ipc.rs # IPC evasion detection, Shannon entropy
│ ├── firmware.rs # UEFI NVRAM & ACPI table analysis
│ ├── stave_ui.rs # egui 4-quarter workspace
│ └── bin/
│ ├── environment_check.rs # Pre-flight dependency validator
│ └── simulate_evasion_telemetry.rs # IPC evasion simulation test
├── bridges/
│ ├── stave_stub.cpp # C++ plugin for x64dbg/Wine
│ └── WarlockStaveBridge.java # JNI bridge for Java-based hosts
└── ebpf_bin/ # Compiled eBPF bytecode (generated by build.sh)
Legal Notices
Warlock's Stave is released under the GNU Affero General Public License v3.0 only. See LICENSE for the full text.
Certain product names mentioned in documentation and code comments are trademarks of their respective owners. These references are made for descriptive and compatibility purposes only and do not imply endorsement, sponsorship, or affiliation. See THIRD_PARTY_NOTICES.md for details.