# Warlock's Stave (stave-core) v7.0

**Warlock's Stave** is a lightweight reverse engineering framework designed for high-velocity dynamic code tracing, predictive instruction auditing, and deep infrastructure pattern inspection.

The system is built on the **Unix Philosophy**, isolating complex analysis logic from volatile user interface layers. The core is written in performance-critical, memory-safe Rust and exposes clean, stateless C-compatible FFI and JNI symbols for integration with industry-standard tools.

## Executive Vision

Rather than anchoring to specific windowing managers, Warlock's Stave serves as a high-speed telemetry hub and data multiplexer. It dynamically assembles the most efficient IPC pipeline (Unix Sockets, Named Pipes, or TCP) based on its host environment — whether bare-metal, virtualized (Wine/Proton), or cloud-native (Kubernetes sidecars).

## Key Architectural Features

- **Vector Hex Timeline:** A high-precision hexagonal pixel-raycaster for visualizing execution ticks across an abstract coordinate system.
- **Predictive Branch Evaluator:** Decodes current opcodes and checks processor flags to display instruction outcomes before hardware commits to execution.
- **"Mirror Illusion" Diff Engine:** A structural binary comparison tool that aligns files by ELF/PE sections rather than raw offsets, preventing misalignment from code shifts.
- **Tri-Tier Scope Engine:** Concurrent analysis at the **Global** (X-Refs, entropy), **Local** (function blocks, stacks), and **Micro** (instruction side-effects) levels.
- **Multiverse Security Providers:** Pluggable auditors for Linux eBPF kernel tracing, Windows ETW telemetry, and polymorphic IPC evasion detection.
- **Shellcode Sentinel:** Monitors runtime memory for suspicious permission transitions (e.g., RW- to RWX).
- **State Decay System:** Frame-to-live counter for mutation highlights that fade smoothly over time.

## Project Structure

```
stave-core/
├── Cargo.toml                          # Crate manifest with all dependencies
├── build.sh                            # Master compilation pipeline
├── src/
│   ├── lib.rs                          # Core engine (hex heatmap, branch evaluator,
│   │                                   #   dictionary scanner, IPC, FFI, JNI, scope,
│   │                                   #   state decay, shellcode sentinel, mirror diff)
│   ├── ebpf.rs                         # Linux eBPF kernel tracing (aya)
│   ├── windows_etw.rs                  # Windows ETW telemetry hooks
│   ├── polymorphic_ipc.rs              # IPC evasion detection, entropy analysis,
│   │                                   #   hidden channel scanning, global state matrix
│   ├── firmware.rs                     # UEFI NVRAM audit, ACPI sideload detection
│   ├── stave_ui.rs                     # egui 4-quarter workspace renderer
│   └── bin/
│       ├── environment_check.rs        # Pre-flight dependency validator
│       └── simulate_evasion_telemetry.rs  # IPC evasion test harness
├── stave_stub.cpp                      # x64dbg / Wine C++ plugin bridge
├── WarlockStaveBridge.java             # Ghidra JNI bridge
└── ebpf_bin/
    └── stave_probe.c                   # eBPF probe source (compiled by build.sh)
```

## Host Integrations

| Host | Bridge | Protocol |
|---|---|---|
| **Ghidra** | `WarlockStaveBridge.java` (JNI) | DirectByteBuffer, zero-copy |
| **x64dbg** | `stave_stub.cpp` (Wine C++ plugin) | Named Pipe → Unix Socket |
| **Custom** | `stave_ingest_frame` (C FFI) | Raw pointer + JSON response |

## Quick Start

See [QuickStart.MD](QuickStart.MD) for the full installation and verification sequence.

## Licensing

Warlock's Stave is free software licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. See [LICENSE](LICENSE) for details.