---

Why LCSAJdump?

Common ROP scanners use a linear "sliding-window" approach over the binary's executable bytes. This method systematically fails to identify Shadow Gadgets: execution chains that traverse non-contiguous memory blocks connected by unconditional jumps or conditional branches.

LCSAJdump overcomes this limitation by reconstructing the Control-Flow Graph (CFG) through LCSAJ (Linear Code Sequence and Jump) analysis. By modeling the binary as a directed graph of basic blocks, the tool identifies:

1. Contiguous Gadgets: Standard linear sequences terminating in a control-flow transfer.
2. Shadow Gadgets (Non-Contiguous): Complex chains that bypass "bad bytes" (e.g., null bytes) by utilizing instructions that would otherwise be unreachable via linear scanning.

---

Key Features

• Multi-Architecture Support: Native support for RISC-V (64GC), x86-64, and ARM64, easily extendable to other architectures via modular profiles.
• Graph-Based Analysis: Segments the .text section into LCSAJ basic blocks and reconstructs flow relationships through a custom-built reverse control-flow graph (lightweight adjacency representation, no heavyweight graph dependency).
• Rainbow BFS Algorithm: Proprietary backward Breadth-First Search starting from control-flow sinks. Now features an O(1) Early-Drop Uniqueness Filter and Hard-Cap Instruction Limits to prevent state explosion and ensure ultra-fast analysis even on dense CISC binaries.
• Lazy Graph Build: Graph construction retains only nodes reachable from gadget tails within --depth hops, drastically reducing memory and build time on large binaries (e.g., libc) while producing identical results.
• Two-Stage Ranking Engine: Combines a hyper-fast heuristic baseline (Bayesian-optimized via Optuna) with a deep-learning LightGBM ML model that refines gadget quality using structural and semantic features.
• Zero-Overhead Inference: The ML model is integrated natively and runs by default, processing tens of thousands of nodes in seconds. It acts as a highly effective filter, rejecting noisy jumps and returning clean, highly controllable gadget chains. Hosted on Hugging Face.
• Pruning Parameters: Configurable "Darkness" factor to balance analysis depth and performance, preventing infinite loops in cyclic graphs.

---

Supported Architectures

(see Benchmarks).

LCSAJdump is designed to be universal. Currently supported:

• RISC-V 64-bit (RV64GC): Full support for compressed 16-bit instructions.
• x86-64: Handles variable-length overlapping instructions. Safely navigates dense graphs without memory explosion.
• ARM64: Handles 32-bit instructions and deeply filters out bloated gadgets via strict heuristic penalties.
• Other Architectures: Can be easily implemented by defining new profiles in config.py.

---

Installation

Via Pip (Recommended)

pip install lcsajdump

From Source (Development)

git clone [https://github.com/Chris1sFlaggin/LCSAJdump.git](https://github.com/Chris1sFlaggin/LCSAJdump.git)
cd LCSAJdump
pip install -r requirements.txt

---

Usage

LCSAJdump offers a powerful CLI for precise binary analysis:

Standard Analysis (Default RISC-V):

python LCSAJdump.py <path_to_binary>

Advanced Analysis (Specifying Architecture and Output File):

lcsajdump -a riscv64 -d 15 -k 10 -l 20 -o gadgets.txt <path_to_binary>

Export as JSON with bad-char filter:

lcsajdump -a x86_64 -d 20 -k 5 -b "000a0d" --json -o gadgets.json <path_to_binary>

Note: Use -o after --json to save JSON to file. Without --json, -o saves plain text.

Save plain text output:

lcsajdump -a riscv64 -d 15 -k 10 -l 20 -o gadgets.txt <path_to_binary>

Analyze all executable sections:

lcsajdump --all-exec -d 25 -k 10 -l 30 <path_to_binary>

Force strictly algorithmic ranking (bypass ML):

lcsajdump --algo <path_to_binary>

CLI Options

Flag	Type	Default	Description
-a, --arch	TEXT	auto	Target architecture (auto, riscv64, x86_64, arm64). Auto-detected from ELF header.
-d, --depth	INTEGER	20	Max search depth in LCSAJ blocks. Controls chain length.
-k, --darkness	INTEGER	5	Pruning threshold — max visits per node. Higher = more gadgets, slower scan.
-l, --limit	INTEGER	10	Max number of gadgets to display in the output.
-s, --min-score	INTEGER	0	Minimum heuristic score for a gadget to appear in results.
-i, --instructions	INTEGER	15	Max number of instructions contained in a single LCSAJ node.
-v, --verbose	FLAG	—	Enable verbose output for detailed per-gadget results.
-o, --output	PATH	—	Write output to file. Plain text by default; use with --json for JSON output.
-b, --bad-chars	TEXT	—	Hex bytes to filter from gadget addresses (e.g. "000a0d").
--json	FLAG	—	Output gadgets as structured JSON. Combine with -o to save to file.
--all-exec	FLAG	—	Analyze all executable sections, not just .text.
-al, --algo	FLAG	—	Use strictly the algorithmic ranking (bypass ML).
--version	FLAG	—	Show the installed version and exit.
--help	FLAG	—	Show help message and exit.

---

---

Accuracy & Benchmarks

LCSAJdump is backed by a rigorous, incrementally validated test suite located in the benchmarkTests/ directory.

Through 14 major iterations of semantic feature engineering, the hybrid model has learned to discriminate gadgets based on actual memory side-effects (extracted via angr symbolic execution) rather than purely syntactic heuristics.

Evaluated with group-aware 5-fold cross-validation (test binaries never seen during training), the ranker achieves NDCG@1 = 0.914 ± 0.047 and NDCG@10 = 0.922 ± 0.052, meaning the most useful gadgets are consistently placed at the top of the output. The Two-Stage engine successfully prioritizes clean stack-popping sequences and ret2csu-like calls, while heavily penalizing crash-prone fixed-offset jumps that deceive traditional static scanners.

---

Developer & ML Guide

The repository is structured to support both end-users and ML researchers.