Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/AFLplusplus/unicornafl
AFL bindings for Unicorn-Engine
https://github.com/AFLplusplus/unicornafl
Last synced: 3 months ago
JSON representation
AFL bindings for Unicorn-Engine
- Host: GitHub
- URL: https://github.com/AFLplusplus/unicornafl
- Owner: AFLplusplus
- License: apache-2.0
- Created: 2021-11-29T14:43:39.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-11-20T10:01:04.000Z (12 months ago)
- Last Synced: 2024-04-14T07:10:59.817Z (7 months ago)
- Language: Rust
- Size: 9.34 MB
- Stars: 54
- Watchers: 5
- Forks: 25
- Open Issues: 2
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
- awesome-embedded-fuzzing - unicornafl
README
# UnicornAFL
The project builds a bridge between AFL++ and unicorn engine.
You can fuzz unicorn targets using python, rust, and C.
Check out [the examples](https://github.com/AFLplusplus/AFLplusplus/tree/stable/unicorn_mode/samples) in AFLplusplus/unicorn_mode
## Compile
If you have unicorn installed globally, you may just:
```bash
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make
```
Or if you prefer a latest build, don't forget to update submodule before building.
```bash
git submodule update --init --recursive
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DUCAFL_NO_LOG=on # disable logging for the maximum speed
make
```
Or if you would like python bindings.
```bash
python3 -m pip install unicornafl
```
Or build it by yourself.
```bash
git submodule update --init --recursive
cd bindings/python/
python3 -m pip install -e .
```
## API
The only API currently unicornafl exposes is:
```C
//
// Start our fuzzer.
//
// If no afl-fuzz instance is found, this function is almost identical to uc_emu_start()
//
// @uc: The uc_engine return-ed from uc_open().
// @input_file: This usually is the input file name provided by the command argument.
// @place_input_callback: This callback is triggered every time a new child is generated. It returns
// true if the input is accepted, or the input would be skipped.
// @exits: All possible exits.
// @exit_count: The count of the @exits array.
// @validate_crash_callback: This callback is triggered every time to check if we are crashed.
// @always_validate: If this is set to False, validate_crash_callback will be only triggered if
// uc_emu_start (which is called internally by uc_afl_fuzz) returns an error. Or
// the validate_crash_callback will be triggered every time.
// @persistent_iters: Fuzz how many times before forking a new child.
// @data: The extra data user provides.
//
// @uc_afl_ret: The error the fuzzer returns.
UNICORNAFL_EXPORT
uc_afl_ret uc_afl_fuzz(uc_engine* uc, char* input_file,
uc_afl_cb_place_input_t place_input_callback,
uint64_t* exits, size_t exit_count,
uc_afl_cb_validate_crash_t validate_crash_callback,
bool always_validate, uint32_t persistent_iters,
void* data);
```
## Migration
unicornafl 2.x remains the same API compatible to unicornafl 1.x so there is no extra work to migrate.
However, a change in unicornafl 2.x is that the monkey patch is no longer needed for Python, which is a bit more elegant. For instance:
```python
# works with both unicornafl 1.x and unicornafl 2.x
import unicornafl
unicornafl.monkeypatch()
uc.afl_fuzz(...)
```
In unicornafl 2.x, we recommend:
```python
# unicornafl 2.x only!
import unicornafl
unicornafl.uc_afl_fuzz(uc, ...)
```
## Debugging
UnicornAFL supports debugging in a similar way to AFL++.
Setting the environment variable `AFL_DEBUG` will provide additional output relating to the forkserver and interaction between parent and child processes during execution.
As usual with AFL++, `AFL_DEBUG_CHILD` will enable the output of the fuzzed children.
This output can be further enriched via the `AFL_DEBUG_UNICORN` variable, which will detail information about child execution including block translations, hooks, and encountered errors. Note that this variable also requires `AFL_DEBUG_CHILD` to be set, as the output is provided from child context.