| --- |
| language: |
| - en |
| - it |
| license: mit |
| tags: |
| - pwn |
| - ctf |
| - rop |
| - reverse-engineering |
| - symbolic-execution |
| - cybersecurity |
| - angr |
| - lightgbm |
| - ranking |
| datasets: |
| - custom |
| metrics: |
| - ndcg |
| --- |
| |
| # LCSAJdump Hybrid ML Gadget Ranker |
|
|
| ## Model Overview |
| This repository contains the pre-trained Machine Learning model used by the **[LCSAJdump](https://github.com/chris1sflaggin/LCSAJdump)** ROP/JOP/COP gadget finder. |
|
|
| The model is a **LightGBM LambdaRank** engine designed to score and sort Return-Oriented Programming (ROP) gadgets extracted from binary executables. It was trained to differentiate between useless instruction sequences and highly valuable, exploit-ready gadgets by combining structural static analysis with **Deep Semantic Features** (extracted via `angr` symbolic execution). |
|
|
| ## How it works |
| Traditional gadget finders (like `ROPgadget` or `ropper`) rely on syntactic heuristics (e.g., "does it end with `ret`?" or "does it pop `rdi`?"). This approach often yields hundreds of false positives, especially in obfuscated binaries or complex architectures like ARM64 and RISC-V. |
|
|
| This LambdaRank model receives a set of 29 features for each gadget, including: |
| 1. **Structural Features:** Extracted by LCSAJdump's RainbowBFS algorithm (e.g., instruction count, presence of internal calls, clobbered registers). |
| 2. **Semantic Features:** Extracted by running the gadget through the `angr` symbolic execution engine. The model mathematically knows if a gadget *actually* performs a stack pivot (`sm_stack_pivot_size`), controls argument registers (`sm_controls_arg_reg`), or performs memory writes (`sm_writes_memory`). |
|
|
| By learning from a ground truth of **real-world CTF exploit scripts**, the model learns to prioritize gadgets that are genuinely useful for building exploit chains, achieving an **NDCG@5 of ~0.90** under group-aware 5-fold cross-validation. |
|
|
| ## Architectures Supported |
| The model is fully architecture-aware and currently supports: |
| - **x86_64** |
| - **x86_32** |
| - **ARM64 (AArch64)** |
| - **RISC-V (64-bit)** |
|
|
| ## Usage in LCSAJdump |
| This model is deeply integrated into the `LCSAJdump` CLI tool. |
| You do not need to download or run this model manually. When you install `LCSAJdump`, the `.pkl` file is bundled in the `lcsajdump/ml/models/` directory. |
|
|
| Simply run the tool against a binary: |
| ```bash |
| python3 -m lcsajdump.cli /path/to/binary |
| ``` |
| If the model is present, LCSAJdump will automatically activate the **ML re-ranking** engine and output: |
| `[+] ML re-ranking active (chainfinder_v7_hybrid.pkl)` |
|
|
| *(To disable the ML engine and fall back to pure static heuristics, use the `--algo` flag).* |
|
|
| ## Training Data & Performance |
| The model was trained on a custom dataset (`gadget_dataset.csv`, 2772 samples) built by automatically extracting and labeling gadgets used in **published exploit scripts** from major CTF competitions (e.g., DEF CON, LACTF, DiceCTF, ROP Emporium). Each binary is capped to its top-scoring gadgets so that no single target dominates and the four architectures stay balanced. |
|
|
| **Performance (group-aware 5-fold cross-validation, mean ± std):** |
| - **NDCG@1:** 0.914 ± 0.047 |
| - **NDCG@3:** 0.895 ± 0.062 |
| - **NDCG@5:** 0.900 ± 0.067 |
| - **NDCG@10:** 0.922 ± 0.052 |
|
|
| *(The low standard deviation across folds shows the ranking quality is stable and not tied to a particular train/test split.)* |
|
|
| ## Feature Importances (SHAP) |
| The most impactful features learned by the model are: |
| 1. `is_ret_terminated` (Clean execution flow is paramount) |
| 2. `heuristic_score` (Base syntactic score) |
| 3. `frame_size_bytes` (Stack damage minimization) |
| 4. `sm_stack_pivot_size` (Semantic stack control via `angr`) |
| 5. `stack_slots` |
|
|
| ## Author |
| Created by [Chris1sFlaggin](https://chris1sflaggin.it/LCSAJdump/) for the LCSAJdump project. |
|
|
