Greenbone Security Assistant
The Greenbone Security Assistant is the web interface developed for the
Greenbone Enterprise appliances
written in React.
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
Prerequisites for GSA:
To install nodejs the following commands can be used
export VERSION=26
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 nodejs
Change into the gsa source directory and delete the possible existing build output
directory.
cd path/to/gsa
rm -rf build
Install 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 build
All 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.
Developing
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 start
Afterwards 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.
Linting
GSA uses Oxlint for JavaScript and
TypeScript linting. The normal lint command uses the committed
oxlint-baseline.json to acknowledge existing diagnostics while still failing
for new diagnostics:
npm run lint
To inspect all current diagnostics without baseline filtering, run:
npm run lint:raw
When a warning has been reviewed and intentionally accepted, update the
baseline explicitly:
npm run lint:baseline:update
Review changes to oxlint-baseline.json together with the code that caused
them. Do not update the baseline to hide new warnings without reviewing them.
During npm run start, TypeScript diagnostics are also reported in the
development browser overlay through the Vite checker plugin. The existing
npm run type-check command remains available for a complete command-line
type check.
Local Playwright E2E
The Playwright end-to-end tests run against a locally running container. Start
the container and make sure the GSA web application is available before running
the tests.
Install the Playwright browser once:
npx playwright install chromium
Run all end-to-end tests:
npm run test:e2e
Translations
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": ""
}
Updating
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.
Support a new Language
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
i18next-parser.config.js.
Settings
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.
Config File
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 = {
foo: 'bar',
};
It is evaluated in the Settings object implemented in the
settings.ts file. The Settings object is
instantiated once for the GSA application
Config Variables
vendorVersion
Allows to adjust the shown product version string at the Login and About pages.
vendorLabel
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.
vendorTitle
Allows to adjust the HTML title, i.e. the text shown in browser tabs which have GSA open.
guestUsername and guestPassword
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 notification about using the community feed. It is enabled by
default.
enableEPSS
Enables the display of EPSS scores and percentiles in CVEs and VTs. It is
enabled by default.
enableKrb5
Enable the ability to add Kerberos credentials.
enableStoreDebugLog
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.
logLevel
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.
timeout
This setting specifies as timeout after a data request to our API provided by
gsad will fail. Default is 5 minutes (300000 ms).
apiServer
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'.
apiProtocol
Defaults to window.location.protocol and must be either 'http' or 'https'.
manualUrl
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.
manualLanguageMapping
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.
protocolDocUrl
This setting contains the URL to the public Greenbone Management Protocol (GMP)
documentation. It is only used at the About page.
reloadInterval
The standard interval for reloading data. The default is 15 seconds
(15000 ms).
reloadIntervalActive
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).
reloadIntervalInactive
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).
reportResultsThreshold
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.
severityRating
Defines which Severity Rating should be used for the severity classes. Currently
the values CVSSv2 and CVSSv3 are allowed. CVSS version 3 introduces a new
Critical level from 9.0 to 10.0 which High level in CVSS version 2. The
severity classes are used for example in the charts.
Support
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.
Maintainer
This project is maintained by Greenbone AG.
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.
License
Copyright © 2009-2026 Greenbone AG
Licensed under the AGPL-3.0 GNU Affero General Public License v3.0 or later.
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)
评论