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.

Install curl Debian package#

sudo apt install curl

Install curl Fedora/CentOS package#

sudo dnf install curl

Installing Docker#

docker is required for running the services within containers. Docker can be installed by running:

Install docker Debian/Ubuntu package#

sudo apt install docker.io

Install docker Fedora package#

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

Install docker Fedora package#

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.

Install docker-compose Debian/Ubuntu package#

sudo apt install docker-compose

Install docker-compose Fedora/CentOS package#

sudo dnf install docker-compose docker-compose-plugin

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.

Add current user to docker group#

sudo adduser $USER docker

Add current user to docker group#

sudo usermod -aG docker $USER

Apply group changes for the current shell environment#

su $USER

For downloading the Greenbone Community Edition docker compose file, a destination directory should be created.

Create download directory#

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:

Docker Compose File#

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:

Downloading docker-compose file#

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	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 `gpg_data_vol` volume on startup. It exits afterwards.
pg-gvm	postgresql	A PostgreSQL database cluster setup for use with gvmd. The actual data is stored in the `psql_data_vol` volume.
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 `gvmd_data_vol` volume. To verify the feed data, the GPG keyring from the `gpg_data_vol` is used.
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 `vt_data_vol` volume. To verify the feed data, the GPG keyring from the `gpg_data_vol` is used. The connection to the redis server is established via a unix socket in a volume.
mqtt-broker	Mosquitto 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 VTs processed by the scanner, this will take a while.#

docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition \
    run --rm ospd-openvas greenbone-nvt-sync

Syncing SCAP, CERT and GVMD Data#

SCAP data contains CPE and CVE information.

Syncing SCAP data processed by gvmd, this will take a while#

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.

Syncing CERT data processed by gvmd#

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.

Syncing data objects processed by gvmd#

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.

Downloading the Greenbone Community Containers#

docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition pull

Starting the Greenbone Community Containers#

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:

Show log messages of all services from the running containers#

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:

ospd-openvas VT loading log message#

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:

ospd-openvas VTs loading finished log message#

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:

gvmd VTs loading 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:

gvmd VTs loading finished log message#

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:

gvmd SCAP data loading log message#

update_scap: Updating data from feed

The SCAP data is loaded and the synchronization is finished when the (gvmd) log contains the following message:

gvmd SCAP data loading finished log 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:

gvmd CERT data loading log message#

sync_cert: Updating data from feed

The CERT data is loaded and the synchronization is finished when the (gvmd) log contains the following message:

gvmd CERT data finished loading log 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:

gvmd port list loaded log message#

Port list All IANA assigned TCP (33d0cd82-57c6-11e1-8ed1-406186ea4fc5) has been created by admin

For report formats:

gvmd report format loaded log message#

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:

gvmd scan config loaded log message#

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:

Updating password of administrator user#

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.

Opening Greenbone Security Assistant 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.

Launching Greenbone Security Assistant for the first time — 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:

Downloading setup and start script#

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

Run setup and start script#

$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:

Downloading the Greenbone Community Containers#

docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition pull

Starting the Greenbone Community Containers#

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:

Remove containers and volumes (all data)#

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:

Gain a Terminal for a Container#

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.

Restart the scanner to ensure that new VTs are loaded#

docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition \
    restart ospd-openvas

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:

Force reload of report formats, scan configs and port lists#

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.

Restart gvmd#

docker-compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition \
    restart gvmd

Greenbone Community Containers 22.4#

Hardware requirements#

Introduction#

Prerequisites#

Install curl#

Installing Docker#

Installing docker-compose#

Setup#

Docker Compose File#

Download#

Description#

Performing a Feed Synchronization#

Downloading the Feed Changes#

Syncing Vulnerability Tests#

Syncing SCAP, CERT and GVMD Data#

Starting the Greenbone Community Containers#

Loading the Feed Changes#

Vulnerability Tests Data#

SCAP Data#

CERT Data#

GVMD Data#

Setting up an Admin User#

Starting the Vulnerability Management#

Setup and Start Script#

Workflows#

Update the Greenbone Community Containers#

Starting from Scratch#

Gain a Terminal for a Container#

Troubleshooting#

VTs are Up-to-Date but Not Visible on the Web Interface#

Port List, Scan Configurations, Report Formats are Up-to-Date but Not Visible on the Web Interface#

Errors while starting pg-gvm container#

Cannot Log in to the Web Interface: Greenbone Vulnerability Manager service is not responding#

Errors while starting `pg-gvm` container#