16. OpenVAS Management Protocol¶

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

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

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

16.1. Activating the OMP Protocol¶

To be able to use the OMP protocol it first needs to be activated on the GSM appliance. The web interfaces uses the OMP protocol only locally on the appliance and not through the network. Activating the OMP protocol can either be performed directly through a variable on the command line (see section OpenVAS Management Protocol (OMP)) or via the GOS-Admin-Menu under Remote and then OMP. It is important that in both cases the GSM appliance needs to be rebooted to activate this setting. Access to the OMP 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.

16.2. Access with `omp`¶

While with the help of the documentation of the OMP protocol your own application for access can be developed, Greenbone has developed a command line application for easy access and makes it available on the website for Linux and Windows.

GNU/Linux omp:
- SHA1 checksum: d6b554361180b4b059bb7dd4be510cf58dcad18b
- SHA256 checksum: 69d384088b8a84770e3ccfb81fe628d2cf12238e2fa9f2d320c7c4f6a615064b
Microsoft Windows omp.exe (digitally signed by Greenbone Networks GmbH)

The tool is a statically linked executable file that should work on most systems. Greenbone has released all components as open source so you can build the tool for other systems as well:

GNU/Linux: * openvas-libraries-8.0.5.tar.gz (0.6 MB) * openvas-cli-1.4.3.tar.gz (0.1 MB)
Microsoft Windows: omp-src-win.tar.gz (40 MB)

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

The command line tool omp supplied by Greenbone Networks offers for one the direct sending and receiving of XML commands and XML responses. This is mostly helpful for batch mode (batch processing, scripting). Also the important commands are available as command line parameter including an option for human readable output. This is meant for spontaneous queries, tests and to create batch processes.

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

.. code-block:: bash

omp –xml=<get_tasks/> omp –get-tasks omp –xml=<help/> omp –help

In general the command line tool omp offers two uses. Via the --xml switch OMP commands are being sent in XML format. The answers will be in XML format as well. Using --pretty-print the output is formatted human readable.

Some commands are available as well as direct switches. --xml=<get_tasks/> corresponds to the switch --get-tasks. When using the latter the output will not be in XML format rather than a simple text table.

16.2.1. Configuring the Client¶

To use the omp command you need to log into the appliance. For this the required information is supplied via the options --user, --password, --host and --port. In order not to have to supply this information with each execution the connection data can be saved in the file omp.config for simplification in the home directory of the user. On Unix like systems it is $(HOME)/omp.config. On Windows systems the file can be found in %USERPROFILE%omp.config. Create the file with the following content (host, username and password need to be changed respectively of course) and pay attention to capitalization). If the password is left out, omp will ask for it when started.

[Connection]
host=gsm
port=9390
username=webadmin
password=password

16.2.2. Starting a Scan¶

A typical example for using the OMP 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 omp is very suitable.

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

For this function there is no simple option in the omp command. This is why this must occur with the help of XML. Under http://docs.greenbone.net/API/OMP/omp-6.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:

$ ./omp -X "<create_target><name>Suspect Host</name><hosts>$IPADDRESS</hosts>
</create_target>"

<create_target_response status="201" id="aa410e98-ff8d-45b6-be98-11fd7a895435"
status_text="OK, resource created"></create_target_response>

Now the task can be created. Using -c you specify the scan configuration. The target is specified using -t:

$ ./omp -C -c daba56c8-73ec-11df-a475-002264764cea --name "ScanSuspectHost" \
-t aa410e98-ff8d-45b6-be98-11fd7a895435

a4bdad7c-6135-45c1-884b-fd226a6e7a19

The output us the ID of the task. It is required for the start.

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

$ ./omp -T
b493b7a8 -7489-11df-a3ec-002264764cea  Localhost
aa410e98-ff8d-45b6-be98-11fd7a895435  Suspect Host

$ ./omp -g
8715c877-47a0-438d-98a3-27c7a6ab2196  Discovery
085569ce-73ed-11df-83c3-002264764cea  empty
daba56c8-73ec-11df-a475-002264764cea  Full and fast
698f691e-7489-11df-9d8c-002264764cea  Full and fast ultimate
708f25c4-7489-11df-8094-002264764cea  Full and very deep
74db13d6-7489-11df-91b9-002264764cea  Full and very deep ultimate
2d3f051c-55ba-11e3-bf43-406186ea4fc5  Host Discovery
bbca7412-a950-11e3-9109-406186ea4fc5  System Discovery

Now the task needs to be started:

$ ./omp -S a4bdad7c-6135-45c1-884b-fd226a6e7a19

58f7f696-5ec7-49f4-9968-1d35991f8f2e

The output is the response of the report. Now it has to be waited until the task is fully completed. The status of the task can be displayed with the following command:

$ ./omp --get-tasks a4bdad7c-6135-45c1-884b-fd226a6e7a19

a4bdad7c-6135-45c1-884b-fd226a6e7a19  Running 20%  ScanSuspectHost
58f7f696-5ec7-49f4-9968-1d35991f8f2e  Running   0   0   1   2  2014-06-27T12:43:17Z
$ ./omp --get-tasks a4bdad7c -6135-45c1-884b-fd226a6e7a19

a4bdad7c-6135-45c1-884b-fd226a6e7a19  Done         ScanSuspectHost
58f7f696-5ec7-49f4-9968-1d35991f8f2e  Done      0   0   1   8  2014-06-27T12:43:17Z

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:

$ ./omp --get-report-formats
910200ca-dc05-11e1-954f-406186ea4fc5  ARF
5ceff8ba-1f62-11e1-ab9f-406186ea4fc5  CPE
9087b18c-626c-11e3-8892-406186ea4fc5  CSV Hosts
c1645568-627a-11e3-a660-406186ea4fc5  CSV Results
35ba7077-dc85-42ef-87c9-b0eda7e903b6  GSR PDF
ebbc7f34-8ae5-11e1-b07b-001f29eadec8  GXR PDF
6c248850-1f62-11e1-b082-406186ea4fc5  HTML
77bd6c4a-1f62-11e1-abf0-406186ea4fc5  ITG
a684c02c-b531-11e1-bdc2-406186ea4fc5  LaTeX
9ca6fe72-1f62-11e1-9e7c-406186ea4fc5  NBE
c402cc3e-b531-11e1-9163-406186ea4fc5  PDF
9e5e5deb-879e-4ecc-8be6-a71cd0875cdd  Topology SVG
a3810a62-1f62-11e1-9219-406186ea4fc5  TXT
a994b278-1f62-11e1-96ac-406186ea4fc5  XML

Now the report can be loaded:

$ ./omp --get-report 58f7f696-5ec7-49f4-9968-1d35991f8f2e --format \
c1645568-627a-11e3-a660-406186ea4fc5 > report.csv

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.

16.2.3. Updating the target host of an alterable task using OMP¶

The following example shows how the target of an alterable task can be changed through OMP, for example based on a list generated by another tool. Variables used in this example:

TASK_UUID The UUID of the task for which you want to modify the target. The task must be set to “alterable”.
NEW_HOSTS The new list of hosts to use for the target.
NEW_NAME The name for the new target object.

16.2.3.1. On UNIX-like systems¶

The following examples use the xmlstarlet tool to parse XML data. This can of course be replaced by other solutions if desired.

Retrieve the UUID of the old target object from the task:

$ OLD_TARGET_UUID=$(omp --xml "<get_tasks task_id=\"$TASK_UUID\"></get_tasks>" | \
xmlstarlet sel -t -v /get_tasks_response/task/target/@id)

Create a new target object by cloning the old target object:

NEW_TARGET_UUID=$(omp --xml "<create_target><copy>$OLD_TARGET_UUID</copy> \
<name>$NEW_NAME</name></create_target>" | \
xmlstarlet sel -t -v /create_target_response/@id)

Update the new target object with the new list of hosts:

omp --xml "<modify_target target_id=\"$NEW_TARGET_UUID\"> \
<hosts>$NEW_HOSTS</hosts><exclude_hosts/></modify_target>"

Update the task to use the new target object:

omp --xml "<modify_task task_id=\"$TASK_UUID\"> \
<target id=\"$NEW_TARGET_UUID\"/></modify_task>"

Remove the now unused old target:

omp --xml "<delete_target target_id=\"$OLD_TARGET_UUID\"/>"

16.2.3.2. On Windows-like systems¶

The following examples use the “Select-XML” command of the PowerShell to parse XML data. This can of course be replaced by other solutions if desired.

Retrieve the UUID of the old target object from the task:

omp --xml "<get_tasks task_id='$TASK_UUID'></get_tasks>" > get_tasks_response.xml
$OLD_TARGET_UUID = Select-Xml .\get_tasks_response.xml `
-xpath "/get_tasks_response/task/target[@id]" | ForEach-Object { $_.Node.id}

Create a new target object by cloning the old target object:

omp --xml "<create_target><copy>$OLD_TARGET_UUID</copy>
<name>$NEW_NAME</name></create_target>" > create_target_response.xml
$NEW_TARGET_UUID = Select-Xml .\create_target_response.xml `
-xpath "/create_target_response[@id]" | ForEach-Object { $_.Node.id }

Update the new target object with the new list of hosts:

omp --xml "<modify_target target_id='$NEW_TARGET_UUID'>
<hosts>$NEW_HOSTS</hosts><exclude_hosts/></modify_target>"

Update the task to use the new target object:

omp --xml "<modify_task task_id='$TASK_UUID'>
<target id='$NEW_TARGET_UUID'/></modify_task>"

Remove the now unused old target:

omp --xml "<delete_target target_id='$OLD_TARGET_UUID'/>"

16.2.4. Status Codes¶

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

The OMP 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. Check the Readiness (see section Readiness)
503: Service unavailable:: The OMP command is blocked on the GSM.