11. Greenbone Management Protocol

The entire control of the GSM appliance is done via the Greenbone Management Protocol (GMP). The web interface is an GMP client as well and accesses the GSM functions via GMP.

GMP is formerly known as OMP. Greenbone provides new tools to use the features of the GMP protocol. While the gvm-tools (see section GVM-Tools) may be used to connect to both GOS 4 and older GOS 3.1 appliances the older omp.exe (see http://docs.greenbone.net/GSM-Manual/gos-3.1/en/omp.html) tool is not compatible with GOS 4.

The GMP protocol is documented at the Greenbone TechDoc portal: http://docs.greenbone.net/API/OMP/omp-7.0.html

This chapter covers the activation and use of the protocol by third party applications.

11.1. Activating the GMP Protocol

To be able to use the GMP protocol it first needs to be activated on the GSM appliance. The web interfaces uses the GMP protocol only locally on the appliance and not through the network. Activating the GMP protocol can either be performed directly through a variable on the command line (see section GMP) or via the GOS-Admin-Menu under Remote and then GMP. It is important that in both cases the GSM appliance needs to be rebooted to activate this setting. Access to the GMP protocol is done in general SSL encrypted and authenticated. The same users as in the web interface are being used. The users are subject to the same restrictions and have the exact same permissions.

11.2. Access with gvm-cli.exe

While with the help of the documentation of the GMP protocol your own application for access can be developed, Greenbone has developed a command line application for easy access and a Python shell and makes both available on the website for Linux and Windows. The tool and the download locations are described in section GVM-Tools.

The GMP protocol is XML based. Every command and every response is a GMP object.

The command line tool gvm-cli.exe supplied by Greenbone Networks offers for one the direct sending and receiving of XML commands and XML responses.

The tool supports the following connections:

  • tls
  • ssh
  • socket

The commandline tool supports several switches. These can be displayed using:

$ gvm-cli -h
usage: gvm-cli [-h] [-V] [connection_type] ...

  gvm-cli 1.2.0 (C) 2017 Greenbone Networks GmbH

  This program is a command line tool to access services via
  GMP (Greenbone Management Protocol).

  Examples:
  gvm-cli --xml "<get_version/>"
  gvm-cli --xml "<commands><authenticate><credentials><username>myuser</username><password>mypass</password></credentials></authenticate><get_tasks/></commands>"
...

While the tool supports more switches the additional options are only displayed when the connection_type is specified:

$ gvm-cli ssh -h
usage: gvm-cli ssh [-h] [-c [CONFIG]] [--timeout TIMEOUT]
                 [--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]]
                 [--gmp-username GMP_USERNAME] [--gmp-password GMP_PASSWORD]
                 [-X XML] --hostname HOSTNAME [--port PORT]
                 [--ssh-user SSH_USER]
                 [infile]

positional arguments:
  infile

optional arguments:
  -h, --help            show this help message and exit
  -c [CONFIG], --config [CONFIG]
                      Configuration file path. Default: ~/.config/gvm-
                      tools.conf

...

While the current GSM Appliances (GOS 4) use ssh to protect the GMP protocol, older appliances used TLS and Port 9390 to transport the GMP protocol. The gvm tools may be used with both the older and the current Greenbone OS.

The tools are mostly helpful for batch mode (batch processing, scripting).

With this tool the GMP protocol can be used in a simple way:

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

11.2.1. Configuring the Client

To use the gvm-cli command you need to log into the appliance. For this the required information is supplied either using command line switches or a configuration file (~/.config/gvm-tools.conf).

To provide the GMP user using command line switches use:

  • --gmp-username
  • --gmp-password

Alternatively a configuration file ~/.config/gvm-tools.conf containing these informations may be created:

[Auth]
gmp_username=webadmin
gmp_password=kennwort

This configuration file is not read be default. You will have to add the commandline switch --config or -c to read the configuration file.

11.2.2. Starting a Scan using gvm-cli

A typical example for using the GMP protocol is the automatic scan of a new system. Below we assume that an Intrusion Detection System is in use that monitors the systems in the DMZ and immediately discovers new systems and unusual TCP ports not used up to now. If such an event is being discovered the IDS should automatically initiate a scan of the new system. This should be done with the help of a script. For the this gvm-cli can be used although the gvm-pyshell or using self written python scripts might be more suitable. The processing of the XML output is better supported by python then by using the shell. This is explained in the following sections.

Starting point is the IP address of the new suspected system. For this IP address a target needs to be created in the GSM.

Under http://docs.greenbone.net/API/OMP/omp-7.0.html#command_create_target the command create_target is described.

If the IP address is saved in the variable IPADDRESS the respective target can be created with the following command:

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

<create_target_response status="201" status_text="OK, resource
created" id="4574473f-a5d0-494c-be6f-3205be487793"/>

Now the task can be created.

$ gvm-cli ssh --gmp-username webadmin --gmp-password kennwort \
--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>"


<create_task_response status="201" status_text="OK, resource created" id="ce225181-c836-4ec1-b83f-a6fcba70e17d"/>

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

The other IDs used by the command may be retrieved using the following commands displaying the available targets and scan configs:

$ gvm-cli ssh --gmp-username webadmin --gmp-password kennwort \
--hostname 192.168.222.115 --xml "<get_targets/>"

$ gvm-cli ssh --gmp-username webadmin --gmp-password kennwort \
--hostname 192.168.222.115 --xml "<get_configs/>"

The output of the above commands is XML.

Now the task needs to be started:

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

The connection will be closed by the GSM.

Now the task is running. The status of the task can be displayed with the following command:

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

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

As soon as the scan is completed the report can be downloaded. For this the ID that was output when the task was started is required. Also a meaningful report format must be entered. The IDs for the report formats can be displayed via:

$ $ gvm-cli ssh --gmp-username webadmin --gmp-password kennwort \
--hostname 192.168.222.115 --xml '<get_report_formats/>'

Now the report can be loaded:

$ gvm-cli ssh --gmp-username webadmin --gmp-password kennwort \
--hostname 192.168.222.115 \
--xml '<get_reports report_id="23a335d6-65bd-4be2-a83e-be330289eef7" \
format_id="35ba7077-dc85-42ef-87c9-b0eda7e903b6"/>'

For a complete automatic processing of the data the task could be combined with an alert that could send out the report automatically at a specific severity level.

11.3. gvm-pyshell

The command line tool gvm-pyshell.exe supplied by Greenbone Networks offers for one the direct sending and receiving of XML commands and XML responses using python commands. These commands take care of the generation and parsing of the XML data.

The tool supports the following connections:

  • tls
  • ssh
  • socket

While the current GSM Appliances (GOS 4) use ssh to protect the GMP protocol, older appliances used TLS and Port 9390 to transport the GMP protocol. The gvm tools may be used with both the older and the current Greenbone OS.

The tools are mostly helpful for batch mode (batch processing, scripting).

The authentication configuration of the gvm-pyshell can be stored in a file in the home directory of the user. The syntax is explained in section Configuring the Client.

The Python implementation follows the GMP API. Under http://docs.greenbone.net/API/OMP/omp-7.0.html the API is described. Optional arguments in the API are identified by a ?. The following example explains the usage of the Python functions:

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

While mandatory arguments may be supplied in the correct order and are identified automatically they may also be specified using their identifier:

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

11.3.1. Starting a Scan using gvm-pyshell

A typical example for using the GMP protocol is the scan of a new system. Below we assume that an Intrusion Detection System is in use that monitors the systems in the DMZ and immediately discovers new systems and unusual TCP ports not used up to now. If such an event is being discovered the IDS should automatically initiate a scan of the new system. This should be done with the help of a script. For the this the gvm-pyshell is very suitable. The processing of the XML output is better supported by python then by using the shell.

Starting point is the IP address of the new suspected system. For this IP address a target needs to be created in the GSM.

Under http://docs.greenbone.net/API/OMP/omp-7.0.html#command_create_target the command create_target is described.

The following lines will first step through the required commands using the interactive python shell:

$ gvm-pyshell ssh \
--gmp-username webadmin --gmp-password kennwort\
--hostname 192.168.222.115
GVM Interactive Console. Type "help" to get information about functionality.
>>> res=gmp.create_target("Suspect Host", True, hosts="192.168.255.254")
>>> target_id = res.xpath('@id')[0]

The variable target_id contains now the id of the created target. This id can now be used to create the corresponding task.

The task creation requires the following input:

  • target_id
  • config_id
  • scanner_id
  • task_name
  • task_comment

To display all available scan configurations the following code may be used:

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

The scanners can be discovered using the same technique. But if only the built in scanners are used the following id are hard-coded:

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

To create the task use the following command:

>>> 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]

To start the task use:

>>> gmp.start_task(task_id)

The current version of the GSM (4.1.7) closes the connection in the gvm-pyshell imediately. Further commands are not possible.

All these commands may be put in a python script which may be invoked by the gvm-pyshell:

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

    Example:
        $ gvm-pyshell ssh newtask target host
    """
    print(message)
    quit()

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

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

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

res=gmp.create_target(target, True, hosts=host)
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)

11.4. Example Scripts

The gvm-tools come with a collection of example scripts which may be used by the gvm-pyshell.exe tool. Currently the following scripts are shipped in the Bitbucket repository:

  • application-detection.gmp

    This script will display all hosts with the searched application.

  • cfg-gen-for-certs.gmp

    This script creates a new scan config with nvts based on a given CERT-Bund Advisory.

  • clean-slave.gmp

    This script removes all resources from a slave except active tasks.

  • create-dummy-data.gmp

    This script generates dummy data.

  • DeleteOverridesByFilter.gmp

    This script deletes overrides using a filter.

  • monthly-report2.gmp

    This script will display all vulnerabilities based on the reports of a given months. Made for GOS 4.x.

  • monthly-report.gmp

    This script will display all vulnerabilities based on the reports of a given months. Made for GOS 3.1.

  • nvt-scan.gmp

    This script creates a new task with specific host and nvt using hardcoded base config.

  • startNVTScan.gmp

    This script interactively creates a new task with specific host and nvt.

  • SyncAssets.gmp

    This script will upload assets to the asset db.

  • SyncReports.gmp

    This script will pull reports and upload these to a second GSM using container tasks.

These scripts may serve as a starting point for the development of private scripts.

11.4.1. Status Codes

The GMP protocol uses status codes for communication. These status codes can be displayed in the web interface.

_images/statuscode.png

The GMP protocol uses status codes and alerts to display statuses.

The status codes are similar to HTTP status codes. The following codes are being 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 could be different syntax errors. Often elements or attributes in the OMP 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 being used for missing or wrong authentication. Currently the value 400 is still being used.
403: Access to resource forbidden
This is the error code that is being used for having not enough permissions. Often 400: Permission denied will be 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 being started while it is already in progress.
5xx:

A server error occurred

500: Internal Error
This could be entries that exceed an internal buffer size.
503: Scanner loading NVTs
The scanner is currently busy loading the NVTs from its cache. Try again later.
503: Service temporarily down
Possibly the scanner daemon is not running. Often the problem could be expired certificates.
503: Service unavailable:
The OMP command is blocked on the GSM.