14 Using the Greenbone Management Protocol¶

The vulnerability management functionality of OPENVAS SCAN is also available via the Greenbone Management Protocol (GMP). GMP is a XML-based human-readable, stateless request-response protocol.

Greenbone provides the Greenbone Vulnerability Management Tools (gvm-tools) to access the functionality made available by GMP (see Chapter 14.3).

The newest version of GMP is documented at https://docs.greenbone.net/API/GMP/gmp-22.7.html.

14.1 Changes to GMP¶

GMP is regularly updated to apply changes in the functionality provided by the underlying service and to provide a consistent and comprehensive interface.

Updates result in a new version of GMP. Each new version includes a list of added, modified and removed protocol elements, for example commands or attributes. The most recent version of the list is available at https://docs.greenbone.net/API/GMP/gmp-22.7.html#changes.

Depending on the changes, the old version may be available for some time. During this transitional phase, the new and the old version are available at the same time.

This list helps to prepare for upcoming changes as soon as possible. It does not represent the complete list of upcoming changes.

14.2 Activating GMP¶

Before GMP can be used, it must be activated on the appliance.

While the web interface uses GMP locally on the appliance, GMP is not remotely accessible via the network by default.

The remote GMP service can be activated using the GOS administration menu (see Chapter 6.2.4.2).

In general, access to GMP is authenticated and encrypted with SSL/TLS. The same users as for the web interface are used. The users are subject to the same restrictions and have the same permissions.

14.3 Using gvm-tools¶

The Greenbone Vulnerability Management Tools (gvm-tools) are a collection of tools that provide access to the functionalities of the Greenbone Management Protocol (GMP). GMP scripts executed with gvm-script use the API provided by the library python-gvm.

Note

python-gvm is automatically installed when installing gvm-tools.

gvm-tools are available as a command line interface (CLI) and as a Python shell for any operating system that supports Python.

The following versions are required to use gvm-tools with GOS 24.10:

gvm-tools: 25.1.1 or higher
python-gvm: 26.0.0 or higher

Note

Both gvm-tools and python-gvm use a different version scheme than GOS, so the versions of gvm-tools, python-gvm and GOS are not necessarily the same.

It is recommended to use the latest versions of gvm-tools and python-gvm.

gvm-tools can be downloaded at the project’s official GitHub repository. Python 3.9 or later is required. To install gvm-tools, follow the instructions provided at https://greenbone.github.io/gvm-tools/.

Important

External links to the Greenbone download website are case-sensitive.

Note that upper cases, lower cases and special characters have to be entered exactly as they are written in the footnotes.

Note

gvm-tools are licensed under the GNU General Public License v3.0 and may be adapted and built for other uses cases, based on the source code.

gvm-tools are helpful for processing either large amounts or specific subsets of data provided by OPENVAS SCAN products (batch processing, scripting).

14.3.1 Using `gvm-cli`¶

The command line tool gvm-cli supplied by Greenbone offers easy access to the broad functionality provided by the XML-based GMP commands documented under https://docs.greenbone.net/API/GMP/gmp-22.7.html. Optional arguments in the API are identified by ?.

gvm-cli supports several command line switches which can be displayed as follows:

$ gvm-cli -h
usage: gvm-cli [-h] [-c [CONFIG]] [--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]] [--timeout TIMEOUT] [--gmp-username GMP_USERNAME]
             [--gmp-password GMP_PASSWORD] [-V] [--protocol {GMP,OSP}]
             CONNECTION_TYPE ...

optional arguments:
  -h, --help            show this help message and exit
  -c [CONFIG], --config [CONFIG]
                        Configuration file path (default: ~/.config/gvm-
                        tools.conf)
  --log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                        Activate logging (default level: None)
  --timeout TIMEOUT     Response timeout in seconds, or -1 to wait
                        indefinitely (default: 60)
  --gmp-username GMP_USERNAME
                        Username for GMP service (default: '')
  --gmp-password GMP_PASSWORD
                        Password for GMP service (default: '')
  -V, --version         Show version information and exit
  --protocol {GMP,OSP}  Service protocol to use (default: GMP)

connections:
  valid connection types

  CONNECTION_TYPE       Connection type to use
    ssh                 Use SSH to connect to service
    tls                 Use TLS secured connection to connect to service
    socket              Use UNIX Domain socket to connect to service

14.3.1.1 Connection Types¶

gvm-cli supports the following connections:

SSH
TLS
Unix Domain Socket

Note

All current appliances use SSH to encrypt GMP. The use of TLS is deprecated, not officially supported and may be removed in a future version.

Additional command line switches for gvm-cli are displayed when the connection type is specified:

$ gvm-cli ssh -h
usage: gvm-cli ssh [-h] [--hostname HOSTNAME] [--port PORT] [--ssh-username SSH_USERNAME] [--ssh-password SSH_PASSWORD] [-A] [-X XML] [-r]
                 [--pretty] [--duration]
                 [infile]

positional arguments:
  infile                File to read XML commands from.

optional arguments:
  -h, --help            show this help message and exit
  --hostname HOSTNAME   Hostname or IP address (default: 127.0.0.1)
  --port PORT           SSH port (default: 22)
  --ssh-username SSH_USERNAME
                        SSH username (default: 'gmp')
  --ssh-password SSH_PASSWORD
                        SSH password (default: 'gmp')
  -A, --auto-accept-host
                      When executed in e.g. CI, auto accept SSH host addition
  -X XML, --xml XML     XML request to send
  -r, --raw             Return raw XML
  --pretty              Pretty format the returned xml
  --duration            Measure command execution time

14.3.1.2 Logging in to the Appliance¶

For using gvm-cli, logging in to the appliance is required. The same users as for the appliance’s web interface are used.

The needed login information must be provided with any command that is used. This can be done either via command line switches or a configuration file (~/.config/gvm-tools.conf).

To provide the information with command line switches, use the following with every command:

--gmp-username <USER_NAME> --gmp-password <PASSWORD>

To provide the information with a configuration file, create the file ~/.config/gvm-tools.conf containing the following information:

[Auth]
gmp_username=<USER_NAME>
gmp_password=<PASSWORD>

This configuration file is not read by default. The command line switch --config or -c must be added to read the configuration file.

14.3.1.3 Creating and Starting a Scan¶

This chapter demonstrates the use of gvm-cli using the example of a simple scan.

14.3.1.3.1 Used Commands¶

The commands used in this example are documented under https://docs.greenbone.net/API/GMP/gmp-22.7.html.

create_target
get_port_lists
create_task
get_configs
start_task
get_tasks
get_report_formats
get_reports

14.3.1.3.2 Used Placeholders¶

The following placeholders are used:

<USER_NAME>: user name of the web/GMP user.
<PASSWORD>: password of the web/GMP user.
<APPLIANCE_IP>: IP address of the appliance that is accessed.
<TARGET_IP>: IP address of the scan target.

<PORT_LIST_ID>: ID of the used port list. All available port lists can be retrieved by running:

$ gvm-cli --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh --hostname <APPLIANCE_IP> --xml "<get_port_lists/>"

<TARGET_ID>: ID of the scan target.

<SCAN_CONFIG_ID>: ID of the used scan configuration. All available scan configurations can be retrieved by running:

$ gvm-cli --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh --hostname <APPLIANCE_IP> --xml "<get_configs/>"

<TASK_ID>: ID of the task.
<REPORT_ID>: ID of the scan report.

<REPORT_FORMAT_ID>: ID of the used report format. All available report formats can be retrieved by running:

$ gvm-cli --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh --hostname <APPLIANCE_IP> --xml "<get_report_formats/>"

14.3.1.3.3 Step-by-Step Instruction¶

The task can be created and started as follows:

Create the scan target:

$ gvm-cli --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh \
--hostname <APPLIANCE_IP> --xml "<create_target><name>Suspect Host</name>\
<hosts><TARGET_IP></hosts><port_list id='<PORT_LIST_ID>'></port_list></create_target>"

→ The output includes the ID of the scan target. It is required to create the task.

<create_target_response status="201" status_text="OK, resource created" id="<TARGET_ID>"/>

Create the task:

$ gvm-cli --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh \
--hostname <APPLIANCE_IP> --xml "<create_task><name>Scan Suspect Host</name> \
<target id='<TARGET_ID>'></target> <config id='<SCAN_CONFIG_ID>'></config></create_task>"

→ The output includes the ID of the task. It is required to start and monitor the task.

<create_task_response status="201" status_text="OK, resource created" id="<TASK_ID>"/>

Start the task:

$ gvm-cli --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh \
--hostname <APPLIANCE_IP> --xml "<start_task task_id='<TASK_ID>'/>"

→ The task is running. The output includes the ID of the scan report.

<start_task_response status="202" status_text="OK, request submitted"><report_id><REPORT_ID></report_id></start_task_response>

Display the status of the task:

$ gvm-cli --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh \
--hostname <APPLIANCE_IP> --xml "<get_tasks task_id='<TASK_ID>'/>"

<get_tasks_response status="200" status_text="OK"><apply_overrides>
...<status>Running</status><progress>98<host_progress>
<host><TARGET_IP></host>98</host_progress></progress>.../>

→ As soon as the scan is completed, the scan report can be loaded. For this, the report ID that was displayed when the task was started is required.

Load the scan report:

$ gvm-cli --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh \
--hostname <APPLIANCE_IP> --xml "<get_reports report_id='<REPORT_ID>' \
format_id='<REPORT_FORMAT_ID>'/>"

Tip

To fully and automatically process the data, the task can be combined with an alert that forwards the report based on a given condition.

14.3.2 Using `gvm-pyshell`¶

The command line tool gvm-pyshell supplied by Greenbone offers easy access to the broad functionality provided by the XML-based GMP commands through an interactive Python shell. The commands take care of the generation and parsing of the XML data. The Python implementation follows the GMP API documented under https://docs.greenbone.net/API/GMP/gmp-22.7.html. Optional arguments in the API are identified by ?.

gvm-pyshell supports several command line switches which can be displayed as follows:

$ gvm-pyshell -h
usage: gvm-pyshell [-h] [-c [CONFIG]] [--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]] [--timeout TIMEOUT]
                   [--gmp-username GMP_USERNAME] [--gmp-password GMP_PASSWORD] [-V] [--protocol {GMP,OSP}]
                   CONNECTION_TYPE ...

options:
  -h, --help            show this help message and exit
  -c, --config [CONFIG]
                        Configuration file path (default: ~/.config/gvm-tools.conf)
  --log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                        Activate logging (default level: None)
  --timeout TIMEOUT     Response timeout in seconds, or -1 to wait indefinitely (default: 60)
  --gmp-username GMP_USERNAME
                        Username for GMP service (default: '')
  --gmp-password GMP_PASSWORD
                        Password for GMP service (default: '')
  -V, --version         Show version information and exit
  --protocol {GMP,OSP}  Service protocol to use (default: GMP)

14.3.2.1 Connection Types¶

gvm-pyshell supports the following connections:

TLS
SSH
Socket

While the current appliances use SSH to protect GMP, older appliances used TLS and Port 9390 to transport GMP. gvm-tools can be used with both the older and the current GOS.

Additional command line switches for gvm-pyshell are displayed when the connection type is specified:

$ gvm-pyshell ssh -h
usage: gvm-pyshell ssh [-h] [--hostname HOSTNAME] [--port PORT] [--ssh-username SSH_USERNAME] [--ssh-password SSH_PASSWORD] [-A] [-i] [SCRIPT] [ARG ...]

positional arguments:
  SCRIPT                Path to script to be preloaded (example: myscript.gmp.py)
  ARG                   Arguments for preloaded script

options:
  -h, --help            show this help message and exit
  --hostname HOSTNAME   Hostname or IP address (default: 127.0.0.1)
  --port PORT           SSH port (default: 22)
  --ssh-username SSH_USERNAME
                        SSH username (default: 'gmp')
  --ssh-password SSH_PASSWORD
                        SSH password (default: 'gmp')
  -A, --auto-accept-host
                        When executed in e.g. CI, auto accept SSH host addition
  -i, --interactive     Start an interactive Python shell

14.3.2.2 Passing Arguments¶

Mandatory arguments can be supplied in the correct order and are identified automatically:

gmp.create_task("Name","Config","Scanner","Target",comment="comment")

Alternatively, they can be specified using their identifier:

gmp.create_task(name="Name",config_id="Config",scanner_id="Scanner",
target_id="Target",comment="comment")

14.3.2.3 Logging in to the Appliance¶

For using gvm-pyshell, logging in to the appliance is required. The same users as for the appliance’s web interface are used.

The needed login information must be provided. This can be done either via command line switches or a configuration file (~/.config/gvm-tools.conf).

To provide the information with command line switches, use the following:

--gmp-username <USER_NAME> --gmp-password <PASSWORD>

To provide the information with a configuration file, create the file ~/.config/gvm-tools.conf containing the following information:

[Auth]
gmp_username=<USER_NAME>
gmp_password=<PASSWORD>

This configuration file is not read by default. The command line switch --config or -c must be added to read the configuration file.

14.3.2.4 Creating and Starting a Scan¶

This chapter demonstrates the use of gvm-pyshell using the example of a simple scan.

14.3.2.4.1 Used Commands¶

The commands used in this example are documented under https://docs.greenbone.net/API/GMP/gmp-22.7.html.

create_target
get_port_lists
create_task
get_configs
start_task

14.3.2.4.2 Used Placeholders¶

The following placeholders are used:

<USER_NAME>: user name of the web/GMP user.
<PASSWORD>: password of the web/GMP user.
<APPLIANCE_IP>: IP address of the appliance that is accessed.
<TARGET_IP>: IP address of the scan target.

<PORT_LIST_ID>: ID of the used port list. All available port lists can be retrieved by running:

>>> res=gmp.get_port_lists()
>>> for i, portlist in enumerate(res.xpath('port_list')):
...     id = portlist.xpath('@id')[0]
...     name = portlist.xpath('name/text()')[0]
...     print('\n({0}) {1}: ({2})'.format(i, name, id))
...

<SCAN_CONFIG_ID>: ID of the used scan configuration. All available scan configurations can be retrieved by running:

>>> res=gmp.get_scan_configs()
>>> for i, scanconfig in enumerate(res.xpath('scan_config')):
...     id = scanconfig.xpath('@id')[0]
...     name = scanconfig.xpath('name/text()')[0]
...     print('\n({0}) {1}: ({2})'.format(i, name, id))
...

14.3.2.4.3 Step-by-Step Instruction¶

The task can be created and started as follows:

Enter the Python shell:

$ gvm-pyshell --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh --hostname <APPLIANCE_IP>

→ The Python shell is opened:

GVM Interactive Console 25.4.3 API 26.8.0.Type "help" to get information about functionality.
>>>

Create the scan target:

>>> res=gmp.create_target("Suspect Host", hosts=['<TARGET_IP>'], port_list_id="<PORT_LIST_ID>")

Define the variable target_id as ID of the created target:

>>> target_id = res.xpath('@id')[0]

Create the task:

>>> res=gmp.create_task("Scan Suspect Host", config_id="<SCAN_CONFIG_ID>", scanner_id="08b69003-5fc2-4037-a479-93b440211c73", target_id=target_id)

Note

All existing scanners can be displayed using the command get_scanners. If only the built-in scanners are used, the following IDs are hard-coded:

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

Define the variable task_id as the ID of the created task:

>>> task_id = res.xpath('@id')[0]

Start the task:

>>> gmp.start_task(task_id)

→ The task is running.

14.3.2.4.4 Using a Script¶

All commands can be put in a Python script which may be invoked by the Python shell.

len_args = len(args.script) - 1
if len_args != 2:
    message = """
    This script creates a new task with a specific host.
    It needs two parameters after the script name.
    The first one is the name of the target and the second
    one is the host to be scanned.

    Example:
        $ gvm-script --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh --hostname <APPLIANCE_IP> <SCRIPT_NAME> "Suspect Host" 127.0.0.1
    """
    print(message)
    quit()

target = args.script[1]
host = [args.script[2]]
task = target + " Task"

# All IANA assigned TCP
myportlist_id = "33d0cd82-57c6-11e1-8ed1-406186ea4fc5"

# Full and Fast
myconfig_id = "daba56c8-73ec-11df-a475-002264764cea"

# OpenVAS Scanner
myscanner_id = "08b69003-5fc2-4037-a479-93b440211c73"

res=gmp.create_target(target, hosts=host, port_list_id=myportlist_id)
mytarget_id = res.xpath('@id')[0]

res=gmp.create_task(name=task, config_id=myconfig_id, scanner_id=myscanner_id, target_id=mytarget_id)
mytask_id = res.xpath('@id')[0]

gmp.start_task(mytask_id)

The script can be executed via the command gvm-script. It requires two arguments: a name for the target and the host that should be scanned.

Example:

gvm-script --gmp-username <USER_NAME> --gmp-password <PASSWORD> ssh --hostname <APPLIANCE_IP> <SCRIPT_NAME> "Suspect Host" 127.0.0.1

14.3.3 Example Scripts¶

The gvm-tools come with a collection of example scripts providing various experimental functionalities and serving as a starting point for the development of custom scripts.

Currently the following scripts are available for gvm-tools: https://github.com/greenbone/gvm-tools/tree/main/scripts

The scripts can be executed via the command gvm-script.

14.4 Status Codes¶

GMP uses status codes similar to HTTP status codes. The following codes are used:

2xx:

The command was sent, understood and accepted successfully.

200: OK
201: Resource created
202: Request submitted

4xx:

A user error occurred.

400: Syntax error

This includes different syntax errors. Often elements or attributes in the GMP command are missing. The status text shows additional information.

Currently this status code is also used for missing or wrong authentication.

401: Authenticate First

This is the error code that is used for missing or wrong authentication. Currently the value 400 is still used.

403: Access to resource forbidden

This is the error code that is used for not having enough permissions. Often 400: Permission denied is displayed instead as well.

404: Resource missing

The resource could not be found. The resource ID was empty or wrong.

409: Resource busy

This error code happens, for example, if the feed synchronization is started while it is already in progress.

5xx:

A server error occurred.

500: Internal Error: This can be caused by entries that exceed an internal buffer size.
503: Scanner loading NVTs: The scanner is currently busy loading the VTs from its cache. The request should be made again at a later time.
503: Service temporarily down: Possibly the scanner daemon is not running. Often the problem are expired certificates.
503: Service unavailable: The GMP command is blocked on the appliance.

14 Using the Greenbone Management Protocol¶

14.1 Changes to GMP¶

14.2 Activating GMP¶

14.3 Using gvm-tools¶

14.3.1 Using gvm-cli¶

14.3.1.1 Connection Types¶

14.3.1.2 Logging in to the Appliance¶

14.3.1.3 Creating and Starting a Scan¶

14.3.1.3.1 Used Commands¶

14.3.1.3.2 Used Placeholders¶

14.3.1.3.3 Step-by-Step Instruction¶

14.3.2 Using gvm-pyshell¶

14.3.2.1 Connection Types¶

14.3.2.2 Passing Arguments¶

14.3.2.3 Logging in to the Appliance¶

14.3.2.4 Creating and Starting a Scan¶

14.3.2.4.1 Used Commands¶

14.3.2.4.2 Used Placeholders¶

14.3.2.4.3 Step-by-Step Instruction¶

14.3.2.4.4 Using a Script¶

14.3.3 Example Scripts¶

14.4 Status Codes¶

14.3.1 Using `gvm-cli`¶

14.3.2 Using `gvm-pyshell`¶