Greenbone Security Assistant HTTP server

The Greenbone Security Assistant HTTP Server is the server developed for the communication with the Greenbone Enterprise appliances.

It connects to the Greenbone Vulnerability Manager Daemon gvmd to provide a full-featured HTTP interface for vulnerability management.

• Releases
• Installation
  • Prerequisites
  • Compiling
  • Unit tests
• Logging Configuration
• Usage
• Settings
• Development
• Support
• Maintainer
• Contributing
  • Code style and formatting
  • CMake formatting
• License

Releases

All release files are signed with the Greenbone Community Feed integrity key. This gpg key can be downloaded at https://www.greenbone.net/GBCommunitySigningKey.asc and the fingerprint is 8AE4 BE42 9B60 A59B 311C 2E73 9823 FAA6 0ED1 E580.

Installation

If you are not familiar or comfortable building from source code, we recommend that you use the Greenbone Security Manager TRIAL (GSM TRIAL), a prepared virtual machine with a readily available setup. Information regarding the virtual machine is available at https://www.greenbone.net/en/testnow.

This module can be configured, built and installed with following commands:

cd path/to/gsad
mkdir build && cd build
cmake ..
make install

Please note: The reference system used by most of the developers is Debian GNU/Linux 'Buster' 10. The build might fail on any other system. Also, it is necessary to install dependent development packages.

Prerequisites

See at the end of this section how to easily install these prerequisites on some supported platforms.

Prerequisites:

• libgvm_base, libgvm_util >= 22.8.0
• libgvm_gmp >= 22.38.0
• gnutls >= 3.2.15
• libgcrypt
• cmake >= 3.18
• glib-2.0 >= 2.42
• libxml
• libmicrohttpd >= 0.9.0
• pkg-config
• gcc
• zlib >= 1.2
• libbrotli (optional, for Brotli compression)

Optional prerequisites

• Doxygen (for building documentation)
• xmltoman (for building man page)
• cgreen (for building tests)
• libasan (for building tests)

Install prerequisites on Debian GNU/Linux:

apt-get install libmicrohttpd-dev libxml2-dev zlib1g-dev

Compiling

If you have installed required libraries to a non-standard location, remember to set the PKG_CONFIG_PATH environment variable to the location of you pkg-config files before configuring:

export PKG_CONFIG_PATH=/your/location/lib/pkgconfig:$PKG_CONFIG_PATH

Create a build directory and change into it with:

mkdir build && cd build

Then configure the build with:

cmake -DCMAKE_INSTALL_PREFIX=/path/to/your/installation ..

Or (if you want to use the default installation path /usr/local):

cmake ..

This only needs to be done once.

Thereafter, the following commands are useful:

make                # build the scanner
make doc            # build the documentation
make doc-full       # build more developer-oriented documentation
make install        # install the build
make rebuild_cache  # rebuild the cmake cache

Please note that you may have to execute make install as root, especially if you have specified a prefix for which your user does not have full permissions.

To clean up the build environment, simply remove the contents of the build directory you created above.

In case you have installed the Greenbone Security Assistant Daemon into a path different from the other GVM modules, you might need to set some paths explicitly before running cmake. See the top-level CMakeLists.txt.

Unit tests

In order to build and run unit tests use the commands below:

cmake -DBUILD_TESTING=1 ..  # enable building unit tests
make tests                  # build the unit tests
make test                   # run the unit tests

Logging Configuration

By default, gsad writes logs to the file

<install-prefix>/var/log/gvm/gsad.log

Logging is configured entirely by the file

<install-prefix>/etc/gvm/gsad_log.conf

The configuration is divided into domains like this one

[gsad main]
prepend=%t %p
prepend_time_format=%Y-%m-%d %Hh%M.%S %Z
file=/var/log/gvm/gsad.log
level=debug

The level field controls the amount of logging that is written. The value of level can be:

error      4  Errors.
critical   8  Critical situation.
warning   16  Warnings.
message   32  Messages.
info      64  Information.
debug    128  Debug.  (Lots of output.)

Enabling any level includes all the levels above it. So enabling Information will include Warnings, Critical situations and Errors.

To get absolutely all logging, set the level to 128 for all domains in the configuration file.

Logging to syslog can be enabled in each domain like:

[gsad main]
prepend=%t %p
prepend_time_format=%Y-%m-%d %Hh%M.%S %Z
file=syslog
syslog_facility=daemon
level=debug

Usage

In case everything was installed using the defaults, then starting the HTTP daemon of the Greenbone Security Assistant can be done with this simple command:

gsad

The daemon will listen on port 443, making the web interface available in your network at https://<your host>.

If port 443 was not available or the user has no root privileges, gsad tries to serve at port 9392 as a fallback (https://<your host>:9392).

To see all available command line options of gsad, enter this command:

gsad --help

Settings

The following settings can be adjusted for the gsad service.

CLI	Env	Type	Default	Description
--drop-privileges	GSAD_DROP_PRIVILEGES	string	false	When starting as root drop priviledges to a different user
-f, --foreground	GSAD_FOREGROUND	boolean	false	Run gsad in the foreground and don't fork at startup
--http-only	GSAD_HTTP_ONLY	boolean	false	Serve HTTP only, without SSL. Implies --no-redirect.
--listen	GSAD_ADDRESS	string	0.0.0.0	IP Address to listen on
--port	GSAD_PORT	int	9392 for HTTP and 443 for HTTPS	Port to listen on
-r, --rport	GSAD_REDIRECT_PORT	int	9392	Redirect port to listen on
--no-redirect	GSAD_NO_REDIRECT	boolean	false	Don't redirect HTTP to HTTPS (implied when using --http-only).
--version, -V		boolean		Print version information
-k, --ssl-private-key	GSAD_TLS_PRIVATE_KEY	path	/var/lib/gvm/private/CA/serverkey.pem	Path to a TLS private key
-c, --ssl-certificate	GSAD_TLS_CERTIFICATE	path	/var/lib/gvm/CA/servercert.pem	Path to a TLS certificate
--dh-params	GSAD_DH_PARAMS	path		Path to a Diffie-Hellman parameters file
--do-chroot	GSAD_DO_CHROOT	boolean	false	Do chroot into the static content directory.
--secure-cookie	GSAD_SECURE_COOKIE	boolean	false	Use a secure cookie (implied when using HTTPS).
--timeout	GSAD_SESSION_TIMEOUT	int	15	Minutes of user idle time before session expires. Has to be between 0 (no timeout) and 40320 (4 weeks).
--client-watch-interval	GSAD_CLIENT_WATCH_INTERVAL	int	0	Interval in seconds to Check if client connection was closed. 0 disables the client watch interval
--debug-tls	GSAD_DEBUG_TLS	int	0	Level at which the TLS debugging is enabled. O to disable.
--gnutls-priorities	GSAD_GNUTLS_PRIORITIES	string		GnuTLS priorities string.
--http-frame-opts	GSAD_HTTP_FRAME_OPTS	string	SAMEORIGIN	X-Frame-Options HTTP header.
--http-csp	GSAD_HTTP_CSP	string		Content-Security-Policy HTTP header.
--http-sts	GSAD_HSTS_ENABLED	boolean	false	Enable HTTP Strict-Transport-Security header.
--http-sts-max-age	GSAD_HSTS_MAX_AGE	int	31536000	max-age in seconds for HTTP Strict-Transport-Security header.
--ignore-x-real-ip	GSAD_IGNORE_X_REAL_IP	boolean	false	Do not use X-Real-IP to determine the client address.
--per-ip-connection-limit	GSAD_PER_IP_CONNECTION_LIMIT	int	30	Sets the maximum number of connections per ip. Use 0 for unlimited.
--unix-socket	GSAD_UNIX_SOCKET	Path		Path to unix socket to listen on. Set to listen on a unix socket.
--unix-socket-owner	GSAD_UNIX_SOCKET_OWNER	string		Owner of the unix socket
--unix-socket-group	GSAD_UNIX_SOCKET_GROUP	string		Group of the unix socket
--unix-socket-mode	GSAD_UNIX_SOCKET_MODE	string		File mode of the unix socket
--munix-socket	GSAD_MANAGER_UNIX_SOCKET	path	/run/gvmd/gvmd.sock	Path to the unix socket of gvmd
--http-coep	GSAD_HTTP_COEP	string		Set Cross-Origin-Embedder-Policy (COEP) http header
--http-coop	GSAD_HTTP_COOP	string		Set Cross-Origin-Resource-Policy (COOP) http header
--http-corp	GSAD_HTTP_CORP	string		Set Cross-Origin-Resource-Policy (CORP) http header
--http-cors	GSAD_HTTP_CORS	string		Set Cross-Origin Resource Sharing (CORS) allow origin http header
--user-session-limit	GSAD_USER_SESSION_LIMIT	int	0	Set maximum number of active sessions per user. 0 for unlimited.
--log-config	GSAD_LOG_CONFIG	path	/etc/gvm/gsad_log.conf	Path to logging configuration file.
--pid-file	GSAD_PID_FILE	path	/run/gsad/gsad.pid	Path to PID file.
--static-content	GSAD_STATIC_CONTENT	path	/usr/local/share/gvm/gsad/web	Path to static content directory.
--api-only	GSAD_API_ONLY	boolean	false	Run in API-only mode, disabling serving of static content.
--jwt-requested	GSAD_JWT_REQUESTED	boolean	false	Enable JWT-based mode using the token returned in the login response.

Development

For development a Devcontainers setup can be used. Devcontainers are currently supported by Visual Studio Code and IntelliJ IDEA. The provided Devcontainers setup comes with all required dependencies for building gsad out of the box.

Support

For any question on the usage of gsad please use the Greenbone Community Portal. If you found a problem with the software, please create an issue on GitHub. If you are a Greenbone customer you may alternatively or additionally forward your issue to the Greenbone Support Portal.

Maintainer

This project is maintained by Greenbone Networks GmbH.

Contributing

Your contributions are highly appreciated. Please create a pull request on GitHub. Bigger changes need to be discussed with the development team via the issues section at github first.

Code style and formatting

Before creating a pull request, it is recommended to run the following command:

make format

This reformats the new code to ensure that it follows the code style and formatting guidelines.

CMake formatting

All CMake files are formatted using gersemi. To install gersemi on a Debian based system the following commands can be used:

sudo apt install pipx
pipx install gersemi

To format all CMake files run the command:

gersemi -i cmake .

License

Copyright (C) 2009-2026 Greenbone AG

Licensed under the GNU Affero General Public License v3.0 or later.