OpenVAS Management Protocol =========================== The entire control of the GSM appliance is done via the :index:`OpenVAS Management Protocol` (:index:`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. .. _activating_omp: 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 :ref:`omp`) or via the GOS-Admin-Menu under :gos:menu:`Remote` and then :gos:menu:`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. 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 :gos:cmd:`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= omp --get-tasks omp --xml= omp --help In general the command line tool :gos:cmd:`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=`` corresponds to the switch ``--get-tasks``. When using the latter the output will not be in XML format rather than a simple text table. Configuring the Client ^^^^^^^^^^^^^^^^^^^^^^ To use the :gos:cmd:`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 :file:`omp.config` for simplification in the home directory of the user. On Unix like systems it is :file:`$(HOME)/omp.config`. On Windows systems the file can be found in :file:`%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. .. code-block:: ini [Connection] host=gsm port=9390 username=webadmin password=password 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 :gos:cmd:`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 :gos:cmd:`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 :gos:omp:`create_target` is described. If the IP address is saved in the variable ``IPADDRESS`` the respective target can be created with the following command: .. code-block:: bash $ ./omp -X "Suspect Host$IPADDRESS " Now the task can be created. Using ``-c`` you specify the scan configuration. The target is specified using ``-t``: .. code-block:: bash $ ./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: .. code-block:: bash $ ./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: .. code-block:: bash $ ./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: .. code-block:: bash $ ./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: .. code-block:: bash $ ./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: .. code-block:: bash $ ./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. .. index:: Status Codes 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. 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: .. code-block:: bash $ OLD_TARGET_UUID=$(omp --xml "" | \ xmlstarlet sel -t -v /get_tasks_response/task/target/@id) * Create a new target object by cloning the old target object: .. code-block:: bash NEW_TARGET_UUID=$(omp --xml "$OLD_TARGET_UUID \ $NEW_NAME" | \ xmlstarlet sel -t -v /create_target_response/@id) * Update the new target object with the new list of hosts: .. code-block:: bash omp --xml " \ $NEW_HOSTS" * Update the task to use the new target object: .. code-block:: bash omp --xml " \ " * Remove the now unused old target: .. code-block:: bash omp --xml "" 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: .. code-block:: bash omp --xml "" > 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: .. code-block:: bash omp --xml "$OLD_TARGET_UUID $NEW_NAME" > 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: .. code-block:: bash omp --xml " $NEW_HOSTS" * Update the task to use the new target object: .. code-block:: bash omp --xml " " * Remove the now unused old target: .. code-block:: bash omp --xml "" Status Codes ^^^^^^^^^^^^ The OMP protocol uses status codes for communication. These status codes can be displayed in the web interface. .. figure:: images-3.0/statuscode.png :align: center :width: 100% 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 :ref:`readiness_check`) 503: Service unavailable: The OMP command is blocked on the GSM.