OpenVAS Change Request #28: OpenVAS Management Protocol (OMP)

Status: Voted +8. Released with openvas-manager 1.0.0.

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

Purpose

To introduce a new protocol for the communication between OpenVAS client and server applications that finally does drop the design flaws of NTP/OTP.

To allow for consistent, privilege-separating server-side management of user data like tasks, reports etc.

To allow for easy HTTP/XML-based implementations.

References

(none)

Rationale

The OpenVAS server and client use the OpenVAS Transfer Protocol (OTP) for communication. OTP is a descendant of the Nessus Transfer Protocol (NTP). OTP cleaned up unused, dangerous and inconsistent elements from NTP and introduced some small helpful extra-features, but it still inherited various design weaknesses of NTP such as broken escaping, newlines etc. OMP aims to implement existing functionality in a clean and modern manner and to be open for future improvements.

The design goals for this new protocol should be:

• Allow for easy and fast parsing of the protocol while retaining human-readability for debugging and development purposes.
• Make the protocol as stateless as possible to avoid unnecessary delays in the communication process.
• Allow for easy integration into other protocols and communication channels.

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.

Effects

Client and server elements need to be provided with the ability to communicate via OMP. On the OpenVAS-Client-side this can be done by offering OMP as an alternative protocol and thus OpenVAS-Client will remain compatible with OTP servers.

It will be possible to develop "light" clients without local storage because OMP offers to store user data.

The server side will need a comprehensive re-design to allow for the features of OMP, namely the user data. For transistion phase it is fairly simple to translate OMP into OTP which essentially means that it is possible to leave openvasd untouched and place a OMP layer between clients and openvasd. Consequently, OTP will always be available as a fall back and thus users are not confronted with a mandatory change of concept, they can decide on their own.

Design and Implementation

The main implementation strategy is to implement a new layer between openvasd and the clients as "openvas-manager" which uses OMP to communicate with the clients, stores user data and communicates via OTP with openvasd. based on this, OpenVAS-Client can be provided with OMP abilities additional to OTP. Eventually openvasd can be drastically minimized to do the core job only and thus allow for privilege separation.

Protocol Design

The OpenVAS Management Protocol is intended for use between OpenVAS clients and an OpenVAS manager component.

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.

One design consideration is to keep the actual syntax adaptable for different communication technologies. The present specification assumes a simple XML-based communication protocol. Possible alternatives are implementations of the OMP functionality using the very same keywords e.g. based on HTTP GET/POST technology. Thus, any implementation of OMP should keep the actual communication technology separate from the implementation of the semantic functionality.

Human-readable strings are encoded as UTF-8.

Files or other binary data is expected to be Base64 encoded.

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

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

For a client, using OMP centers around creating and manipulating resources. The key resource is the task. A task defines a network vulnerability scan. The scan can be performed by running the task, for example with the start_task command. A task is created with the create_task command by combining at least two of the other resources: a config and a target.

Numerical response codes

The OpenVAS manager uses numerical response codes to indicate whether a command issued by the client could be executed successfully. The response codes are very 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 manager during the processing of this command.
Responses are expected to include helpful information whenever possible, like the ID of the resulting report when a task is started.
Implementations which transfer OMP using a response-code aware protocol (e.g. HTTP) might want to consider including this status code in the message generated by this protocol.

Unique ID scheme

The protocol uses random UUIDs as described in RFC 4122.

Authentication

The client is expected to execute an authentication command at the beginning of each connection. The only commands that can precede authentication are get_version and commands. The authenticate command looks like the following:

<authentication>
  <credentials>
    <username>FooBar</username>
    <password>276LkeFHJWnCaD6ynSlP6mnf9</password>
  </credentials>
</authentication>

In future version of the protocol, other types of credentials are to be expected. If the credentials supplied by the client are not sufficient, the manager must reply with:

<authentication_response status="400" status_text="Authentication failed" />

Summary of Protocol Primitives / Commands

authenticate	Authenticate with the manager.
commands	Execute a list of OMP commands.
create_agent	Create an agent.
create_config	Create a scan configuration.
create_escalator	Create an escalator.
create_lsc_credential	Create a local security check credential.
create_note	Create a note.
create_override	Create an override.
create_schedule	Create a schedule.
create_target	Create a target.
create_task	Create a new task.
delete_agent	Delete an agent.
delete_config	Delete a config.
delete_escalator	Delete an escalator.
delete_lsc_credential	Delete a local security check credential.
delete_note	Delete a note.
delete_override	Delete an override.
delete_report	Delete an existing report.
delete_schedule	Delete a schedule.
delete_target	Delete a target.
delete_task	Delete an existing task.
get_agents	Get all agents.
get_configs	Get all configs.
get_dependencies	Get dependencies for all available NVTs.
get_escalators	Get all escalators.
get_lsc_credentials	Get all local security check credentials.
get_notes	Get all notes.
get_nvts	Get all available NVTs.
get_nvt_families	Get a list of all NVT families.
get_nvt_feed_checksum	Get checksum for entire NVT collection.
get_overrides	Get all overrides.
get_preferences	Get preferences for all available NVTs.
get_reports	Get all reports.
get_results	Get results.
get_schedules	Get all schedules.
get_system_reports	Get all system reports.
get_target_locators	Get configured target locators.
get_targets	Get all targets.
get_tasks	Get task status information.
get_version	Get the OpenVAS Manager Protocol version.
help	Get the help text.
modify_config	Update an existing config.
modify_note	Modify an existing note.
modify_override	Modify an existing override.
modify_report	Modify an existing report.
modify_task	Update an existing task.
pause_task	Pause a running task.
resume_or_start_task	Resume task if stopped, else start task.
resume_paused_task	Resume a paused task.
resume_stopped_task	Resume a stopped task.
start_task	Manually start an existing task.
stop_task	Stop a running task.
test_escalator	Run an escalator.

Details of Protocol Primitives / Commands

authenticate

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

Command elements:

• <credentials>
  • <username> is the login name of the user.
  • <password> is the user's password.

Example:

C:

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

M:

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

M:

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

M:

<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 OMP commands in the given sequence. The reply contains the result of each command, in the same order as the given commands.

Command elements:

• Any OMP command.

Example:

C:

<commands>
  <create_task>
    <rcfile>asdf3235saf3kjBVF...</rcfile>
    <name>Scan Webserver</name>
    <comment>Hourly scan of the webserver</comment>
  </create_task>
</commands>

M:

<commands_response status="200" status_text="OK">
  <create_task_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />
</commands_response>

create_agent

The client uses the create_agent command to create a new agent. This command must include an installer for the agent and an human-readable identifier assigned by the user. The command may include a comment, an install HOWTO and a user HOWTO. The installer may include a signature.

If there was no error with the command sent by the client, the manager will assign a unique ID to the agent and include this ID in its reply to the client.

Command elements:

• <installer> is a file that installs the agent on a target machine. The file must be Base64 encoded.
  • <signature> is a detached OpenPGP signature of the installer.
• <name> is a human-readable identifier.
• <comment> is a human-readable text.
• <howto_install> is a file describing how to install the agent. The file must be Base64 encoded.
• <howto_use> is a file describing how to use the agent. The file must be Base64 encoded.

Example:

C:

<create_agent>
  <installer>
    asdf3235saf3kjBVF...
    <signature>iEYEABECAAYFA...</signature>
  </installer>
  <name>SLAD</name>
</create_agent>

M:

<create_agent_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_agent_response status="4xx" />

M:

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

create_config

The client uses the create_config command to create a new config. This command can be called in three ways:

• With a copy element. The text of the element must be the ID of an existing config. In this case a name element is required. The new config is a copy of the existing config, with the given name.
• With an embedded get_configs response element. The config is created as described in the element.
• With an rcfile element. The config is created as described in the file. In this case a name element is required. The new config is given this name.

If there was no error with the command sent by the client, the manager will assign a unique ID to the config and include this ID in its reply to the client.

Command elements:

• <rcfile> is a file that defines the config. This file is in the openvasrc format. The file must be Base64 encoded.
• <comment> is a human-readable text.
• <copy> is the UUID of an existing config.
• <get_configs_response> is an element as returned by get_configs.
• <name> is a human-readable identifier.

Examples:

C:

<create_config>
  <copy>daba56c8-73ec-11df-a475-002264764cea</copy>
  <name>Full</name>
</create_config>

M:

<create_config_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_config_response status="4xx" />

M:

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

C:

<create_config>
  <rcfile>asdf3235saf3kjBVF...</rcfile>
  <name>Full</name>
</create_config>

M:

<create_config_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

C:

<create_config>
  <get_configs_response>
    <config id="daba56c8-73ec-11df-a475-002264764cea">
      <name>Full and fast</name>
      ...
    </config>
  </get_configs_response>
</create_config>

M:

<create_config_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

create_escalator

The client uses the create_escalator command to create a new escalator. This command must include a human-readable identifier assigned by the user, an escalation condition, an escalation event and an escalation method. The command may include a comment.

If there was no error with the command sent by the client, the manager will assign a unique ID to the escalator and include this ID in its reply to the client.

Command elements:

• <name> is a human-readable identifier.
• <comment> is a human-readable text.
• <condition> is the condition that must be satisfied for escalation, e.g. "Threat level at least".
  • <data> is some data that defines the condition, e.g. "High".
  • <name> is the name of the condition data, e.g. "level".
• <event> is the event that must happen for escalation, e.g. "Task run status changed".
  • <data> is some data that defines the event, e.g. "Done".
  • <name> is the name of the event data, e.g. "status".
• <method> is the method by which escalation must occur, e.g. "Email".
  • <data> is some data that defines the method, e.g. "sally@example.org".
  • <name> is the name of the method data, e.g. "to_address".

Example:

C:

<create_escalator>
  <name>emergency</name>
  <condition>
    Threat level at least
    <data>
      <name>level</name>
      High
    </data>
  </condition>
  <event>
    Task run status changed
    <data>
      <name>status</name>
      Done
    </data>
  </event>
  <method>
    Email
    <data>
      <name>to_address</name>
      sally@example.org
    </data>
    <data>
      <name>from_address</name>
      bob@example.org
    </data>
  </method>
</create_escalator>

M:

<create_escalator_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_escalator_response status="4xx" />

M:

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

create_lsc_credential

The client uses the create_lsc_credential command to create a new LSC credential. This command must include a human-readable identifier assigned by the user, and a login name. The command may include a comment and a password.

If the command includes a password, then the manager creates a password only credential, otherwise the manager creates a key-based credential.

If there was no error with the command sent by the client, the manager will assign a unique ID to the credential and include this ID in its reply to the client.

Command elements:

• <name> is a human-readable identifier.
• <login> is a login name.
• <password> is a password string.
• <comment> is a human-readable text.

Example:

C:

<create_lsc_credential>
  <name>cluster sally</name>
  <login>sally</login>
  <password>secret</password>
  <comment>Sally's login to the cluster.</comment>
</create_lsc_credential>

M:

<create_lsc_credential_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_lsc_credential_response status="4xx" />

M:

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

create_note

The client uses the create_note command to create a new note. This command must include a human-readable text and an NVT. The command may include a comment, a host list, a threat, a port, a task and a result.

If there was no error with the command sent by the client, the manager will assign a unique ID to the note and include this ID in its reply to the client.

Command elements:

• <text> is a human-readable text.
• <comment> is a human-readable text.
• <hosts> is a textual list of hosts.
• <nvt> is an empty element with an oid attribute.
• <port> is a port.
• <threat> is a threat.
• <task> is an empty element with an id attribute.
• <result> is an empty element with an id attribute.

Example:

C:

<create_note>
  <text>This issue should be resolved after the upgrade.</text>
  <nvt>1.3.6.1.4.1.25623.1.0.10330</nvt>
  <result>254cd3ef-bbe1-4d58-859d-21b8d0c046c6</result>
</create_note>

M:

<create_note_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_note_response status="4xx" />

M:

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

create_override

The client uses the create_override command to create a new override. This command must include a human-readable text, a new threat and an NVT. The command may include a comment, a host list, a threat, a port, a task and a result.

If there was no error with the command sent by the client, the manager will assign a unique ID to the override and include this ID in its reply to the client.

Command elements:

• <text> is a human-readable text.
• <comment> is a human-readable text.
• <hosts> is a textual list of hosts.
• <nvt> is an empty element with an oid attribute.
• <port> is a port.
• <threat> is a threat.
• <new_threat> is a threat.
• <task> is an empty element with an id attribute.
• <result> is an empty element with an id attribute.

Example:

C:

<create_override>
  <text>This is actually of little concern.</text>
  <nvt>1.3.6.1.4.1.25623.1.0.10330</nvt>
  <new_threat>Low</new_threat>
  <result>254cd3ef-bbe1-4d58-859d-21b8d0c046c6</result>
</create_override>

M:

<create_override_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_override_response status="4xx" />

M:

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

create_schedule

The client uses the create_schedule command to create a new schedule. This command must include a human-readable identifier assigned by the user, a first time, a period and a duration. The command may include a comment.

If there was no error with the command sent by the client, the manager will assign a unique ID to the schedule and include this ID in its reply to the client.

Command elements:

• <name> is a human-readable identifier.
• <comment> is a human-readable text.
• <first_time>
  • <minute> is an integer.
  • <hour> is an integer.
  • <day_of_month> is an integer.
  • <month> is an integer.
  • <year> is an integer.
• <duration> is an integer.
  • <unit> is the unit of duration: second, minute, hour, day, week, month, year or decade.
• <period> is an integer.
  • <unit> is the unit of period: second, minute, hour, day, week, month, year or decade.

Example:

C:

<create_schedule>
  <name>Every night</name>
  <first_time>
    <day_of_month>1</day_of_month>
    <hour>0</hour>
    <minute>0</minute>
    <month>1</month>
    <year>2011</year>
  </first_time>
  <duration>
    3
    <unit>hour</unit>
  </duration>
  <period>
    1
    <unit>day</unit>
  </period>
</create_schedule>

M:

<create_schedule_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_schedule_response status="4xx" />

M:

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

create_target

The client uses the create_target command to create a new target. This command must include a human-readable identifier assigned by the user and a list of hosts. If the list of hosts is empty, the command must also include a target locator. The command may always include a comment and an LSC credential.

If there was no error with the command sent by the client, the manager will assign a unique ID to the target and include this ID in its reply to the client.

Command elements:

• <name> is a human-readable identifier.
• <comment> is a human-readable text.
• <hosts> is a optionally empty textual list of hosts.
• <lsc_credential> is an empty element with an id attribute.
• <target_locator> is a name of a target locator.
  • <username> is a login name.
  • <password> is a password.

Example:

C:

<create_target>
  <name>All GNU/Linux machines</name>
  <hosts>192.168.1.0/24</hosts>
</create_target>

M:

<create_target_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_target_response status="4xx" />

M:

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

create_task

The client uses the create_task command to create a new task. This command must always include an human-readable identifier assigned by the user. The command must also include either a config and target or a file specifying the task. The command may always include a comment. If the command includes a config and target, it may also include an escalator and schedule.

The file version of the command is special support for OpenVAS-Client, and may be removed in upcoming versions.

If there was no error with the command sent by the client, the manager will assign a unique ID to the task and include this ID in its reply to the client.

Command elements:

• <name> is a human-readable identifier.
• <comment> is a human-readable text.
• <config> is an empty element with an id attribute.
• <target> is an empty element with an id attribute.
• <escalator> is an empty element with an id attribute.
• <schedule> is an empty element with an id attribute.
• <rcfile> is a file describing the task. As of OMP 1.0, this file is in the openvasrc format. The file must be Base64 encoded.

Examples:

C:

<create_task>
  <name>Scan Webserver</name>
  <comment>Hourly scan of the webserver</comment>
  <config id="daba56c8-73ec-11df-a475-002264764cea"/>
  <target id="b493b7a8-7489-11df-a3ec-002264764cea"/>
</create_task>

M:

<create_task_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_task_response status="4xx" />

M:

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

C:

<create_task>
  <rcfile>asdf3235saf3kjBVF...</rcfile>
  <name>Scan Webserver</name>
  <comment>Hourly scan of the webserver</comment>
</create_task>

M:

<create_task_response status="201" status_text="OK, resource created" id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

M:

<create_task_response status="4xx" />

M:

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

delete_agent

The client uses the delete_agent command to delete an existing agent. This command must include the ID of an existing agent.

If there was no error with the command sent by the client, the manager will delete the agent and will reply with a response code indicating success.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "agent_id" is the ID of the agent which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_agent agent_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" />

M:

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

M:

<delete_agent_response status="4xx" />

M:

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

delete_config

The client uses the delete_config command to delete an existing config. This command must include the ID of an existing config.

If there was no error with the command sent by the client, the manager will delete the config and will reply with a response code indicating success.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "config_id" is the ID of the config which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_config config_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" />

M:

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

M:

<delete_config_response status="4xx" />

M:

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

delete_escalator

The client uses the delete_escalator command to delete an existing escalator. This command must include the ID of an existing escalator.

If there was no error with the command sent by the client, the manager will delete the escalator and will reply with a response code indicating success.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "escalator_id" is the ID of the escalator which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_escalator escalator_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" />

M:

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

M:

<delete_escalator_response status="4xx" />

M:

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

delete_lsc_credential

The client uses the delete_lsc_credential command to delete an existing LSC credential. This command must include the ID of an existing LSC credential.

If there was no error with the command sent by the client, the manager will delete the LSC credential and will reply with a response code indicating success.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "lsc_credential_id" is the ID of the LSC credential which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_lsc_credential lsc_credential_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" />

M:

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

M:

<delete_lsc_credential_response status="4xx" />

M:

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

delete_note

The client uses the delete_note command to delete an existing note. This command must include the ID of an existing note.

If there was no error with the command sent by the client, the manager will delete the note and will reply with a response code indicating success.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "note_id" is the ID of the note which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_note note_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" />

M:

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

M:

<delete_note_response status="4xx" />

M:

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

delete_override

The client uses the delete_override command to delete an existing override. This command must include the ID of an existing override.

If there was no error with the command sent by the client, the manager will delete the override and will reply with a response code indicating success.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "override_id" is the ID of the override which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_override override_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" />

M:

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

M:

<delete_override_response status="4xx" />

M:

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

delete_report

The client uses the delete_report command to delete an existing report. This command must include the ID of an existing report.

If there was no error with the command sent by the client, the manager will delete the report and will reply with a response code indicating success.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "report_id" is the ID of the report which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_report report_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" />

M:

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

M:

<delete_report_response status="4xx" />

M:

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

delete_schedule

The client uses the delete_schedule command to delete an existing schedule. This command must include the ID of an existing schedule.

If there was no error with the command sent by the client, the manager will delete the schedule and will reply with a response code indicating success.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "schedule_id" is the ID of the schedule which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_schedule schedule_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" />

M:

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

M:

<delete_schedule_response status="4xx" />

M:

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

delete_target

The client uses the delete_target command to delete an existing target. This command must include the ID of an existing target.

If there was no error with the command sent by the client, the manager will delete the target and will reply with a response code indicating success.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "target_id" is the ID of the target which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_target target_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" />

M:

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

M:

<delete_target_response status="4xx" />

M:

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

delete_task

The client uses the delete_task command to delete an existing task. This command must include the ID of an existing task.

If there was no error with the command sent by the client, the manager will delete the task and all relevant objects (reports etc.) and will reply with a response code indicating success and the ID of the task that was deleted.

Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the manager.

Command attributes:

• "task_id" is the ID of the task which should be deleted.

Command elements:

• (n/a)

Example:

C:

<delete_task task_id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6" />

< b>M:

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

M:

<delete_task_response status="4xx" />

M:

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

get_agents

The client uses the get_agents command to get agent information. This command may include the ID of an existing agent, a format, a sort order and a sort field.

If there was no error with the command sent by the client, the manager will reply with a list of agents to the client.

Command attributes:

• "agent_id" is the ID of an agent.
• "format" is either "installer", "howto_install" or "howto_use".
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Examples:

C:

<get_agents />

M:

<get_agents_response status="200" status_text="OK">
  <agent id="c33864a9-d3fd-44b3-8717-972bfb01dfcf">
    <name>Custom Scan Agent</name>
    <comment>Custom agent for use on the Web servers.</comment>
    <in_use>1</in_use>
    <installer><trust>yes</trust></installer>
  </agent>
  ...
</get_agents_response>

C:

<get_agents agent_id="c33864a9-d3fd-44b3-8717-972bfb01dfcf" format="installer"/>

M:

<get_agents_response status="200" status_text="OK">
  <agent id="c33864a9-d3fd-44b3-8717-972bfb01dfcf">
    <name>Custom Scan Agent</name>
    <comment>Custom agent for use on the Web servers.</comment>
    <in_use>1</in_use>
    <package format="installer">
      <filename>agent.deb</filename>
      CgoKCgoKCgoKCgoKCSAgI...
    </package>
  </agent>
</get_agents_response>

get_configs

The client uses the get_configs command to get config information. This command may include the ID of an existing config, a families flag, an export flag, a preferences flag, a sort order and a sort field.

If there was no error with the command sent by the client, the manager will reply with a list of configs to the client.

Command attributes:

• "config_id" is the ID of a config.
• "families" is boolean (0 is false, anything else is true).
• "preferences" is boolean (0 is false, anything else is true).
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Examples:

C:

<get_configs />

M:

<get_configs_response status="200" status_text="OK">
  <config id="daba56c8-73ec-11df-a475-002264764cea">
    <name>Full and fast</name>
    <comment>All NVT's; optimized by using previously collected information.</comment>
    <family_count>
      4
      <growing>1</growing>
    </family_count>
    <nvt_count>
      12
      <growing>1</growing>
    </nvt_count>
    <in_use>1</in_use>
    <tasks>
      <task id="13bb418a-4220-4575-b35b-ec398bff7417">
        <name>Web Servers</name>
      </task>
      ...
    </tasks>
  </config>
  ...
</get_configs_response>

C:

<get_configs config_id="daba56c8-73ec-11df-a475-002264764cea" preferences="1" families="1" />

M:

<get_configs_response status="200" status_text="OK">
  <config id="daba56c8-73ec-11df-a475-002264764cea">
    <name>Full and fast</name>
    <comment>All NVT's; optimized by using previously collected information.</comment>
    <family_count>
      4
      <growing>1</growing>
    </family_count>
    <nvt_count>
      12
      <growing>1</growing>
    </nvt_count>
    <in_use>1</in_use>
    <tasks>
      <task id="13bb418a-4220-4575-b35b-ec398bff7417">
        <name>Web Servers</name>
      </task>
      ...
    </tasks>
    <families>
      <family>
        <name>Credentials</name>
        <nvt_count>8</nvt_count>
        <max_nvt_count>8</max_nvt_count>
        <growing>1</growing>
      </family>
      ...
    </families>
    <preferences>
      <preference>
        <nvt oid="1.3.6.1.4.1.25623.1.0.10330">
          <name>Services</name>
        </nvt>
        <name>Network connection timeout :</name>
        <type>entry</type>
        <value>5</value>
      </preference>
      ...
    </preferences>
  </config>
  ...
</get_configs_response>

get_dependencies

The client uses the get_dependencies command to request the dependencies for one or all NVTs available through this manager. This command may include an NVT OID.

If the manager possesses such a collection, it will reply with a response code indicating success, and the dependencies. If the manager cannot access a list of available NVTs at present, it will reply with the 503 response.

Command attributes:

• "nvt_oid" is the OID of an NVT.

Example:

C:

<get_dependencies/>

M:

<get_dependencies_response status="200" status_text="OK">
  <nvt oid="1.3.6.1.4.1.25623.1.0.114664">
    <name>Dependency Test</name>
    <requires>
      <nvt oid="1.3.6.1.4.1.25623.1.0.114663">
        <name>File Upload Test</name>
      </nvt>
    </requires>
  </nvt>
  ...
</get_dependencies_response>

C:

<get_dependencies nvt_oid="1.3.6.1.4.1.25623.1.0.114664" />

M:

<get_dependencies_response status="200" status_text="OK">
  <nvt oid="1.3.6.1.4.1.25623.1.0.114664">
    <name>Dependency Test</name>
    <requires>
      <nvt oid="1.3.6.1.4.1.25623.1.0.114663">
        <name>File Upload Test</name>
      </nvt>
    </requires>
  </nvt>
</get_dependencies_response>

get_escalators

The client uses the get_escalators command to get escalator information. This command may include the ID of an existing escalator, a sort order and a sort field.

If there was no error with the command sent by the client, the manager will reply with a list of escalators to the client.

Command attributes:

• "escalator_id" is the ID of an escalator.
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Examples:

C:

<get_escalators />

M:

<get_escalators_response status="200" status_text="OK">
  <escalator id="6181e65d-8ba0-4937-9c44-8f2b10b0def7">
    <name>Team alert</name>
    <comment></comment>
    <in_use>1</in_use>
    <condition>
      Threat level at least
      <data>
        <name>level</name>
        High
      </data>
    </condition>
    <event>
      Task run status changed
      <data>
        <name>status</name>
        Done
      </data>
    </event>
    <method>
      Email
      <data>
        <name>to_address</name>
        team@example.org
      </data>
      <data>
        <name>from_address</name>
        admin@example.org
      </data>
      <data>
        <name>notice</name>
        0
      </data>
    </method>
  </escalator>
  ...
</get_escalators_response>

get_lsc_credentials

The client uses the get_lsc_credentials command to get LSC credential information. This command may include the ID of an existing LSC credential, a format, a sort order and a sort field.

If there was no error with the command sent by the client, the manager will reply with a list of LSC credentials to the client.

Command attributes:

• "lsc_credential_id" is the ID of an LSC credential.
• "format" is a string describing the requested format.
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Examples:

C:

<get_lsc_credentials />

M:

<get_lsc_credentials_response status="200" status_text="OK">
  <lsc_credential id="c33864a9-d3fd-44b3-8717-972bfb01dfcf">
    <name>sally</name>
    <login>sally</login>
    <comment></comment>
    <in_use>0</in_use>
    <type>gen</type>
    <targets></targets>
  </lsc_credential>
  <lsc_credential id="8e305b0b-260d-450d-91a8-dadf0b144e15">
    <name>bob</name>
    <login>bob</login>
    <comment>Bob on the web server.</comment>
    <in_use>1</in_use>
    <type>pass</type>
    <targets>
      <target id="1f28d970-17ef-4c69-ba8a-13827059f2b9">
        <name>Web server</name>
      </target>
    </targets>
  </lsc_credential>
  ...
</get_lsc_credentials_response>

C:

<get_lsc_credentials lsc_credential_id="8e305b0b-260d-450d-91a8-dadf0b144e15" format="key"/>

M:

<get_lsc_credentials_response status="200" status_text="OK">
  <lsc_credential id="8e305b0b-260d-450d-91a8-dadf0b144e15">
    <name>bob</name>
    <login>bob</login>
    <comment>Bob on the web server.</comment>
    <in_use>1</in_use>
    <type>pass</type>
    <targets>
      <target id="1f28d970-17ef-4c69-ba8a-13827059f2b9">
        <name>Web server</name>
      </target>
    </targets>
    <public_key>
      ssh-rsa AAAAB3...Z64IcQ== Key generated by OpenVAS Manager
    </public_key>
  </lsc_credential>
</get_lsc_credentials_response>

C:

<get_lsc_credentials lsc_credential_id="8e305b0b-260d-450d-91a8-dadf0b144e15" format="deb"/>

M:

<get_lsc_credentials_response status="200" status_text="OK">
  <lsc_credential id="8e305b0b-260d-450d-91a8-dadf0b144e15">
    <name>bob</name>
    <login>bob</login>
    <comment>Bob on the web server.</comment>
    <in_use>1</in_use>
    <type>pass</type>
    <targets>
      <target id="1f28d970-17ef-4c69-ba8a-13827059f2b9">
        <name>Web server</name>
      </target>
    </targets>
    <package format="deb">ITxhcmNoPgpk...DmvF0AKAAACg==</package>
  </lsc_credential>
</get_lsc_credentials_response>

get_notes

The client uses the get_notes command to get note information. This command may include the ID of an existing note, a details flag, a result flag, an NVT, a task, a sort order and a sort field.

If there was no error with the command sent by the client, the manager will reply with a list of notes to the client.

Command attributes:

• "note_id" is the ID of a note.
• "nvt_oid" is the OID of an NVT.
• "task_id" is the ID of a task.
• "details" is boolean (0 is false, anything else is true).
• "result" is boolean (0 is false, anything else is true).
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Examples:

C:

<get_notes />

M:

<get_notes_response status="200" status_text="OK">
  <note id="b76b81a7-9df8-42df-afff-baa9d4620128">
    <nvt oid="1.3.6.1.4.1.25623.1.0.75">
      <name>Test NVT: long lines</name>
    </nvt>
    <text excerpt="0">This is the full text of the note.</text>
    <orphan>1</orphan>
  </note>
  ...
</get_notes_response>

C:

<get_notes note_id="7f618bbb-4664-419e-9bbf-367d93954cb0" details="1" result="1"/>

M:

<get_notes_response status="200" status_text="OK">
  <note id="7f618bbb-4664-419e-9bbf-367d93954cb0">
    <nvt oid="1.3.6.1.4.1.25623.1.0.77">
      <name>Test NVT: control chars in report result</name>
    </nvt>
    <creation_time>Sun Jun 27 08:49:46 2010</creation_time>
    <modification_time>Sun Jun 27 08:49:46 2010</modification_time>
    <text>note fixed to result</text>
    <hosts>127.0.0.1</hosts>
    <port>general/tcp</port>
    <threat>Medium</threat>
    <task id="40b236a9-2b0f-4813-b8c7-bc2b98d9d7e4">
      <name>test</name>
    </task>
    <orphan>0</orphan>
    <result id="0c95e6b3-1100-4dfd-88f1-4bed1fad29de">
      <subnet>127.0.0.1</subnet>
      <host>127.0.0.1</host>
      <port>general/tcp</port>
      <nvt oid="1.3.6.1.4.1.25623.1.0.77">
        <name>Test NVT: control chars in report result</name>
        <cvss_base></cvss_base>
        <risk_factor></risk_factor>
      </nvt>
      <threat>Medium</threat>
      <description>Warning with control char between fullstops: . .</description>
    </result>
  </note>
  ...
</get_notes_response>

get_nvts

The client uses the get_nvts command to request NVT information. This command may include one of an NVT OID and a family name. This command may always include a details flag, a config, a sort order and a sort field. If the command includes a details flag, it may also include timeout, preference_count and preferences flags. The timeout and preferences flags require a config.

The NVT OID, family name and config attributes limit the listing to a single NVT or all NVTs in a particular family and/or config. With the preferences flag the manager includes in the listing, the values of each listed NVT's preferences for the given config. The timeout flag does the same for the special timeout preference.

If the manager possesses an NVT collection, it will reply with a response code indicating success, and the NVT information. If the manager cannot access a list of available NVTs at present, it will reply with the 503 response.

Command attributes:

• "nvt_oid" is the OID of an NVT.
• "details" is boolean (0 is false, anything else is true).
• "preferences" is boolean (0 is false, anything else is true).
• "preference_count" is boolean (0 is false, anything else is true).
• "timeout" is boolean (0 is false, anything else is true).
• "config_id" is the ID of a config.
• "family" is the name of a family.
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Command elements:

• (n/a)

Example:

C:

<get_nvts details="1" timeout="1" preference_count="1" preferences="1"/>

M:

<get_nvts_response status="200" status_text="OK">
  <nvt oid="1.3.6.1.4.1.25623.1.7.13005">
    <name>Services</name>
    <category>Services</category>
    <copyright>GNU GPL v2</copyright>
    <description>This script attepts to detects with service is running on which port.</description>
    <summary>Find what is listening on which port</summary>
    <family>Service detection</family>
    <version>$Revision: 1852 $</version>
    <cvss_base></cvss_base>
    <risk_factor>None</risk_factor>
    <cve_id>NOCVE</cve_id>
    <bugtraq_id>NOBID</bugtraq_id>
    <xrefs>NOXREF</xrefs>
    <fingerprints>NOSIGNKEYS</fingerprints>
    <tags>NOTAG</tags>
    <preference_count>-1</preference_count>
    <timeout></timeout>
    <checksum>
      <algorithm>md5</algorithm>
      2397586ea5cd3a69f953836f7be9ef7b
    </checksum>
    <preferences>
      <timeout></timeout>
      <preference>
        <nvt oid="1.3.6.1.4.1.25623.1.0.10330">
          <name>Services</name>
        </nvt>
        <name>Network connection timeout :</name>
        <type>entry</type>
        <value>5</value>
      </preference>
      ...
    </preferences>
  </nvt>
  <nvt oid="1.3.6.1.4.1.25623.1.7.13006">
    <name>FooBar 21</name>
    <category>Services</category>
    <copyright>GNU GPL v2</copyright>
    <description>This script detects whether the FooBar 2.1 XSS vulnerability is present.</description>
    ...
  </nvt>
  ...
</get_nvts_response>

C:

<get_nvts nvt_oid="1.3.6.1.4.1.25623.1.0.10330" />

M:

<get_nvts_response status="200" status_text="OK">
  <nvt oid="1.3.6.1.4.1.25623.1.0.10330">
    <name>Services</name>
    <checksum>
      <algorithm>md5</algorithm>
      2397586ea5cd3a69f953836f7be9ef7b
    </checksum>
  </nvt>
</get_nvts_response>

get_nvt_families

The client uses the get_nvt_families command to get NVT family information. This command may include a sort order.

If there was no error with the command sent by the client, the manager will reply with a list of families to the client.

Command attributes:

• "sort_order" is "descending" for descending, anything else for ascending.

Examples:

C:

<get_nvt_families />

M:

<get_nvt_families_response status="200" status_text="OK">
  <families>
    <family>
      <name>Credentials</name>
      <max_nvt_count>8</max_nvt_count>
    </family>
    <family>
      <name>Port scanners</name>
      <max_nvt_count>12</max_nvt_count>
    </family>
    ...
  </families>
</get_nvt_families_response>

get_nvt_feed_checksum

The client uses the get_nvt_feed_checksum command to request a checksum for the complete NVT collection available through this manager. The client may specify an algorithm to be used for computing this checksum.

If the specified algorithm is not implemented in the manager, then the manager will reply with a response code in the 4xx range.

If the client does not specify a checksum algorithm, the manager is expected to use the MD5 algorithm for computing the checksum.

If the manager possesses such a collection, it will reply with a response code indicating success, and the checksum over all NVT files. If the manager cannot access a list of available NVTs at present, it will reply with the 503 response.

Command attributes:

• "algorithm" is the algorithm which should be used for computing the checksum.

Command elements:

• (n/a)

Example:

C:

<get_nvt_feed_checksum algorithm="md5" />

M:

<get_nvt_feed_checksum_response status="200" status_text="OK">
  <checksum algorithm="md5">931db829a06b9a440a2ecaeb68c03715</checksum>
</get_nvt_feed_checksum_response>

get_overrides

The client uses the get_overrides command to get override information. This command may include the ID of an existing override, a details flag, a result flag, an NVT, a task, a sort order and a sort field.

If there was no error with the command sent by the client, the manager will reply with a list of overrides to the client.

Command attributes:

• "override_id" is the ID of an override.
• "nvt_oid" is the OID of an NVT.
• "task_id" is the ID of a task.
• "details" is boolean (0 is false, anything else is true).
• "result" is boolean (0 is false, anything else is true).
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Command elements:

• (n/a)

Examples:

C:

<get_overrides />

M:

<get_overrides_response status="200" status_text="OK">
  <override id="b76b81a7-9df8-42df-afff-baa9d4620128">
    <nvt oid="1.3.6.1.4.1.25623.1.0.75">
      <name>Test NVT: long lines</name>
    </nvt>
    <text excerpt="0">This is the full text of the override.</text>
    <threat>High</threat>
    <new_threat>Log</new_threat>
    <orphan>1</orphan>
  </override>
  ...
</get_overrides_response>

C:

<get_overrides override_id="7f618bbb-4664-419e-9bbf-367d93954cb0" details="1"/>

M:

<get_overrides_response status="200" status_text="OK">
  <override id="7f618bbb-4664-419e-9bbf-367d93954cb0">
    <nvt oid="1.3.6.1.4.1.25623.1.0.77">
      <name>Test NVT: control chars in report result</name>
    </nvt>
    <creation_time>Sun Jun 27 08:49:46 2010</creation_time>
    <modification_time>Sun Jun 27 08:49:46 2010</modification_time>
    <text>override fixed to result</text>
    <hosts>127.0.0.1</hosts>
    <port>general/tcp</port>
    <threat>Medium</threat>
    <new_threat>Low</new_threat>
    <task id="40b236a9-2b0f-4813-b8c7-bc2b98d9d7e4">
      <name>test</name>
    </task>
    <orphan>0</orphan>
    <result id="0c95e6b3-1100-4dfd-88f1-4bed1fad29de" />
  </override>
  ...
</get_overrides_response>

get_preferences

The client uses the get_preferences command to request NVT preferences. This command may include an NVT OID, a config ID and a preference name.

If the manager possesses such a collection, it will reply with a response code indicating success, and the NVT preferences. If the manager cannot access a list of available NVTs at present, it will reply with the 503 response.

Command attributes:

• "nvt_oid" is the OID of an NVT.
• "config_id" is the ID of a config.
• "preference" is the name of a preference.

Command elements:

• (n/a)

Example:

C:

<get_preferences/>

M:

<get_preferences_response status="200" status_text="OK">
  <preference>
    <name>Services[entry]:Network connection timeout :</name>
    <value>5</value>
  </preference>
  ...
</get_preferences_response>

C:

<get_preferences nvt_oid="1.3.6.1.4.1.25623.1.0.10330" />

M:

<get_preferences_response status="200" status_text="OK">
  <preference>
    <name>Services[entry]:Network connection timeout :</name>
    <value>5</value>
  </preference>
  ...
</get_preferences_response>

C:

<get_preferences config_id="daba56c8-73ec-11df-a475-002264764cea"/>

M:

<get_preferences_response status="200" status_text="OK">
  <preference>
    <nvt oid="1.3.6.1.4.1.25623.1.0.10330">
      <name>Services</name>
    </nvt>
    <name>Network connection timeout :</name>
    <type>entry</type>
    <value>5</value>
  </preference>
  ...
</get_preferences_response>

C:

<get_preferences config_id="daba56c8-73ec-11df-a475-002264764cea" nvt_oid="1.3.6.1.4.1.25623.1.0.10330" />

M:

<get_preferences_response status="200" status_text="OK">
  <preference>
    <nvt oid="1.3.6.1.4.1.25623.1.0.10330">
      <name>Services</name>
    </nvt>
    <name>Network connection timeout :</name>
    <type>entry</type>
    <value>5</value>
  </preference>
  ...
</get_preferences_response>

get_reports

The client uses the get_reports command to request reports. This command may include a report ID, format, first result number, maximum result count, sort order, sort field, level contraint, search phrase, minimum CVSS base constraint, notes flag, note details flag, overrides flag, override details flag and result hosts only flag.

If there was no error with the command sent by the client, the manager will reply with a response code indicating success and the report. If the report format is a binary format, the report will be in Base64 encoding.

Command attributes:

• "report_id" is the ID of the report which should be retrieved.
• "format" is a string describing the requested format.
• "first_result" is an integer.
• "max_results" is an integer.
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.
• "level" is a string that may include the characters h, m, l, g and d.
• "search_phrase" is a text phrase.
• "min_cvss_base" is a number.
• "notes" is boolean (0 is false, anything else is true).
• "notes_details" is boolean (0 is false, anything else is true).
• "overrides" is boolean (0 is false, anything else is true).
• "overrides_details" is boolean (0 is false, anything else is true).
• "result_hosts_only" is boolean (0 is false, anything else is true).

Command elements:

• (n/a)

Example:

C:

<get_reports report_id="267a3405-e84a-47da-97b2-5fa0d2e8995e" format="PDF"/>

M:

<get_reports_response status="200" status_text="OK">
  <report id="f0fdf522-276d-4893-9274-fb8699dc2270">hsisn3qaVFhkjFRG4...</report>
</get_reports_response>

C:

<get_reports report_id="267a3405-e84a-47da-97b2-5fa0d2e8995e"/>

M:

<get_reports_response status="200" status_text="OK">
  <report id="f0fdf522-276d-4893-9274-fb8699dc2270">
    <sort>
      <field>
        type
        <order>descending</order>
      </field>
    </sort>
    <filters>
      hmlgd
      <phrase></phrase>
      <notes>0</notes>
      <overrides>0</overrides>
      <apply_overrides>0</apply_overrides>
      <result_hosts_only>1</result_hosts_only>
      <min_cvss_base></min_cvss_base>
      <filter>High</filter>
      <filter>Medium</filter>
      <filter>Low</filter>
      <filter>Log</filter>
      <filter>Debug</filter>
    </filters>
    <scan_run_status>Done</scan_run_status>
    <result_count>
      10
      <filtered>10</filtered>
      <debug>0</debug>
      <hole>0</hole>
      <info>7</info>
      <log>0</log>
      <warning>3</warning>
    </result_count>
    <task id="13bb418a-4220-4575-b35b-ec398bff7417">
      <name>dik mm</name>
    </task>
    <ports start="1" max="-1">
      <port>
        general/tcp
        <host>127.0.1.1</host>
        <threat>Medium</threat>
      </port>
      ...
    </ports>
    <results start="1" max="-1">
      <result id="634f7a2e-8ca1-43b7-b6d7-0d4841449508">
        <subnet>127.0.1.1</subnet>
        <host>127.0.1.1</host>
        <port>general/tcp</port>
        <nvt oid="1.3.6.1.4.1.25623.1.0.74">
          <name>Test NVT: fields with ISO-8859-1 chars (ü)</name>
          <cvss_base>5.0</cvss_base>
          <risk_factor>Medium</risk_factor>
        </nvt>
        <threat>Medium</threat>
        <description>Test with ü umlaut Warning Port 0.</description>
      </result>
      ...
    </results>
    <scan_start>Mon Feb  1 19:11:21 2010</scan_start>
    <host_start>Mon Feb  1 19:11:21 2010<host>127.0.1.1</host></host_start>
    <host_end>Mon Feb  1 19:11:52 2010<host>127.0.1.1</host></host_end>
    <scan_end>Mon Feb  1 19:11:52 2010</scan_end>
  </report>
</get_reports_response>

get_results

The client uses the get_results command to get result information. This command may include the ID of an existing result, a task ID, a notes flag, a notes_details flag, an overrides flag, an overrides_details flag and an apply_overrides flag.

If the request includes a notes flag, an overrides flag or an apply_overrides flag and any of these is true, then the request must also include a task ID.

If there was no error with the command sent by the client, the manager will reply with a list of results to the client.

Command attributes:

• "result_id" is the ID of a result.
• "task_id" is the ID of a task.
• "notes" is boolean (0 is false, anything else is true).
• "notes_details" is boolean (0 is false, anything else is true).
• "overrides" is boolean (0 is false, anything else is true).
• "overrides_details" is boolean (0 is false, anything else is true).
• "apply_overrides" is boolean (0 is false, anything else is true).

Examples:

C:

<get_results />

M:

<get_results_response status="200" status_text="OK">
  <results>
    <result id="634f7a2e-8ca1-43b7-b6d7-0d4841449508">
      <subnet>127.0.1.1</subnet>
      <host>127.0.1.1</host>
      <port>general/tcp</port>
      <nvt oid="1.3.6.1.4.1.25623.1.0.74">
        <name>Test NVT: fields with ISO-8859-1 chars</name>
        <cvss_base>5.0</cvss_base>
        <risk_factor>Medium</risk_factor>
      </nvt>
      <threat>Medium</threat>
      <description>Test with umlaut.</description>
    </result>
    ...
  </results>
</get_results_response>

C:

<get_results result_id="cac9e7c8-c726-49fd-a710-5f99079ab93e"
             task_id="40b236a9-2b0f-4813-b8c7-bc2b98d9d7e4"
             notes="1"
             overrides="1" />

M:

<get_results_response status="200" status_text="OK">
  <results>
    <result id="cac9e7c8-c726-49fd-a710-5f99079ab93e">
      <subnet>127.0.0.1</subnet>
      <host>127.0.0.1</host>
      <port>general/tcp</port>
      <nvt oid="1.3.6.1.4.1.25623.1.0.75">
        <name>Test NVT: long lines</name>
        <cvss_base>9</cvss_base>
        <risk_factor>High</risk_factor>
      </nvt>
      <threat>High</threat>
      <description>Test with very long warning.</description>
      <original_threat>Medium</original_threat>
      <notes></notes>
      <overrides>
        <override id="b0832812-75f1-45eb-b676-99c6e6bf2b24">
          <nvt oid="1.3.6.1.4.1.25623.1.0.75">
            <name>Test NVT: long lines</name>
          </nvt>
          <text excerpt="0">Test override</text>
          <new_threat>High</new_threat>
          <orphan>0</orphan>
        </override>
      </overrides>
    </result>
  </results>
</get_results_response>

get_schedules

The client uses the get_schedules command to get schedule information. This command may include the ID of an existing schedule, a details flag, a sort order and a sort field.

If there was no error with the command sent by the client, the manager will reply with a list of schedules to the client.

Command attributes:

• "schedule_id" is the ID of a schedule.
• "details" is boolean (0 is false, anything else is true).
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Examples:

C:

<get_schedules />

M:

<get_schedules_response status="200" status_text="OK">
  <schedule id="c33864a9-d3fd-44b3-8717-972bfb01dfcf">
    <name>Overnight</name>
  </schedule>
  ...
</get_schedules_response>

C:

<get_schedules schedule_id="c33864a9-d3fd-44b3-8717-972bfb01dfcf" details="1"/>

M:

<get_schedules_response status="200" status_text="OK">
  <schedule id="c33864a9-d3fd-44b3-8717-972bfb01dfcf">
    <name>Overnight</name>
    <comment>3 hours, starting at 12h00.</comment>
    <first_time>Tue Jun 29 00:00:00 2010</first_time>
    <next_time>Tue Jun 29 00:00:00 2010</next_time>
    <period>86400</period>
    <period_months>0</period_months>
    <duration>10800</duration>
    <in_use>1</in_use>
    <tasks>
      <task id="d4daf4c4-25c7-40ac-87d3-38e489f34330">
        <name>kk</name>
      </task>
    </tasks>
  </schedule>
</get_schedules_response>

get_system_reports

The client uses the get_system_reports command to get system reports. This command may include a name, a duration and a brief flag.

If there was no error with the command sent by the client, the manager will reply with the system reports to the client.

Command attributes:

• "name" is a string describing the requested report.
• "duration" is a number of seconds.
• "brief" is boolean (0 is false, anything else is true).

Examples:

C:

<get_system_reports brief="1" />

M:

<get_system_reports_response status="200" status_text="OK">
  <system_report>
    <name>proc</name>
    <title>Processes</title>
  </system_report>
  <system_report>
    <name>load</name>
    <title>System Load</title>
  </system_report>
  <system_report>
    <name>cpu_0</name>
    <title>CPU Usage: CPU 0</title>
  </system_report>
</get_system_reports_response>

C:

<get_system_reports name="proc" />

M:

<get_system_reports_response status="200" status_text="OK">
  <system_report>
    <name>proc</name>
    <title>Processes</title>
    <report format="png" duration="86400">
      iVBORw0KGgoAAAANSUhEUgAAArkAAAEMCAYAAADAsa7vAAAABmJLR0QA/wD/AP+gvaeTAAAAB3RJ
      TUUH2gYbDCUmRM0cqQAAIABJREFUeJzsnXl4FFW+/t9mGRFpAiRsIZCEsIhJQAZRBAxpAoERh6DX
      ...
      JYQQol9Xr16Fg4PDhHdwpVeap0+frtMpegkhRF3UySWEkEksMDBQL/uloQiEEENHb1cghBBCCCFT
      DnVyCSGEEELIlEOdXEIIIYQQMuVwbt++PSoWi3Hv3j19l4UQQgghhBCtMKIOLiGEEEIImWr+B9Md
      9A602bEdAAAAAElFTkSuQmCC
    </report>
  </system_report>
</get_system_reports_response>

get_target_locators

The client uses the get_target_locators command to get target locator information.

If there was no error with the command sent by the client, the manager will reply with a list of target locators to the client.

Command elements:

• (n/a)

Examples:

C:

<get_target_locators />

M:

<get_target_locators_response status="200" status_text="OK">
  <target_locator>
    <name>ldap</name>
  </target_locator>
  ...
</get_target_locators_response>

get_targets

The client uses the get_targets command to get target information. This command may include the ID of an existing target, a tasks flag, a sort order and a sort field.

If there was no error with the command sent by the client, the manager will reply with a list of targets to the client.

Command attributes:

• "target_id" is the ID of a target.
• "tasks" is boolean (0 is false, anything else is true).
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Examples:

C:

<get_targets />

M:

<get_targets_response status="200" status_text="OK">
  <target id="b493b7a8-7489-11df-a3ec-002264764cea">
    <name>Localhost</name>
    <hosts>localhost</hosts>
    <max_hosts>1</max_hosts>
    <comment></comment>
    <in_use>7</in_use>
    <lsc_credential id="">
      <name></name>
    </lsc_credential>
  </target>
  ...
</get_targets_response>

C:

<get_targets target_id="c33864a9-d3fd-44b3-8717-972bfb01dfcf" tasks="1" />

M:

<get_targets_response status="200" status_text="OK">
  <target id="1f28d970-17ef-4c69-ba8a-13827059f2b9">
    <name>dik</name>
    <hosts>dik.example.org</hosts>
    <max_hosts>1</max_hosts>
    <comment>dik mm</comment>
    <in_use>4</in_use>
    <lsc_credential id="58ff2793-2dc7-43fe-85f9-20bfac5a87e4">
      <name>mm</name>
    </lsc_credential>
    <tasks>
      <task id="13bb418a-4220-4575-b35b-ec398bff7417">
        <name>dik mm</name>
      </task>
      ...
    </tasks>
  </target>
</get_targets_response>

get_tasks

The client uses the get_tasks command to request task information. This command may include a task ID, details flag, apply overrides flag, sort order and sort field,

If the command includes the details flag each task will include details of all reports on the task.

As a convenience for clients the response includes a task count and the values of the sort order, sort field and apply overrides flag that the manager applied when selecting the tasks.

Command attributes:

• "task_id" is the ID of the task which should be queried.
• "details" is boolean (0 is false, anything else is true).
• "apply_overrides" is boolean (0 is false, anything else is true).
• "sort_order" is "descending" for descending, anything else for ascending.
• "sort_field" is the field to sort on.

Command elements:

• (n/a)

Example:

C:

<get_tasks />

M:

<get_tasks_response status="200" status_text="OK">
  <task_count>2</task_count>
  <sort>
    <field>
      ROWID
      <order>ascending</order>
    </field>
  </sort>
  <apply_overrides>0</apply_overrides>
  <task id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6">
    <name>Scan Webserver</name>
    <comment>Scan of the web server.</name>
    <status>Done</status>
    <progress>-1</progress>
    <config id="daba56c8-73ec-11df-a475-002264764cea">
      <name>Full and fast</name>
    </config>
    <escalator id="">
      <name></name>
    </escalator>
    <target id="1f28d970-17ef-4c69-ba8a-13827059f2b9">
      <name>dik</name>
    </target>
    <schedule id="">
      <name></name>
      <next_time>over</next_time>
    </schedule>
    <result_count>
      <debug>0</debug>
      <log>0</log>
      <info>14</info>
      <warning>0</warning>
      <hole>6</hole>
    </result_count>
    <report_count>
      2
      <finished>2</finished>
    </report_count>
    <trend></trend>
    <first_report>
      <report id="f0fdf522-276d-4893-9274-fb8699dc2270">
        <timestamp>Mon Feb  1 19:11:20 2010</timestamp>
        <result_count>
          <debug>0</debug>
          <hole>0</hole>
          <info>7</info>
          <log>0</log>
          <warning>3</warning>
        </result_count>
      </report>
    </first_report>
    <last_report>
      <report id="f0fdf522-276d-4893-9274-fb8699dc2270">
        <timestamp>Mon Feb  1 19:11:20 2010</timestamp>
        <result_count>
          <debug>0</debug>
          <hole>0</hole>
          <info>7</info>
          <log>0</log>
          <warning>3</warning>
        </result_count>
      </report>
    </last_report>
  </task>
  <task id="f14747d3-a4d7-4e79-99bb-a0a1276cb78c">
    <name>Scan Mailserver</name>
    ...
  </task>
</get_tasks_response>

C:

<get_tasks task_id="f14747d3-a4d7-4e79-99bb-a0a1276cb78c" details="1" />

M:

<get_tasks_response status="200" status_text="OK">
  <task_count>1</task_count>
  <sort>
    <field>
      ROWID
      <order>ascending</order>
    </field>
  </sort>
  <apply_overrides>0</apply_overrides>
  <task id="13bb418a-4220-4575-b35b-ec398bff7417">
    <name>Scan Mailserver</name>
    <comment>Scan of the web server.</name>
    <status>Done</status>
    <progress>-1</progress>
    <config id="daba56c8-73ec-11df-a475-002264764cea">
      <name>Full and fast</name>
    </config>
    <escalator id="">
      <name></name>
    </escalator>
    <target id="1f28d970-17ef-4c69-ba8a-13827059f2b9">
      <name>dik</name>
    </target>
    <schedule id="">
      <name></name>
      <next_time>over</next_time>
    </schedule>
    <result_count>
      <debug>0</debug>
      <log>0</log>
      <info>14</info>
      <warning>0</warning>
      <hole>6</hole>
    </result_count>
    <report_count>
      2
      <finished>2</finished>
    </report_count>
    <trend></trend>
    <first_report>
      <report id="f0fdf522-276d-4893-9274-fb8699dc2270">
        <timestamp>Mon Feb  1 19:11:20 2010</timestamp>
        <result_count>
          <debug>0</debug>
          <hole>0</hole>
          <info>7</info>
          <log>0</log>
          <warning>3</warning>
        </result_count>
      </report>
    </first_report>
    <last_report>
      <report id="2688e6c7-db29-4505-80f1-0fd4a09e1011">
        <timestamp>Mon Feb  1 19:11:20 2010</timestamp>
        <result_count>
          <debug>0</debug>
          <hole>0</hole>
          <info>7</info>
          <log>0</log>
          <warning>3</warning>
        </result_count>
      </report>
    </last_report>
    <reports>
      <report id="f0fdf522-276d-4893-9274-fb8699dc2270">
        <timestamp>Mon Feb  1 18:51:38 2010</timestamp>
        <scan_run_status>Done</scan_run_status>
        <result_count>
          <debug>0</debug>
          <hole>0</hole>
          <info>7</info>
          <log>0</log>
          <warning>3</warning>
        </result_count>
      </report>
      <report id="2688e6c7-db29-4505-80f1-0fd4a09e1011">
        <timestamp>Mon Feb  1 19:11:20 2010</timestamp>
        <scan_run_status>Done</scan_run_status>
        <result_count>
          <debug>0</debug>
          <hole>0</hole>
          <info>7</info>
          <log>0</log>
          <warning>3</warning>
        </result_count>
      </report>
    </reports>
  </task>
</get_tasks_response>

get_version

The client uses the get_version command to request the protocol version which may be used when communicating with this manager. The manager 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:

• (n/a)

Example:

C:

<get_version/>

M:

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

help

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

Command elements:

• (n/a)

Example:

C:

<help/>

M:

<help_response status="200" status_text="OK">
    AUTHENTICATE           Authenticate with the manager.
    COMMANDS               Run a list of commands.
    CREATE_AGENT           Create an agent.
    CREATE_CONFIG          Create a config.
    CREATE_ESCALATOR       Create an escalator.
    CREATE_LSC_CREDENTIAL  Create a local security check credential.
    CREATE_NOTE            Create a note.
    CREATE_OVERRIDE        Create an override.
    CREATE_SCHEDULE        Create a schedule.
    CREATE_TARGET          Create a target.
    CREATE_TASK            Create a task.
    DELETE_AGENT           Delete an agent.
    DELETE_CONFIG          Delete a config.
    DELETE_ESCALATOR       Delete an escalator.
    DELETE_LSC_CREDENTIAL  Delete a local security check credential.
    DELETE_NOTE            Delete a note.
    DELETE_OVERRIDE        Delete an override.
    DELETE_REPORT          Delete a report.
    DELETE_SCHEDULE        Delete a schedule.
    DELETE_TARGET          Delete a target.
    DELETE_TASK            Delete a task.
    GET_AGENTS             Get all agents.
    GET_CONFIGS            Get all configs.
    GET_DEPENDENCIES       Get dependencies for all available NVTs.
    GET_ESCALATORS         Get all escalators.
    GET_LSC_CREDENTIALS    Get all local security check credentials.
    GET_NOTES              Get all notes.
    GET_NVTS               Get one or all available NVTs.
    GET_NVT_FAMILIES       Get a list of all NVT families.
    GET_NVT_FEED_CHECKSUM  Get checksum for entire NVT collection.
    GET_OVERRIDES          Get all overrides.
    GET_PREFERENCES        Get preferences for all available NVTs.
    GET_REPORTS            Get all reports.
    GET_RESULTS            Get results.
    GET_SCHEDULES          Get all schedules.
    GET_SYSTEM_REPORTS     Get all system reports.
    GET_TARGET_LOCATORS    Get configured target locators.
    GET_TARGETS            Get all targets.
    GET_TASKS              Get all tasks.
    GET_VERSION            Get the OpenVAS Manager Protocol version.
    HELP                   Get this help text.
    MODIFY_CONFIG          Update an existing config.
    MODIFY_NOTE            Modify an existing note.
    MODIFY_OVERRIDE        Modify an existing override.
    MODIFY_REPORT          Modify an existing report.
    MODIFY_TASK            Update an existing task.
    PAUSE_TASK             Pause a running task.
    RESUME_OR_START_TASK   Resume task if stopped, else start task.
    RESUME_PAUSED_TASK     Resume a paused task.
    RESUME_STOPPED_TASK    Resume a stopped task.
    START_TASK             Manually start an existing task.
    STOP_TASK              Stop a running task.
    TEST_ESCALATOR         Run an escalator.
</help_response>

modify_config

The client uses the modify_config command to change an existing config. This command must include the ID of an existing config and either a preference, an NVT selection or a family selection.

The first option, a preference, must include a name. If the preference includes an NVT, then the preference is an NVT preference, otherwise the preference is a Scanner preference. If the preference includes a value then the manager updates the value of the preference, otherwise the manager removes the preference.

The second option, a family selection, lets the client modify the NVTs selected by the config at a family level. The idea is that the client modifies the entire family selection at once, so a client will often need to include many families in a family selection.

The family_selection may include a growing element to indicate whether new families should be added to the selection. It may also include any number of family elements.

A family element must always include a name and may include a growing element and an all element. The all element indicates whether all NVTs in the family should be selected. The growing element indicates whether new NVTs in the family should be added to the selection as they arrive. Leaving a family out of the family_selection is equivalent to including the family with all 0 and growing 0.

The effect of the all 0 and growing 0 case is subtle: if all NVTs were selected then all are removed (effectively removing the family from the config). However if some NVTs were selected then they remain selected. As a result the client must include in the family_selection all families that must have all NVTs selected.

The third option, an NVT selection, must include a family and may include any number of NVTs. The manager updates the given family in the config to include only the given NVTs.

If there was no error with the command sent by the client, the manager will apply the changes to the config and will reply with a response code indicating success.

Command attributes:

• "config_id" is the ID of the config which should be changed.

Command elements:

• <preference>
  • <name> is the name of a preference. This is OpenVAS Scanner style, including the NVT name and preference type, for example "LDAPsearch[entry]:Timeout value".
  • <nvt> is an empty element with an oid attribute.
  • <value> is the new value of the preference, Base64 encoded.
• <family_selection>
  • <growing> is boolean (after C atoi conversion, 0 is false, anything else is true).
  • <family>
    • <all> is boolean (after C atoi conversion, 0 is false, anything else is true).
    • <growing> is boolean (after C atoi conversion, 0 is false, anything else is true).
    • <name> is the name of an NVT family.
• <nvt_selection>
  • <family> is the name of an NVT family
  • <nvt> is an empty element with an oid attribute.

Examples:

C:

<modify_config config_id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6">
  <preference>
    <nvt oid="1.3.6.1.4.1.25623.1.0.14259"/>
    <name>Nmap (NASL wrapper)[checkbox]:UDP port scan</name>
    <value>eWVz</value>
  </preference>
</modify_config>

M:

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

M:

<modify_config_response status="4xx" />

M:

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

C:

<modify_config config_id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6">
  <family_selection>
    <!-- Set the config to add any new families that arrive. -->
    <growing>1</growing>
    <!-- Keep the single family that has all NVTs selected -->
    <family>
      <name>Debian Local Security Checks</name>
      <all>1</all>
      <growing>1</growing>
    </family>
  </family_selection>
</modify_config>

M:

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

M:

<modify_config_response status="4xx" />

M:

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

C:

<modify_config config_id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6">
  <family_selection>
    <!-- Keep the single family that has all NVTs selected -->
    <family>
      <name>Debian Local Security Checks</name>
      <all>1</all>
      <growing>1</growing>
    </family>
    <!-- Switch a family to receive any new NVTs that arrive. -->
    <family>
      <name>General</name>
      <growing>1</growing>
    </family>
  </family_selection>
</modify_config>

M:

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

M:

<modify_config_response status="4xx" />

M:

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

C:

<modify_config config_id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6">
  <nvt_selection>
    <family>Debian Local Security Checks</family>
    <nvt oid="1.3.6.1.4.1.25623.1.0.53797"/>
    <nvt oid="1.3.6.1.4.1.25623.1.0.63272"/>
    <nvt oid="1.3.6.1.4.1.25623.1.0.55615"/>
    <nvt oid="1.3.6.1.4.1.25623.1.0.53546"/>
  </nvt_selection>
</modify_config>

M:

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

M:

<modify_config_response status="4xx" />

M:

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

modify_note

The client uses the modify_note command to change an existing note. This command must include the ID of an existing note and the note text. This command may include a host list, port, threat, task and result.

If an optional element is left out, the existing value will be cleared, generalising that constraint.

If there was no error with the command sent by the client, the manager will apply the changes to the note and will reply with a response code indicating success.

Command attributes:

• "note_id" is the ID of the note which should be changed.

Command elements:

• <text> is a human-readable text.
• <hosts> is a textual list of hosts.
• <port> is a port.
• <threat> is a threat.
• <task> is an empty element with an id attribute.
• <result> is an empty element with an id attribute.

Example:

C:

<modify_note note_id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6">
  <text>This issue should be resolved after the upgrade.</text>
  <result id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6"/>
</modify_note>

M:

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

M:

<modify_note_response status="4xx" />

M:

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

modify_override

The client uses the modify_override command to change an existing override. This command must include the ID of an existing override and the override text. This command may include a host list, port, new threat, threat, task and result.

If an optional element is left out, the existing value will be cleared, generalising that constraint.

If there was no error with the command sent by the client, the manager will apply the changes to the override and will reply with a response code indicating success.

Command attributes:

• "override_id" is the ID of the override which should be changed.

Command elements:

• <text> is a human-readable text.
• <hosts> is a textual list of hosts.
• <new_threat> is a threat.
• <port> is a port.
• <threat> is a threat.
• <task> is an empty element with an id attribute.
• <result> is an empty element with an id attribute.

Example:

C:

<modify_override override_id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6">
  <text>This issue is less important in our setup.</text>
  <new_threat>Low</new_threat>
</modify_override>

M:

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

M:

<modify_override_response status="4xx" />

M:

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

modify_report

The client uses the modify_report command to modify an existing report. This command must include the ID of an existing report and a comment.

If there was no error with the command sent by the client, the manager will add the comment to the report and will reply with a response code indicating success.

Command attributes:

• "report_id" is the ID of the report which should be modified.

Command elements:

• <comment> is the new text for the comment.

Example:

C:

<modify_report report_id="65defe9b-bb28-4e85-9ed7-3f2a57ac8263">
  <comment>This is the report where vulnerability XYZ was found on our Webserver.</comment>
</modify_report>

M:

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

modify_task

The client uses the modify_task command to change an existing task. This command must include the ID of an existing task and must either include a name, a comment, an escalator, a schedule, an rcfile or a file.

If there was no error with the command sent by the client, the manager will apply the changes to the task and will reply with a response code indicating success.

Command attributes:

• "task_id" is the ID of the task which should be changed.

Command elements:

• <rcfile> is a file describing the task. As of OMP 1.0, this file is in the openvasrc format. The file must be Base64 encoded.
• <name> is a human-readable identifier.
• <comment> is a human-readable text.
• <escalator> is an empty element with an id attribute.
• <schedule> is an empty element with an id attribute.
• <file> is the text of a file, with name and action attributes. The file must be Base64 encoded. Name is the name the manager associates with the file. Action must be either "update" or "remove".

Example:

C:

<modify_task task_id="254cd3ef-bbe1-4d58-859d-21b8d0c046c6">
  <comment>Monthly scan of the webserver</comment>
</modify_task>

M:

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

M:

<modify_task_response status="4xx" />

M:

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

pause_task

The client uses the pause_task command to manually pause an existing task. This command must include the ID of an existing task.

If there was no error with the command sent by the client, the manager will pause the task and will reply with a response code indicating success.

Command attributes:

• "task_id" is the ID of the task which should be paused.

Command elements:

• (n/a)

Example:

C:

<pause_task task_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" />

M:

<pause_task_response status="201" status_text="OK, resource created" task_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" />

M:

<pause_task_response status="4xx" task_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" />

M:

<pause_task_response status="500" status_text="Internal error" task_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" />

resume_or_start_task

The client uses the resume_or_start_task command to manually start an existing task, ensuring that the task will resume from its previous position if the task is in the Stopped state. This command must include the ID of an existing task.

If there was no error with the command sent by the client, the manager will resume or start the task and will reply with a response code indicating success.

Command attributes:

• "task_id" is the ID of the task which should be resumed or started.

Command elements:

• (n/a)

Example:

C:

<resume_or_start_task task_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" />

M:

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

M:

<resume_or_start_task_response status="4xx" />

M:

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

resume_paused_task

The client uses the resume_paused_task command to manually resume a paused task. This command must include the ID of an existing task.

If there was no error with the command sent by the client and if the task is currently paused, the manager will resume the task and will reply with a response code indicating success.

Command attributes:

• "task_id" is the ID of the task which should be resumed.

Command elements:

• (n/a)

Example:

C:

<resume_paused_task task_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" />

M:

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

M:

<resume_paused_task_response status="4xx" />

M:

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

resume_stopped_task

The client uses the resume_stopped_task command to manually resume a stopped task. This command must include the ID of an existing task.

If there was no error with the command sent by the client and if the task is currently stopped, the manager will resume the task and will reply with a response code indicating success.

Command attributes:

• "task_id" is the ID of the task which should be resumed.

Command elements:

• (n/a)

Example:

C:

<resume_stopped_task task_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" />

M:

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

M:

<resume_stopped_task_response status="4xx" />

M:

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

start_task

The client uses the start_task command to manually start an existing task. This command must include the ID of an existing task.

If there was no error with the command sent by the client, the manager will start the task and will reply with a response code indicating success.

Command attributes:

• "task_id" is the ID of the task which should be started.

Command elements:

• (n/a)

Example:

C:

<start_task task_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" />

M:

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

M:

<start_task_response status="4xx" />

M:

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

stop_task

The client uses the stop_task command to manually stop a running task. This command must include the ID of an existing task.

If there was no error with the command sent by the client, the manager will stop the task and will reply with a response code.

Command attributes:

• "task_id" is the ID of the task which should be stopped.

Command elements:

• (n/a)

Example:

C:

<stop_task task_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" /<

M:

<stop_task_response status="201" status_text="OK" status_text="OK" />

M:

<stop_task_response status="4xx" />

M:

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

test_escalator

The client uses the test_escalator command to invoke a test run of an escalator.

If there was no error with the command sent by the client, the manager will run the escalator and will reply with a response code indicating success.

Command attributes:

• "escalator_id" is the ID of the escalator which should be tested.

Command elements:

• (n/a)

Example:

C:

<test_escalator escalator_id="825a5d10-24b2-4473-a4e0-55f8cfd4bf23" />

M:

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

M:

<test_escalator_response status="4xx" />

M:

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

History

• 2010-11-03 Matthew Mundell <matthew.mundell@greenbone.net>:
  Correct CREATE_CONFIGS rcfile description. Remove username and password from CREATE_TARGET target locator sentence. Clean up brackets on CREATE_TASK. Correct INSTALLER and add missing attribute in GET_AGENTS examples. Correct GET_PREFERENCES examples, adding two more. Correct MODIFY_NOTE example. Cleanup MODIFY_NOTE example tags.
• 2010-10-12 Matthew Mundell <matthew.mundell@greenbone.net>:
  Add examples and better explanations of the MODIFY_CONFIG alternatives, correcting the descriptions of the boolean elements.
• 2010-10-11 Matthew Mundell <matthew.mundell@greenbone.net>:
  Cleanup GET_NVTS_RESPONSE brackets.
• 2010-10-04 Matthew Mundell <matthew.mundell@greenbone.net>:
  Correct GET_REPORTS attribute names and the MODIFY_CONFIG example NAME and VALUE.
• 2010-07-20 Michael Wiegand <michael.wiegand@greenbone.net>:
  Updated status.
• 2010-07-16 Matthew Mundell <matthew.mundell@greenbone.net>:
  In CREATE_CONFIG correct reference and add example.
• 2010-07-14 Matthew Mundell <matthew.mundell@greenbone.net>:
  Describe commands that can precede authentication. Reduce GET_VERSION to a single fixed version.
• 2010-07-13 Matthew Mundell <matthew.mundell@greenbone.net>:
  Cleanup TODOs.
• 2010-07-06 Matthew Mundell <matthew.mundell@greenbone.net>:
  Add SIGNATURE to CREATE_AGENT/INSTALLER. Add TRUST to GET_AGENTS response.
• 2010-07-05 Matthew Mundell <matthew.mundell@greenbone.net>:
  Add THREAT to GET_OVERRIDES brief example.
• 2010-06-28 Matthew Mundell <matthew.mundell@greenbone.net>:
  Comment out GET_CERTIFICATES.
• 2010-06-27 Matthew Mundell <matthew.mundell@greenbone.net>:
  Add missing get commands. Bring remaining commands up to date.
• 2010-06-22 Matthew Mundell <matthew.mundell@greenbone.net>:
  Make UUID scheme permanent. Update authentication to match Manager. Add a few new commands. Remove IDs from fail cases of create commands. Remove ABORT_TASK criterion. Update HELP. Update renamed commands. Add all commands to index. Add missing create and delete commands.
• 2010-06-10 Matthew Mundell <matthew.mundell@greenbone.net>:
  Update HELP text. Add a few new commands. Remove ABORT_TASK criterion.
• 2009-06-10 Matthew Mundell <matthew.mundell@intevation.de>:
  Add IDs to HTML entities in command index. Remove ID from CREATE_TASK. Rename CREATE_TASK's FILE to RCFILE. Add special entities to MODIFY_TASK. Improve MODIFY_TASK example. Move GET_NVT_ALL and GET_NVT_DETAILS OID entity to an attribute. Separate attributes from command element lists.
• 2009-06-04 Matthew Mundell <matthew.mundell@intevation.de>:
  Add summary of commands, with links to detailed descriptions.
• 2009-06-04 Matthew Mundell <matthew.mundell@intevation.de>:
  Note get_nvt_feed_checksum behaviour when algorithm missing.
• 2009-05-13 Matthew Mundell <matthew.mundell@intevation.de>:
  Add task name and state to STATUS response when ID given.
• 2009-05-11 Matthew Mundell <matthew.mundell@intevation.de>:
  Added HELP command.
• 2009-02-04 Michael Wiegand <michael.wiegand@intevation.de>:
  Made command names more consistent.
• 2009-01-29 Michael Wiegand <michael.wiegand@intevation.de>:
  Updated protocol specification based on feedback received.
• 2009-01-08 Michael Wiegand <michael.wiegand@intevation.de>:
  Initial text.