Metadata-Version: 2.4
Name: crackers
Version: 0.6.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: pydantic>=2.10.6
Requires-Dist: z3-solver==4.15.3.0
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: mypy ; extra == 'dev'
Requires-Dist: nox ; extra == 'dev'
Requires-Dist: z3-solver ; extra == 'dev'
Requires-Dist: pydantic>=2.10.6 ; extra == 'dev'
Provides-Extra: dev
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<div align="center">

<img src="https://raw.githubusercontent.com/toolCHAINZ/crackers/refs/heads/main/crackers.svg" width="350"/>

</div>

# `crackers`: A Tool for Synthesizing Code-Reuse Attacks from `p-code` Programs

[![Build](https://github.com/toolCHAINZ/crackers/actions/workflows/build.yml/badge.svg)](https://github.com/toolCHAINZ/crackers/actions/workflows/build.yml)
[![docs.rs](https://docs.rs/crackers/badge.svg)](https://docs.rs/crackers)

This package contains the Python bindings for `crackers`, a tool for synthesizing
code-reuse attacks (e.g., ROP) built around the Z3 SMT Solver and Ghidra's SLEIGH code translator.

For more details, please refer to the [GitHub project](https://github.com/toolCHAINZ/crackers).

## Usage

[![PyPI](https://img.shields.io/pypi/v/crackers)](https://pypi.org/project/crackers/)

The easiest way to use `crackers` is through the [PyPI](https://pypi.org/project/crackers/) package. For every release, we provide wheels for `[MacOS, Windows, Linux] x [3.10, 3.11, 3.12, 3.13]`.

A simple usage looks like the following:

```python
import logging
logging.basicConfig(level=logging.INFO)

from z3 import BoolRef, BoolVal

from crackers import State, ModeledBlock
from crackers.config import MetaConfig, LibraryConfig, SleighConfig,
    ReferenceProgramConfig, SynthesisConfig, ConstraintConfig, CrackersConfig
from crackers.config.constraint import RegisterValuation,
    RegisterStringValuation, MemoryValuation, PointerRange,
    CustomStateConstraint, CustomTransitionConstraint, PointerRangeRole
from crackers.config.log_level import LogLevel
from crackers.config.synthesis import SynthesisStrategy

# Custom state constraint example
def my_constraint(s: State, _addr: int) -> BoolRef:
    rdi = s.read_register("RDI")
    rcx = s.read_register("RCX")
    return rdi == (rcx ^ 0x5a5a5a5a5a5a5a5a)

# Custom transition constraint example
def my_transition_constraint(block: ModeledBlock) -> BoolRef:
    # Dummy: always true
    return BoolVal(True)

meta = MetaConfig(log_level=LogLevel.INFO, seed=42)
library = LibraryConfig(max_gadget_length=8, path="libz.so.1", sample_size=None,
                        base_address=None)
sleigh = SleighConfig(ghidra_path="/Applications/ghidra")
reference_program = ReferenceProgramConfig(path="sample.o", max_instructions=8, base_address=library.base_address)
synthesis = SynthesisConfig(strategy=SynthesisStrategy.SAT, max_candidates_per_slot=200, parallel=8, combine_instructions=True)
constraint = ConstraintConfig(
    precondition=[
        RegisterValuation(name="rdi", value=0xdeadbeef),
        MemoryValuation(space="ram", address=0x1000, size=4, value=0x41),
        RegisterStringValuation(reg="rsi", value="/bin/sh"),
        CustomStateConstraint(code=my_constraint)
    ],
    postcondition=[
        RegisterValuation(name="rax", value=0x1337),
        CustomStateConstraint(code=my_constraint)
    ],
    transition=[
        PointerRange(role=PointerRangeRole.READ, min=0x2000, max=0x3000),
        CustomTransitionConstraint(code=my_transition_constraint)
    ]
)
config = CrackersConfig(meta=meta, library=library, sleigh=sleigh, specification=reference_program, synthesis=synthesis, constraint=constraint)
config.run()
```

# Research Paper

`crackers` was initially developed in support of our research paper, _Synthesis of Code-Reuse Attacks from `p-code` Programs_,
presented at [Usenix Security 2025](https://www.usenix.org/conference/usenixsecurity25/presentation/denhoed).

If you found the paper or the implementation useful, you can cite it with the following BibTeX:

```bibtex
@inproceedings{denhoed2025synthesis,
  title={Synthesis of ${Code-Reuse}$ Attacks from p-code Programs},
  author={DenHoed, Mark and Melham, Tom},
  booktitle={34th USENIX Security Symposium (USENIX Security 25)},
  pages={395--411},
  year={2025}
}
```

