Installation

Warning

VulnerableCode is going through a major structural change and the installations are likely to not produce enough results. This is tracked in https://github.com/nexB/vulnerablecode/issues/597

Welcome to VulnerableCode installation guide! This guide describes how to install VulnerableCode on various platforms. Please read and follow the instructions carefully to ensure your installation is functional and smooth.

The preferred VulnerableCode installation is to Run with Docker as this is the simplest to setup and get started. Running VulnerableCode with Docker guarantees the availability of all features with the minimum configuration required. This installation works across all Operating Systems.

Alternatively, you can install VulnerableCode locally as a development server with some limitations and caveats. Refer to the Local development installation section.

Run with Docker

Get Docker

The first step is to download and install Docker on your platform. Refer to Docker documentation and choose the best installation path for your system: Get Docker.

Build the Image

VulnerableCode is distributed with Dockerfile and docker-compose.yml files required for the creation of the Docker image.

Clone the git VulnerableCode repo, create an environment file, and build the Docker image:

git clone https://github.com/nexB/vulnerablecode.git && cd vulnerablecode
make envfile
docker-compose build

Note

The image will need to be re-built when the VulnerableCode app source code is modified or updated via docker-compose build --no-cache vulnerablecode

Run the App

Run your image as a container:

docker-compose up

At this point, the VulnerableCode app should be running at port 8000 on your Docker host. Go to http://localhost:8000/ on a web browser to access the web UI. Optionally, you can set NGINX_PORT environment variable in your shell or in the .env file to run on a different port than 8000.

Note

To access a dockerized VulnerableCode app from a remote location, the ALLOWED_HOSTS setting need to be provided in your docker.env file:

ALLOWED_HOSTS=.domain.com,127.0.0.1

Refer to Django ALLOWED_HOSTS settings for more details.

Warning

Serving VulnerableCode on a network could lead to security issues and there are several steps that may be needed to secure such a deployment. Currently, this is not recommendend.

Execute a Command

You can execute a one of manage.py commands through the Docker command line interface, for example:

docker-compose run vulnerablecode ./manage.py import --list

Note

Refer to the Command Line Interface section for the full list of commands.

Alternatively, you can connect to the Docker container bash and run commands from there:

docker-compose run vulnerablecode bash
./manage.py import --list

Local development installation

Supported Platforms

VulnerableCode has been tested and is supported on the following operating systems:

  1. Debian-based Linux distributions

  2. macOS 12.1 and up

Warning

On Windows VulnerableCode can only Run with Docker and is not supported.

Pre-installation Checklist

Before you install VulnerableCode, make sure you have the following prerequisites:

System Dependencies

In addition to the above pre-installation checklist, there might be some OS-specific system packages that need to be installed before installing VulnerableCode.

On Debian-based distros, several system packages are required by VulnerableCode. Make sure those are installed:

sudo apt-get install python3-venv python3-dev postgresql libpq-dev build-essential

Clone and Configure

Clone the VulnerableCode Git repository:

git clone https://github.com/nexB/vulnerablecode.git && cd vulnerablecode

Install the required dependencies:

make dev

Note

You can specify the Python version during the make dev step using the following command:

make dev PYTHON_EXE=python3.8.10

When PYTHON_EXE is not specified, by default, the python3 executable is used.

Create an environment file:

make envfile

Database

PostgreSQL is the preferred database backend and should always be used on production servers.

  • Create the PostgreSQL user, database, and table with:

    make postgres

Note

You can also use a SQLite database for local development as a single user with:

make sqlite

Warning

Choosing SQLite over PostgreSQL has some caveats. Check this link for more details.

Tests

You can validate your VulnerableCode installation by running the tests suite:

make test

Web Application

A web application is available to create and manage your projects from a browser; you can start the local webserver and access the app with:

make run

Then open your web browser and visit: http://127.0.0.1:8000/ to access the web application.

Warning

This setup is not suitable for deployments and only supported for local development.

Upgrading

If you already have the VulnerableCode repo cloned, you can upgrade to the latest version with:

cd vulnerablecode
git pull
make dev
make migrate

Using Nix

You can install VulnerableCode with Nix (Flake support is needed):

cd etc/nix
nix-shell -p nixFlakes --run "nix --print-build-logs flake check " # build & run tests

There are several options to use the Nix version:

# Enter an interactive environment with all dependencies set up.
cd etc/nix
nix develop
> ../../manage.py ... # invoke the local checkout
> vulnerablecode-manage.py ... # invoke manage.py as installed in the nix store

# Test the import prodecure using the Nix version.
etc/nix/test-import-using-nix.sh --all # import everything
# Test the import using the local checkout.
INSTALL_DIR=. etc/nix/test-import-using-nix.sh ruby # import ruby only

Keeping the Nix setup in sync

The Nix installation uses mach-nix to handle Python dependencies because some dependencies are currently not available as Nix packages. All Python dependencies are automatically fetched from ./requirements.txt. If the mach-nix-based installation fails, you might need to update mach-nix itself and the pypi-deps-db version in use (see etc/nix/flake.nix:inputs.machnix and machnixFor.pypiDataRev).

Non-Python dependencies are curated in:

etc/nix/flake.nix:vulnerablecode.propagatedBuildInputs