Please note that the Firmware_Vault project will expose ports of your system to the local network, which might cause a security issue. Additionally, SQL statements executed by the user will not be checked for malicious queries.
Please be careful when running this project!
Installation
Prerequisites
Before proceeding, make sure to have the following tools installed on your system:
- git
- Docker (on Windows, WSL2 will need to be installed alongside with Docker Desktop)
- Docker Compose
- macOS: Disable AirPlay Receiver in System Settings → General → AirDrop & Handoff (uses port 5000).
Setting up Firmware_Vault
The following steps describe setting up the project and getting it ready to run.
Clone the repository to your machine
Make sure to have a VPN connection to the university network and open a terminal at the location, where you want the project to be located.
If you have already set up an ssh key in your GitLab account, type the following command:
git clone ssh://git@gitlab.informatik.hs-augsburg.de:2222/firmware-analysis/firmware_vault.git
If you have no ssh key in your GitLab account, use this command instead:
git clone https://gitlab.informatik.hs-augsburg.de/firmware-analysis/firmware_vault.git
Build and run the project
Once you have cloned it, navigate to the projects directory and execute the init script (configure).
After the init script was executed, navigate to docker_compose_dir.
The init script creates the /config.json and /docker_compose_dir/.env files. Both files are ignored by Git and should not be committed. These files are used by the Docker containers.
The script will also set the VOLUMES_BASE variable, which is used by the docker-compose.yaml file as the base path for creating Docker volumes. By default, /docker_compose_dir/volumes/ is used as the base path.
The script can be run interactively (it will prompt for each option) or non-interactively via CLI arguments:
# Interactive (default)
./configure
# Headless – use all defaults, no prompts
./configure --headless
# Headless with custom values
./configure --headless --developer_mode=y --log_level=DEBUG --db_password=secret --vendors=AVM,ABB
All configurable options and their defaults can be listed with:
./configure --help
| Argument | Default | Description |
|---|---|---|
--headless | off | Skip all prompts; use defaults or supplied arguments |
--developer_mode | n | Enable developer mode (y/n) |
--log_level | WARNING | Log verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
--db_host | localhost | Database host |
--db_port | 3306 | Database port |
--db_schema | firmware | Database schema name |
--db_user | scraper | Database user |
--db_root_password | (see defaults) | Database root password |
--db_password | (see defaults) | Database user password |
--db_container | mysql_db | Database container name |
--frontend_baseurl | http://localhost:5000/ | Frontend base URL |
--ssl_verify | y | Enable SSL certificate verification (y/n) |
--volumes_base | ./docker_compose_dir/volumes | Docker volumes base path |
--vendors | (AVM only) | Comma-separated list of vendors to enable (e.g. AVM,ABB,tp-link) |
To build and run the project, execute the following command:
docker compose up -d --build
Building all Docker containers will take some time.
After all containers are built, the scraper will start to catalogue and download firmware images from all specified vendors. This can take up a lot of disk space. On how to configure, which vendors are scraped, please see the chapter Firmware Scraper.
Alternatively, the project can be run with specified containers only:
docker compose up --build -d <container1> <container2>
To see, which containers are available, please see the chapter Docker.
After the containers are successfully built, the Webfrontend page can be accessed under http://localhost:80.