The Greenbone Security Assistant is the web interface developed for the Greenbone Enterprise appliances written in React.
- Releases
- Installation
- Developing
- Translations
- Settings
- Support
- Maintainer
- Contributing
- License
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.
Prerequisites for GSA:
- node.js >= 18.0
To install nodejs the following commands can be used
export VERSION=18
export KEYRING=/usr/share/keyrings/nodesource.gpg
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource.gpg.key | gpg --dearmor | sudo tee "$KEYRING" >/dev/null
gpg --no-default-keyring --keyring "$KEYRING" --list-keys
echo "deb [signed-by=$KEYRING] https://deb.nodesource.com/node_$VERSION.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
echo "deb-src [signed-by=$KEYRING] https://deb.nodesource.com/node_$VERSION.x nodistro main" | sudo tee -a /etc/apt/sources.list.d/nodesource.list
sudo apt update && sudo apt install nodejsChange into the gsa source directory and delete the possible existing build output directory.
cd path/to/gsa
rm -rf buildInstall the JavaScript dependencies and start the build process. The build process
creates a build directory with a production build of GSA. The build/img directory
will contain images like logos and banners. The build/static directory will contain
generated JavaScript and CSS files and additionally in the build/static/media
directory SVG files for all icons will be found.
npm install
npm run buildAll content of the production build can be shipped with every web server. For
providing GSA via our gsad web server, the
files need to be copied into the share/gvm/gsad/web/ subdirectory of your
chosen CMAKE_INSTALL_PREFIX directory when building gsad. Normally this is
set to /usr or /usr/local.
mkdir -p $INSTALL_PREFIX/share/gvm/gsad/web/
cp -r build/* $INSTALL_PREFIX/share/gvm/gsad/web/If you are not familiar or comfortable building from source code, we recommend that you use the Greenbone Enterprise TRIAL, a prepared virtual machine with a readily available setup. Information regarding the virtual machine is available at https://www.greenbone.net/en/testnow.
Using GSA requires to re-build the JavaScript bundle. This process is very time-consuming and therefore may be avoided during development. It is possible to run GSA in a special web development server. The development server can be started with:
cd path/to/gsa && npm run startAfterwards the development web server is set up and a new browser window is
opened at the URL http://127.0.0.1:8080, containing the GSA web application.
When a JavaScript file of GSA in the src folder is changed, the browser window
will reload automatically.
Besides the development server gsad needs to be running with CORS enabled.
gsad --http-cors="http://127.0.0.1:8080"To be able to communicate with gsad, the web application needs to know the
server URL. This can be accomplished by editing the path/to/gsa/public/config.js
file. The following lines can be used for a local gsad running
with HTTP on port 9392:
config = {
apiProtocol: 'http',
apiServer: '127.0.0.1:9392',
};For HTTPS only the protocol property must be 'https' accordingly.
After changing the config.js file, the browser window should be reloaded
manually.
For translations and internationalization i18next is used.
With our configuration of i18next the translations are stored in language specific JSON files. The existing translations can be found at the public/locales/ directory.
The translations are stored in the JSON files as key-value pairs with the key
being the English string and the value the translation of the specific language.
Not translated strings have an empty string “” as the value.
Example with German translations:
{
"Create a new Tag": "Einen neuen Tag erstellen",
"Create a new Target": "Ein neues Ziel erstellen",
"Create a new Task": ""
}To change or extend translations new values can be added to the specific JSON file, committed to git and finally uploaded through a pull request to GitHub.
But sometimes the UI changes and new English descriptions are added or existing ones have been rephrased. In this case the new keys must be extracted from the source code and added to the JSON files. This can be done by running
npm run i18n-extract
New translation strings are added with an empty string “” as default value.
Therefore searching for empty strings will find the to be translated values.
Keys with a _plural suffix can be ignored. They are just added for technical
reasons and are unused.
If not all strings are translated at once the remaining empty strings would cause missing text in web UI. Therefore, the JSON files must be cleaned up before adding the changes to git and creating a pull request. To clean up the JSON files the following command can be used
npm run clean-up-translations
The currently supported languages are listed at src/gmp/locale/languages.js. If a new language should be available in the web UI, it needs an entry in this object. Additionally the corresponding language codes must be added to the babel config and cleanup script.
The behavior of GSA can be changed via settings. All of the settings can be adjusted via a config file. Some of the settings can be changed during runtime too. Some of them are persistent during reload, some are reset during reload.
This sections lists all settings and explains their behavior.
The config file is a normal JavaScript file (with a .js suffix). It is named
config.js and will be loaded from the /usr/share/gvm/gsad/web/ (or
/usr/local/share/gvm/gsad/web/) directory when using gsad for providing GSA
e.g. in production environments.
During development when using the on-the-fly-transpiling JavaScript development
server (via npm run start) the file is loaded from the public/ directory.
The config.js file must contain a global config object with settings as
properties e.g.
config = {
// javascript files in contrast to JSON files allow comments
foo: 'bar',
}It is evaluated in the GmpSettings object implemented in the
gmpsettings.js file. The GmpSettings object is
instantiated once for the GSA application
| Name | Type | Default | Changeable during runtime | Persistent after reload |
|---|---|---|---|---|
| apiProtocol | String ('http' or 'https') | global.location.protocol |
- | x |
| apiServer | String | global.location.host |
- | x |
| enableGreenboneSensor | Boolean | false | - | x |
| disableLoginForm | Boolean | false | - | x |
| enableEPSS | Boolean | false | x | x |
| enableStoreDebugLog | Boolean | false | x | x |
| guestUsername | String | undefined | - | x |
| guestPassword | String | undefined | - | x |
| locale | String | undefined | x | x |
| logLevel | String | 'warn' |
x | x |
| manualUrl | String | https://docs.greenbone.net/GSM-Manual/gos-22.04/ | - | x |
| manualLanguageMapping | Object | undefined | - | x |
| protocolDocUrl | String | https://docs.greenbone.net/API/GMP/gmp-22.4.html | - | x |
| reloadInterval | Integer | 15 * 1000; // fifteen seconds | x | - |
| reloadIntervalActive | Integer | 3 * 1000; // three seconds | x | - |
| reloadIntervalInactive | Integer | 60 * 1000; // one minute | x | - |
| reportResultsThreshold | Integer | 25000 | x | - |
| timeout | Integer | 300000; // 5 minutes | x | - |
| vendorVersion | String | undefined | - | x |
| vendorLabel | String | undefined | - | x |
Allows to adjust the shown product version string at the Login and About pages.
Allows to adjust the product info image at the Login page. It must be a relative
path e.g. foo.png. The path will be mapped to $INSTALL_PREFIX/share/gvm/gsad/web/img/
on production (with gsad) and gsa/public/img for the development server.
Both settings allow to login with a single click. This user has to be set up
carefully. E.g. if this user is created with admin privileges it will have these
permissions after login. Thus be careful when creating a guest user. If
guestUsername is contained in the config.js file the Login as Guest button
will be shown.
This setting allows to deactivate the username password form at the Login page. It can be used to deactivate login for normal users.
Enables the display of EPSS scores and percentiles in CVEs and NVTs.
The data required for this is not available in the feed yet, so this is disabled by default.
Changes to this settings are persistent during browser reload. If the value has
been changed in the browser console e.g. via gmp.settings.enableStoreDebugLog = true
the browser window needs to be reloaded to apply this setting. The setting can
be true, false or undefined.
If either enableStoreDebugLog is true or it is undefined and logLevel
is debug the changes of the redux store are shown. The store contains all data
visible to the user.
The value of logLevel is persistent during browser reload. If the value has been
changed e.g. by running gmp.settings.logLevel = 'debug' in the browser console
the browser window needs to be reloaded to apply this setting. Also this setting
must be reset via gmp.settings.logLevel = undefined to not display the debug
logs anymore and to use the default setting again. If logLevel is set to
'debug' and enableStoreDebugLog is not false the
store debug logs are shown too.
This setting specifies as timeout after a data request to our API provided by gsad will fail. Default is 5 minutes (300000 ms).
Defaults to window.location.host. It contains the domain/IP address of the
gsad server including the port e.g. '192.168.10.123:9392'.
Defaults to window.location.protocol and must be either 'http' or 'https'.
URL to the manual. On a Greenbone Enterprise Appliance the manuals are served
locally and the value is the relative URL '/manual'. The URL is used for all
links from help icons pointing to a page at the user manual.
Because we could possibly have a different number of translated manuals then
available locales, a setting for mapping a locale to a corresponding translated
manual is provided. If a current locale isn't mapped it always falls back to the
English (en) locale.
This setting contains the URL to the public Greenbone Management Protocol (GMP) documentation. It is https://docs.greenbone.net/API/GMP/gmp-22.4.html and only used at the About page.
The standard interval for reloading data. The default is 15 seconds (15000 ms).
This interval is used for reloading data on pages with an active process. This is currently the case for a task list page, task details page, report list page and report details page containing at least one actively scanning task. The default is 3 seconds (3000 ms).
This interval is used instead of reloadInterval or reloadIntervalActive for reloading data when GSA is not the active browser window or tab. The default is 60 seconds (60000 ms).
If the number of filtered results of a shown report extends this threshold only the report without details is loaded and an information panel is show at the Hosts, Ports, Applications, Operating Systems, CVEs, Close CVEs and TLS Certificates tabs to prompt the user for lowering the number of results by additional filtering. This setting can be used to improve the responsiveness of the report details page.
For any question on the usage of gsa 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.
This project is maintained by Greenbone AG.
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.
Copyright (C) 2009-2023 Greenbone AG
Licensed under the AGPL-3.0 GNU Affero General Public License v3.0 or later.