How to create a new LAVA Project

To convert an open-source project to LAVA, these are the current steps. We do want to enable support for CMake, but this will be done at a later date. Please feel free to submit a Pull Request. I provided a high-level tip for approaching this.

For now, this guide uses folder names in this repository, but LAVA is built to work with any folder. This will be most visible on the Chaff Bug repository.

Tarball Creation

1. You need to have your source code turned into a tarball. Ensure it compiles into a binary.

• Make sure that your output Makefile allows for passing in CC, CXX, and CFLAGS environment variables. LAVA uses Clang and certain environment flags needed to compile, modify source code, and inject bugs!

2. Common Issue: LAVA does source code pre-processing between the configure step and the make step. However, if the configure step fails to generate some headers needed during the make step, LAVA will fail. Personally, I have compiled some larger projects and manually added the necessary pre-generated headers so that the lava pre-process step works.

Also, another thing to be careful about: if you have to install other dependency packages. Right now, LAVA has no way to factor this in as well.

You would see this error if you get messages like this,

Setting up LAVA configurations

3. You will need to create a JSON file of configurations for your project. Create a folder, and create a sub-folder called inputs. This contains all the inputs you intend to run with your modified program, which will be injected with bugs. **The security bugs can only be injected based on the lines of code executed. The higher the code coverage of your inputs, the more places security bugs can be planted.

To create your JSON, it will look like something below

{
    "name": "toy",
    "db": "toy",
    
    "tarfile": "toy.tar.gz",

    "make": "make CFLAGS+=-gdwarf-2",
    "clean": "make clean",
    "install": "make install",
    "command": "{install_dir}/bin/toy {input_file}",

    "main_file": [ "toy.c" ],

    "dataflow": true
}

Expected LAVA workflow:

1. If there is a configure run the configure script, with any arguments. Note that LAVA will attempt to append this with a --prefix={install_dir}, so if your configure step breaks on the append, make sure to parametrize {install_dir} so LAVA knows where to put the installation

2. LAVA will implicitly run a make lava-preprocess right after configure, which updates the C source code with some necessary pre-processing for tainting.

Note: If the project links complex static/support libraries (like GNU Coreutils or file), you must ensure these libraries are already compiled cleanly BEFORE this pre-processing step occurs. See Common Pitfalls #1 for why we often include a baseline make at the end of Step 1 to protect these libraries.

See here

3. Then it runs make. Sometimes, as described before, you need to re-make some components, which are just the binary and not the entire project, then you just re-make the subsection and use the -B flag.

Common Pitfalls

1. When I run Taint analysis, my PANDA logs show no hypercalls or anything of that nature. Why?

• First, make sure that the binary and inputs do NOT crash. If they crash inside PANDA, there will be no hypercalls or tainting occurring!

• Second, this is a common issue with some bigger projects that link static libraries, e.g., file. You do not want to pre-process the code that will be used to create the static libraries! You only want the executable code itself to be LAVA-tainted! That may also cause some crashing. This is exactly why sometimes there is a make step inside' configure' to build the libraries, right before the pre-process step, to avoid libraries being compiled incorrectly for LAVA. But if you add a make in the configure step, then you need to use the {install_dir} placement holder so the --prefix is correctly placed on the configure step and not the make step.

Fuzzbench and LAVA

To make life easier, a few of the binaries used for Fuzz bench are available; see the list of the forks here. It is identical to the original, just that the source code has been updated with LAVA to contain the security bugs.