English | Deutsch
Home »

OpenVAS Change Request #30: OpenVAS Administration Protocol (OAP)

Status: Voted +6. Released with openvas-administrator 1.0.0.

For the final specification of OAP please refer to this page: Protocol Documentation.

Purpose

To introduce a new protocol which allows a client to control the settings of an OpenVAS server.

References

(none)

Rationale

Configuration of an OpenVAS server currently requires the human server administrator to access the server through a shell and execute shell scripts or modify configuration files manually. This can lead to server misconfiguration if not done carefully and might not be possible or desired under certain circumstances.

As a basis for an application intended to address this issue, this change request propose a network protocol to be used for communicating OpenVAS configuration data.

The design goals for this new protocol should be:

This change request proposes an XML based approach to satisfy the goals described above. A first draft of the proposed protocol is available in the section "Design and Implementation" of this Change Request.

This protocol is intended to be very similar to the OpenVAS Management Protocol (OMP) to make use of existing functionality.

Effects

It will become possible to implement an application which automates and simplifies the configuration of an OpenVAS server.

Design and Implementation

Design Considerations

The current specification proposes an XML based approach. This is intended to allow for easy integration into other XML capable protocols and communication methods, e.g. Web Services/SOAP, XmlHttpRequest, REST or other methods of invoking remote functionality.

Human-readable strings are encoded as UTF-8.

The OAP communication between a client and the administrator takes a simple command response form. The client sends a command, a single XML element, to the administrator. The administrator responds with a single XML element.

There is a predefined set of OAP commands, each of which is described below.

Numerical response codes:
The OpenVAS administrator uses numerical response codes to indicate whether a command issued by the client could be executed successfully. The response codes are similar to the response codes used by HTTP as specified in RFC 2616; a response code in the 2xx range indicates that the command has been successfully received, understood, and accepted. A response code in the 4xx range indicates that the command issued could not be executed due to error made by the client. A response in the 5xx range indicates that an error occurred in the administrator during the processing of this command.
Responses are expected to include helpful information whenever possible, like the ID of the task when a command on this task was executed.
Implementations which transfer OAP using a response-code aware protocol (e.g. HTTP) might want to consider including this status code in the message generated by this protocol.

Authentication:
The client is expected to send an authentication element with each request. Initially, this element will be expected to look like the following:

<authentication>
  <credentials>
    <username>FooBar</username>
    <password>276LkeFHJWnCaD6ynSlP6mnf9</password>
  </credentials>
</authentication>
Over time, other types of credentials are to be expected. If the credentials supplied by the client are not sufficient, the administrator must reply with:
<authentication_response status="400" status_text="Authentication failed" />
and must not handle the actual request made by the client.

Summary of Protocol Primitives / Commands

authenticate Authenticate with the administrator.
commands Execute a list of OAP commands.
create_user Create a new user.
delete_user Delete an existing user.
describe_auth Get details about the used authentication methods.
describe_feed Get details of the NVT feed this administrator uses.
get_settings Get scanner settings.
get_users Get all users.
get_version Get the OpenVAS Administrator Protocol version.
help Get the help text.
modify_auth Modify the authentication methods.
modify_user Modify a user
sync_feed Synchronize with an NVT feed.

Details of Protocol Primitives / Commands

authenticate

The client uses the authenticate command to authenticate with the administrator.

Command elements:

Example:

C:

<authenticate>
  <credentials>
    <username>sally</username>
    <password>secret</password>
  </credentials>
</authenticate>

A:

<authenticate_response status="200" status_text="OK" />

A:

<authenticate_response status="400" status_text="Authenticate failed" />

A:

<authenticate_response status="500" status_text="Internal error" />

commands

The client uses the commands command to run a list of commands. The elements are executed as OAP commands in the given sequence. The reply contains the result of each command, in the same order as the given commands.

Command elements:

Example:

C:

<commands>
  <delete_user name="foobar"/>
  <get_users/>
</commands>

A:

<commands_response status="200" status_text="OK">
  <delete_user_response status="200" status_text="OK"/>
  <get_users_response status="200" status_text="OK">
    <user>
      <name>notfoobar</name>
      <role>User</role>
      <hosts allow="2"></hosts>
    </user>
  </get_users_response>
</commands_response>

create_user

The client uses the "create_user" command to create an user account on the OpenVAS server. The client must supply an name for the user, a password to be used for this user and a role that should be assigned to this user. It may contain a hosts element describing the restrictions to be placed on the new user. If the request does not contain a hosts element, the user account will be unrestricted.

The status code in the administrator response will indicate whether or not the requested action was successfully completed.

Command elements:

Example:

C:

<create_user>
  <name>foobar</name>
  <password>f00bar</password>
  <role>User</role>
</create_user>

A:

<create_user_response status="201" status_text="OK, resource created"/>

delete_user

The client uses the "delete_user" command to request the deletion of an user account on the OpenVAS server. The client must supply the name of the user to be deleted.

The status code in the administrator response will indicate whether the deletion of the user with the supplied name was successful or not.

Command attributes:

Example:

C:

<delete_user name="foobar"/>

A:

<delete_user_response status="200" status_text="OK"/>

describe_auth

The client uses the "describe_auth" command to get details about the used authentication methods.

The administrator will reply with a list of all used authentication methods if such a list is available.

Command elements:

Example:

C:

<describe_auth/>

A:

<describe_auth_response status="200" status_text="OK">
  <group name="Foo">
    <auth_conf_setting key="Bar" value="Baz"/>
  </group>
</describe_auth_response>

describe_feed

The client uses the "describe_feed" command to get details about the NVT feed used by the administrator.

The administrator will reply with a feed element containing information about the NVT feed.

Command elements:

Example:

C:

<describe_feed/>

A:

<describe_feed_response status="200" status_text="OK">
  <feed>
    <name>OpenVAS NVT Feed</name>
    <version>201011221324</version>
    <description>
      This script synchronizes an NVT collection with the 'OpenVAS NVT Feed'.
      The 'OpenVAS NVT Feed' is provided by 'The OpenVAS Project'.
      Online information about this feed: 'http://www.openvas.org/openvas-nvt-feed.html'.
    </description>
  </feed>
</describe_feed_response>

get_settings

The client uses the "get_settings" command to retrieve a list of all settings set for the OpenVAS server controlled by this OpenVAS administrator.

The administrator will reply with a list of all known settings and their values.

Command elements:

Example:

C:

<get_settings/>

A:

<get_settings_response status="200" status_text="OK">
  <scanner_settings sourcefile="/etc/openvas/openvassd.conf" editable="0">
    <setting name="safe_checks">yes</setting>
    ...
  </scanner_settings>
</get_settings_response>

get_users

The client uses the "get_users" command to retrieve the list of user accounts on the OpenVAS server.

The administrator response will contain as many user elements as there are user accounts on the server. The user elements will consist of a name element, a role element and a hosts element.

Command elements:
None

Example:

C:

<get_users/>

A:

<get_users_response status="200" status_text="OK">
  <user>
    <name>foobar</name>
    <role>User</role>
    <hosts allow="2"></hosts>
  </user>
</get_users_response>

get_version

The client uses the get_version command to request the protocol version which may be used when communicating with this administrator. The administrator will reply with a response code indicating success and the version.

The client is advised to use this command before using any other command.

Command elements:

Example:

C:

<get_version/>

A:

<get_version_response status="200" status_text="OK">
  <version>1.0</version>
</get_version_response>

help

The help command requests a human-readable description of the available OAP commands. The administrator will reply with a response code indicating success and a textual description of all commands.

Command elements:

Example:

C:

<help/>

M:

<help_response status="200" status_text="OK">
    AUTHENTICATE     Authenticate with the administrator.
    COMMANDS         Run a list of commands.
    CREATE_USER      Create a new user.
    DELETE_USER      Delete an existing user.
    DESCRIBE_AUTH    Get details about the used authentication methods.
    DESCRIBE_FEED    Get details of the NVT feed this administrator uses.
    GET_SETTINGS     Get scanner settings.
    GET_USERS        Get all users.
    GET_VERSION      Get the OpenVAS Administrator Protocol version.
    HELP             Get this help text.
    MODIFY_AUTH      Modify the authentication methods.
    MODIFY_USER      Modify a user.
    SYNC_FEED        Synchronize with an NVT feed.
</help_response>

modify_auth

The client uses the "modify_auth" command to modify the authentication methods.

The status code in the administrator response will indicate whether or not the requested action was successfully completed.

Command elements:

Example:

C:

<modify_auth>
  <group name="Foo">
    <auth_conf_setting key="Bar" value="Baz"/>
  </group>
</modify_auth>

A:

<modify_auth_response status="200" status_text="OK"/>

modify_user

The client uses the "modify_user" command to modify an user account on the OpenVAS server. The client must supply an name for the user, a password to be used for this user and a role that should be assigned to this user. It may contain a hosts element describing the restrictions to be placed on the new user. If the request does not contain a hosts element, the user account will be unrestricted.

The status code in the administrator response will indicate whether or not the requested action was successfully completed.

Command elements:

Example:

C:

<modify_user>
  <name>Foobar</name>
  <password modify="0"></password>
  <role>Admin</role>
  <hosts allow="0"></hosts>
</modify_user>

A:

<modify_user_response status="200" status_text="OK"/>

sync_feed

The client uses the "sync_feed" command to request a synchronization with the NVT feed service the administrator uses.

The status code in the administrator response will indicated whether or not the requested action has been initiated.

Command elements:

Example:

C:

<sync_feed/>

A:

<sync_feed_response status="202" status_text="OK, request submitted"/>

History