Skip to main content

Automation, Sensors & Integrations

What this covers

The advanced operations layer of the Greenbone Enterprise Appliance: driving the appliance programmatically over the Greenbone Management Protocol (GMP) with gvm-tools, distributing scans across a master-sensor setup and using sensors as remote scanners, monitoring and tuning scan performance plus the scan queue, and connecting the appliance to external systems - verinice, Nagios, Cisco Firepower Management Center, Alemba vFire and Splunk.

Source scope

Based on the Greenbone Enterprise Appliance manual (GOS 22.04 / OPENVAS SCAN 22.04), chapters 15-18, verified June 2026. GMP automation applies to the free Community Edition too; the master-sensor setup and the listed integrations are appliance-oriented. Not every appliance model supports every menu option - check the model tables in manual chapter 3 if a feature is missing.

1. GMP Automation​

The full vulnerability management functionality of the appliance is also available over the Greenbone Management Protocol (GMP). The web interface itself uses GMP locally. Greenbone ships the Greenbone Vulnerability Management Tools (gvm-tools) to access this functionality (§15). The newest version of GMP is documented at the Greenbone API site.

1.1 Changes to GMP​

GMP is updated regularly to track the underlying service and to keep a consistent, comprehensive interface. Each update produces a new GMP version with a published list of added, modified and removed protocol elements such as commands or attributes (§15.1). Depending on the change, the old version may stay available for a transitional period during which both versions run side by side. The change list helps you prepare early, but it does not represent the complete set of upcoming changes.

1.2 Activating GMP​

GMP must be activated before it can be used. The web interface uses GMP locally, but the remote GMP service is not reachable over the network by default. Activate the remote service in the GOS administration menu (§15.2, GOS menu §7.2.4.2).

Access to GMP is authenticated and encrypted with SSL/TLS. GMP uses the same user accounts as the web interface, with the same restrictions and permissions.

1.3 Using gvm-tools​

gvm-tools is a collection of tools that expose GMP. Scripts executed with gvm-script use the API provided by the python-gvm library, which is installed automatically with gvm-tools (§15.3). The tools ship as a command line interface and a Python shell, for Microsoft Windows and any OS that supports Python (including Linux). Python 3.5 or later is required.

Note that gvm-tools, python-gvm and GOS use different version schemes, so their version numbers are not necessarily the same - use the latest versions of gvm-tools and python-gvm. For Windows, statically linked EXE builds (gvm-cli.exe, gvm-pyshell.exe) are available directly from Greenbone and do not require Python. Links to the Greenbone download site are case-sensitive.

GMP is XML based: every command and every response is a GMP object. gvm-cli supports SSH, TLS and Unix Domain Socket connections. All current appliances use SSH to encrypt GMP - TLS is deprecated, not officially supported, and may be removed in a future version. The tools are most useful for batch processing and scripting.

A few minimal gvm-cli invocations:

gvm-cli --xml "<get_version/>"
gvm-cli --xml "<get_tasks/>"
gvm-cli < file

1.3.1 Configuring the client​

Using gvm-cli requires logging into the appliance. The login can be supplied either with command line switches (--gmp-username, --gmp-password) or with a configuration file at ~/.config/gvm-tools.conf (§15.3.1.1). The configuration file is not read by default - the --config (-c) switch must be added to read it.

[Auth]
gmp_username=webadmin
gmp_password=kennwort

1.3.2 Starting a scan with gvm-cli​

A typical use case is the automatic scan of a newly discovered host - for example, an Intrusion Detection System in a DMZ that triggers a scan when it spots a new system or an unusual open TCP port (§15.3.1.2). Starting from the IP address of the suspect host, the workflow is: create a target, create a task, start the task, monitor it, then download the report.

Create the target (the response returns the new target ID):

gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
  --hostname 192.168.222.115 \
  --xml "<create_target><name>Suspect Host</name><hosts>$IPADDRESS</hosts></create_target>"

Create the task referencing the target ID and a scan config ID (the response returns the task ID, which is needed to start and monitor it):

gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
  --hostname 192.168.222.115 \
  --xml "<create_task><name>Scan Suspect Host</name> \
  <target id=\"4574473f-a5d0-494c-be6f-3205be487793\"></target> \
  <config id=\"daba56c8-73ec-11df-a475-002264764cea\"></config></create_task>"

The IDs of existing targets and scan configs can be retrieved with <get_targets/> and <get_configs/> (the output is XML). Start and monitor the task with its ID:

gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
  --hostname 192.168.222.115 \
  --xml '<start_task task_id="ce225181-c836-4ec1-b83f-a6fcba70e17d"/>'

gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
  --hostname 192.168.222.115 \
  --xml '<get_tasks task_id="ce225181-c836-4ec1-b83f-a6fcba70e17d"/>'

The appliance closes the connection once the task starts; the task keeps running. When the scan is done, list report-format IDs with <get_report_formats/> and download the report with <get_reports report_id="..." format_id="..."/>. To fully automate processing, combine the task with an alert that forwards the report when a given condition is met.

1.3.3 Starting a scan with gvm-pyshell​

gvm-pyshell sends and receives the same XML commands and responses using Python commands - the tool generates and parses the XML for you, which makes processing the output easier than in the shell (§15.3.2). It supports TLS, SSH and Socket connections; the authentication file format is the same as for gvm-cli. The Python implementation follows the GMP API, where optional arguments are marked with a ?.

gvm-pyshell --gmp-username webadmin --gmp-password kennwort ssh --hostname 192.168.222.115

Inside the interactive console, mandatory arguments can be passed positionally or by identifier:

res = gmp.create_target("Suspect Host", make_unique=True, hosts=['192.168.255.254'])
target_id = res.xpath('@id')[0]

res = gmp.create_task(name="Scan Suspect Host",
                      config_id="daba56c8-73ec-11df-a475-002264764cea",
                      scanner_id="08b69003-5fc2-4037-a479-93b440211c73",
                      target_id=target_id)
task_id = res.xpath('@id')[0]
gmp.start_task(task_id)

Task creation needs a target_id, config_id, scanner_id, task name and task comment. Existing scan configs and scanners can be enumerated with gmp.get_configs(); if only the built-in scanners are used, their IDs are fixed:

  • OpenVAS scanner: 08b69003-5fc2-4037-a479-93b440211c73
  • CVE scanner: 6acd0832-df90-11e4-b9d5-28d24461215b

1.3.4 Example scripts​

gvm-tools ships a collection of example scripts that run with gvm-script (§15.3.3). They are a good starting point for custom scripts. The set for gvm-tools 2.0.0 includes, among others:

ScriptPurpose
application-detection.gmp.pyDisplay all hosts running the searched application.
cfg-gen-for-certs.gmp.pyCreate a scan config from VTs based on a given CERT-Bund advisory.
clean-sensor.gmp.pyRemove all resources from a sensor except active tasks.
nvt-scan.gmp.pyCreate a task for a specific host and VT from a hardcoded base config.
startNVTScan.gmp.pyCreate a task for a specific host and VT interactively.
SyncAssets.gmp.pyUpload assets to the asset database.
SyncReports.gmp.pyPull reports and upload them to a second appliance via container tasks.
monthly-report.gmp.py / monthly-report2.gmp.pyList all vulnerabilities from the reports of a given month (GOS 3.1 / 4.x).

1.3.5 Status codes​

GMP uses status codes modelled on HTTP status codes (§15.4):

CodeMeaning
200OK
201Resource created
202Request submitted
400Syntax error - missing or wrong elements/attributes; also currently used for missing or wrong authentication
401Authenticate first (missing or wrong authentication; 400 is still used in practice)
403Access to resource forbidden - insufficient permissions (often shown as 400 Permission denied)
404Resource missing - the resource ID was empty or wrong
409Resource busy - e.g. a feed synchronization started while one is already running
500Internal error - e.g. entries that exceed an internal buffer size
503Scanner loading NVTs / service temporarily down (often expired certificates) / service unavailable (GMP command blocked)

2. Master-Sensor Setup​

For security reasons some network segments cannot be scanned directly. The appliance supports a distributed scan system where two or more appliances in different network segments are securely connected (§16). One appliance (the master) controls one or more others (sensors).

  • All appliance models from Greenbone Enterprise 400/DECA can act as a master.
  • All models except Greenbone Enterprise ONE can act as a sensor; the Greenbone Enterprise 35 and 25V can only be sensors and are always controlled by a master.
  • A sensor needs network connectivity only to the master and to the scan targets, stores no information permanently (except VTs), and needs no further administration after the initial setup.
  • The master can manage sensors directly, including automatic or manual feed updates and GOS upgrades.

The master-sensor link is set up over SSH (port 22/TCP). It is important to distinguish two features (§16):

  • Sensors - the master-sensor link configured in the GOS administration menu of both appliances. It supports remote feed synchronization and upgrade management of the sensor.
  • Remote scanners - configured in the web interface on the master. This is what enables scans to be executed via the sensor. A remote scanner connection uses the Open Scanner Protocol (OSP) over SSH.

The master and sensor are paired by exchanging a public key and verifying its fingerprint (§16.1). In outline:

  1. On the master: Setup > Master > Master Identifier > Download, then open the displayed URL and download the PUB file. Do not confirm the fingerprint yet.
  2. On the sensor: Setup > Sensor > Configure Master > Upload, open the displayed URL, browse to the PUB file and upload it.
  3. Compare the fingerprints shown on both appliances. If they match, confirm on both, then Save on the sensor.
  4. On the sensor, enable SSH (Services > SSH > SSH State) and enable OSP (Services > OSP), saving each change.
  5. On the master: Setup > Master > Sensors > Add a new sensor, enter the sensor IP or host name, then select Auto so the master retrieves the sensor identifier.
  6. Verify the sensor identifier fingerprint against Setup > Sensor > Sensor Identifier > Fingerprint on the sensor, Save, then run Test.

Once configured successfully, sensors can be managed directly on the master in the GOS administration menu (GOS menus §7.3.5 and §7.3.7).

2.2 Managing configured sensors​

Setup > Master > Sensors on the master lists actions for all configured sensors (§16.2): test all sensor connections, update all sensor protocols, add a new sensor, and Edit/Delete the sensor... for a specific one. Per-sensor settings include the sensor address, remote port, proxy, sensor identifier, enabling or disabling automatic feed updates when the master's feed is updated, setting the port and identifier automatically, testing the configuration, and deleting the sensor.

2.3 Deploying sensors in secure networks​

Because the master holds all vulnerability information and credentials while a sensor stores nothing permanently (except VTs), the master belongs in the highest security zone and all communication is initiated from the master down to the sensor (§16.3). A firewall separating the zones only needs to allow connections from the master to the sensor - no connections into the higher security zone are required.

Master and sensor communicate over SSH on port 22/TCP by default; for backward compatibility, port 9390/TCP can be enabled on the sensor (Setup > Sensor > Port 9390 > Save). Sensor feed updates and GOS upgrades can come either directly from the Greenbone servers or via the master; routing them through the master means only the master contacts Greenbone. To stop a sensor from contacting Greenbone, disable automatic synchronization (Setup > Feed > Synchronisation > Save). As an extra layer, source and destination NAT rules on a firewall with stateful packet inspection can avoid the need for default routes on the appliances.

2.4 Configuring a sensor as a remote scanner​

The master-sensor link (section 2.1) must be complete first. A sensor can then be used as a remote scanning engine alongside the default OpenVAS and CVE scanners, configured in the master web interface (§16.4):

  1. Log into the master web interface and select Configuration > Scanners.
  2. Create a new scanner and enter its Name.
  3. In the Type drop-down, select Greenbone Sensor. It is mandatory to choose Greenbone Sensor; OSP Scanner must not be used.
  4. Enter the sensor IP or host name in Host and Save.
  5. In the row of the new scanner, verify it. A correct setup verifies successfully.

Scanners are configured per user; create them per user, or grant usage rights via permissions (§9.4).

2.5 Using a remote scanner​

Once a sensor is configured as a remote scanner, it can be selected as the scanner when creating a new scan task or audit (§16.5; see also Scanning a System and the audit chapters). For an existing task or audit, there are two options: if it is marked as alterable, change its scanner directly; otherwise clone the task/audit and change the scanner on the clone.

3. Performance​

Operating the appliance moves significant data between the appliance, scan targets and any sensors, and the results still have to be analyzed, filtered and processed - often many processes concurrently, depending on model, user count and task configuration (§17).

3.1 Monitoring appliance performance​

Administration > Performance shows resource utilization for the last hour, day, week, month or year (§17.1). The performance of a configured sensor can also be displayed on the master. Key sections to read:

SectionWhat to watch for
ProcessesA high count is not critical; mostly sleeping and running processes should be shown.
System LoadOngoing high utilization is critical. A load of 4 on a 4-core system is acceptable.
CPU UsageA high Wait-IO is especially critical.
Memory UsageThe appliance caches aggressively; most memory used as cache is acceptable.
Swap UsageSwap use points to a potential system overload.

3.2 Optimizing scan performance​

Scan speed depends mainly on three levers (§17.2):

LeverEffect
Port list (§17.2.1)The port list configured on a target drives the duration of both the alive test and the vulnerability scan. There are 65535 TCP and 65535 UDP ports per system; TCP scans are usually fast, UDP slower because responses are not necessarily confirmed. Predefined lists range from All IANA assigned TCP (usually a few minutes) up to All TCP and combinations with Nmap top UDP ports. Services on ports not in the list are not tested. Scanning all TCP and UDP ports can take 24 hours or more per host under throttling. Additional port lists can be created (§10.7).
Scan configuration (§17.2.2)Four configs exist: Full and fast, Full and fast ultimate, Full and very deep, Full and very deep ultimate. The two fast configs reuse information found earlier and run only useful VTs, reducing duration; the two very deep configs ignore earlier findings and run all available VTs without exception.
Scanning order of targets (§17.2.3)The progress bar is a rough estimate. With sequential default order, large empty IP ranges make progress jump to ~95% quickly, then crawl from 95% to 100% over the few live hosts. Setting Order for target hosts to Random when creating the task improves the progress estimate.

3.3 Scan queuing​

When a task or audit is started, it is added to a waiting queue with status Queued; the scanner begins only when sufficient system resources are free, and queued scans start at 1-minute intervals to avoid overloading the system (§17.3). The most relevant resource is RAM - each scan needs a minimum amount because one scan process cannot handle multiple scans, and RAM cannot be shared satisfactorily. CPU, network and disk I/O matter too but can be shared at the cost of slower execution; the performance charts show RAM over time (section 3.1).

Tasks stay queued when too many scans run at once and RAM is short, or while the appliance is loading new VTs during a feed update or just after startup. When RAM frees up or VT loading finishes, queued scans start on a first-in, first-out basis. Workload management is handled by the scanner; in a master-sensor setup each sensor manages its own resources, and sensor scans affect the master's scanning capacity only minimally.

4. Integrations​

The appliance can connect to other systems through several interfaces (§18): GMP for full remote control, configurable report formats, alerts (Syslog, e-mail, SNMP trap, HTTP), Greenbone-built result-forwarding connectors, and SNMP monitoring via the published MIB file. Several systems are integrated directly:

SystemPurpose
verinice (§18.1)Free open-source ISMS by SerNet. The appliance feeds scan data into verinice to drive the vulnerability remediation workflow, risk analysis (ISO 27005), and ISMS operation (ISO 27001).
Nagios (§18.2)Monitoring system that integrates scan results as an additional test and matches scanned systems against monitored ones, making results available to Nagios alert rules.
Cisco Firepower Management Center (§18.3)NIDS/IPS whose asset database is augmented with appliance data for better attack identification; it can also trigger scans on suspect high-risk systems.
Alemba vFire (§18.4)Enterprise Service Management application; the appliance creates tickets ("calls") in vFire based on events such as finished scans.
Splunk (§18.5)Forwards scan results to a Splunk Enterprise on-premise installation for further analysis and correlation.

4.1 verinice​

Greenbone provides two report formats via the Greenbone Enterprise Feed - Verinice ISM and Verinice ISM all results - to export appliance data into verinice (§18.1). With Verinice ISM, only results that carry a note are transferred (plus the assets and the full vulnerability report); with Verinice ISM all results, all results are transferred without needing notes. Exporting produces a VNA file (a ZIP of the scan data) that is imported into verinice's Information Security Management perspective. Data can also be transferred fully automatically to verinice.PRO, the server extension. After import, the remediation workflow runs through verinice tasks (for example Remediate Vulnerabilities) assigned to a responsible person; for connector support, contact SerNet or Greenbone Enterprise Support.

4.2 Nagios​

When linked, Nagios takes the controlling role and regularly retrieves the newest scan results from the appliance using gvm-script to call the check-gmp.gmp.py script (§18.2). Compatible products such as Open Monitoring Distribution, Icinga or Centreon should generally work with small adjustments. High-level setup:

  • Configure an appliance user for Nagios that owns the relevant scan targets (or has unrestricted read access) and run those tasks as scheduled scans. GMP access must be activated (section 1.2).
  • Copy the check-gmp.gmp.py plug-in into the Nagios libexec/ directory and verify connectivity:
gvm-script --gmp-username="user name" --gmp-password="password" \
  ssh --hostname 192.168.10.169 /.../libexec/check-gmp.gmp.py --ping
  • Define the monitored host, a service that calls the check_gmp_status command, and the command itself (which passes the task name as an argument) in the Nagios configuration, then restart the Nagios service.

The plug-in supports caching: new reports are cached in a SQLite database (default /tmp/check_gmp/reports.db, overridable with --cache), so subsequent calls only fetch a report from the appliance if the scan end time changed (§18.2.3). It can also cap simultaneous instances (MAX_RUNNING_INSTANCES, default 10, overridable with -I) to limit load.

4.3 Cisco Firepower Management Center​

The Firepower Management Center (formerly Sourcefire IPS) augments its own asset database with appliance data and can trigger scans on suspect systems (§18.3). Two connection methods are available: automatic data transfer from the appliance to the NIDS/IPS as an alert after a scan completes (a weekly scheduled scan yields a fully automated alerting and optimization loop), and active control of the appliance by the NIDS/IPS to check a high-risk system. The receiving option must be enabled in the Firepower Management Center.

High-level setup: create a Host Input Client in the Firepower Management Center (System > Integration > Host Input Client) with the appliance IP as host name and a password; saving generates a TLS-encrypted PKCS#12 client certificate and key bound to that IP. On the appliance, create an alert (Configuration > Alerts) using the Sourcefire Connector method, supplying the Management Center IP and port, the PKCS#12 file, and - if the file is password-protected - a PKCS12 credential.

4.4 Alemba vFire​

The appliance can create tickets ("calls") in a vFire instance on events such as finished scans (§18.4). Prerequisites on the vFire side: vFire 9.7 or later with the RESTful Alemba API enabled (the legacy API is not supported), an Alemba API client with the correct session type and password login enabled, and a user account permitted to use the Alemba API. The integration is an alert (Configuration > Alerts) with the Alemba vFire method. Configurable details include report formats for attachments, the base URL of the Alemba instance, login credential, session type (analyst or user), Alemba client ID, partition, call description template, call template, call type, impact and urgency.

4.5 Splunk​

Connecting to Splunk is an add-on rather than core functionality: Greenbone provides a Greenbone-Splunk app for Splunk Enterprise on-premise (§18.5). Splunk Light and Splunk Cloud are not supported. The links to the Greenbone download page are case-sensitive. High-level setup:

  • Install the app in Splunk Enterprise from the downloaded TAR file. It sets up a TCP data input on port 7680 by default, tags incoming data as Greenbone Scan Results, and places it in the default index; field-name aliases can be edited for readability.
  • On the appliance, create an alert (Configuration > Alerts) using the Send to host method, pointing at the Splunk server IP on port 7680 with the XML report format, then add the alert to a task (or trigger it on an existing report to test).

In Splunk, the Greenbone Dashboard shows results from reports less than 7 days old (older reports still land in the main index), and the Search view can query indexed fields such as host, VulnerabilityResultNvtCVE, VulnerabilityResultSeverity and VulnerabilityResultThreat. Custom dashboards (for example top 5 affected hosts and incoming reports) can be built from these fields.