greenbone/docs

Documentation for the Greenbone Community Edition

Documentation for the Greenbone Community Edition

The documentation is build automatically via GitHub Actions and available at https://greenbone.github.io/docs/

Requirements

For a manual build locally Python >= 3.9 and poetry is required.

Install Poetry

The project requires poetry >= 1.8.0.

To install poetry it is recommended to use pipx. pipx can be installed with the following command on Debian based systems:

sudo apt install pipx

Install poetry using pipx

python3 -m pipx install poetry

Install and Upgrade Dependencies

When building the docs you should ensure that all the dependencies are installed and up to date. To install for the first time or to update the project dependencies via poetry run:

poetry install

You should run this command once a week to install the latest dependencies.

Manual Build

After installing poetry and the project's dependencies, the docs can be built with:

poetry run make html

To open the generated HTML docs with Firefox you can run:

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:

poetry run make livehtml

To open the served docs with Firefox you can run:

firefox http://127.0.0.1:8000

Starting From Scratch

If something is wrong with your dependencies or you just want to re-start from a clean environment you need to remove the virtual environment. First of all ensure that poetry's virtual environment is placed within the project:

poetry config virtualenvs.in-project true

Afterwards the virtual environment including all installed dependencies can be deleted:

rm -rf .venv

docs's Issues

Suggest this be moved to the top of the page under a new TL;DR section

docs/src/22.4/container/index.md

Line 98 in ba8fcef

As a quick solution we provide all the commands above in a single script. This

Suggest this be shown first, before user deploys and finds this too late

docs/src/22.4/container/admin-user.md

Line 1 in ba8fcef

## Setting up an Admin User

End users should know this up front before following all the instructions to the end only to find the deployment is using a hard coded weak and known password, and not having the ability to change it in the now deployed instance and having to destroy and rebuild with the admin user instructions.

"docker compose" command doesn't work, "docker-compose" with a hyphen ("-") is required based on docker install method.

Expected behavior

Docker workflow commands in the documentation should work.

Actual behavior

The docker-compose commands in the documentation were all changed to docker compose recently.
The official tool for managing multi-container Docker applications is "docker-compose" with a hyphen ("-").

opsd-openvas install failed

The pip version installed by default on Debian 10 is 18.1, which will cause the installation of ospd-openvas to fail.

root@debian:~/source/ospd-openvas-21.4.4# python3 -m pip install . --prefix=$INSTALL_PREFIX --root=$INSTALL_DIR --no-warn-script-location
Processing /root/source/ospd-openvas-21.4.4
  Installing build dependencies ... done
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/usr/lib/python3.7/tokenize.py", line 447, in open
        buffer = _builtin_open(filename, 'rb')
    FileNotFoundError: [Errno 2] No such file or directory: '/tmp/pip-req-build-kweufads/setup.py'
    
    ----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-req-build-kweufads/

Should upgrade the pip before install.

python3 -m pip install pip --upgrade

404 on file docker-composer (latest)

docs/src/_static/setup-and-start-greenbone-community-edition.sh

Line 26 in f7aa955

curl -f -O https://greenbone.github.io/docs/latest/_static/docker-compose.yml

manual feed sync instructions incorrect for docker containers

Expected behavior

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

manual update of greenbone feeds

Actual behavior

manual update will fail since greenbone-nvt-sync and greenbone-feed-sync are nolonger part of the ospd-openvas and gvmd containers.

Fix update documentation to remove this reference. Alternatively update the documentation to explain what would be required to use the new greenbone-feed-sync python script running on the host.

How-to SSL for container gsa

Strictly speaking not a bug (unless you find non-secured communication to a security solution faulty ;-) but a proposal to enrich the docs.

There are quite some questions in the forum how to enable SSL with GSA. For the community docs, the answer is "when it's not documented, it's not there", "you need to build your own container".

Luckily, the gsa start script already accepts an environment variable. Here's my solution, working with the existing containers:

• bake the certificate, and place them in /etc/ssl/gsa/gsa.crt and /etc/ssl/gsa/gsa.key
• chown -r 1001 /etc/ssl/gsa
• modify docker-compose.yaml:

gsa:
    image: greenbone/gsa:${GSA_TAG}
    container_name: gsa
    environment:
      GSAD_ARGS: --ssl-private-key=/cert/gsa.key --ssl-certificate=/cert/gsa.crt
    ports:
      - 9392:443
    volumes:
      - gvmd_socket_vol:/run/gvmd
      - /etc/ssl/gsa:/cert:ro
    depends_on:
      - gvmd

docker-compose 1.29 required

The install documentation at https://greenbone.github.io/docs/latest/21.4/container/index.html#installing-docker-compose states that docker-compose 1.27 is required (which would be provided by bullseye-backports). This is actually not sufficient: since service_completed_successfully is used, the minimum required version is 1.29.

Web port bound to all interfaces, documentation should reflect this

docs/src/_static/docker-compose-22.4.yml

Line 92 in ba8fcef

- 9392:80

The web ui interface is bound to all interfaces but the documentation says

xdg-open "http://127.0.0.1:9392" 2>/dev/null >/dev/null &

This is misleading and makes the end user think that the service is only bound to loopback. Either the documentation should state to use the host name or reconfigure the deployment to bind the web ui port to loopback for security purposes.

Differences between dependencies for building and for operating recognizable

Expected behavior

That the Docs showing me, what I really need to build the binaries and what I really need to run the binary.

Actual behavior

Currently all are deps for build and run are mixed deps.

Typo error in some containers' description

Expected behavior

In docs/src/22.4/container/index.md , some containers' description should contain "Shows the license and exits afterwards."

Actual behavior

In docs/src/22.4/container/index.md , some containers' descriptions contain "Shows the license and exists afterwards."
This is saying the opposite of their actual behavior.

Steps to reproduce

Go to the containers documentation, to the "Description" paragraph. There are several descriptions concerned.

Remove MQTT port mapping in image: greenbone/mqtt-broker

docs/src/_static/docker-compose-22.4.yml

Line 140 in c48f9d0

- 1883:1883

see also: https://forum.greenbone.net/t/mqtt-without-authentication/13647/10

cause MQTT Broker Does Not Require Authentication triggering otherwise.

FeatureRequest: Kubernetes manifest

Hello, as there is a docker-compose.yml in your documentation, I am migrating it to a kubernets-manifest.

Are you interested in an PR for this docs?

As I am quite new to greenbone, I need some help about the connections needed between the containers/services.

E.g. docker-compose.yml is here quite implicit in many cases, but for kubernetes I have to configure the ports the containers want to connect each other. There are also some other concrete questions I will ask when there is somebody who wants to support here. Please comment if you would like to contribute. Thanks and kind regards!

mqtt server bound to all interfaces

docs/src/_static/docker-compose-22.4.yml

Line 140 in ba8fcef

- 1883:1883

The deployment results in the mqtt service binding to all interfaces, allowing network adversaries to access the service, when it should not be exposed outside the host.