README.md

[![Static analysis](https://github.com/ligurio/afl-lua/actions/workflows/check.yaml/badge.svg)](https://github.com/ligurio/afl-lua/actions/workflows/check.yaml)
[![Testing](https://github.com/ligurio/afl-lua/actions/workflows/test.yaml/badge.svg)](https://github.com/ligurio/afl-lua/actions/workflows/test.yaml)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
[![Luarocks](https://img.shields.io/luarocks/v/ligurio/afl-lua/scm-1)](https://luarocks.org/modules/ligurio/afl-lua)

# afl-lua

<img src="afl-lua.png" alt="AFL + Lua" width="400"/>

is a project that brings integration of [AFL++][aflplus-url] (American Fuzzy
Lop) with Lua programming language. It allows to perform fuzzing testing of
programs written in Lua.

## Installation

- Download and setup Lua interpreter and LuaRocks.
- Install AFL++ package: `sudo apt install -y afl++` (on Debian).
- Install module using LuaRocks: `luarocks --local install afl-lua`.
- Update a `PATH`: `export PATH=$PATH:$(luarocks path --lr-bin)`.

## Usage

Create a file with Lua program that reads a string from a STDIN:

```sh
$ cat << EOF > example.lua
function fuzz()
    local buf = io.read("*a")
    local b = {}
    buf:gsub(".", function(c) table.insert(b, c) end)
    if b[1] == 'l' then
        if b[2] == 'u' then
            if b[3] == 'a' then
                assert(nil)
            end
        end
    end
end

fuzz()
EOF
```

Make sure Lua script has failed when string "lua" is passed to STDIN:

```sh
$ echo "lua" | lua example.lua
lua: example.lua:8: assertion failed!
stack traceback:
        [C]: in function 'assert'
        example.lua:8: in function 'fuzz'
        example.lua:14: in main chunk
        [C]: in ?
```

Execute `afl-lua` against a Lua script:

```sh
$ mkdir -p {in,out}
$ echo -n "\0" > in/corpus
$ __AFL_SHM_ID=$RANDOM afl-fuzz -D -i in/ -o out/ afl-lua example.lua
```

After some time, the fuzzer will find a test case with which the program will crash:

```sh
$ cat out/default/crashes/id\:000000\,sig\:06\,src\:000008\,time\:197253\,execs\:113636\,op\:havoc\,rep\:4
luaiiiii^ii
```

## License

- Copyright © 2022-2023 [Sergey Bronnikov](https://bronevichok.ru/)
- Copyright © 2020 Steven Johnstone

Distributed under the MIT License.

[aflplus-url]: https://aflplus.plus/
[aflplus-mutators-url]: https://aflplus.plus/docs/custom_mutators/