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
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
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
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:
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.
To access a dockerized VulnerableCode app from a remote location, the
setting need to be provided in your
Refer to Django ALLOWED_HOSTS settings for more details.
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
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
docker-compose run vulnerablecode bash ./manage.py import --list
Local development installation
VulnerableCode has been tested and is supported on the following operating systems:
Debian-based Linux distributions
macOS 12.1 and up
On Windows VulnerableCode can only Run with Docker and is not supported.
Before you install VulnerableCode, make sure you have the following prerequisites:
Python: 3.8+ found at https://www.python.org/downloads/
Git: most recent release available at https://git-scm.com/
PostgreSQL: release 10 or later found at https://www.postgresql.org/ or https://postgresapp.com/ on macOS
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:
You can specify the Python version during the
make dev step using the following
make dev PYTHON_EXE=python3.8.10
PYTHON_EXE is not specified, by default, the
python3 executable is
Create an environment file:
PostgreSQL is the preferred database backend and should always be used on production servers.
Create the PostgreSQL user, database, and table with:
You can also use a SQLite database for local development as a single user with:
Choosing SQLite over PostgreSQL has some caveats. Check this link for more details.
You can validate your VulnerableCode installation by running the tests suite:
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:
Then open your web browser and visit: http://127.0.0.1:8000/ to access the web application.
This setup is not suitable for deployments and only supported for local development.
If you already have the VulnerableCode repo cloned, you can upgrade to the latest version with:
cd vulnerablecode git pull make dev make migrate
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
Non-Python dependencies are curated in: