Skip to main content

LAVA: Large Scale Automated Vulnerability Addition

Publish Lava Package and Container

Lava Tests

Evaluating and improving bug-finding tools is currently difficult due to a shortage of ground truth corpora (i.e., software that has known bugs with triggering inputs). LAVA attempts to solve this problem by automatically injecting bugs into software. Every LAVA bug is accompanied by an input that triggers it whereas normal inputs are extremely unlikely to do so. These vulnerabilities are synthetic but, we argue, still realistic, in the sense that they are embedded deep within programs and are triggered by real inputs. Our work forms the basis of an approach for generating large ground-truth vulnerability corpora on demand, enabling rigorous tool evaluation and providing a high-quality target for tool developers.

LAVA is the product of a collaboration between MIT Lincoln Laboratory, NYU, and Northeastern University.

Quick Start

Docker

The latest version of LAVA's master branch is automatically built as a docker images based on Ubuntu 22.04 and published to Docker Hub. Most users will want to use the lava container which has PANDA and LAVA installed along with their runtime dependencies, but no build artifacts or source code to reduce the size of the container.

To use the lava container you can pull it from Docker Hub:

$ docker pull pandare/lava

Or build from this repository:

$ DOCKER_BUILDKIT=1 docker build -t pandare/lava:local .

If Docker Engine runs directly inside WSL and build steps cannot access the network (for example, APT reports Temporary failure resolving), try using WSL's host network for the build:

DOCKER_BUILDKIT=1 docker build --network=host -t pandare/lava:local .

This applies to build steps only; containers launched later use their own network settings.

Container workspace

From a workspace containing target_bins/ and target_configs/, use the launcher to open a shell or run a command. It mounts the workspace at the same absolute path so paths written to host.json remain valid between runs. Replace /path/to/lava with the checkout containing the launcher:

/path/to/lava/scripts/docker-shell.sh
/path/to/lava/scripts/docker-shell.sh lava-init
/path/to/lava/scripts/docker-shell.sh lava --help

Docker runs as your UID/GID with your host HOME path and always mounts ~/.panda/ at that same path in the container. Existing QCOWs and kernel files are reused, and downloads and cache changes persist there. The launcher creates ~/.panda/ if needed. The launcher uses pandare/lava:latest by default; use --image pandare/lava:v3.3.4 to select a release, or --image pandare/lava:local for the local build above.

PostgreSQL must already be running. Export POSTGRES_USER and POSTGRES_PASSWORD. The launcher defaults to Docker host networking. On Linux, this lets LAVA reach PostgreSQL on the host machine; keep "host": "localhost" and set "port" to PostgreSQL's listening port in host.json (for example, 5433):

/path/to/lava/scripts/docker-shell.sh lava -ak toy

Override the default with --network NETWORK for a database container on a shared Docker network. Use its container name as "host" and its internal PostgreSQL port (usually 5432). Once configured:

/path/to/lava/scripts/docker-shell.sh --network NETWORK lava -ak toy

-k deletes existing project data without confirmation. The launcher replaces the old project-name-first interface. Put launcher options before the command; the -- separator remains supported but is optional.

HPC with Apptainer / Singularity

On an allocated compute node, use the runtime provided by the cluster. Pull a versioned image once into persistent storage, then reuse it for jobs:

apptainer pull /path/to/scratch/lava-v3.3.4.sif docker://pandare/lava:v3.3.4
/path/to/lava/scripts/docker-shell.sh --runtime apptainer \
  --image /path/to/scratch/lava-v3.3.4.sif lava-init
/path/to/lava/scripts/docker-shell.sh --runtime apptainer \
  --image /path/to/scratch/lava-v3.3.4.sif lava -tc toy

Use --runtime singularity if that is the installed command. These runtimes use the host user's identity and network; configure host.json for a reachable PostgreSQL service and export the same credentials. The launcher neither starts the database nor requests a scheduler allocation. Run it inside your cluster's interactive allocation or batch script. This does not establish that a release image supports the complete pipeline; verify the image installation and run a toy project before submitting a large mining job.

Ubuntu, Debian

Local Installation

On a system running Ubuntu 22.04, you should be able to just run bash install.sh. Note that this install script will install packages and make changes to your system. You can remove the binaries using sudo apt-get remove lava.

Once you finish installing the binary, then you can install locally running pip install ..

NOTE that the Python package requires a SQL file generated from compiling the binaries that is placed into python/src/pyroclastic/data/lava.sql. Without this file, the Python package will not work correctly.

Regular installation

Alternatively, you can manually install LAVA's dependencies and then build from source. Download the Debian packages located in the releases. Then install the python package pip install pyroclastic.

Final steps

Utilizing host.json

Next, run init-host to generate a host.json in your current working directory directory. This file is used by LAVA to store settings specific to your machine. You can edit these settings as necessary, but the default values should work, see vars.py.

A few values to keep in mind are the following:

  • host is the name of the Postgres SQL database with all the LAVA bugs. Currently, it defaults to database, although if you installed LAVA locally, you likely should change this to localhost

NOTE: You also need two environment variables for the Postgres SQL database:

  • POSTGRES_PASSWORD This is the password for the Postgres SQL user
  • POSTGRES_USER This is the Postgres SQL username

Project configurations

Project configurations are located in the target_configs directory, where every configuration is located at target_configs/projectname/projectname.json. Paths specified within these configuration files are relative to values set in your host.json file.

Setting up postgres SQL database

As alluded to, you should create a Postgres SQL user. You can use a script to using the environment variables for the following:

  • Create the user with provided username and password from environment variables.
  • Update Postgres SQL database on host to accept traffic from external sources (e. g. LAVA Docker container)

Usage

Finally, you can run lava to actually inject bugs into a program. Just provide the name of a project that is in the target_configs directory, for example:

lava -ak toy

You should now have a buggy copy of toy!

If you want to inject bugs into a new target, you will likely need to make some modifications. Check out How-to-Lava for guidance.

Documentation

Check out the docs folder to get started.

Authors

LAVA is the result of several years of development by many people; a partial (alphabetical) list of contributors is below:

  • Andy Davis
  • Brendan Dolan-Gavitt
  • Andrew Fasano
  • Zhenghao Hu
  • Patrick Hulin
  • Amy Jiang
  • Engin Kirda
  • Tim Leek
  • Andrea Mambretti
  • Andrew Quijano
  • Wil Robertson
  • Aaron Sedlacek
  • Rahul Sridhar
  • Frederick Ulrich
  • Ryan Whelan

Metadata

Release files for pyroclastic 3.3.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for pyroclastic 3.3.5
File Interpreter ABI Platform Actions
pyroclastic-3.3.5-py3-none-any.whl Python 3 none any Details for pyroclastic-3.3.5-py3-none-any.whl

Release files / pyroclastic-3.3.5-py3-none-any.whl

Download URL pyroclastic-3.3.5-py3-none-any.whl
Size 141.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
69e7c14f7bd7f5d0d7342e1295c9e84d8d0cce4d1d3b4dd0ad7b0257609ea5c5
BLAKE2b-256 checksum
How to use checksums
cef1f48b5e8b0f56cc030c1e768bbafccc35237e5091885a49165af80942445f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for pyroclastic 3.3.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

1 file in this release has been uploaded with provenance metadata.

Attestation for pyroclastic-3.3.5-py3-none-any.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page