# 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](LICENSE) ![Warlocks-Stave-GUI](/home/dcosnet/Desktop/projects-preped/warlocks-stave/warlocks-stave-gui.png) --- ## 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//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_connect` via 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: ```c 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](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](THIRD_PARTY_NOTICES.md) for details.