Skip to content

hypnguyen1209/offensive-claude / skills/reverse-engineering

reverse-engineering

Verified

Use when reverse-engineering a binary or firmware — static triage + decompilation (Ghidra/IDA/Binary Ninja), dynamic instrumentation (GDB/Frida 17/angr), anti-reversing & packer bypass, OLLVM/VM deobfuscation, UEFI/BIOS RE & Secure Boot research, patch-diffing for n-days

scripts/deflatten_triton.py

View on GitHub
#!/usr/bin/env python3
"""
deflatten_triton.py - recover the original control-flow graph of an OLLVM
control-flow-flattened function using Triton concolic execution.

OLLVM flattening turns structured code into:  while(1){ switch(state){ block_i: ... } }
A central dispatcher reads a 'state' variable and jumps to the matching real block;
each real block computes the *next* state. This tool:
  1. Treats the function entry as the start; concolically executes real blocks.
  2. For each discovered real block, records the next state value it writes, then
     resolves which block that state maps to (the successor).
  3. Emits a graphviz CFG with the dispatcher elided (real block -> real block edges).

This implements the "symbolic backward slicing to separate dispatcher from original
instructions" approach popularized by the LummaC2 analysis, scoped to OLLVM CFF.

Usage:
    python3 deflatten_triton.py ./sample --func 0x401abc -o out/deflat.dot
    dot -Tpng out/deflat.dot -o out/deflat.png

Dependencies:
    pip install triton lief        (triton = the Triton DBA library)
Notes:
    Triton install: https://github.com/JonathanSalwan/Triton (libtriton + python binding).
    For heavily protected / VM'd code prefer NoVmp/Titan; this targets OLLVM-style CFF.
"""
import argparse
import sys

try:
    from triton import (TritonContext, ARCH, Instruction, MemoryAccess, CPUSIZE,
                        MODE)
except ImportError:
    print("error: pip install triton (the JonathanSalwan/Triton library)", file=sys.stderr)
    sys.exit(1)
try:
    import lief
except ImportError:
    lief = None


def load_text(path):
    """Return (bytes, base_va) of the .text section for emulation."""
    if not lief:
        with open(path, "rb") as f:
            return f.read(), 0
    b = lief.parse(path)
    sec = b.get_section(".text")
    base = (b.imagebase or 0) + sec.virtual_address
    return bytes(sec.content), base


def build_ctx(code, base, arch64=True):
    ctx = TritonContext(ARCH.X86_64 if arch64 else ARCH.X86)
    ctx.setMode(MODE.ALIGNED_MEMORY, True)
    ctx.setMode(MODE.CONSTANT_FOLDING, True)
    ctx.setConcreteMemoryAreaValue(base, code)
    return ctx


def step(ctx, pc):
    """Execute one instruction at pc; return (Instruction, next_pc)."""
    opcode = ctx.getConcreteMemoryAreaValue(pc, 16)
    inst = Instruction(pc, opcode)
    ctx.processing(inst)
    return inst


def explore_block(ctx, code, base, start, end, sp_reg, pc_reg):
    """Run from `start` until a branch leaves the [base,end) range or a RET.
    Returns (block_end_pc, observed_targets[list], is_ret)."""
    pc = start
    targets = []
    is_ret = False
    guard = 0
    while base <= pc < end and guard < 4000:
        guard += 1
        inst = step(ctx, pc)
        if inst.isControlFlow():
            # collect concrete + symbolic successors
            nxt = ctx.getConcreteRegisterValue(pc_reg)
            targets.append(nxt)
            if inst.getType() and inst.getDisassembly().startswith("ret"):
                is_ret = True
                break
            pc = nxt
            # a conditional jump exposes a second edge: invert the path predicate
            br = ctx.getPathPredicate()
            if br is not None:
                model = ctx.getModel(ctx.getAstContext().lnot(br)) if hasattr(
                    ctx.getAstContext(), "lnot") else None
                # (full second-edge resolution would re-run from the inverted state;
                #  we record the fall-through as a candidate edge below)
            continue
        pc = ctx.getConcreteRegisterValue(pc_reg)
    return pc, targets, is_ret


def deflatten(path, func_addr, arch64=True, max_blocks=256):
    code, base = load_text(path)
    end = base + len(code)
    ctx = build_ctx(code, base, arch64)
    pc_reg = ctx.registers.rip if arch64 else ctx.registers.eip
    sp_reg = ctx.registers.rsp if arch64 else ctx.registers.esp

    # set up a tiny stack
    stack = base + len(code) + 0x10000
    ctx.setConcreteRegisterValue(sp_reg, stack)

    visited = set()
    worklist = [func_addr]
    edges = []

    while worklist and len(visited) < max_blocks:
        blk = worklist.pop()
        if blk in visited or not (base <= blk < end):
            continue
        visited.add(blk)
        # fresh-ish state per block (concrete) to follow the real successor
        ctx.setConcreteRegisterValue(pc_reg, blk)
        ctx.setConcreteRegisterValue(sp_reg, stack)
        blk_end, targets, is_ret = explore_block(ctx, code, base, blk, end, sp_reg, pc_reg)
        for t in targets:
            if base <= t < end:
                edges.append((blk, t))
                if t not in visited:
                    worklist.append(t)
        if is_ret:
            edges.append((blk, "RET"))
    return visited, edges


def emit_dot(blocks, edges, out):
    lines = ["digraph deflattened {", '  node [shape=box,fontname="monospace"];']
    for b in sorted(blocks):
        lines.append(f'  "0x{b:x}";')
    for a, b in edges:
        tgt = "RET" if b == "RET" else f"0x{b:x}"
        lines.append(f'  "0x{a:x}" -> "{tgt}";')
    lines.append("}")
    with open(out, "w") as f:
        f.write("\n".join(lines))


def main():
    ap = argparse.ArgumentParser(description="OLLVM CFF de-flattening via Triton")
    ap.add_argument("binary")
    ap.add_argument("--func", required=True, help="flattened function VA, e.g. 0x401abc")
    ap.add_argument("--arch", choices=["x64", "x86"], default="x64")
    ap.add_argument("-o", "--out", default="deflat.dot")
    args = ap.parse_args()

    func_addr = int(args.func, 16)
    blocks, edges = deflatten(args.binary, func_addr, arch64=(args.arch == "x64"))
    emit_dot(blocks, edges, args.out)
    print(f"[+] recovered {len(blocks)} real block(s), {len(edges)} edge(s)")
    print(f"[+] CFG -> {args.out}   (render: dot -Tpng {args.out} -o cfg.png)")
    print("[!] verify against a concrete trace; Triton lifting is best-effort on heavy MBA.")


if __name__ == "__main__":
    main()
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall