Greenbone Community Containers 22.4#
Running the Greenbone Community Edition from containers requires knowledge about:
Using a terminal
Using docker
Running services via docker-compose
Additionally, a basic knowledge about the architecture of the Greenbone Community Edition is required to understand the setup.
Hardware requirements#
Minimal:
CPU Cores: 2
Random-Access Memory: 4GB
Hard Disk: 20GB free
Recommended:
CPU Cores: 4
Random-Access Memory: 8GB
Hard Disk: 60GB free
Note
This guide is intended for users who want to test the newest features and/or want to get familiar with the Greenbone Community Edition. It is not intended for production setups.
Currently the docs support the following distributions
Debian stable (bullseye)
Ubuntu 22.04 LTS
Fedora 35 and 36
CentOS 9 Stream
Most likely, other Debian derivatives like Mint and Kali will also work with only minor adjustments required.
Introduction#
This document provides a guide for running the Greenbone Community Edition from pre-build container images using Docker. It consists of a distributed service architecture, where each service is run in a dedicated container. The orchestration of these services is done via a docker-compose file.
With the Greenbone Community Containers, it is possible to scan your local network independent of the underlying operating system, installed software and tool chains.
Prerequisites#
Note
Please follow the guide step by step. Later steps might require settings or output of a previous command.
The command sudo is used for executing commands that require privileged access on the system.
Install curl#
curl is required for downloading files from this guide.
Installing Docker#
docker is required for running the services within containers. Docker can be installed by running:
sudo apt install docker.io
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io
Installing docker-compose#
docker-compose is required for starting and connecting the services of the Greenbone Community Edition. The description of the service orchestration is done by using compose files. A compose file for the Greenbone Community Edition is provided later on.
Setup#
To allow the current user to run docker and therefore start the containers, they must be added to the docker user group. To make the group change effective, either logout and login again or use su.
sudo adduser $USER docker
sudo usermod -aG docker $USER
su $USER
For downloading the Greenbone Community Edition docker compose file, a destination directory should be created.
export DOWNLOAD_DIR=$HOME/greenbone-community-container && mkdir -p $DOWNLOAD_DIR
Docker Compose File#
To run the Greenbone Community Edition with containers, the following compose file should be used:
version: '3.7'
services:
redis-server:
image: greenbone/redis-server
restart: on-failure
volumes:
- redis_socket_vol:/run/redis/
gpg-data:
image: greenbone/gpg-data
volumes:
- gpg_data_vol:/mnt
pg-gvm:
image: greenbone/pg-gvm:stable
restart: on-failure
volumes:
- psql_data_vol:/var/lib/postgresql
- psql_socket_vol:/var/run/postgresql
gvmd:
image: greenbone/gvmd:stable
restart: on-failure
volumes:
- gvmd_data_vol:/var/lib/gvm
- vt_data_vol:/var/lib/openvas
- psql_data_vol:/var/lib/postgresql
- gvmd_socket_vol:/run/gvmd
- ospd_openvas_socket_vol:/run/ospd
- psql_socket_vol:/var/run/postgresql
depends_on:
- pg-gvm
gsa:
image: greenbone/gsa:stable
restart: on-failure
ports:
- 9392:80
volumes:
- gvmd_socket_vol:/run/gvmd
depends_on:
- gvmd
ospd-openvas:
image: greenbone/ospd-openvas:stable
restart: on-failure
cap_add:
- NET_ADMIN # for capturing packages in promiscuous mode
- NET_RAW # for raw sockets e.g. used for the boreas alive detection
security_opt:
- seccomp=unconfined
- apparmor=unconfined
command: [
"ospd-openvas",
"-f",
"--config", "/etc/gvm/ospd-openvas.conf",
"--mqtt-broker-address", "mqtt-broker",
"--notus-feed-dir", "/var/lib/notus/advisories",
"-m", "666",
]
volumes:
- gpg_data_vol:/etc/openvas/gnupg
- vt_data_vol:/var/lib/openvas
- notus_data_vol:/var/lib/notus
- ospd_openvas_socket_vol:/run/ospd
- redis_socket_vol:/run/redis/
depends_on:
- redis-server
- gpg-data
mqtt-broker:
restart: on-failure
image: greenbone/mqtt-broker
ports:
- 1883:1883
networks:
default:
aliases:
- mqtt-broker
- broker
notus-scanner:
restart: on-failure
image: greenbone/notus-scanner:stable
volumes:
- notus_data_vol:/var/lib/notus
- gpg_data_vol:/etc/openvas/gnupg
environment:
NOTUS_SCANNER_MQTT_BROKER_ADDRESS: mqtt-broker
NOTUS_SCANNER_PRODUCTS_DIRECTORY: /var/lib/notus
depends_on:
- mqtt-broker
- gpg-data
volumes:
gpg_data_vol:
gvmd_data_vol:
psql_data_vol:
vt_data_vol:
notus_data_vol:
psql_socket_vol:
gvmd_socket_vol:
ospd_openvas_socket_vol:
redis_socket_vol:
Download#
It is possible to just copy and paste the docker compose file. Alternatively, it can be downloaded with the following command directly:
cd $DOWNLOAD_DIR && curl -f -L https://greenbone.github.io/docs/latest/_static/docker-compose-22.4.yml -o docker-compose.yml
Description#
The following table describes the provided containers of the docker compose file and their services in detail.
Container |
Service |
Description |
---|---|---|
redis-server |
A redis server with an adjusted config. Used to store VT data and scan results by the scanner. |
|
gpg-data |
A container that copies a GPG keyring with Greenbone’s public signing keys into the |
|
pg-gvm |
A PostgreSQL database cluster setup for use with gvmd. The actual data is stored in the |
|
gvmd |
gvmd |
A container for gvmd that uses unix sockets in volumes to communicate with the PostgreSQL database and ospd-openvas scanner. The downloaded feed data is stored in the |
gsa |
gsad |
A container running the gsad web server for providing the web application GSA. The web interface is available at localhost on port 9392. For communication with gvmd, a unix socket in a volume is used. |
ospd-openvas |
ospd-openvas |
A container providing the vulnerability scanner. The VT data from the feed is stored in the |
mqtt-broker |
An MQTT Broker used for communication between notus-scanner, openvas-scanner and ospd-openvas. |
|
notus-scanner |
notus-scanner |
A container running the notus-scanner used for local security checks. |
Performing a Feed Synchronization#
For the actual vulnerability scanning, Vulnerability Tests, security information like CVEs, port lists and scan configurations are required. All this data is provided by the Greenbone Community Feed and must be download and loaded initially before starting a vulnerability scan.
A synchronization always consists of two parts:
Downloading the changes via rsync
The changes get loaded into memory and a database by a daemon
Both steps may take a while, from several minutes up to hours, especially for the initial synchronization. Only if both steps are finished, the synchronized data is up-to-date and can be used.
The first step is done via the greenbone-nvt-sync and greenbone-feed-sync scripts. The second step is done automatically when the daemons are started.
Downloading the Feed Changes#
Note
The duration of downloading the data during the synchronization depends on the network connection and server resources.
Syncing Vulnerability Tests#
VT data contains .nasl
and .notus
files for creating results
during a vulnerability scan. The .nasl
files are processed by the OpenVAS
Scanner and the .notus
files by the Notus Scanner.
Syncing SCAP, CERT and GVMD Data#
SCAP data contains CPE and CVE information.
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition \
run --rm gvmd greenbone-feed-sync --type SCAP
CERT data contains vulnerability information from the German DFN-CERT and CERT-Bund agencies.
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition \
run --rm gvmd greenbone-feed-sync --type CERT
gvmd data (or also called data-objects) are scan configurations, compliance policies, port lists and report formats.
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition \
run --rm gvmd greenbone-feed-sync --type GVMD_DATA
Starting the Greenbone Community Containers#
Using the docker compose file, the container images can be downloaded (pulled) and the containers can be started in the background.
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition pull
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition up -d
To get a continuous stream of the log output of all services, run the following command:
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition logs -f
The log stream can be stopped by pressing Ctrl-C.
Loading the Feed Changes#
Important
When feed content has been downloaded, the new data needs to be loaded by the corresponding daemons. This may take several minutes up to hours, especially for the initial loading of the data. Without loaded data, scans will contain incomplete and erroneous results.
After starting the Greenbone Community Containers, the running daemons will pick up the feed content and load the data automatically.
Vulnerability Tests Data#
If the log (of ospd-openvas) contains the following output, the OpenVAS Scanner starts to load the new VT data:
Loading VTs. Scans will be [requested|queued] until VTs are loaded. This may
take a few minutes, please wait...
The loading of the VT data is finished if the log message can be found:
Finished loading VTs. The VT cache has been updated from version X to Y.
After the scanner is aware of the VT data, it will be requested by gvmd. This will result in the following log message:
OSP service has different VT status (version X) from database (version (Y), Z VTs). Starting update ...
When gvmd has finished loading all VTs, the following message appears:
Updating VTs in database ... done (X VTs).
SCAP Data#
gvmd starts loading the SCAP data containing CPE and CVE information when the following message can be found in the logs:
update_scap: Updating data from feed
The SCAP data is loaded and the synchronization is finished when the (gvmd) log contains the following message:
update_scap_end: Updating SCAP info succeeded
CERT Data#
gvmd starts loading the CERT data containing DFN-CERT and CERT-Bund advisories when the following message can be found in the logs:
sync_cert: Updating data from feed
The CERT data is loaded and the synchronization is finished when the (gvmd) log contains the following message:
sync_cert: Updating CERT info succeeded.
GVMD Data#
The log contains several messages when the gvmd data is loaded. For port lists, these messages are similar to:
Port list All IANA assigned TCP (33d0cd82-57c6-11e1-8ed1-406186ea4fc5) has been created by admin
For report formats:
Report format XML (a994b278-1f62-11e1-96ac-406186ea4fc5) has been created by admin
Hint
Scan Configs can only be loaded if the VT data is available in gvmd.
For scan configs:
Scan config Full and fast (daba56c8-73ec-11df-a475-002264764cea) has been created by admin
Setting up an Admin User#
Warning
By default, a user admin with the password admin is created. This is insecure and it is highly recommended to set a new password.
To update the administrator user with a password of your choice instead of the generated password, the following command can be used:
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition \
exec -u gvmd gvmd gvmd --user=admin --new-password=<password>
Starting the Vulnerability Management#
After the services have started and all data has been loaded, the Greenbone Security Assistant web interface – GSA – can be opened in the browser.
xdg-open "http://127.0.0.1:9392" 2>/dev/null >/dev/null &
The browser will show the login page of GSA and after using the credentials created before, it is possible to start with vulnerability scanning.

Greenbone Security Assistant after logging in for the first time#
Setup and Start Script#
As a quick solution we provide all the commands above in a single script. This script can be downloaded with the following command directly:
cd $DOWNLOAD_DIR && curl -f -O https://greenbone.github.io/docs/latest/_static/setup-and-start-greenbone-community-edition.sh
To execute the script following command needs to be run
$DOWNLOAD_DIR/setup-and-start-greenbone-community-edition.sh 22.4
Workflows#
Update the Greenbone Community Containers#
To update the Greenbone Community Containers to the latest version, it is required to pull the images and restart the containers which have new images. This can be done with:
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition pull
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition up -d
Starting from Scratch#
To start from scratch, the containers must be stopped. Afterwards, the containers and volumes must be removed to delete all data. All this can be done by running:
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition down -v
Gain a Terminal for a Container#
If you want to debug something in a container, install additional software, take a look at the file content, or change some configuration, it is possible to gain shell access to a container.
To access a container with a bash shell as a root user, you can run:
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition exec <container-name> /bin/bash
Afterwards, you can execute standard bash commands within the running container.
Troubleshooting#
VTs are Up-to-Date but Not Visible on the Web Interface#
It may be possible, especially for the initial synchronization, that the scanner does not notice new VT files have arrived. Therefore, it is best to restart the scanner.
Port List, Scan Configurations, Report Formats are Up-to-Date but Not Visible on the Web Interface#
If port lists, scan configurations, or report formats are missing on the web interface, you may run:
docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition \
exec -u gvmd gvmd gvmd --rebuild-gvmd-data=all
to force gvmd
to reload the data from the file system.
Errors while starting pg-gvm
container#
While starting up the pg-gvm
container, some errors are displayed. For example
createuser: error: creation of new role failed: ERROR: role "gvmd" already exists
or ERROR: extension "uuid-ossp" already exists
.
The code behind these errors tries to set up the database. If the database is already initialized, all tables, users, permissions and extensions exist, errors are raised. At the moment, it is not possible to silence these errors but they can be ignored safely.
Cannot Log in to the Web Interface: Greenbone Vulnerability Manager service is not responding#
If it is not possible to log in to the web interface and the following error message is shown

and/or the logs contain a Failed to connect to server at /run/gvmd/gvmd.sock: Connection refused
message, the gvmd container must be restarted. It is very likely it
had some issues accessing the PostgreSQL database.