## 1. Project Overview & Quickstart (greenbone/http2_close_handle) ## 1. Project Overview & Quickstart (greenbone/http2_close_handle) # http2_close_handle Open-source repository greenbone/http2_close_handle ### Repository Details - **Repository:** [greenbone/http2_close_handle](https://github.com/greenbone/http2_close_handle) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (greenbone/docs) # Documentation for the Greenbone Community Edition The documentation is build automatically via GitHub Actions and available at [https://greenbone.github.io/docs/](https://greenbone.github.io/docs/) ## Requirements For a manual build locally Python >= 3.9 and [uv] is required. ## Install uv The project requires [uv]. See [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/) for detailed instructions for installing uv. A simple method to install uv is to use [pipx]. pipx can be installed with the following command on Debian based systems: ```sh sudo apt install pipx ``` Install uv using pipx ```sh python3 -m pipx install uv ``` ## Manual Build After installing [uv], the docs can be built with: ```sh uv run make html ``` To open the generated HTML docs with Firefox you can run: ```sh firefox _build/html/index.html ``` ## Auto Rebuild Alternatively it is possible to start a local HTTP server that automatically rebuilds the docs on every file change: ```sh uv run make livehtml ``` To open the served docs with Firefox you can run: ```sh firefox http://127.0.0.1:8000 ``` ## Writing Content The documentation uses [Sphinx](https://www.sphinx-doc.org/) in conjunction with [myst](https://myst-parser.readthedocs.io) to create the HTML content. Each document uses [Markdown](https://en.wikipedia.org/wiki/Markdown) with [extended syntax](https://myst-parser.readthedocs.io/en/latest/intro.html#extend-markdown-with-myst-syntax) to integrate with Docutils and Sphinx. All Markdown files are in the [src](./src) folder or one of its sub-folders. The entry point is the [index.md](./src/index.md) file. It contains a [toctree directive](https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html#using-toctree-to-include-other-documents-as-children) to reference and include other Markdown files. When a Pull Request is reviewed and merged, the HTML content is built automatically and published afterwards to [https://greenbone.github.io/docs/](https://greenbone.github.io/docs/) via a GitHub Actions [workflow](.github/workflows/github-pages.yml). For viewing the HTML content during development, please take a look at the [auto rebuild](#auto-rebuild) and/or [manual build](#manual-build) sections in this README. [uv]: https://docs.astral.sh/uv/ [pipx]: https://pipx.pypa.io/stable/ ## 2. Official Technical Reference & Guides (greenbone/docs) ## File: README.md # Documentation for the Greenbone Community Edition The documentation is build automatically via GitHub Actions and available at [https://greenbone.github.io/docs/](https://greenbone.github.io/docs/) ## Requirements For a manual build locally Python >= 3.9 and [uv] is required. ## Install uv The project requires [uv]. See [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/) for detailed instructions for installing uv. A simple method to install uv is to use [pipx]. pipx can be installed with the following command on Debian based systems: ```sh sudo apt install pipx ``` Install uv using pipx ```sh python3 -m pipx install uv ``` ## Manual Build After installing [uv], the docs can be built with: ```sh uv run make html ``` To open the generated HTML docs with Firefox you can run: ```sh firefox _build/html/index.html ``` ## Auto Rebuild Alternatively it is possible to start a local HTTP server that automatically rebuilds the docs on every file change: ```sh uv run make livehtml ``` To open the served docs with Firefox you can run: ```sh firefox http://127.0.0.1:8000 ``` ## Writing Content The documentation uses [Sphinx](https://www.sphinx-doc.org/) in conjunction with [myst](https://myst-parser.readthedocs.io) to create the HTML content. Each document uses [Markdown](https://en.wikipedia.org/wiki/Markdown) with [extended syntax](https://myst-parser.readthedocs.io/en/latest/intro.html#extend-markdown-with-myst-syntax) to integrate with Docutils and Sphinx. All Markdown files are in the [src](./src) folder or one of its sub-folders. The entry point is the [index.md](./src/index.md) file. It contains a [toctree directive](https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html#using-toctree-to-include-other-documents-as-children) to reference and include other Markdown files. When a Pull Request is reviewed and merged, the HTML content is built automatically and published afterwards to [https://greenbone.github.io/docs/](https://greenbone.github.io/docs/) via a GitHub Actions [workflow](.github/workflows/github-pages.yml). For viewing the HTML content during development, please take a look at the [auto rebuild](#auto-rebuild) and/or [manual build](#manual-build) sections in this README. [uv]: https://docs.astral.sh/uv/ [pipx]: https://pipx.pypa.io/stable/ --- ## File: src/api.md # API ## python-gvm Greenbone Vulnerability Management Python Library [https://greenbone.github.io/python-gvm/](https://greenbone.github.io/python-gvm/) ## gvm-tools Remote control your Greenbone Community Edition or Greenbone Enterprise Appliance [https://greenbone.github.io/gvm-tools/](https://greenbone.github.io/gvm-tools/) ## pontos Common utilities and tools maintained by Greenbone [https://greenbone.github.io/pontos/](https://greenbone.github.io/pontos/) ## autohooks Library for managing git hooks [https://greenbone.github.io/autohooks/](https://greenbone.github.io/autohooks/) --- ## File: src/architecture.md ## Architecture The Greenbone Community Edition consists of a framework with several services. It is developed as part of the commercial [Greenbone Enterprise] product line. The Greenbone Community Edition was originally built as a community project named [OpenVAS] and is primarily developed and forwarded by [Greenbone]. The architecture for the Greenbone Community Edition is grouped into three major parts: - Executable scanner applications that run vulnerability tests (VT) against target systems - Greenbone Vulnerability Management Daemon (gvmd) - Greenbone Security Assistant (GSA) with the Greenbone Security Assistant Daemon (gsad) The following figure shows an overview of the architecture for the 22.4 release. > :::{figure} images/greenbone-community-22.4-architecture.png > :alt: Greenbone Community Edition Architecture > > Architecture in release 22.4 > ::: The Greenbone Community Edition is released under open-source licenses. By using it, Linux distributions can create and provide the software components in the form of installation packages. ### Greenbone Vulnerability Management Daemon (gvmd) The [Greenbone Vulnerability Management Daemon (gvmd)] – also called Greenbone Vulnerability Manager is the central service that consolidates plain vulnerability scanning into a full vulnerability management solution. gvmd controls the OpenVAS Scanner via Open Scanner Protocol (OSP). The service itself offers the XML-based, {term}`Greenbone Management Protocol (GMP)`. gvmd also controls an SQL database (PostgreSQL) where all configuration and scan result data is centrally stored. Furthermore, gvmd also handles user management including permissions control with groups and roles. And finally, the service has an internal runtime system for scheduled tasks and other events. ### Greenbone Security Assistant (GSA) The [Greenbone Security Assistant (GSA)] is the web interface that a user controls scans and accesses vulnerability information with. It is the main contact point for a user. It connects to gvmd via the web server [Greenbone Security Assistant Daemon (gsad)][greenbone security assistant daemon (gsad)] to provide a full-featured web application for vulnerability management. The communication occurs using the {term}`Greenbone Management Protocol (GMP)` with which the user can also communicate directly by using different tools. ### OpenVAS Scanner The main scanner [OpenVAS Scanner] is a full-featured scan engine that executes {term}`Vulnerability Tests (VTs) ` against target systems. For this, it uses the daily updated and comprehensive feeds: the full-featured, extensive, commercial {term}`Greenbone Enterprise Feed ` or the free available {term}`Greenbone Community Feed `. The scanner consists of the components [ospd-openvas] and [openvas-scanner]. The OpenVAS Scanner is controlled via {term}`OSP`. The OSP Daemon for the OpenVAS Scanner (ospd-openvas) communicates with gvmd via OSP: VT data is collected, scans are started and stopped, and scan results are transferred to gvmd via ospd. ### Notus Scanner The [Notus Scanner] scans during every regular scan, so no user interaction is necessary. It offers better performance due to less system resource consumption and thus, faster scanning. The Notus Scanner replaces the logic of potentially all NASL-based local security checks (LSCs). A comparison of installed software on a host against a list of known vulnerable software is done instead of running a VT script for each LSC. The regular OpenVAS Scanner loads each NASL LSC individually and executes it one by one for every host. A single known vulnerability is then compared with the installed software. This is repeated for all LSCs. With the Notus Scanner, the list of installed software is loaded in the same way, but is directly compared with all known vulnerable software for the operating system of the scanned host. This eliminates the need to run the LSCs because the information about the known vulnerable software is collected in one single list and not distributed in individual NASL scripts. ### Additional Software The [Greenbone Vulnerability Management Tools (gvm-tools)] are a collection of tools that help with remote controlling Greenbone Community Edition installations or Greenbone Enterprise Appliances. The tools aid in accessing the communication protocols {term}`GMP (Greenbone Management Protocol)` and {term}`OSP (Open Scanner Protocol)`. This module is comprised of interactive and non-interactive clients. The programming language Python is supported directly for interactive scripting. But it is also possible to issue remote GMP/OSP commands without programming in Python. [greenbone]: https://www.greenbone.net/en/ [greenbone enterprise]: https://www.greenbone.net/en/products/ [greenbone security assistant (gsa)]: https://github.com/greenbone/gsa [greenbone security assistant daemon (gsad)]: https://github.com/greenbone/gsad [greenbone vulnerability management tools (gvm-tools)]: https://github.com/greenbone/gvm-tools [greenbone vulnerability manager (gvmd)]: https://github.com/greenbone/gvmd [notus scanner]: https://github.com/greenbone/notus-scanner [openvas]: https://www.openvas.org/ [openvas scanner]: https://github.com/greenbone/openvas-scanner [openvas-scanner]: https://github.com/greenbone/openvas-scanner [ospd-openvas]: https://github.com/greenbone/ospd-openvas --- ## File: src/background.md # Background ```{include} ./architecture.md ``` ```{include} ./history.md ``` --- ## File: src/changelog.md # Changelog All notable changes to this documentation will be listed in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Calendar Versioning](https://calver.org). ## Latest * Provide a single compose file and remove the versioned compose file. The compose setup follows a rolling release model. * Rename `docker-compose.yml` to `compose.yaml` as the later one is the [preferred canonical name nowadays](https://docs.docker.com/compose/intro/compose-application-model/#the-compose-file). * Update the compose architecture: * Use nginx to serve the GSA frontend. * Run gsad in API-only mode. * Introduce a new gvm-config container that configures nginx and generates a self-signed TLS certificate. * Use https in the default setup. * Port 9392 now redirects to 443. * Upgrade PostgreSQL to v16 for Ubuntu * Use [`restart_policy`](https://docs.docker.com/reference/compose-file/deploy/#restart_policy) for container services * Use `compose.yaml` instead of `docker-compose.yml` everywhere in the docs * Use environment variables for the settings of gsad * Refresh the GSA dashboard image * Revise the hardware specifications view * Rewrite the container pre-requisites and -amble files * Update component versions for source build * Update gvm-libs to 23.9.3 * Update gvmd to 26.37.0 * Update gsad to 27.2.0 * Update gsa to 28.3.0 * Update pg-gvm to 22.6.18 * Update ospd-openvas to 22.10.5 ## 26.2.0 - 2026-02-24 * Improve hints about following rustup.sh instructions on Debian and CentOS to build openvasd * Require Ubuntu 24.04 for source build to fix building gvm-libs * Ensure cargo is up-to-date by running `rustup update stable` for openvasd * Include info to update the `docker-compose.yml` file before updating the Docker container * Keep data containers alive to restart them only if a new image is pulled * Add new `pg-gvm-migrator` container for handling PostgreSQL major version changes * Fix typo in gvmd build for Fedora/Centos ## 25.5.0 - 2025-05-30 * Update gvm-libs to 22.22.0 * Update gvmd to 26.0.0 * Update gsad to 24.3.0 * Update GSA to 25.0.0 * Update pg-gvm to 22.6.9 * Update openvas-scanner to 23.20.1 * Update ospd-openvas to 22.9.0 * Drop `lcov` development dependency in gvmd install instructions * Fix - Docs copy (Feed Status moved to Administration) * Update source build guide for a section explaining the environment variables * Add section about getting a 404 to source guide troubleshooting ## 25.2.0 - 2025-02-18 * Fix file path to compose file in setup and start script * Update openvas-smb dependency from heimdal-dev to heimdal-multidev * Update openvas-scanner dependency from libkrb5-dev to krb5-multidev * Update openvas-scanner and openvasd to 23.15.3 * Remove fedora in openvas-smb. * Fix openvasd path to binaries after file path structure changes. * Call `systemctl daemon-reload` after all service files are installed * Update gvm-libs to 22.17.0 * Update gvmd to 25.0.0 * Update pg-gvm to 22.6.7 * Update gsad to 24.2.0 and support brotli compression * Update GSA to 24.2.0 and the description * Drop python3-defusedxml from dependencies of gvm-tools * Simplify instructions for setting up sudo * Update docker compose file for using the 24.10 feed release * Add libcjson dependency for gvm-libs ## 25.1.0 - 2025-01-09 * Corrected the path for moving the openvasd built files * Add instructions for Kali Linux installation * Add instructions to enable SSL/TLS * Quote passwords when creating an admin user via `gvmd` * Add a disclaimer that Greenbone isn't involved in packaging for Kali Linux * Move `Facing an issue with the Greenbone Community Edition` section from source build troubleshooting to generic troubleshooting page * Add section about getting the log messages for the Community Containers * Extend history about current release changes and semver usage * Improved troubleshooting for *Failed to find port_list* * Fix command for downloading gvmd-data manual manually when using the containers * Update gvm-libs to 22.8.0 * Update gvmd to 23.2.0 * Update pg-gvm to 22.6.4 * Update gsad to 22.9.0 * Update GSA to 23.0.0 * Update OpenVAS Scanner to 23.0.1 * Drop notus-scanner in favor of the new OpenVAS Daemon (openvasd). This made the Mosquitto MQTT broker obsolete too. * Drop mention of obsolete dependency on xml-twig-tools / perl-XML-Twig * Changed container registry from DockerHub to registry.community.greenbone.net in compose file * Update supported Ubuntu version for docker compose guide to 24.04 * Use unversioned `docker-compose.yml` file for the download * Set [docker compose project](https://docs.docker.com/reference/compose-file/version-and-name/#name-top-level-element) via compose file. This allows to remove the `-p greenbone-community-edition` argument from all docker compose commands. * Update image names in examples where the compose file is adjusted ## 23.11.0 - 23-11-21 * Add workflow page for source builds * Add documentation for updating source builds * Don't expose MQTT broker port in docker compose setup by default * Add workflow for source builds on howto access GSA/gsad remotely * Only run gsad on 127.0.0.1 for the community containers setup * Add workflow for container setup on howto access GSA/gsad remotely * Fix log warning from tini init server in the ospd-openvas container * Fix manual feed sync workflow for the container setup * Update gvm-libs to 22.7.3 * Update gvmd to 23.0.1 * Update gsad to 22.7.0 * Update GSA to 22.8.0 * Update openvas-scanner to 22.7.6 * Update ospd-openvas to 22.6.1 * Add general troubleshooting page ## 23.9.0 - 23-09-23 * Update pg-gvm to 22.6.1 * Improve description of GSA and its build process in the source build * Use Debian 12 bookworm also for the community container docs * Update ospd-openvas to 22.6.0 * Update notus-scanner to 22.6.0 * Update openvas-scanner to 22.7.5 * Update gvmd to 22.9.0 * Update gsad to 22.6.0 * Update GSA to 22.7.0 * Update gvm-libs to 22.7.1 * Replace docker-compose v1 with Docker Compose v2 ## 23.7.0 – 23-07-25 * Update gvmd to 22.6.0 * Update gsad to 22.5.1 * Update GSA to 22.5.3 * Update ospd-openvas to 22.5.3 * Update openvas-scanner to 22.7.3 * Update pg-gvm to 22.6.0 * Remove *Setting the Version* chapter * Document how to configure a mail transport agent (MTA) for the community containers * Add section about redis-socket error to troubleshooting chapter of the community containers ## 23.6.2 – 23-06-27 * Update to use Debian 12 (bookworm) * Install GSA from pre-built distributable files * Update openvas-smb to 22.5.3 * Update gvmd to 22.5.0 * Update pg-gvm to 22.5.1 * Update gsad to 22.5.0 * Removed adjusting permissions for greenbone-feed-sync script unnecessarily * Enable services only after first feed sync * Update source build instructions for Fedora 38 ## 23.6.1 – 23-06-15 * Update gvm-libs to 22.6.3 * Update notus-scanner to 22.5.0 * Update openvas-scanner to 22.7.2 * Update ospd-openvas to 22.5.1 * Update FAQ about which release contains which version * Don't install old `greenbone-nvt-sync` script anymore ## 23.6.0 – 23-06-15 * Fix tab title in *Setting up sudo for Scanning* section from Debian/CentOS to Debian/Ubuntu. * Update notus-scanner to 22.4.5 * Change all documents to use markdown instead of rst * Change current working directory before setting up postgres database * Add a section about update help to FAQ ## 23.3.0 – 23-03-08 * Unify the directory layout of the documentation files * Use distinct installation directories for each component * Add missing python3-gnupg as dependency to ospd-openvas * Don't display copy button for GPG verification output * Fix PostgreSQL setup and make it possible to copy and paste the corresponding commands again * Use new `greenbone-feed-sync` script for the feed data download * Use ospd-openvas 22.4.6, notus-scanner 22.4.4 and gvm-libs 22.4.4 * Remove 21.4 from the architecture docs * Try to fix installation of `ospd-openvas`, `notus-scanner`, `gvm-tools` and `greenbone-feed-sync` again due to issues with distributions patching Python installation paths. See [discuss.python.org](https://discuss.python.org/t/linux-distro-patches-to-sysconfig-are-changing-pip-install-prefix-outside-virtual-environments/18240) for more details. * Switch *Choosing an Install Prefix* and *Setting the PATH* section in source build to allow using $INSTALL_PREFIX when setting the $PATH. ## 23.1.1 – 23-01-31 * Set `table_drive_lsc = yes` setting for openvas scanner to enable local security checks scanning via notus scanner * Remove docs for 21.04 because it is end-of-life and won't get any updates anymore. * Extend FAQ for no results after finished scan * Update systemd service files to start the daemons in foreground to avoid issues with systemd tracking the started processes * Use ospd-openvas 22.4.5 * Update ospd-openvas.service file to depend on the mosquitto and notus-scanner services ## 23.1.0 – 23-01-13 * Fix installing ospd-openvas and notus-scanner on Debian 11 * Update components to 22.4.1 release ## 22.12.0 – 22-12-27 * Fix setting executable permission for setup and install script after the download * Check for docker being installed in setup and install script * Download the setup and install script to the current working directory * Add license header to docker startup script * Fix variable name typo in docker startup script * Fix the checks for required programs in the setup script * Use ospd-openvas 22.4.2 for 22.4 source build * Add HTML and Open Graph meta information * Fix: Remove -rf statements within `$INSTALL_DIR` to prevent deletion of root. * Update gsad systemd service file to start gsad in foreground to avoid issues with systemd tracking the started processes * Add: docker init process to prevent nmap, grep zombie processes in the ospd-openvas container * Add troubleshooting for ospd-openvas connection issue with containers * Add troubleshooting pages for source builds * Add hostname to ospd-openvas container, to avoid error Could not get a bpf, ethernet address used in non-ether expression * Extend troubleshooting for source build * Update docker compose requirement to 1.29.0 ## 22.8.2 – 22-08-31 * Improve feed sync documentation for source build * Use feed data containers for feed sync in Greenbone Community Containers docs * Extract workflows and troubleshooting to own pages for Greenbone Community Container docs * Require docker-compose 1.27.0 or later to avoid issues with the ospd-openvas startup * Use notus-scanner 22.4.1 and ospd-openvas 22.4.1 for 22.4 source build ## 22.8.1 – 2022-08-29 * Add workflow for exposing the gvmd unix socket from the container * Add an API page for links to our other community documentation * Fix path of the notus-scanner product advisories directory for the 22.4 container setup * Add gvm-tools container and usage workflow documentation ## 22.8.0 – 2022-08-16 * Fix Community Container setup and start script * Fix installing yarn from third party debian package repository * Improve and extend feed sync chapters for community containers * Use openvas-smb 22.4.0 for both releases * Add installation instructions for Fedora (35 and 26), CentOS 9 and Ubuntu 22.04 * Use new [sphinx theme](https://pradyunsg.me/furo/) for a cleaner structure and new features like dark mode ## 22.7.0 – 2022-07-25 * Update docs for supporting 22.4 release ## 22.5.0 – 2022-05-30 * New Greenbone Community Containers documentation * Update index page, history, architecture, faq and glossary for adjusted terms and naming. * Allow to copy & paste commands via a button click * Re-arrange page structure and therefore the URLs of the documents ## 22.3.3 – 2022-03-31 * Fix setting cmake parameter of runtime directory for gvmd * Fix starting the correct postgresql cluster ## 22.3.2 – 2022-03-30 * The build guide uses Debian Stable (Bullseye) * Fix installing dependencies of gvmd and openvas-scanner for Debian Bullseye * Remove obsolete cmake parameter when building gvm-libs to avoid a warning ## 22.3.1 – 2022-03-21 * Fix runtime directory for gvmd in systemd service file * Add runtime directory and mode for gsad in systemd service file ## 22.3.0 – 2022-03-07 * Fix source paths for gsad * Fix build and installation of GSA * Add hint about yarn package on Debian * Fix PIDFile settings in systemd service files for gsad and gvmd ## 22.2.0 – 2022-02-24 * Drop GVM 20.8. * Split of GSA and gsad * Merge of ospd and ospd-openvas ## 21.10.1 – 2021-10-13 * Drop usage of gsa-node-modules. These tarballs are only useful for specific nodejs versions. ## 21.10.0 – 2021-10-12 * Update for GVM 21.4.3 and 20.8.4 releases * Mark GVM 20.08 as end-of-life. User should switch to 21.04. ## 21.8.0 – 2021-08-05 * Update for GVM 21.4.2 and 20.8.3 releases * Changed feed look file location to `/var/lib/gvm/feed-update.lock`. This file is used by `gvmd` and `greenbone-feed-sync` * Add option `-f` to all curl commands to fail if an URL is not available * Change permission of `/run/gvm initially` because otherwise `gvmd` can't create the admin user ## 21.7.0 – 2021-07-05 * Initial version --- ## File: src/faq.md # Frequently Asked Questions (FAQ) ## Greenbone, GVM and OpenVAS – How are they connected? For a comprehensive background see {doc}`History of OpenVAS `. ## Where can I ask questions and get support? Support is only provided for the Greenbone Enterprise product line. Besides that, the Greenbone Community can be reached at the [community forum] to ask question. In this forum, several Greenbone developers try to help on a voluntary basis. ## Can you help with my issue on Kali, Cent OS, XYZ distribution? Greenbone does not provide any packages for any Linux distribution besides the commercial Greenbone OS. If you have installed the Greenbone Community Edition from your distribution like Kali Linux, an external package repository or even some random docker image, Greenbone was not involved in providing this installation method to you. The development of the Greenbone Community Edition and packaging for a distribution or container image is completely independent. Therefore, our software provided from these sources may be heavily adjusted, outdated or even completely broken. If you have issues with the software, please contact the provider of the packages first and create a ticket at their issue tracker. How to contact the provider depends and varies. ## Please help me with the installation of OpenVAS and also advise me on the recommended OS platform. This is very similar to [Can you help with my issue on Kali, Cent OS, XYZ distribution](#can-you-help-with-my-issue-on-kali-cent-os-xyz-distribution). Greenbone cannot provide installation docs for the many available Linux distributions available. Setups, configurations, build systems, packaging tools, available software, best practices, ... diverge to much to offer *official* packages, scripts or anything else from Greenbone. We offer this Greenbone Community Edition documentation and the [community forum] for discussing setup problems. Therefore, Greenbone also does not recommend any distribution nor do we prefer one distribution over the other. Most of the time, we are not even aware which distribution ships which version of our software. ## Can you help me updating my OpenVAS installation? This is also very similar to [Can you help with my issue on Kali, Cent OS, XYZ distribution](#can-you-help-with-my-issue-on-kali-cent-os-xyz-distribution). For updating your **source build** from a previous version of this guide, see [](./22.4/source-build/workflows.md#updating-to-newer-releases). For updating your installation of the **Greenbone Community Containers**, see [](./22.4/container/workflows.md#updating-the-greenbone-community-containers). We are **not** able to offer any help on updating installations done via any **external** source like Kali packages, Cent OS packages, some other guide or some random docker images because we are not aware of their specific needs and changes! Please contact the author(s) of your installation method. ## Which release contains which component? It was often confusing to find out which software component of the {term}`Greenbone Community Edition` belongs to which release. Additionally, the {term}`Greenbone OS ` used in the [Greenbone Free](https://www.greenbone.net/en/testnow/) had a different versioning scheme than the Community Edition. The following table contains an overview which component in which version belongs to a release. | Release | GOS | gvmd | GMP | GSA | gvm-libs | OpenVAS Scanner | Notus Scanner | Status | Release Date | |:--------|----:|------|-----|-----:|----------|-----------------|:-------------:|:------:|--------------| | [Greenbone Community Edition 22.4](https://forum.greenbone.net/t/greenbone-community-edition-22-4-stable-initial-release-2022-07-25/12638) | 22.04.y | 22.x.y | 22.4 | 22.x.y | 22.x.y | 22.x.y | 22.x.y | stable | 2022-07-25 | | [GVM 21.4](https://forum.greenbone.net/t/gvm-21-04-stable-initial-release-2021-04-16/8942) | 21.04.y | 21.4.y | 21.4 | 21.4.y | 21.4.y | 21.4.y | - | end-of-life ([Community Edition: since 2023-01-17](https://forum.greenbone.net/t/greenbone-community-edition-21-04-end-of-life/13837), [GOS: since 2023-04-03](https://forum.greenbone.net/t/greenbone-os-21-04-retired-final-patch-level-gos-21-04-26/14365)) | 2021-04-16 | | [GVM 20.08](https://forum.greenbone.net/t/gvm-20-08-stable-initial-release-2020-08-12/6312) | [20.08](https://forum.greenbone.net/t/greenbone-os-20-08-0-released/6535) | 20.8.y | 20.8 | 20.8.y | 20.8.y | 20.8.y | - | end-of-life (since 2021-12-02) | 2020-08-12 | | [GVM 11](https://forum.greenbone.net/t/gvm-11-stable-initial-release-2019-10-14/3674) | 6.0.y | 9.0.y | 9.0 | 9.0.y | 11.0.y | 7.0.y | - |end-of-life (since 2020-12-31) | 2019-10-14 | | [GVM 10](https://forum.greenbone.net/t/gvm-10-old-stable-initial-release-2019-04-05/208) | 5.0.y | 8.0.y | 8.0 | 8.0.y | 10.0.y | 6.0.y | - | end-of-life (since 2020-12-31) | 2019-04-05 | | [OpenVAS 9](https://forum.greenbone.net/t/gvm-9-end-of-life-initial-release-2017-03-07/211) | 4.x.y | openvas-manager 7.0.y | OMP 7 | 7.0.y | openvas-libraries 9.0.y | 5.1.y | - | end-of-life | 2017-03-07 | ## My self-compiled version is not working as expected. Can you help me? All questions should be handled at the [community forum] but please be aware that your questions are answered on a voluntary basis. Therefore, please do not expect immediate responses. The community forum is for individuals to exchange experiences and problems about a [Free Software](https://en.wikipedia.org/wiki/Free_software) project and not to get instant advises from the developers or professional support to fix your current issue. If you are using a self-compiled version of the Greenbone software stack not build from this guide or packages from an external third party like a distribution please always check if you can reproduce the same behavior with the [Greenbone Free](https://www.greenbone.net/en/testnow/) If we are able to reproduce your issue it will be much easier to fix. ## Can I mix components from different releases? Short answer: **no**. You must **never** mix versions of our components from different releases. Often people try to use version e.g. the scanner from the main branch in combination with a release version of the other components like gvmd to check if their failing scan works with a newer version. While it may work for some components in most circumstances it is very likely to break for gvmd, ospd, ospd-openvas and openvas-scanner. These components interact with each other a lot and rely on public and private interfaces that change with **every** release. Internal incompatible changes even might happen in bugfix releases. Therefore never mix components from different releases. Always use the latest releases or the same release branches. In the release announcements of the [community forum], we always update the linked released versions which should be used and are known to work flawlessly. ## I am looking for an overview about OpenVAS. See {doc}`Greenbone, GVM, OpenVAS and How They Are Connected ` for some background about Greenbone OpenVAS. Our software consists of several software components. All components are free software and can be found at [GitHub](https://github.com/greenbone/). For an overview of the components and their connections, please take a look at the {doc}`Architecture `. [community forum]: https://forum.greenbone.net ## I still fail to see/understand the concept of `greenbone-feed-sync --type` vs. `greenbone-nvt-sync`/`greenbone-certdata-sync`/`greenbone-scapdata-sync` vs. `gvm-feed-update` **gvm-feed-update** is **NOT** maintained by Greenbone and is therefore not used anywhere in our docs or in code provided by Greenbone. It is maintained by the Kali/Debian packagers and just calls the standard `greenbone-*-sync` scripts. **greenbone-certdata-sync** is just the same as [`greenbone-feed-sync --type CERT`](https://github.com/greenbone/gvmd/blob/v22.5.0/tools/greenbone-certdata-sync.in). It is/was only provided for backwards compatibility and does not get installed (by default) anymore since [`gvmd` 22.5.0](https://github.com/greenbone/gvmd/releases/tag/v22.5.0). **greenbone-scapdata-sync** is just the same as [`greenbone-feed-sync --type SCAP`](https://github.com/greenbone/gvmd/blob/v22.5.0/tools/greenbone-scapdata-sync.in). It is/was only provided for backwards compatibility and does not get installed (by default) anymore since [`gvmd` 22.5.0](https://github.com/greenbone/gvmd/releases/tag/v22.5.0). **greenbone-nvt-sync** is the *old* sync script written in bash to download the vulnerability tests data ({file}`.nasl` and {file}`.notus` files). It is deprecated since [`openvas-scanner` 22.6.0](https://github.com/greenbone/openvas-scanner/releases/tag/v22.6.0). **/usr/sbin/greenbone-feed-sync** is the *old* sync script written in bash to download the CERT, SCAP and GVMD data. It does not get installed (by default) anymore since [`gvmd` 22.5.0](https://github.com/greenbone/gvmd/releases/tag/v22.5.0). There is a new **greenbone-feed-sync** script written in Python to replace all of the above scripts, see the announcement at [https://forum.greenbone.net/t/new-greenbone-feed-sync-script/13925](https://forum.greenbone.net/t/new-greenbone-feed-sync-script/13925). This script is used in the build-from-source guide already but has not been picked up by the distributions yet. Hopefully, it will arrive at the distributions in the next months. It even supports the `gvm-feed-update` use case because by default, if no arguments are passed, `--type all` is run which downloads all feed data types. --- ## File: src/glossary.md # Glossary ```{glossary} gvmd Management daemon shipped with GVM 10 and later. Abbreviation for **G**reenbone **V**ulnerability **M**anagement **D**aemon. openvassd Scanner daemon used by GVM 10 and before. It listens for incoming connections and starts scan processes to run the actual vulnerability tests. It collects the results and reports them to the management daemon. With the GVM 11 release, it has been converted to the {term}`openvas` application by removing the daemon and replacing the communication protocol. Abbreviation for **OpenVAS** **S**canner **D**aemon. openvas Scanner application executable to run vulnerability tests against targets and to store scan results into a Redis database. Used in GVM 11 and later. It has originated from the {term}`openvassd`. openvasd A new service introduced with the OpenVAS Scanner release 23.0 to execute nasl scripts and provide static version comparisons. It has a http based [API](https://greenbone.github.io/scanner-api/) to control scans and get results. The adaptation will be done in various downwards compatible ways. As of 23.0.1 `openvas` is using the `/notus` endpoint for version checks, additionally `OpenVASD` is setting up redis and controls `openvas` for scanning. In the next phases it will gradually take over `openvas` functionality with the end goal of replacing `ospd-openvas` and `openvas` completely. OSPd A [framework](https://github.com/greenbone/ospd) for several scanner daemons speaking the {term}`Open Scanner Protocol (OSP) `. ospd-openvas A {term}`OSP ` scanner daemon managing the {term}`openvas ` executable for reporting scan results to the management daemon {term}`gvmd`. Used in GVM 11 and later. gsad A web server providing the {term}`Greenbone Security Assistant ` web application. GSA The Greenbone Security Assistant (GSA) web application to control scans and access vulnerability information via a web interface in a browser. GOS Greenbone Operating System, the operating system of the {term}`Greenbone Enterprise` Appliance. It provides the commercial version of the {term}`Greenbone Community Edition` with enterprise support and features. GSM Greenbone Security Manager (GSM) is the former name of our commercial product line {term}`Greenbone Enterprise` as hardware or virtual appliances. GMP The Greenbone Management Protocol (GMP) is an XML-based communication protocol provided by {term}`gvmd`. It provides an API to create, read, update and delete scans and vulnerability information. OSP The Open Scanner Protocol is an XML-based communication protocol provided by {term}`ospd-openvas`. It provides an API to start scans, get {term}`VT` information and to receive scan results. GVM The {term}`Greenbone Community Edition` consists of several services. This software framework has been named Greenbone Vulnerability Management (GVM) in the past. Greenbone Community Edition The Greenbone Community Edition covers the actual releases of the Greenbone application framework for vulnerability scanning and vulnerability management provided as open-source software to the community. The Greenbone Community Edition is adopted by external third parties, e.g., if the software framework is provided by a Linux distribution, it is build from the Greenbone Community Edition. It is developed as part of the commercial {term}`Greenbone Enterprise` product line. Sometimes referred to as the OpenVAS framework. Greenbone Community Containers Container images that are pre-built on [GitHub](https://github.com/greenbone) and available via [dockerhub](https://hub.docker.com/u/greenbone). These images can be used to run the newest versions of the {term}`Greenbone Community Edition` without having to care about the operating system, compiler and build tool chains. Greenbone Enterprise Greenbone Enterprise is the [Greenbone product line for on-premises solutions](https://www.greenbone.net/en/product-comparison/). Included are virtual or hardware Greenbone Enterprise Appliances with the {term}`Greenbone Operating System (GOS)`, the {term}`Greenbone Vulnerability Management (GVM) framework `, and the {term}`Greenbone Enterprise Feed`. Greenbone Community Feed The [Greenbone Community Feed](https://www.greenbone.net/en/feed-comparison/) is the freely available feed for vulnerability information licensed as open-source. It contains basic scan configurations, report formats, port lists and the most important vulnerability tests. The provided data is updated on a daily basis with no warranty or promises for fixes or completeness. Greenbone Enterprise Feed The [Greenbone Enterprise Feed](https://www.greenbone.net/en/feed-comparison/) is the commercial feed provided by Greenbone containing additional enterprise features like vulnerability tests for enterprise products, policy and compliance checks, extensive reports formats and special scan configurations. The feed comes with a service-level agreement ensuring support, quality assurance and availability. VT Vulnerability Tests (VTs), also known as Network Vulnerability Tests (NVTs), are scripts written in the {term}`NASL` programming language to detect vulnerabilities at remote hosts. SCAP Abbreviation for [Security Content Automation Protocol](https://csrc.nist.gov/projects/security-content-automation-protocol/). It is used for providing {term}`CPE` and {term}`CVE` data via the Greenbone Enterprise and Community Feeds. CPE Abbreviation for [Common Platform Enumeration](https://csrc.nist.gov/Projects/Security-Content-Automation-Protocol/Specifications/cpe). Common Platform Enumeration (CPE) is a standardized method of describing and identifying classes of applications, operating systems, and hardware devices present among an enterprise's computing assets. CVE Abbreviation for [Common Vulnerabilities and Exposures](https://www.cve.org/). It provides unique, common identifiers for publicly known information-security vulnerabilities in publicly released software packages. notus-scanner A scanner to improve the so-called local security checks. Local security checks are comparisons of vulnerable and installed versions of a software. Before notus-scanner, all checks have been implemented in {term}`NASL` scripts and each {term}`NASL` script ran in an own openvas-scanner process. With notus-scanner, checks are run in one go per host. With the OpenVAS Scanner release 23.0 it got replaced by {term}`openvasd`. Feed The feed is a set of different files continuously delivered via {command}`rsync` and updated on a daily basis. It contains {term}`CPE`, {term}`CVE`, {term}`VT`, CERT, Port List, Report Format and Scan Config information. The feed is available in a {term}`Commercial` and {term}`Community` edition. NASL The NASL Attack Scripting Language (NASL) is a language which is part of the OpenVAS Project and interpreted by the NASL interpreter. It is a simple language with focus on detecting vulnerabilities on network devices. Therefore it provides many built-in functions to attack hosts to discover vulnerabilities. A NASL script can be either run directly with the NASL interpreter `openvas-nasl` or within a scan with {term}`openvas`. ``` --- ## File: src/history.md ## Greenbone, GVM, OpenVAS and How They Are Connected When the OpenVAS project was launched, it only consisted of an engine for scanning vulnerabilities. Shortly after that, the company [Greenbone] was founded to achieve professional support for vulnerability scanning. Greenbone started to lead the development of OpenVAS, added several software components and turned OpenVAS into a vulnerability management solution while keeping the values of free software. This vulnerability management solution was later named {term}`Greenbone Vulnerability Management (GVM)` to reflect the origins and brand changes. Therefore, after the release of the OpenVAS 9 framework, the following releases got named GVM. With this in mind, OpenVAS could mean - a vulnerability scanner (OpenVAS Scanner), - a name for a software framework of several components (GVM), - a software project led by the company [Greenbone] (Greenbone Source Edition), - a source code release of a vulnerability management solution (OpenVAS 9, GVM 20.08, ...), or - a community of users and developers (Greenbone Community) depending on the context. To have a unique name we decided to use the term {term}`Greenbone Community Edition` as an umbrella for all Open Source/Free Software efforts of the company Greenbone in 2022. ## History of the OpenVAS project In 2005, the developers of the vulnerability scanner Nessus decided to discontinue the work under open-source licenses and switch to a proprietary business model. At this point, developers from Intevation and DN-Systems – the two companies which would later found the Greenbone AG – were already contributing developments to Nessus, focusing on client tools. The works were primarily supported by the German Federal Office for Information Security (BSI). In 2006, several forks of Nessus were created in response to the discontinuation of the open-source solution. Of these forks, only one has continued to show activity: OpenVAS, the Open Vulnerability Assessment System. OpenVAS was registered as a project at Software in the Public Interest, Inc. to hold and protect the domain "openvas.org". The years 2006 and 2007 brought little activity other than cleanups of the status quo. But in late 2008, the Greenbone AG, based in Osnabrück, Germany was founded to drive OpenVAS forward. Essentially, Greenbone's business plan was about 3 cornerstones: > 1. Go beyond plain vulnerability scanning towards a comprehensive > vulnerability management solution. > 2. Create a turn-key appliance product for enterprise customers. > 3. Continue the open-source concept of creating a transparent security > technology. Also in 2008, two further companies became active: Secpod from India and Security Space from Canada. Both of them had a focus on contributing vulnerability tests, and teamed up with Greenbone to start producing a reliable and up-to-date feed of vulnerability tests. This started with removing any source code and vulnerability tests where the license was not clear or not compatible. Several thousands of vulnerability tests were eliminated to get a clean starting point. Shortly after, the feed content grew quickly and steadily. In 2009, Greenbone added the first additional modules to build a vulnerability management solution. The web interface and the central management service were developed from scratch, with generic protocols defined as their API. At the same time, the OpenVAS scanner was carefully improved and quickly lost compatibility with its ancestor. All open-source work was branded "OpenVAS". The first "Greenbone Security Manager" appliance products entered the market in spring 2010. In the years 2010 to 2016, the commercial product was systematically improved and extended, and so were the open-source modules. The vulnerability management was extended to include daily updated security advisories, which were made available to the public with a GPL-compatible license by the German CERTs DFN-CERT and CERT-Bund, a division of the BSI. In March 2017, the OpenVAS framework reached version 9. Many new modules and numerous features were added during the release cycles. Several hundreds of thousands of lines of code were produced and there was almost no day without a couple of released code improvements by a growing development team. The year 2017 marked the beginning of a new era: first of all, Greenbone became visible as the driving force behind OpenVAS, by introducing several naming changes. This included several activities, the most essential one using the term {term}`Greenbone Vulnerability Management" (GVM)` instead of "OpenVAS framework" for the releases. Since then the OpenVAS Scanner is only one of many modules. This led to "GVM-10" as the successor of "OpenVAS-9". There were no license changes, all modules remained free and open-source software. The second major change in 2017 involved the feed service. Apart from the branding confusion, several companies integrated the technology and feed, passing it off as their work or claiming to be an alternative to Greenbone's product at a better price. Only a minority of them contributed to the project and properly complied with the GPL licenses. None of them cooperates with Greenbone commercially. To achieve better visibility, less misunderstanding, and better differentiation from other OpenVAS-based products, the public feed was renamed to {term}`Greenbone Community Feed` and the feed development was internalized. Furthermore, the release scheme has been changed from a 14-day delay to a daily publication without delay, now excluding vulnerability tests for enterprise products. The third major change to the new era was the transition to a modern infrastructure, namely GitHub and a community forum. The whole transition was completed in 2018 and boosted both productivity and community activity. The OpenVAS Scanner released with GVM-10 received numerous performance optimization to meet the challenge of a growing number of vulnerability tests scanning target networks of increasing size and heterogeneity. GVM-11 introduced substantial architectural changes: the former service {term}`openvassd` was turned into a command-line tool {term}`openvas`. It is controlled by the service layer {term}`ospd-openvas`. This concept essentially replaces the old stateful, permanent and proprietary OTP (OpenVAS Transfer Protocol) by the new stateless, request-response XML-based and generic {term}`OSP (Open Scanner Protocol)`. With [GVM 20.08](https://forum.greenbone.net/t/gvm-20-08-end-of-life-initial-release-2020-08-12/6312), the release versioning changed to [Calendar Versioning](https://calver.org/). Most important change in this release was to ship and sync the gvmd object data consisting of the report formats, port lists, policies and scan configs with the feed. Besides removing legacy features like GMP scanners, the [21.4 release](https://forum.greenbone.net/t/gvm-21-04-end-of-life-initial-release-2021-04-16/8942) got support for CVSSv3.0/CVSSv3.1. The [Greenbone Community Edition 22.4](https://forum.greenbone.net/t/greenbone-community-edition-22-4-stable-initial-release-2022-07-25/12638) release added the Notus Scanner and removed some legacy features like support for generic OSP scanners. During 2023 the decision was taken to allow more flexible development of the components and to release them independently of each other. To allow to express software compatibility most components switched to [semantic versioning](https://semver.org/). --- ## File: src/index.md ```{eval-rst} .. meta:: :description lang=en: Greenbone Community Edition - Documentation :description lang=de: Greenbone Community Edition - Dokumentation :keywords: OpenVAS, Greenbone, Community, Greenbone Community Edition, GVM, Container, Docker, Documentation :property=og:locale: en_US ``` # Greenbone Community Edition – Documentation The Greenbone Community Edition covers the actual source code of the Greenbone Vulnerability Management software stack, which is also known as [OpenVAS](./history.md). It is available as regularly updated source code snapshots/release archives confirmed to work and as source code checkouts directly from the git source code repositories at [GitHub](https://github.com/greenbone/). The latter is not recommended for production scenarios as the code is edited on a daily basis and issues and incomplete functionality may appear. The sources of the Greenbone Community Edition are adopted by third parties, for example Linux distributions like Kali, Alpine, etc. This documentation covers the stable version of the Greenbone Community Edition. ```{image} _static/greenbone-banner.png ``` ```{toctree} :hidden: true background 22.4/source-build/index 22.4/container/index 22.4/kali/index faq troubleshooting glossary changelog api ``` --- ## File: src/troubleshooting.md # Troubleshooting This page contains hints for troubleshooting general issues with the Greenbone Community Edition. - For source build specific troubleshooting, see [Troubleshooting the source build](./22.4/source-build/troubleshooting.md). - For community container specific troubleshooting see [Troubleshooting the community containers](./22.4/container/troubleshooting.md). - For Kali Linux specific troubleshooting see [Troubleshooting a Kali Linux installation](./22.4/kali/troubleshooting.md). ### Facing an issue with the Greenbone Community Edition If you have an issue with the Greenbone Community Edition because something doesn't work as expected and/or you are getting an error in the web UI it is necessary to check the log files to get some technical hints about the issue. If something doesn't work during the scan the {file}`/var/log/gvm/ospd-openvas.log` and {file}`/var/log/gvm/openvas.log` files should be checked for errors. Otherwise the {file}`/var/log/gvm/gvmd.log` file needs to be inspected. Afterwards using the collected error messages in the [search of our Community Forum](https://forum.greenbone.net/search) may bring up possible results to resolve the issue already. If no fitting results can be found feel free to create a new topic at our [Community Forum](https://forum.greenbone.net/). A post in the forum should always contain the installation method and the version of the Greenbone Community Edition (build from source via this guide, official community containers, Kali packages, ...) and the found error message. ## My scan does not show any results After a finished scan, your report does not contain any results or errors. Some common issues if scans does not return any results are: 1. The targets are not answering to an **ICMP Echo Request** → Check the **Alive Test** setting of your target definition and try some of the other available methods. Further reading: - [Greenbone Enterprise Appliance documentation - Hosts not found](https://docs.greenbone.net/GSM-Manual/gos-22.04/en/scanning.html#hosts-not-found) - [Greenbone Enterprise Appliance documentation - Creating a target](https://docs.greenbone.net/GSM-Manual/gos-22.04/en/scanning.html#creating-a-target) - [Greenbone Enterprise Appliance documentation - Alive Test](https://docs.greenbone.net/GSM-Manual/gos-22.04/en/scanning.html#alive-test) 2. You are using a custom scan configuration which does not include the following two VTs from the **Port scanners** family. - [Nmap (NASL wrapper) - OID: 1.3.6.1.4.1.25623.1.0.14259](https://secinfo.greenbone.net/nvt/1.3.6.1.4.1.25623.1.0.14259) - [Ping Host - OID: 1.3.6.1.4.1.25623.1.0.100315](https://secinfo.greenbone.net/nvt/1.3.6.1.4.1.25623.1.0.100315) Further reading [here](https://community.greenbone.net/t/hint-self-created-scan-configs-copy-of-empty-scan-config-showing-no-results/331) 3. You are using a [port list](https://docs.greenbone.net/GSM-Manual/gos-22.04/en/performance.html#selecting-a-port-list-for-a-task) which is not optimal for your environment: e.g., a ``All TCP and All UDP`` port list might be responsible for your port scan timing out, causing your scan to not return any results at all. It is suggested to start with a smaller port list, e.g., ``All IANA TCP``. 4. **SELinux** is enabled and blocking the scanner from doing its job. 5. You do not have **nmap** installed or not available within your **PATH**. For further debugging/logging, the mentioned **Nmap (NASL wrapper)** and **Ping Host** VTs allow to configure various settings: * Ping Host 1. **Report about unreachable Hosts** configured to **yes**: include notes if a remote host is considered as dead/not reachable, and the reason why. 2. **Log failed nmap calls** and **Log nmap output** configured to **yes**: Logs additional output if nmap was used. * Nmap (NASL wrapper) 1. **Log nmap output** configured to **yes**: Log additional output if nmap was used. ## OOM is killing Redis on large scans During a larger scan, the machine is running out of memory. Therefore, the Linux Out-of-Memory (OOM) killer is terminating the Redis database server and the scan gets interrupted. The problem described is not easy to solve as it can have several root causes, from known issues to usage behavior. In particular, there can be problems with vHosts and CGI caching. In general, we recommend the following: * Prevent overloading the system by adjusting the usage: * Do not start scan tasks all at once. Use schedules to start them at intervals. * Reconfigure scan targets to include less hosts. Split the hosts into more targets and tasks instead. * Do not run or schedule feed updates for times where scan tasks are running or scheduled to run. * Do not view or download large reports while scan tasks are running. * Disable vHost expansion for scans that cause problems: * Clone and edit the used scan configuration. * Set the scanner preference `expand_vhosts` to `0` and save the change. * Disable CGI caching for scans that cause problems: * Clone and edit the used scan configuration. * Navigate to the VT family *Settings*. * Edit the VT `Global Variable Settings` (OID: *1.3.6.1.4.1.25623.1.0.12288*). * Set the preference `Disable caching of web pages during CGI scanning` to `Yes` and save the change. If you think that you can narrow the problem down to a specific issue in the scanner please open an issue for the scanner at [https://github.com/greenbone/openvas-scanner/issues](https://github.com/greenbone/openvas-scanner/issues). For support on scan configuration changes like mentioned above to reduce the memory usage during a scan please open a topic at [Scanning / scan configuration - Greenbone Community Forum](https://forum.greenbone.net/c/scanning-scan-configuration/26). ## Vulnerabilities are not found A scan report does not contain any results or some known vulnerabilities do not show up in the report. This may have several reasons. Most likely, the {term}`feed` synchronization is not finished yet. The feed data has been downloaded to the file system of the local machine but {command}`gvmd` and {command}`ospd-openvas` did not have enough resources to load them into their databases and memory yet. This can be checked on the web interface by opening the {menuselection}`SecInfo > NVTs` page to see whether {term}`VTs` are listed there and the {menuselection}`Administration > Feed Status` page to see whether a synchronization process is currently running. If both pages are fine, you may take a look at the following sections in our product manual: - [20.2 Why Is a Service/Product Not Detected?](https://docs.greenbone.net/GSM-Manual/gos-22.04/en/faq.html#why-is-a-service-product-not-detected) - [20.3 Why Is a Vulnerability Not Detected?](https://docs.greenbone.net/GSM-Manual/gos-22.04/en/faq.html#why-is-a-vulnerability-not-detected) --- ## File: src/22.4/container/admin-user.md ## 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: ```{code-block} shell --- caption: Updating password of administrator user --- docker compose -f $DOWNLOAD_DIR/compose.yaml \ exec -u gvmd gvmd gvmd --user=admin --new-password='' ``` ```{note} Please be aware if your password includes special characters like `$` it needs to be quoted in single quotes. ``` --- ## File: src/22.4/container/hardware.md ## Hardware Requirements ```{list-table} :header-rows: 1 :width: 100% :widths: 70 15 15 * - Component - Minimal - Recommended * - CPU Cores (Compute) - 2 - 4 * - Random-Access Memory (RAM) - 4 GB - 8 GB * - Available Storage - 20 GB - 60 GB ``` --- ## File: src/22.4/container/index.md # Greenbone Community Containers ```{include} /22.4/container/preamble.md ``` ```{include} /22.4/container/introduction.md ``` ```{include} /22.4/container/hardware.md ``` ```{include} /22.4/container/prerequisites.md ``` (docker-compose-file)= ## Docker Compose File ```{important} Please always ensure to use the latest version of the `compose.yaml` file when following this guide. The file might get updates and important changes since your last download. ``` To run the Greenbone Community Edition with containers, the following compose file should be used: ```{literalinclude} compose.yaml --- language: yaml caption: "Docker Compose File" --- ``` ### Download It is possible to just copy and paste the docker compose file. Alternatively, it can be downloaded with the following command directly: ```{code-block} shell --- caption: Downloading Docker compose file --- curl -f -O -L https://greenbone.github.io/docs/latest/_static/compose.yaml --output-dir "$DOWNLOAD_DIR" ``` ### 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](https://redis.io/) | A redis server with an adjusted config. Used to store VT data and scan results by the scanner. | | pg-gvm | [postgresql](https://www.postgresql.org/) | A PostgreSQL database cluster setup for use with {term}`gvmd`. The actual data is stored in the `psql_data_vol` volume. | | pg-gvm-migrator | | A container for migrating the database from one PostgreSQL major version to another | | gvmd | gvmd | A container for {term}`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. | | gsad | gsad | A container running the {term}`gsad` service for providing the web API. It translates between http and {term}`GMP`. For communication with gvmd, a unix socket in a volume is used. | | gsa | | A container that copies the static content for the web application {term}`GSA` to the `gsa_data_vol` volume on startup. | | gvm-config | | A container providing the nginx config and self-signed certificates for https communication. | | nginx | nginx | A nginx web server providing {term}`GSA`. It forwards API requests to the gsad service. | | 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. | | gvm-tools | | A container providing the [gvm-tools](https://github.com/greenbone/gvm-tools/) CLI to query and control gvmd and ospd-openvas. | | 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. | | vulnerability-tests | | A container that copies vulnerability tests (VTs) into the `vt_data_vol` volume on startup. Shows the license and exits afterwards. | | notus-data | | A container that copies vulnerability information for notus-scanner into the `notus_data_vol` volume on startup. Shows the license and exits afterwards. | | scap-data | | A container that copies CVE and CPE data into the `scap_data_vol` volume on startup. Shows the license and exits afterwards. | | cert-bund-data | | A container that copies CERT-Bund data into the `cert_data_vol` volume on startup. Shows the license and exits afterwards. | | dfn-cert-data | | A container that copies DFN-CERT data into the `cert_data_vol` volume on startup. Shows the license and exits afterwards. | | data-objects | | A container that copies scan configs, compliance policies and port lists into the `data_objects_vol` volume on startup. Shows the license and exits afterwards. | | report-formats | | A container that copies report formats into the `data_objects_vol` volume on startup. Shows the license and exits afterwards. | | configure-openvas | | A container for setting up the configuration for OpenVAS Scanner | | openvas | | A container that shows the logs of OpenVAS Scanner | | openvasd | openvasd | A container for [openvasd](https://github.com/greenbone/openvas-scanner/tree/main/rust/openvasd). It is providing notus, a static vulnerability engine, functionality. | ```{include} /22.4/container/starting.md ``` ```{include} /22.4/container/admin-user.md ``` ## Starting the Vulnerability Management After the services have started and [all feed data has been loaded](./workflows.md#loading-the-feed-changes), the {term}`Greenbone Security Assistant web interface – GSA –` can be opened in the browser. ```{code-block} shell --- caption: Opening Greenbone Security Assistant in the browser --- xdg-open "https://127.0.0.1" 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. ```{figure} /images/GSA-20260709.png --- alt: Launching Greenbone Security Assistant for the first time --- Greenbone Security Assistant after logging in for the first time ``` ## Setup and Start Script ```{note} Please remember to follow the instructions described in the [Prerequisites](#prerequisites) first. ``` As a quick solution we provide all the commands above in a single script. This script can be downloaded with the following command directly: ```{code-block} shell --- caption: Downloading setup and start script to the current working dir --- curl -f -O https://greenbone.github.io/docs/latest/_static/setup-and-start-greenbone-community-edition.sh && chmod u+x setup-and-start-greenbone-community-edition.sh ``` To execute the script following command needs to be run ```{code-block} shell --- caption: Run setup and start script --- ./setup-and-start-greenbone-community-edition.sh ``` ```{toctree} :hidden: workflows troubleshooting ``` [docker]: https://docs.docker.com/ [docker-compose]: https://docs.docker.com/compose/ --- ## File: src/22.4/container/introduction.md ## Introduction This document provides a guide for running the {term}`Greenbone Community Edition` from pre-built container images using [Docker]. It consists of a distributed service {doc}`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. --- ## File: src/22.4/container/manual-feed-sync.md ## Performing a Manual Feed Sync It is possible to do a manual feed sync using {command}`rsync` instead of pulling the current feed content via the newest container images. ```{warning} Please be aware that the manually synced data will be overridden if the data containers are (re-)started. ``` For the manual feed sync, the [`greenbone-feed-sync`](https://github.com/greenbone/greenbone-feed-sync/) script will be used. The `greenbone-feed-sync` script is also provided via a container image. Using the container image requires extending the docker compose file as follows: ```{code-block} yaml --- caption: Extending the docker compose file for performing a manual feed sync using the greenbone-feed-sync script --- ... greenbone-feed-sync: image: registry.community.greenbone.net/community/greenbone-feed-sync volumes: - vt_data_vol:/var/lib/openvas/plugins - notus_data_vol:/var/lib/notus - gvmd_data_vol:/var/lib/gvm - scap_data_vol:/var/lib/gvm/scap-data - cert_data_vol:/var/lib/gvm/cert-data - data_objects_vol:/var/lib/gvm/data-objects/gvmd ... ``` ### Syncing Vulnerability Tests VT data contains {file}`.nasl` and {file}`.notus` files for creating results during a vulnerability scan. ```{code-block} shell --- caption: Downloading {term}`NASL` {term}`VTs` processed by the ospd-openvas scanner, this will take a while. --- docker compose -f $DOWNLOAD_DIR/compose.yaml \ run --rm greenbone-feed-sync greenbone-feed-sync --type nasl ``` ```{code-block} shell --- caption: Downloading `notus` {term}`VTs` processed for local security checks, this will take a while. --- docker compose -f $DOWNLOAD_DIR/compose.yaml \ run --rm greenbone-feed-sync greenbone-feed-sync --type notus ``` ### Syncing SCAP, CERT and GVMD Data {term}`SCAP` data contains {term}`CPE` and {term}`CVE` information. ```{code-block} shell --- caption: Downloading SCAP data processed by gvmd, this will take a while --- docker compose -f $DOWNLOAD_DIR/compose.yaml \ run --rm greenbone-feed-sync greenbone-feed-sync --type scap ``` CERT data contains vulnerability information from the German [DFN-CERT](https://www.dfn-cert.de/) and [CERT-Bund](https://cert-bund.de/) agencies. ```{code-block} shell --- caption: Downloading CERT data processed by gvmd --- docker compose -f $DOWNLOAD_DIR/compose.yaml \ run --rm greenbone-feed-sync greenbone-feed-sync --type cert ``` gvmd data (or also called data-objects) are scan configurations, compliance policies, port lists and report formats. ```{code-block} shell --- caption: Downloading data objects processed by gvmd --- docker compose -f $DOWNLOAD_DIR/compose.yaml \ run --rm greenbone-feed-sync greenbone-feed-sync --type gvmd-data ``` --- ## File: src/22.4/container/preamble.md Running the Greenbone Community Edition from containers requires knowledge about: * Using a terminal/shell (e.g. {command}`bash` or {command}`sh`). * Using [docker](https://www.docker.com/) and/or [podman](https://podman.io/). * Running services via [docker compose](https://docs.docker.com/compose/). Additionally, a basic knowledge about the {doc}`architecture ` of the Greenbone Community Edition is required to understand the setup and inner workings. ```{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** [(bookworm)](https://www.debian.org/releases/stable) * **Ubuntu 24.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. ``` --- ## File: src/22.4/container/prerequisites.md ## Prerequisites ```{note} Please follow the guide step by step. Later steps might require settings or output of a previous command. ``` The {command}`sudo`-command is used for executing commands and binaries that require privileged access on the system. ### Dependencies There are a few dependencies required for the following steps like [curl](https://curl.se/) and [docker](https://www.docker.com/), of which the former is required to downloading files from this guide. [curl](https://curl.se/) can be separately downloaded through the instructions below, but it will also be installed when following the Docker engine installation docs. `````{tabs} ````{tab} Debian/Ubuntu ```{code-block} shell --- caption: Install ca-certificates and curl Debian/Ubuntu packages --- sudo apt install ca-certificates curl ``` ```` ````{tab} Fedora/CentOS ```{code-block} shell --- caption: Install ca-certificates and curl Fedora/CentOS packages --- sudo dnf install ca-certificates curl ``` ```` ````` ### Installing Docker [Docker](https://www.docker.com/) (alternatively [podman](https://podman.io/)) is the application with which the Greenbone stack will be deployed. Docker can be installed by following the instructions provided directly by them. Please refer to the: [Official Docker Engine Installation Guide](https://docs.docker.com/engine/install/): ### Setting up Docker To allow the current user to run {command}`docker`-commands and therefore start the containers, they must be added to the *docker* user group (or be run as root). To make the group change effective, either logout and login again or use the {command}`su`-command. ```{code-block} shell --- caption: Add current user to docker group and apply group changes for the current shell environment --- sudo usermod -aG docker $USER && su $USER ``` For downloading the Greenbone Community Edition docker compose file, a destination directory should be created. ```{code-block} shell --- caption: Create download directory --- export DOWNLOAD_DIR=$HOME/greenbone-community-edition && mkdir -p $DOWNLOAD_DIR ``` --- ## File: src/22.4/container/starting.md ## 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. ```{code-block} shell --- caption: Downloading the Greenbone Community Containers --- docker compose -f $DOWNLOAD_DIR/compose.yaml pull ``` ```{code-block} shell --- caption: Starting the Greenbone Community Containers --- docker compose -f $DOWNLOAD_DIR/compose.yaml up -d ``` To get a continuous stream of the log output of all services, run the following command: ```{code-block} shell --- caption: Show log messages of all services from the running containers --- docker compose -f $DOWNLOAD_DIR/compose.yaml logs -f ``` The log stream can be stopped by pressing {kbd}`Ctrl-C`. --- ## File: src/22.4/container/troubleshooting.md ## Troubleshooting This page contains hints for troubleshooting Greenbone Community Container specific issues. ### Facing an issue with the Greenbone Community Containers If you have an issue with the Greenbone Community Containers because something doesn't work as expected and/or you are getting an error in the web UI it is necessary to check the log output to get some technical hints about the issue. To inspect the logs you can use the [`docker compose logs`](https://docs.docker.com/engine/reference/commandline/compose_logs/) command. For displaying the complete log output you can run ```{code-block} shell --- caption: Display all logs --- docker compose -f $DOWNLOAD_DIR/compose.yaml logs ``` To follow the current log output to display log messages as they occur use the following command ```{code-block} shell --- caption: Follow current log output --- docker compose -f $DOWNLOAD_DIR/compose.yaml logs -f ``` It's also possible to just display the logs of a specific container by using `docker compose logs ` where service is the [name of the container within the docker compose file](./index.md#description). ```{code-block} shell --- caption: Follow the log messages of the gvmd container only --- docker compose -f $DOWNLOAD_DIR/compose.yaml logs -f gvmd ``` Additionally it is possible to bypass the `docker compose log` command and access the log files directly. For example run the following command to display the content of the OpenVAS scanner log file via {command}`cat` ```{code-block} shell --- caption: Print messages from /var/log/gvm/openvas.log --- docker compose -f $DOWNLOAD_DIR/compose.yaml \ exec ospd-openvas cat /var/log/gvm/openvas.log ``` Afterwards using the collected error messages in the [search of our Community Forum](https://forum.greenbone.net/search) may bring up possible results to resolve the issue already. If no fitting results can be found feel free to create a new topic the [Community Containers category in our Community Forum](https://forum.greenbone.net/c/community-containers/40). ### 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. ```{code-block} shell --- caption: Restart the scanner to ensure that new {term}`VTs` are loaded --- docker compose -f $DOWNLOAD_DIR/compose.yaml 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: ```{code-block} shell --- caption: Forcing reload of report formats, scan configs and port lists --- docker compose -f $DOWNLOAD_DIR/compose.yaml \ 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. ### `osp_scanner_feed_version: failed to connect to /run/ospd/ospd-openvas.sock` If the `gvmd` log contains this error, `gvmd` is not able to connect to the `ospd-openvas` scanner. Most likely `ospd-openvas` is not running. Try to restart the corresponding container with: ```{code-block} shell --- caption: Restarting the ospd-openvas scanner --- docker compose -f $DOWNLOAD_DIR/compose.yaml restart ospd-openvas ``` If you still get errors, you need to take a look at the `ospd-openvas` logs. ```{code-block} shell --- caption: Showing log message of the ospd-openvas scanner --- docker compose -f $DOWNLOAD_DIR/compose.yaml log -f ospd-openvas ``` ### 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 ```{image} gvmd-not-responding.png --- alt: gvmd not responding width: 200px align: center --- ``` and/or the logs contain a `Failed to connect to server at /run/gvmd/gvmd.sock: Connection refused` message, the {term}`gvmd` container must be restarted. It is very likely it had some issues accessing the PostgreSQL database. ```{code-block} shell --- caption: Restarting {term}`gvmd` --- docker compose -f $DOWNLOAD_DIR/compose.yaml restart gvmd ``` ### Redis server keeps restarting `rm: cannot remove ‘/run/redis/redis.sock’: Permission denied` Under some circumstances the [Unix Domain Socket](https://en.wikipedia.org/wiki/Unix_domain_socket) of the Redis server has got wrong permissions. To fix this issue it is required to shutdown the `redis-server` and `ospd-openvas` containers and remove the `redis_socket_vol` [docker volume](https://docs.docker.com/storage/volumes/). The volume can be removed safely because it gets recreated on the next startup. ```{code-block} shell --- caption: Recreating the Redis server socket volume --- docker compose -f $DOWNLOAD_DIR/compose.yaml \ rm -s -f redis-server ospd-openvas docker volume rm greenbone-community-edition_redis_socket_vol docker compose -f $DOWNLOAD_DIR/compose.yaml up -d ``` --- ## File: src/22.4/container/workflows.md # Workflows ## Updating the Greenbone Community Containers ```{important} Please always ensure to use the latest version of the docker [compose.yaml](#docker-compose-file) file when following these steps. The file might got updates and important changes since your last download. ``` 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: ```{code-block} shell --- caption: Downloading the Greenbone Community Containers --- docker compose -f $DOWNLOAD_DIR/compose.yaml pull ``` ```{code-block} shell --- caption: Starting the Greenbone Community Containers --- docker compose -f $DOWNLOAD_DIR/compose.yaml up -d ``` ## Performing a Feed Synchronization For the actual vulnerability scanning, {term}`Vulnerability Tests`, security information like CVEs, port lists and scan configurations are required. All this data is provided by the {term}`Greenbone Community Feed` via dedicated data container images. A feed synchronization always consists of two parts: 1. Downloading the changes via pulling new container images 2. Loading the changes 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 {command}`docker compose pull`. The second step is done automatically when the daemons are running. ### Downloading the Feed Changes The data of the {term}`Greenbone Community Feed` is provided via several container images. When these images are started, they copy the data into the used docker volumes automatically. Afterwards, the data is picked up from the volumes by the running daemons. To download the latest feed data container images run ```{code-block} shell --- caption: Downloading the Greenbone Community Edition feed data containers --- docker compose -f $DOWNLOAD_DIR/compose.yaml pull notus-data vulnerability-tests scap-data dfn-cert-data cert-bund-data report-formats data-objects ``` To copy the data from the images to the volumes run ```{code-block} shell --- caption: Starting the Greenbone Community feed data containers --- docker compose -f $DOWNLOAD_DIR/compose.yaml up -d notus-data vulnerability-tests scap-data dfn-cert-data cert-bund-data report-formats data-objects ``` ### Loading the Feed Changes ```{important} When feed content has been downloaded, the new data must 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 the Greenbone Community Containers have been started, the running daemons will always 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: ```{code-block} none --- caption: 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: ```{code-block} none --- caption: 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, the data will be requested by gvmd. This will result in the following log message: ```{code-block} none --- caption: 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: ```{code-block} none --- caption: gvmd VTs loading finished log message --- Updating VTs in database ... done (X VTs). ``` #### SCAP Data gvmd starts loading the {term}`SCAP` data containing {term}`CPE` and {term}`CVE` information when the following message can be found in the logs: ```{code-block} none --- caption: 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: ```{code-block} none --- caption: 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: ```{code-block} none --- caption: 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: ```{code-block} none --- caption: 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: ```{code-block} none --- caption: 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: ```{code-block} none --- caption: 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 and a *Feed Import Owner* is set. ``` For scan configs: ```{code-block} none --- caption: gvmd scan config loaded log message --- Scan config Full and fast (daba56c8-73ec-11df-a475-002264764cea) has been created by admin ``` ## Accessing the Web Interface Remotely When using the docker compose file, the web server is configured to listen only on the local address of the host (127.0.0.1). To allow remote access on all interfaces of the host, the compose file must be modified to configure the web server {command}`nginx` to listen on all network interfaces. The following change of the docker compose file can be applied (it also changes to the default http port to port 80 as an example): ```{code-block} diff --- caption: Allowing access on all host interfaces --- ... gvm-config: image: registry.community.greenbone.net/community/gvm-config:latest environment: ENABLE_NGINX_CONFIG: true ENABLE_TLS_GENERATION: true + # e.g. "greenbone.your-domain.com" (default is localhost) + NGINX_HOST: "" + # change http port to 80 (default is 9392) + NGINX_HTTP_PORT: 80 + # e.g. "https://greenbone.your-domain.com:443" (default is https://${NGINX_HOST}:${NGINX_HTTPS_PORT}) + NGINX_ACCESS_CONTROL_ALLOW_ORIGIN_HEADER: "https://" ... nginx: image: registry.community.greenbone.net/community/nginx:latest ports: - - 127.0.0.1:443:443 - - 127.0.0.1:9392:9392 + - 80:80 + - 443:443 volumes: - nginx_config_vol:/etc/nginx/templates:ro - nginx_certificates_vol:/etc/nginx/certs:ro - gsa_data_vol:/usr/share/nginx/html:ro depends_on: gvm-config: condition: service_completed_successfully gsa: condition: service_healthy gsad: condition: service_started ... ``` ## 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: ```{code-block} shell --- caption: Remove containers and volumes (all data) --- docker compose -f $DOWNLOAD_DIR/compose.yaml down -v ``` ## Gaining 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: ```{code-block} shell --- caption: Gain a Terminal for a Container --- docker compose -f $DOWNLOAD_DIR/compose.yaml exec /bin/bash ``` Afterwards, you can execute standard bash commands within the running container. ## Using gvm-tools for CLI access To query data or control gvmd and ospd-openvas via CLI, [gvm-tools](https://github.com/greenbone/gvm-tools/) can be used. gvm-tools is provided in the gvm-tools container. This container can be started with: ```{code-block} shell --- caption: Start container for gvm-tools CLI access --- docker compose -f $DOWNLOAD_DIR/compose.yaml run --rm gvm-tools ``` Afterwards, a bash shell is provided and `gvm-cli`, `gvm-pyshell` or `gvm-script` can be run. For example: ```{code-block} shell --- caption: Query gvmd version via gvm-cli --- gvm-cli --gmp-username admin socket --pretty --xml "" ``` ## Exposing gvmd Unix socket for GMP Access To enable the use of the protocol {term}`GMP` provided by {term}`gvmd` from the docker host, a [bind mount](https://docs.docker.com/compose/compose-file/compose-file-v3/#volumes) must be used for the `/run/gvmd` directory. To make the gvmd Unix socket available, a directory must be created first and the permissions must be adjusted. ```sh mkdir -p /tmp/gvm/gvmd chmod -R 777 /tmp/gvm ``` In the next step, the docker compose file must be changed as follows: ```diff 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 + - /tmp/gvm/gvmd:/run/gvmd - ospd_openvas_socket_vol:/run/ospd - psql_socket_vol:/var/run/postgresql depends_on: - pg-gvm ... gsad: image: registry.community.greenbone.net/community/gsad:stable restart: on-failure environment: GSAD_ARGS: "--listen=0.0.0.0 --http-only --api-only -f" volumes: - - gvmd_socket_vol:/run/gvmd + - /tmp/gvm/gvmd:/run/gvmd depends_on: gvmd: condition: service_started ``` After restarting the containers with ```bash docker compose -f $DOWNLOAD_DIR/compose.yaml up -d ``` the Unix socket should be available at `/tmp/gvm/gvmd/gvmd.sock`. For example, to use the socket with [gvm-tools](https://github.com/greenbone/gvm-tools), the following command can be executed: ```bash gvm-cli socket --socketpath /tmp/gvm/gvmd/gvmd.sock --pretty --xml "" ``` ## Setting up a mail transport agent inside Docker container {term}`gvmd` uses the `msmtp` client as MTA. It can be configured with environment variables within compose file or command line. Available variables (for detailed explanation refer to [msmtp documentation](https://marlam.de/msmtp/msmtp.html), note that not all `mstmp` options implemented in `gvmd` container): - `MTA_HOST`: The SMTP server to send the mail to. (_Mandatory parameter_). - `MTA_PORT`: The port that the SMTP server listens on. (_default = '25'_). - `MTA_TLS`: Enable or disable TLS (_on|off'_). - `MTA_STARTTLS`: TLS variant: start TLS from within the session (_‘on’, default_), or nnel the session through TLS (_‘off’_). - `MTA_TLS_CERTCHECK`: Enable or disable checks of the server certificate. (WARNING: When the checks are disabled, TLS sessions will not be secure!) (_'on'|'off'_). - `MTA_AUTH`: Enable or disable authentication and optionally choose a method to use 'on'|'off'|'method'_). - `MTA_USER`: Username for authentication. - `MTA_PASSWORD`: Password for authentication. - `MTA_FROM`: Set the envelope-from address. - `MTA_LOGFILE`: Enable logging to the specified file. Examples: ```{code-block} yaml --- caption: Use a local network relay without authorization --- ... gvmd: image: registry.community.greenbone.net/community/gvmd:stable environment: - MTA_HOST=postfix-server.example.org - MTA_PORT=25 - MTA_TLS=off - MTA_STARTTLS=off - MTA_AUTH=off ... ``` ```{code-block} yaml --- caption: Use the Google Mail services with SSL and authorization --- ... gvmd: image: registry.community.greenbone.net/community/gvmd:stable environment: - MTA_HOST=smtp.gmail.com - MTA_PORT=587 - MTA_TLS=on - MTA_STARTTLS=on - MTA_AUTH=on - MTA_USER= - MTA_FROM=@gmail.com - MTA_PASSWORD= ... ``` ```{include} /22.4/container/manual-feed-sync.md ``` ## Setting up SSL/TLS for GSA Enabling SSL/TLS for the the web interface ({term}`GSA`) requires generating a private key and public certificate. By default a self signed certificate is generated automatically. To provide an own certificate the following steps are necessary. As of September 2020, the maximum validity period for publicly trusted SSL/TLS certificates is 398 days. An expiration date of more than 397 days is not valid and may cause some browsers to block the connection. OpenSSL can be used to generate the private key and certificate: ```{code-block} yaml openssl req -x509 -newkey rsa:4096 -keyout server.key -out servercert.cert.pem -nodes -days 397 ``` The user that executes the `docker compose` command must have read access to the private key and certificate. So, they must be placed in an appropriate location such as the user's home directory or the `tmp` directory. ```{code-block} yaml mkdir $HOME/.ssl && mv server.key server.cert.pem $HOME/.ssl ``` Finally, the nginx configuration in the `compose.yaml` file must be modified to use the new certificate files. Sample `nginx` service settings to use own TLS certificate files: ```diff nginx: image: registry.community.greenbone.net/community/nginx:latest ports: - 127.0.0.1:443:443 - 127.0.0.1:9392:9392 volumes: - nginx_config_vol:/etc/nginx/templates:ro - - nginx_certificates_vol:/etc/nginx/certs:ro + - /home//.ssl/:/etc/nginx/certs:ro - gsa_data_vol:/usr/share/nginx/html:ro depends_on: gvm-config: condition: service_completed_successfully gsa: condition: service_healthy gsad: condition: service_started ``` After modifying the `compose.yaml` file, restart the containers to enable the changes. ```{code-block} shell --- caption: Restart the Greenbone Community Containers --- docker compose -f $DOWNLOAD_DIR/compose.yaml up -d ``` ================================================ SYMLINK: src/22.4/container/compose.yaml -> compose.yaml ================================================ --- ## File: src/22.4/kali/feed-sync.md ## Community Feed Synchronization The standard `greenbone-feed-sync` commands must be used to maintain current security information. A detailed guide on using the `greenbone-feed-sync` command is [available here](../source-build/feed-sync.md). --- ## File: src/22.4/kali/file-system.md ## Log And Configuration File Locations Here are the locations of the various Greenbone Community Edition log and configuration files. ```{code-block} :caption: View all Greenbone Community Edition log files ls /var/log/gvm ``` ```{code-block} :caption: View the OpenVAS Scanner configuration files ls /etc/openvas ``` ```{code-block} :caption: View the other Greenbone Community Edition configuration files ls /etc/gvm ``` --- ## File: src/22.4/kali/index.md # Kali Linux Install Guide ```{include} /22.4/kali/introduction.md ``` ```{include} /22.4/kali/installation.md ``` ```{include} /22.4/kali/feed-sync.md ``` ```{include} /22.4/kali/optional-configs.md ``` ```{include} /22.4/kali/file-system.md ``` ```{toctree} :hidden: true troubleshooting ``` --- ## File: src/22.4/kali/installation.md ## Installing Greenbone Community Edition on Kali Linux ### Quick Start Install For those who want a quick start guide, here is an overview of the standard installation process: > 1. Update Kali Linux with `sudo apt update`. > 2. Install Greenbone Community Edition with `sudo apt install gvm`. > 3. Configure Greenbone Community Edition with `sudo gvm-setup` and note the provided *admin* password from the output > 4. Check the install status with `gvm-check-setup`. > 5. Visit [https://127.0.0.1:9392](https://127.0.0.1:9392) and log in using the credentials output in step 3. > 6. Verify the feed status before starting your first scan. ### Detailed Installation Instructions In this section includes a more detailed look at each step of the installation process. ### 1. Update Kali Linux The first step is to update the system's local package lists for repositories and PPAs (Personal Package Archives). Kali Linux is a "rolling" distribution which means that it continuously updates all of its software (the kernel, libraries, applications, and other system software) to the latest versions without requiring a complete OS reinstallation. Rolling releases typically offer the latest versions of software soon after they are released. Therefore, It's highly advised to also do a full package `upgrade` before installing `gvm` since Greenbone Community Edition requires the newest version of PostgreSQL. If you are having trouble upgrading and configuring PostgreSQL during the installation process, see the [troubleshooting section](troubleshooting.md). ```{warning} System upgrades may result in changes to the existing kernel, libraries, and software that could interfere with existing functionality. Before doing an upgrade you should make a complete backup of all critical files on your system including the contents of your PostgreSQL database. ``` ```{code-block} :caption: Full package list update and system upgrade sudo apt update && sudo apt upgrade ``` ### 2. Install Greenbone Community Edition Greenbone Community Edition and required dependencies can be installed with a single command: ```bash sudo apt install gvm -y ``` Note that this is the same as executing the command: ```bash sudo apt install openvas -y ``` ### 3. Run The Automatic Configuration Script After installing the required packages, a configuration script must be run to complete the installation. To run the automatic configuration execute the command: ```{note} During `gvm-setup` you must record the default password created for the admin user. ``` ```bash sudo gvm-setup ``` ### 4. Verify The Installation The Kali Linux native installation includes a script to verify the installed services. This script can be run using the command: ```bash sudo gvm-check-setup ``` If your installation has been successfully configured, you will see the following message at the end of the verification out: ``` It seems like your GVM-22.5.0 installation is OK. ``` #### Starting And Stopping Greenbone Community Edition The following commands can be used to start and stop Greenbone Community Edition and all its required services: ```{code-block} :caption: Start all services sudo gvm-start ``` ```{code-block} :caption: Stop all services sudo gvm-stop ``` ### 5. Log Into The Greenbone Web Interface Once the installation is complete you can log into the {term}`GSA` web interface by visiting [https://127.0.0.1:9392](https://127.0.0.1:9392) in your browser and providing the default admin credentials from step 3. ### 6. Verify The Feed Status Before starting the first scan, Greenbone needs to parse the vulnerability feeds and store them into the `gvmd` PostgreSQL database, otherwise, it will not be able to initialize or complete scans without errors. This process is initialized during the setup stage, but typically takes anywhere from a few minutes to several hours to complete, depending on your system resources. The feed status can be checked by going to the `Feed Status` page from the `Administration` section in the top menu bar. --- ## File: src/22.4/kali/introduction.md This documentation provides instructions on how to install {term}`Greenbone Community Edition` from the Kali Linux native repository. The install packages are maintained by [Offensive Security](https://www.kali.org/tools/gvm/). Any bugs discovered during installation or use should be reported to [Kali Linux Bug Tracker](https://bugs.kali.org/main_page.php). Guidelines for submitting bugs to Kali Linux can be [found here](https://www.kali.org/docs/community/submitting-issues-kali-bug-tracker/). ```{important} Greenbone does not hold responsibility for use of the Greenbone Community Edition installed via the native Kali Linux packages, and is not involved in the packaging process of the Greenbone Community Edition for Kali Linux. ``` --- ## File: src/22.4/kali/optional-configs.md ## Optional Configurations The Greenbone Community Edition on Kali Linux installation relies on the same sub-system components as the [source code installation](/22.4/source-build/index.md) and all configuration options are available. Let's cover some common custom configurations. ### Configure Remote Access To The Web Interface By default Greenbone Community Edition is installed with only `localhost` access to the {term}`GSA` web interface. This means Greenbone Community Edition can only be accessed via the IP address `127.0.0.1`. To enable remote access to the web interface, the {term}`gsad` systemd service file must be modified and the gsad service must be restarted. Edit the contents of the `gsad.service` systemd service file: ```{code-block} :caption: Use nano to edit the gsad.sevice file nano /usr/lib/systemd/system/gsad.service ``` Change the value of the `--listen` argument to `0.0.0.0` and optionally change the value of `--port` to the standard SSL/TLS port 443: ```diff -ExecStart=/usr/local/sbin/gsad --foreground --listen=127.0.0.1 --port=9392 +ExecStart=/usr/local/sbin/gsad --foreground --listen=0.0.0.0 --port=443 ``` Restart the `gsad` service: ```{code-block} sudo systemctl daemon-reload sudo systemctl restart gsad ``` ### Setting A Password Policy The password policy configuration file defines the rules for user passwords such as minimum length, complexity, and expiration period, ensuring that all user passwords adhere to the desired security standards. ```{code-block} :caption: Edit the Greenbone Community Edition password policy configuration nano /etc/gvm/pwpolicy.conf ``` --- ## File: src/22.4/kali/troubleshooting.md # Troubleshooting ## Troubleshooting A Kali Linux Installation Here are some common issues encountered during installation and steps to fix them. ## Upgrading The Default PostgreSQL Version If you encounter an error regarding the PostgreSQL version when running `sudo gvm-setup`, you must upgrade the installed version of PostgreSQL to the newest version required by the Kali native `gvm` package. In the example below shows the upgrade from PostgreSQL version 15 to version 16, but these steps will work to upgrade between any versions. ```{code-block} :caption: Error indicating the need to upgrade your PostgreSQL cluster ┌──(dev㉿kali)-[~] └─$ sudo gvm-setup [>] Starting PostgreSQL service [-] ERROR: The default PostgreSQL version (15) is not 16 that is required by libgvmd [-] ERROR: libgvmd needs PostgreSQL 16 to use the port 5432 [-] ERROR: Use pg_upgradecluster to update your PostgreSQL cluster ``` To complete the Greenbone Community Edition setup you must: 1. Migrate PostgreSQL settings and data to a new upgraded cluster 2. Configure the new cluster to use port `5432` 3. Install the newest pg-gvm extension 4. Fix the gmvd database COLLATION mismatch 5. Resolve Any Outstanding Dependencies 6. Complete the Greenbone Community Edition Setup ### 1. Upgrade PostgreSQL Cluster ```{warning} You should consider the contents of your existing PostgreSQL database and complete any backups of that data before you complete the following steps. It's also important to consider that upgrading Kali Linux packages could disrupt the functionality of your system. ``` You can list all existing PostgreSQL clusters using the command `pg_lsclusters`. ```{code-block} :caption: Listing the existing PostgreSQL clusters ┌──(dev㉿kali)-[~] └─$ pg_lsclusters Ver Cluster Port Status Owner Data directory Log file 15 main 5432 online postgres /var/lib/postgresql/15/main /var/log/postgresql/postgresql-15-main.log 16 main 5433 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log ``` The output above shows two online clusters listening on ports `5432` and `5433`. Since the target cluster `16/main` already exists, it must be temporarily deleted to avoid the error `Error: target cluster 16/main already exists`. The existence of the `16/main` cluster does not necessarily mean that the old cluster has already been upgraded; it simply means that a cluster for that version is present. ```{code-block} :caption: Trying to upgrade to an existing cluster will fail. ┌──(dev㉿kali)-[~] └─$ sudo pg_upgradecluster 15 main 16 Error: target cluster 16/main already exists ``` To complete the upgrade, the `16/main` cluster must first be stopped and deleted. ```bash sudo pg_ctlcluster 16 main stop sudo pg_dropcluster 16 main ``` Now upgrade the old cluster to a new one. The `pg_upgradecluster` command migrates databases from the old cluster to the new cluster. ```{code-block} :caption: The basic syntax of the pg_upgradecluster command. pg_upgradecluster [options] oldversion oldclustername [newversion] ``` To upgrade your PostgreSQL cluster, you should use the following command: ```bash sudo pg_upgradecluster 15 main ``` If you do not need the older PostgreSQL cluster, you should delete it. ```bash sudo pg_dropcluster 15 main ``` And remove the PostgreSQL 15 packages ```bash sudo apt autoremove ``` Now only the new PostgreSQL cluster exists. ```{code-block} :caption: Listing the existing PostgreSQL clusters ┌──(dev㉿kali)-[~] └─$ pg_lsclusters Ver Cluster Port Status Owner Data directory Log file 16 main 5433 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log ``` ### 2. Configure The PostgreSQL Port Typically, the `pg_upgradecluster` will also configure the new version of PostgreSQL to use the standard port `5432`, which is required by Greenbone Community Edition. However, if the port is not automatically changed, you must change it manually by editing the `postgresql.conf` configuration file and restarting the PostgreSQL systemd service. On Kali the `postgresql.conf` configuration file is located in the `/etc/postgresql//main` directory, but to be sure you can issue a command to locate the configuration file. ```bash sudo -u postgres psql -c 'SHOW config_file' ``` ```{code-block} :caption: Executing command to locate the PostgreSQL config file ┌──(dev㉿kali)-[~] └─$ sudo -u postgres psql -c 'SHOW config_file' config_file ----------------------------------------- /etc/postgresql/16/main/postgresql.conf (1 row) ``` Edit the configuration file and change the connection settings port to `5432` and restart the PostgreSQL port. ```{code-block} :caption: Use nano to edit the postgresql.conf file sudo nano /etc/postgresql/16/main/postgresql.conf ``` ```diff # - Connection Settings - #listen_addresses = 'localhost' # what IP address(es) to listen on; # comma-separated list of addresses; # defaults to 'localhost'; use '*' for all # (change requires restart) -port = 5433 # (change requires restart) +port = 5432 # (change requires restart) max_connections = 100 # (change requires restart) #reserved_connections = 0 # (change requires restart) #superuser_reserved_connections = 3 # (change requires restart) ``` ```{code-block} :caption: Restart the PostgreSQL systemd service sudo systemctl restart postgresql ``` ### 3. Install The Newest pg-gvm Extension For PostgreSQL When upgrading PostgreSQL cluster to a newer version, the `pg-gvm` package must also be updated. If you do not update this package before running `sudo gvm-check-setup`, you will encounter the following error when rebuilding the `gvmd` database: ```{code-block} :caption: Missing pg-gvm extention error when running gvm-check-setup [*] Creating extension pg-gvm ERROR: extension "pg-gvm" is not available DETAIL: Could not open extension control file "/usr/share/postgresql/16/extension/pg-gvm.control": No such file or directory. HINT: The extension must first be installed on the system where PostgreSQL is running. ``` You can find all available versions of `pg-gvm` using the `apt-cache search` command: ```{code-block} :caption: Searching the Linux package repository for all versions of pg-gvm ┌──(dev㉿kali)-[~] └─$ apt-cache search pg-gvm postgresql-16-pg-gvm - PostgreSQL extension for ical object manipulation ``` After updating the aptitude package repository is `postgresql-16-pg-gvm` which matches the new PostgreSQL version. So, you need to install that package: ```bash sudo apt install postgresql-16-pg-gvm -y ``` ### 4. Fixing The gvmd COLLATION Version Mismatch During a PostgreSQL cluster upgrade you may encounter a COLLATION mismatch warning. This warning must be resolved before `gvm-setup` can be completed. ```{code-block} :caption: Error message indicating a COLLATION version mismatch WARNING: database "gvmd" has a collation version mismatch DETAIL: The database was created using collation version 2.36, but the operating system provides version 2.37. HINT: Rebuild all objects in this database that use the default collation and run ALTER DATABASE gvmd REFRESH COLLATION VERSION, or build PostgreSQL with the right library version. ``` To fix the collation mismatch, login to the `psql` command line and execute the suggested commands to update all databases in the cluster. This will at least include the `gvmd` and `postgres` databases. ```{code-block} :caption: Become the postgres user to access the psql shell as a superadmin sudo su postgres ``` ```{code-block} :caption: Start the PostgreSQL shell psql ``` ```{code-block} :caption: Update each database COLLATION version postgres=# ALTER DATABASE postgres REFRESH COLLATION VERSION; NOTICE: changing version from 2.36 to 2.37 ALTER DATABASE postgres=# ALTER DATABASE gvmd REFRESH COLLATION VERSION; NOTICE: changing version from 2.36 to 2.37 ALTER DATABASE postgres-# \q postgres@kali:/home/dev$ exit ``` ### 5. Resolve Any Outstanding Dependencies In order to complete the database cluster migration, you may also need to update various outdated extensions depending on the particular changes between PostgreSQL versions. For example, when migrating between PostgreSQL 15 and 16, the `pgcrypto` module must be updated. To update any unresolved dependencies... ```bash sudo apt install pgcrypto ``` ### 6. Complete The Greenbone Community Edition Setup You can now run the `gvm-setup` command to complete the setup. ``` sudo gvm-setup ``` ```{note} During setup it's important to note and record the default password created for the GVM admin user. ``` ```{code-block} :caption: The admin password is included in gvm-setup output [+] Done [*] Please note the password for the admin user [*] User created with password 'ff006a29-8977-4ffa-882c-cd430fdc9bb8'. [>] You can now run gvm-check-setup to make sure everything is correctly configured ``` ## Other Common Setup Errors ```{note} Here are some other common setup errors you may encounter when installing Greenbone Community Edition from the native Kali Linux package. In most cases, hints are available in the `gvm-setup` and `gvm-check-setup` command output. ``` ### ERROR: extention "pg-gvm" is not available [See the instructions here](#3-install-the-newest-pg-gvm-extension-for-postgresql) to find and install the latest version of `pg-gvm`. ### ERROR: No users found If you encounter the error **ERROR: No users found.** when running `sudo gvm-check-setup`, you will need to create at least one an admin user. Replace `` with your own password. ```bash sudo runuser -u _gvm -- gvmd --create-user=admin --password='' ``` ### ERROR: The Postgresql DB does not exist If the PostgreSQL database was not created during initial setup of Greenbone Community Edition, or not transferred when migrating to a new cluster, you must manually create the database with the following command: ``` sudo runuser -u postgres -- /usr/share/gvm/create-postgresql-database ``` ### ERROR: Required systemd service did not start If the ospd-openvas service or any other required Greenbone `systemd` services did not start during the setup or initialization, you can attempt to manually start the process. Here is an example for troubleshooting the `ospd-openvas` systemd service, but you can use this process for other services as well: ```{code-block} :caption: Try to manually start the service sudo systemctl start ospd-openvas ``` If the service still fails to start properly, you can check for errors using the following methods: ```{code-block} :caption: Display the systemd service status including any errors sudo systemctl status ospd-openvas | less ``` ```{code-block} :caption: View detailed system logs with extended output journalctl -xe ``` ```{code-block} :caption: View most recent items in the ospd-openvas log file tail -20 /var/log/gvm/ospd-openvas.log ``` ```{note} You can find all the Greenbone Community Edition log files in the `/var/log/gvm` directory. ``` ### ERROR: The client certificate file of gsad is not valid If the required SSL/TLS certificates failed to generate during the standard setup process, or if the existing certificates are not valid any longer, you must generate the necessary SSL/TLS certificate files. The script `gvm-manage-certs` is used for managing the certificates required by Greenbone Community Edition. ```{code-block} :caption: Generate all required SSL/TLS certificates sudo runuser -u _gvm -- gvm-manage-certs -a -f ``` ### ERROR: Database is wrong version. You have installed a new gvmd version When upgrading Greenbone Community Edition, you may need to also update the `gvmd` PostgreSQL database schema. You can update the `gvmd` database to the with the following command: ```bash sudo runuser -u _gvm -- gvmd --migrate ``` ### ERROR: No postgresql version uses the port 5432. Greenbone Community Edition requires a PostgreSQL connection on port 5432. [See instructions here](#2-configure-the-postgresql-port) to change the PostgreSQL port. --- ## File: src/22.4/source-build/admin-user.md ### Setting up an Admin User For accessing and configuring the vulnerability data, an administrator user needs to be created. This user can log in via the Greenbone Security Assistant (GSA) web interface. They will have access to all data and will later be configured to act as the *Feed Import Owner*. ```{code-block} :caption: Creating an administrator user with generated password /usr/local/sbin/gvmd --create-user=admin ``` The new administrator user's password is printed on success. An administrator user can later create further users or administrators via the GSA web interface. To create the administrator user with a password of your choice instead of the generated password, the following command can be used: ```{code-block} :caption: Creating an administrator user with provided password /usr/local/sbin/gvmd --create-user=admin --password='' ``` ```{note} Please be aware if your password includes special characters like `$` it needs to be quoted in single quotes. ``` If the output doesn't show ```{code-block} none :class: no-copybutton User created. ``` you need to look at the {file}`/var/log/gvm/gvmd.log` for errors. --- ## File: src/22.4/source-build/directory-permissions.md ### Adjusting Permissions For a system-wide multi-user installation, it must be ensured that the directory permissions are set correctly and are matching the group setup. All users of the group *gvm* should be able to read and write logs, lock files and data like VTs. ```{code-block} :caption: Adjusting directory permissions sudo mkdir -p /var/lib/notus sudo mkdir -p /run/gvmd sudo chown -R gvm:gvm /var/lib/gvm sudo chown -R gvm:gvm /var/lib/openvas sudo chown -R gvm:gvm /var/lib/notus sudo chown -R gvm:gvm /var/log/gvm sudo chown -R gvm:gvm /run/gvmd sudo chmod -R g+srw /var/lib/gvm sudo chmod -R g+srw /var/lib/openvas sudo chmod -R g+srw /var/log/gvm ``` To allow all users of the group *gvm* access to the postgres database via the various *gvmd* commands, the permissions of the *gvmd* executable will be adjusted to always run as the *gvm* user and under the *gvm* group. ```{code-block} :caption: Adjusting gvmd permissions sudo chown gvm:gvm /usr/local/sbin/gvmd sudo chmod 6750 /usr/local/sbin/gvmd ``` --- ## File: src/22.4/source-build/feed-import-owner.md ### Setting the Feed Import Owner Certain resources that were previously part of the gvmd source code are now shipped via the feed. An example is the scan configuration "Full and Fast". Currently every resource needs an owner to apply the permissions and manage the access to the resources. Therefore, *gvmd* will only create these resources if a *Feed Import Owner* is configured. Here the previously created admin user will be used as the *Feed Import Owner*. ```{code-block} :caption: Setting the Feed Import Owner /usr/local/sbin/gvmd --modify-setting 78eceaec-3385-11ea-b237-28d24461215b --value `/usr/local/sbin/gvmd --get-users --verbose | grep admin | awk '{print $2}'` ``` --- ## File: src/22.4/source-build/feed-loading.md ### Vulnerability Tests Data If the log file of ospd-openvas ({file}`/var/log/gvm/ospd-openvas.log`) contains the following output, the OpenVAS Scanner starts to load the new VT data: ```{code-block} none :caption: 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 following log message can be found: ```{code-block} none :caption: 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, the data will be requested by gvmd. This will result in the following log message in {file}`/var/log/gvm/gvmd.log`: ```{code-block} none :caption: 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: ```{code-block} none :caption: gvmd VTs loading finished log message Updating VTs in database ... done (X VTs). ``` ### SCAP Data gvmd starts loading the {term}`SCAP` data containing {term}`CPE` and {term}`CVE` information when the following message can be found in the logs ({file}`/var/log/gvm/gvmd.log`): ```{code-block} none :caption: 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: ```{code-block} none :caption: 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 ({file}`/var/log/gvm/gvmd.log`): ```{code-block} none :caption: 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: ```{code-block} none :caption: gvmd CERT data finished loading log message sync_cert: Updating CERT info succeeded. ``` ### GVMD Data The log ({file}`/var/log/gvm/gvmd.log`) contains several messages when the gvmd data is loaded. For port lists, these messages are similar to: ```{code-block} none :caption: 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: ```{code-block} none :caption: 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 and a *Feed Import Owner* is set. ::: For scan configs: ```{code-block} none :caption: gvmd scan config loaded log message Scan config Full and fast (daba56c8-73ec-11df-a475-002264764cea) has been created by admin ``` --- ## File: src/22.4/source-build/feed-sync.md ## Performing a Feed Synchronization For the actual vulnerability scanning, {term}`Vulnerability Test scripts`, security information like {term}`CVEs `, port lists and scan configurations are required. All this data is provided by the {term}`Greenbone Community Feed` and should be downloaded initially before starting the services. A synchronization always consists of two parts: 1. Downloading the changes via [rsync](https://en.wikipedia.org/wiki/Rsync) 2. Loading the changes 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 {command}`greenbone-feed-sync` script. The second step is done automatically when the daemons are started. ### Downloading the Data ```{note} Downloading the data during the synchronization may take a while depending on the network connection and server resources. ``` The downloaded data consist of four different kind of data: - VT data - SCAP data - CERT data - GVMD data VT data contain {file}`.nasl` and {file}`.notus` files for creating results during a vulnerability scan. The {file}`.nasl` files are processed by the OpenVAS Scanner and the {file}`.notus` files by the {term}`Notus Scanner `. {term}`SCAP` data contains {term}`CPE` and {term}`CVE` information. CERT data contain vulnerability information from the German [DFN-CERT](https://www.dfn-cert.de/) and [CERT-Bund](https://www.bsi.bund.de/EN/Themen/Unternehmen-und-Organisationen/Cyber-Sicherheitslage/Reaktion/CERT-Bund/cert-bund_node.html) agencies. GVMD data (or also called "data objects") are scan configurations, compliance policies, port lists and report formats. ```{code-block} :caption: Downloading the data from the Greenbone Community Feed sudo /usr/local/bin/greenbone-feed-sync ``` --- ## File: src/22.4/source-build/finish.md ## Starting the Vulnerability Management After the services have started and all data has been loaded, the {term}`Greenbone Security Assistant web interface – GSA – ` can be opened in the browser. ```{code-block} :caption: 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 in the *Setting Up an Admin User* chapter, it is possible to start with the vulnerability scanning. ```{figure} /images/GSA-20260709.png :alt: Launching Greenbone Security Assistant for the first time Greenbone Security Assistant after logging in for the first time ``` --- ## File: src/22.4/source-build/gpg.md ### Feed Validation For validating the feed content, a GnuPG keychain with the *Greenbone Community Feed integrity key* needs to be created. ```{code-block} :caption: Creating a GPG keyring for feed content validation curl -f -L https://www.greenbone.net/GBCommunitySigningKey.asc -o /tmp/GBCommunitySigningKey.asc export GNUPGHOME=/tmp/openvas-gnupg mkdir -p $GNUPGHOME gpg --import /tmp/GBCommunitySigningKey.asc echo "8AE4BE429B60A59B311C2E739823FAA60ED1E580:6:" | gpg --import-ownertrust export OPENVAS_GNUPG_HOME=/etc/openvas/gnupg sudo mkdir -p $OPENVAS_GNUPG_HOME sudo cp -r /tmp/openvas-gnupg/* $OPENVAS_GNUPG_HOME/ sudo chown -R gvm:gvm $OPENVAS_GNUPG_HOME ``` --- ## File: src/22.4/source-build/hardware.md ## 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 --- ## File: src/22.4/source-build/index.md # Building from Source ```{include} /22.4/source-build/introduction.md ``` ```{highlight} shell-session ``` ```{include} /22.4/source-build/hardware.md ``` ```{include} /22.4/source-build/prerequisites.md ``` ## Building and Installing the Components ```{note} The components should be build and installed in the listed order. ``` ### gvm-libs ```{include} /22.4/source-build/gvm-libs/description.md ``` ```{code-block} :caption: Setting the gvm-libs version to use export GVM_LIBS_VERSION=23.9.3 ``` ```{include} /22.4/source-build/gvm-libs/dependencies.md ``` ```{include} /22.4/source-build/gvm-libs/download.md ``` Afterwards, gvm-libs can be build and installed. ```{include} /22.4/source-build/gvm-libs/build.md ``` ### gvmd ```{include} /22.4/source-build/gvmd/description.md ``` ```{code-block} :caption: Setting the gvmd version to use export GVMD_VERSION=26.37.0 ``` ```{include} /22.4/source-build/gvmd/dependencies.md ``` Details about the optional dependencies can be found at . ```{include} /22.4/source-build/gvmd/download.md ``` ```{include} /22.4/source-build/gvmd/build.md ``` ### pg-gvm ```{include} /22.4/source-build/pg-gvm/description.md ``` ```{code-block} :caption: Setting the pg-gvm version to use export PG_GVM_VERSION=22.6.9 ``` ```{include} /22.4/source-build/pg-gvm/dependencies.md ``` ```{include} /22.4/source-build/pg-gvm/download.md ``` Afterwards, pg-gvm can be build and installed. ```{include} /22.4/source-build/pg-gvm/build.md ``` ### Greenbone Security Assistant The Greenbone Security Assistant (GSA) sources consist of two parts: - Web server *gsad* - Web application *GSA* #### GSA ```{include} /22.4/source-build/gsa/description.md ``` ```{code-block} :caption: Setting the GSA version to use export GSA_VERSION=28.3.0 ``` ```{include} /22.4/source-build/gsa/download.md ``` ```{include} /22.4/source-build/gsa/build.md ``` #### gsad ```{include} /22.4/source-build/gsad/description.md ``` ```{code-block} :caption: Setting the GSAd version to use export GSAD_VERSION=27.2.0 ``` ```{include} /22.4/source-build/gsad/dependencies.md ``` ```{include} /22.4/source-build/gsad/download.md ``` ```{include} /22.4/source-build/gsad/build.md ``` ### openvas-smb ```{include} /22.4/source-build/openvas-smb.md ``` ### openvas-scanner ```{include} /22.4/source-build/openvas-scanner/description.md ``` ```{code-block} :caption: Setting the openvas-scanner version to use export OPENVAS_SCANNER_VERSION=23.20.1 ``` ```{include} /22.4/source-build/openvas-scanner/dependencies.md ``` ```{include} /22.4/source-build/openvas-scanner/download.md ``` ```{include} /22.4/source-build/openvas-scanner/build.md ``` ### ospd-openvas ```{include} /22.4/source-build/ospd-openvas/description.md ``` ```{code-block} :caption: Setting the ospd and ospd-openvas versions to use export OSPD_OPENVAS_VERSION=22.10.5 ``` ```{include} /22.4/source-build/ospd-openvas/dependencies.md ``` ```{include} /22.4/source-build/ospd-openvas/download.md ``` ```{include} /22.4/source-build/ospd-openvas/build.md ``` ### openvasd ```{include} /22.4/source-build/openvasd/description.md ``` ```{code-block} :caption: Setting the openvas versions to use export OPENVAS_DAEMON=23.20.0 ``` ```{include} /22.4/source-build/openvasd/dependencies.md ``` ```{include} /22.4/source-build/openvasd/download.md ``` ```{include} /22.4/source-build/openvasd/build.md ``` ### greenbone-feed-sync ```{include} /22.4/source-build/greenbone-feed-sync/description.md ``` ```{include} /22.4/source-build/greenbone-feed-sync/dependencies.md ``` ```{include} /22.4/source-build/greenbone-feed-sync/install.md ``` ### gvm-tools ```{include} /22.4/source-build/gvm-tools/description.md ``` ```{include} /22.4/source-build/gvm-tools/dependencies.md ``` ```{include} /22.4/source-build/gvm-tools/install.md ``` ## Performing a System Setup ```{include} /22.4/source-build/redis.md ``` ```{include} /22.4/source-build/directory-permissions.md ``` ```{include} /22.4/source-build/gpg.md ``` ```{include} /22.4/source-build/sudo-scanning.md ``` ```{include} /22.4/source-build/postgres.md ``` ```{include} /22.4/source-build/admin-user.md ``` ```{include} /22.4/source-build/feed-import-owner.md ``` ```{include} /22.4/source-build/systemd.md ``` ```{include} /22.4/source-build/feed-sync.md ``` ```{include} /22.4/source-build/start-services.md ``` ```{include} /22.4/source-build/feed-loading.md ``` ```{include} /22.4/source-build/finish.md ``` ```{toctree} :hidden: true workflows troubleshooting ``` --- ## File: src/22.4/source-build/introduction.md Building the Greenbone Community Edition from source requires knowledge about: - Using a terminal - Shell programming basics - Installing software via *apt* or *dnf* - Using a C compiler - Using *CMake* and *make* - The [Linux File System Hierarchy](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard) - Running services via *systemd* Additionally, a basic knowledge about the {doc}`architecture ` of the Greenbone Community Edition is required to follow this guide. :::{note} This guide is intended for developers who want to try out the newest features and/or want to get familiar with the source code. It is not intended for production setups. Currently the docs support the following distributions - **Debian stable** [(bookworm)](https://www.debian.org/releases/stable) - **Ubuntu 24.04 LTS** - **Fedora 38** - **CentOS 9 Stream** Most likely, other Debian derivatives like Mint and Kali will also work with only minor adjustments required. ::: --- ## File: src/22.4/source-build/openvas-smb.md *openvas-smb* is a helper module for *openvas-scanner*. It includes libraries (openvas-wmiclient/openvas-wincmd) to interface with Microsoft Windows Systems through the Windows Management Instrumentation API and a winexe binary to execute processes remotely on that system. It is an optional dependency of *openvas-scanner* but is required for scanning Windows-based systems. ```{warning} *openvas-smb* doesn't work on CentOS at the moment! It is not a hard requirement. ``` ```{code-block} :caption: Setting the openvas-smb version to use export OPENVAS_SMB_VERSION=22.5.3 ``` ```{eval-rst} .. tabs:: .. tab:: Debian/Ubuntu .. code-block:: :caption: Required dependencies for openvas-smb sudo apt install -y \ gcc-mingw-w64 \ libgnutls28-dev \ libglib2.0-dev \ libpopt-dev \ libunistring-dev \ heimdal-multidev \ perl-base ``` ```{code-block} :caption: Downloading the openvas-smb sources curl -f -L https://github.com/greenbone/openvas-smb/archive/refs/tags/v$OPENVAS_SMB_VERSION.tar.gz -o $SOURCE_DIR/openvas-smb-$OPENVAS_SMB_VERSION.tar.gz curl -f -L https://github.com/greenbone/openvas-smb/releases/download/v$OPENVAS_SMB_VERSION/openvas-smb-v$OPENVAS_SMB_VERSION.tar.gz.asc -o $SOURCE_DIR/openvas-smb-$OPENVAS_SMB_VERSION.tar.gz.asc ``` ```{code-block} :caption: Verifying the source file gpg --verify $SOURCE_DIR/openvas-smb-$OPENVAS_SMB_VERSION.tar.gz.asc $SOURCE_DIR/openvas-smb-$OPENVAS_SMB_VERSION.tar.gz ``` The output of the last command should be similar to: ```{include} /22.4/source-build/verify.md ``` If the signature is valid, the tarball can be extracted. ``` tar -C $SOURCE_DIR -xvzf $SOURCE_DIR/openvas-smb-$OPENVAS_SMB_VERSION.tar.gz ``` ```{code-block} :caption: Building openvas-smb mkdir -p $BUILD_DIR/openvas-smb cmake \ -S $SOURCE_DIR/openvas-smb-$OPENVAS_SMB_VERSION \ -B $BUILD_DIR/openvas-smb \ -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX \ -DCMAKE_BUILD_TYPE=Release cmake --build $BUILD_DIR/openvas-smb -j$(nproc) ``` ```{code-block} :caption: Installing openvas-smb mkdir -p $INSTALL_DIR/openvas-smb && cd $BUILD_DIR/openvas-smb make DESTDIR=$INSTALL_DIR/openvas-smb install sudo cp -rv $INSTALL_DIR/openvas-smb/* / ``` --- ## File: src/22.4/source-build/postgres.md ### Setting up PostgreSQL The [PostgreSQL](https://www.postgresql.org/) database management system is used as a central storage for user and scan information. *gvmd* connects to a PostgreSQL database and queries the data. This database must be created and configured. ```{eval-rst} .. tabs:: .. tab:: Debian/Ubuntu .. code-block:: :caption: Installing the PostgreSQL server sudo apt install -y postgresql .. tab:: Fedora/CentOS .. code-block:: :caption: Installing the PostgreSQL server sudo dnf install -y postgresql-server postgresql-contrib ``` If necessary the PostgreSQL database server needs to be started manually ```{eval-rst} .. tabs:: .. tab:: Debian .. code-block:: :caption: Starting the PostgreSQL database server sudo systemctl start postgresql@15-main .. tab:: Ubuntu .. code-block:: :caption: Starting the PostgreSQL database server sudo systemctl start postgresql@16-main .. tab:: Fedora/CentOS .. code-block:: :caption: Starting the PostgreSQL database server sudo postgresql-setup --initdb --unit postgresql sudo systemctl start postgresql ``` For setting up the PostgreSQL database it is required to become the postgres user. ```{code-block} :caption: Changing to the postgres user sudo -u postgres bash ``` ```{code-block} :caption: Setting up PostgreSQL user and database for the Greenbone Community Edition cd createuser -DRS gvm createdb -O gvm gvmd ``` ```{code-block} :caption: Setting up database permissions and extensions psql gvmd -c "create role dba with superuser noinherit; grant dba to gvm;" exit ``` --- ## File: src/22.4/source-build/prerequisites.md ## 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. ### Creating a User and a Group The services provided by the Greenbone Community Edition should run as a dedicated user and group. Therefore a `gvm` user and a group with the same name will be created. ```{eval-rst} .. tabs:: .. tab:: Debian/Ubuntu .. code-block:: :caption: Creating a gvm system user and group sudo useradd -r -M -U -G sudo -s /usr/sbin/nologin gvm .. tab:: Fedora/CentOS .. code-block:: :caption: Creating a gvm system user and group sudo useradd -r -M -U -G wheel -s /usr/sbin/nologin gvm ``` ### Adjusting the Current User To allow the current user to run *gvmd* he must be added to the *gvm* group. To make the group change effective either logout and login again or use {command}`su`. ```{code-block} :caption: Add current user to gvm group sudo usermod -aG gvm $USER su $USER ``` ### Setting Environment Variables For easier installation and not having to repeat the same directory paths over and over again the build from source guide uses [environment variables](https://en.wikipedia.org/wiki/Environment_variable). These environment variables are used later in the guide. ```{attention} If you close your linux shell/terminal or start a new one, for example due to a system reboot while following this guide, you need to set the environment variables again. Environment variables are only valid in your current shell/terminal. ``` #### Choosing an Install Prefix Before building the software stack, a (root) directory must be chosen where the built software will finally be installed. For example, when building packages, the distribution developers set this path to {file}`/usr`. By default, it is {file}`/usr/local` which is also used in this guide. This directory will be stored in an environment variable {envvar}`INSTALL_PREFIX` to be able to reference it later. ```{code-block} :caption: Setting an install prefix environment variable export INSTALL_PREFIX=/usr/local ``` #### Setting the PATH On Debian systems the locations {file}`/sbin`, {file}`/usr/sbin` and {file}`/usr/local/sbin` are not in the {envvar}`PATH` of normal users. To run *gvmd* which is located in {file}`/usr/local/sbin` the {envvar}`PATH` environment variable should be adjusted. ```{code-block} :caption: Adjusting PATH for running gvmd export PATH=$PATH:$INSTALL_PREFIX/sbin ``` #### Setting a Source, Build and Install Directory To separate the sources and the build artifacts, a source and a build directory must be created. This source directory will be used later in this guide via an environment variable {envvar}`SOURCE_DIR`. Accordingly, a variable {envvar}`BUILD_DIR` will be set for the build directory. Both can be set to any directory to which the current user has write permissions. Therefore directories in the current user's home directory are chosen in this guide. ```{code-block} :caption: Choosing a source directory export SOURCE_DIR=$HOME/source mkdir -p $SOURCE_DIR ``` ```{code-block} :caption: Choosing a build directory export BUILD_DIR=$HOME/build mkdir -p $BUILD_DIR ``` Additionally, an install directory will be set as an environment variable {envvar}`INSTALL_DIR`. It is used as a temporary installation directory before moving all built artifacts to the final destination. ```{code-block} :caption: Choosing a temporary install directory export INSTALL_DIR=$HOME/install mkdir -p $INSTALL_DIR ``` ### Choosing the Installation Source For building the GVM software stack, three different sources can be chosen depending on the desired stability: - Building from release [tarballs] - Building from git tags - Building from release branches Linux distributions use the release [tarballs] because it is the most common and well known method to share source code. Newer build systems may stick with the git tags. If you are a developer and very familiar with building from source already, you may also try out using the git release branches. These have the advantage that they contain the newest fixes which may not yet be included in the release tarballs or git tags. As a downside, the release branches may contain only partially fixed issues and need to be updated more often. This guide will use the tarballs to build the software. ### Installing Common Build Dependencies For downloading, configuring, building and installing the Greenbone Community Edition components, several tools and applications are required. To install this requirements the following commands can be used: ```{eval-rst} .. tabs:: .. tab:: Debian/Ubuntu .. code-block:: :caption: Installing common build dependencies sudo apt update sudo apt install --no-install-recommends --assume-yes \ build-essential \ curl \ cmake \ pkg-config \ python3 \ python3-pip \ gnupg .. tab:: Fedora .. code-block:: :caption: Installing common build dependencies sudo dnf upgrade -y sudo dnf groupinstall 'Development Tools' -y sudo dnf install -y \ cmake \ python3-pip \ tar \ gcc-c++ sudo tee /etc/ld.so.conf.d/local.conf <