Warning
VulnerableCode is going through a major structural change and the installations are likely to not produce enough results. This is tracked in #597
Welcome to the 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 :ref:`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 :ref:`local_development_installation` section.
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.
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/aboutcode-org/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 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 the 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
and CSRF_TRUSTED_ORIGINS setting need to be provided in your docker.env file:
ALLOWED_HOSTS=.domain.com,127.0.0.1 CSRF_TRUSTED_ORIGINS=https://*.domain.com,http://127.0.0.1
Refer to Django ALLOWED_HOSTS settings and CSRF_TRUSTED_ORIGINS settings for more details.
Warning
Serving VulnerableCode on a network could lead to security issues and several steps may be needed to secure such a deployment. Currently, this is not recommended.
You can execute one of the manage.py commands through the Docker command line
interface, for example:
docker compose run vulnerablecode ./manage.py import --list
Note
Refer to the :ref:`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
VulnerableCode has been tested and is supported on the following operating systems:
- Debian-based Linux distributions
- macOS 12.1 and up
Warning
On Windows VulnerableCode can only :ref:`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 the VulnerableCode Git repository:
git clone https://github.com/aboutcode-org/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
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 an 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.
You can validate your VulnerableCode installation by running the tests suite:
make test
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.
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 procedure 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