diff --git a/README.md b/README.md index d376732..60e3f43 100644 --- a/README.md +++ b/README.md @@ -17,26 +17,51 @@ NYU, and Northeastern University. # Quick Start -On a system running Ubuntu 16.04, with the appropriate dependencies installed -(see [docs/setup.md](docs/setup.md) for details), you should be able to just -run `python2 setup.py`. Note that this install script will install packages -and make changes to your system. Once it finishes, you should have -[PANDA](https://github.com/panda-re/panda) installed into `panda/build/` -(PANDA is used to perform dynamic taint analysis). +## 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](https://hub.docker.com/r/pandare/lava). 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 lava . +``` + +## Ubuntu, Debian +On a system running Ubuntu 22.04, you should be able to just run `bash install.sh`. Note that this [install script](./install.sh) will install packages and make changes to your system. + +## Final steps + +### Utilizing host.json Next, run `init-host.py` to generate a `host.json`. 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. +values should work, see [vars.sh](scripts/vars.sh). + +A few values to keep in mind are the following: +* **buildhost** This is the location of where LAVA is being executed from. Currently, it defaults to `localhost` +* **docker** is the name of the docker image to use that has the LAVA binaries. Currently it defaults to `lava32`, but you can switch this to `pandare/lava` +* **pguser** This is the name of database user, currently defaults to `postgres` +* **pgpass** This is the password of the database user, currently defaults to `postgrespostgres` +* **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` +### 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. -Finally, you can run `./scripts/lava.sh` to actually inject bugs -into a program. Just provide the name of a project that is in the -`target_configs` directory, for example: +### Setting up postgres SQL database +As alluded to, you should create a Postgres SQL user. You can use a script to [use default credentials](scripts/setup_postgres.sh) for the following: +* Create the user with default password +* Update Postgres SQL database on host to accept traffic from external sources (e. g. LAVA Docker container) +* Switch password encryption to md5 (Do we need this?) + +# Usage + +Finally, you can run `./scripts/lava.sh` to actually inject bugs into a program. Just provide the name of a project that is in the `target_configs` directory, for example: ``` ./scripts/lava.sh toy @@ -85,6 +110,7 @@ partial (alphabetical) list of contributors is below: * Engin Kirda * Tim Leek * Andrea Mambretti +* Andrew Quijano * Wil Robertson * Aaron Sedlacek * Rahul Sridhar