OAP: OpenVAS Administrator ProtocolVersion: 1.0 The "administrator" protocol of the Open Vulnerability Assessment System. Contents
1 Summary of Data Types
2 Summary of Elements
3 Summary of Commands
4 RNC Preamble### Preamble start = command | response command = authenticate | commands | create_user | delete_user | describe_auth | describe_feed | get_settings | get_users | get_version | help | modify_auth | modify_user | sync_feed response = authenticate_response | commands_response | create_user_response | delete_user_response | describe_auth_response | describe_feed_response | get_settings_response | get_users_response | get_version_response | help_response | modify_auth_response | modify_user_response | sync_feed_response 5 Data Type Details5.1 Data Type base64In short: Base64 encoded data. 5.1.1 RNCbase64 = xsd:base64Binary 5.2 Data Type booleanIn short: A true or false value. Zero is false, anything else is true. As a result, the empty string is considered true. 5.2.1 RNCboolean = text 5.3 Data Type boolean_atoiIn short: A true or false value, after conversion to an integer. Zero is false, anything else is true. The value is first converted to an integer, as by the C `atoi' routine. This means that an empty string is considered false. 5.3.1 RNCboolean_atoi = text 5.4 Data Type ctimeIn short: A date and time, in the C `ctime' format. An example string in this format is "Wed Jun 30 21:49:08 1993\n". 5.4.1 RNCctime = text 5.5 Data Type type_nameIn short: A name of a data type. 5.5.1 RNCtype_name = xsd:string - xsd:whitespace 5.6 Data Type integerIn short: An integer. 5.6.1 RNCinteger = xsd:integer 5.7 Data Type levelsIn short: A string that may include the characters h, m, l, g and d. 5.7.1 RNClevels = xsd:token { pattern = "h?m?l?g?d?" } 5.8 Data Type nameIn short: A name. 5.8.1 RNCname = xsd:string 5.9 Data Type oidIn short: An Object Identifier (OID). 5.9.1 RNCoid = xsd:token { pattern = "[0-9\.]{1,80}" } 5.10 Data Type sort_orderIn short: A string describing an order for sorting. The string "descending" denotes descending order, anything else means ascending. 5.10.1 RNCsort_order = text 5.11 Data Type statusIn short: The success or failure status of a command. 5.11.1 RNCstatus = xsd:token { pattern = "200|201|202|400|401|403|404|409|500|503" } 5.12 Data Type task_statusIn short: A task run status. 5.12.1 RNCtask_status = xsd:token { pattern = "Delete Requested|Done|New|Pause Requested|Paused|Requ↵ ested|Resume Requested|Running|Stop Requested|Stopped|Internal Error" } 5.13 Data Type task_trendIn short: The trend of results for a task. 5.13.1 RNCtask_trend = xsd:token { pattern = "up|down|more|less|same" } 5.14 Data Type threatIn short: A threat level. 5.14.1 RNCthreat = xsd:token { pattern = "High|Medium|Low|Log|Debug" } 5.15 Data Type time_unitIn short: A unit of time. 5.15.1 RNCtime_unit = xsd:token { pattern = "second|minute|hour|day|week|month|year|decade" } 5.16 Data Type uuidIn short: A Universally Unique Identifier (UUID). 5.16.1 RNCuuid = xsd:token { pattern = "[0-9abcdefABCDEF\-]{1,40}" } 5.17 Data Type uuid_or_emptyIn short: A Universally Unique Identifier (UUID), or the empty string. 5.17.1 RNCuuid_or_empty = xsd:token { pattern = "[0-9abcdefABCDEF\-]{0,40}" } 6 Element Details6.1 Element cIn short: A reference to a command. 6.1.1 Structure6.1.2 RNCc = element c { text } 6.2 Element eIn short: A reference to an element. 6.2.1 Structure6.2.2 RNCe = element e { text } 6.3 Element rIn short: A reference to a response. 6.3.1 Structure6.3.2 RNCr = element r { text } 6.4 Element oIn short: An optional pattern item. 6.4.1 Structure6.4.2 RNCo = element o { ( c | e | r | g ) } 6.5 Element gIn short: A group of pattern items. 6.5.1 Structure6.5.2 RNCg = element g { c* & e* & r* & o* & any* } 6.6 Element anyIn short: Pattern item indicating "any number of". 6.6.1 Structure6.6.2 RNCany = element any { ( c | e | r | g ) } 6.7 Element patternIn short: The pattern element of a command or command descendant. It's actually either a 't' element, or the word "text", or "". 6.7.1 Structure6.7.2 RNCpattern = element pattern { text & pattern_attrib* & c* & e* & r* & o* & g* & any* & pattern_t? } pattern_attrib = element attrib { pattern_attrib_name & pattern_attrib_type & pattern_attrib_required } pattern_attrib_name = element name { type_name } pattern_attrib_type = element type { type_name } pattern_attrib_required = element required { boolean } pattern_t = element t { type_name } 6.8 Element command_definitionIn short: Definition of a command in OAP describing HELP command. 6.8.1 Structure
6.8.2 RNCcommand_definition = element command_definition { command_definition_name & command_definition_summary? & command_definition_description? & ( ( command_definition_pattern & command_definition_response ) | ( command_definition_type & command_definition_ele* ) ) & command_definition_example* } command_definition_name = element name { type_name } command_definition_summary = element summary { text } command_definition_description = element description { text & command_definition_description_p* } command_definition_description_p = element p { text } command_definition_pattern = element pattern # type pattern { text & pattern_attrib* & c* & e* & r* & o* & g* & any* & pattern_t? } command_definition_response = element response # type pattern { text & pattern_attrib* & c* & e* & r* & o* & g* & any* & pattern_t? } command_definition_example = element example { command_definition_example_summary? & command_definition_example_description? & command_definition_example_request & command_definition_example_response } command_definition_example_summary = element summary { text } command_definition_example_description = element description { text } command_definition_example_request = element request { text } command_definition_example_response = element response { text } command_definition_type = element type { text } command_definition_ele = element ele # type command_definition { command_definition_name & command_definition_summary? & command_definition_description? & ( ( command_definition_pattern & command_definition_response ) | ( command_definition_type & command_definition_ele* ) ) & command_definition_example* } 7 Command Details7.1 Command authenticateIn short: Authenticate with the Administrator. The client uses the authenticate command to authenticate with the Administrator. The client normally executes this command at the beginning of each connection. The only commands permitted before authentication are get_version and commands. 7.1.1 Structure
7.1.2 RNC
Command
authenticate = element authenticate { authenticate_credentials } authenticate_credentials = element credentials { authenticate_credentials_username & authenticate_credentials_password } authenticate_credentials_username = element username { text } authenticate_credentials_password = element password { text } authenticate_response = element authenticate_response { attribute status { status } & attribute status_text { text } } 7.1.3 Example: Authenticate with a good password
Client
<authenticate> <credentials> <username>sally</username> <password>secret</password> </credentials> </authenticate> <authenticate_response status="200" status_text="OK"/> 7.1.3 Example: Authenticate with a bad password
Client
<authenticate> <credentials> <username>sally</username> <password>secrte</password> </credentials> </authenticate> <authenticate_response status="400" status_text="Authentication failed"/> 7.2 Command commandsIn short: Run a list of 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. 7.2.1 Structure
7.2.2 RNC
Command
commands = element commands { ( authenticate | commands | create_user | delete_user | describe_auth | describe_feed | get_settings | get_users | get_version | help | modify_auth | modify_user | sync_feed )* } commands_response = element commands_response { attribute status { status } & attribute status_text { text } & ( authenticate_response | commands_response | create_user_response | delete_user_response | describe_auth_response | describe_feed_response | get_settings_response | get_users_response | get_version_response | help_response | modify_auth_response | modify_user_response | sync_feed_response )* } 7.3 Command create_userIn short: Create a user. The client uses the create_user command to create a new user. 7.3.1 Structure
7.3.2 RNC
Command
create_user = element create_user { create_user_name & create_user_hosts? & create_user_password? & create_user_role? } create_user_name = element name { text } create_user_hosts = element hosts { text & attribute allow { boolean }? } create_user_password = element password { text } create_user_role = element role { xsd:token { pattern = "Administrator|User" } } create_user_response = element create_user_response { attribute status { status } & attribute status_text { text } & attribute id { uuid } } 7.3.3 Example: Create a user
Client
<create_user> <name>foobar</name> <password>f00bar</password> <role>User</role> </create_user> <create_user_response status="201" status_text="OK, resource created"/> 7.4 Command delete_userIn short: Delete a user. The client uses the delete_user command to delete an existing user. Since this is a destructive command, the client is advised to ask for confirmation from the user before sending this command to the Administrator. 7.4.1 Structure
7.4.2 RNC
Command
delete_user = element delete_user { delete_user_name } delete_user_name = element name { text } delete_user_response = element delete_user_response { attribute status { status } & attribute status_text { text } } 7.4.3 Example: Delete a user
Client
<delete_user name="foobar"/> <delete_user_response status="200" status_text="OK"/> 7.5 Command describe_authIn short: Describe a 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. 7.5.1 Structure
7.5.2 RNC
Command
describe_auth = element describe_auth { "" } describe_auth_response = element describe_auth_response { attribute status { status } & attribute status_text { text } & describe_auth_response_group } describe_auth_response_group = element group { attribute name { text } & describe_auth_response_group_auth_conf_setting } describe_auth_response_group_auth_conf_setting = element auth_conf_setting { attribute key { text } & attribute value { text } } 7.5.3 Example: Describe the authentication methods
Client
<describe_auth/> <describe_auth_response status="200" status_text="OK"> <group name="Foo"> <auth_conf_setting key="Bar" value="Baz"/> </group> </describe_auth_response> 7.6 Command describe_feedIn short: Describe the NVT 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. 7.6.1 Structure
7.6.2 RNC
Command
describe_feed = element describe_feed { "" } describe_feed_response = element describe_feed_response { attribute status { status } & attribute status_text { text } & describe_feed_response_feed } describe_feed_response_feed = element feed { describe_feed_response_feed_name & describe_feed_response_feed_version & describe_feed_response_feed_description } describe_feed_response_feed_name = element name { text } describe_feed_response_feed_version = element version { text } describe_feed_response_feed_description = element description { text } 7.6.3 Example: Describe the feed
Client
<describe_feed/> <describe_feed_response status="200" status_text="OK"> <feed> <name>OpenVAS NVT Feed</name> <version>201011221324</version> <description> The 'OpenVAS NVT Feed' is provided by 'The OpenVAS Project'. ... </description> </feed> </describe_feed_response> 7.7 Command get_settingsIn short: Get all settings. The client uses the "get_settings" command to retrieve a list of all settings set for the Scanner controlled by this Administrator. The Administrator will reply with a list of all known settings and their values. 7.7.1 Structure
7.7.2 RNC
Command
get_settings = element get_settings { "" } get_settings_response = element get_settings_response { attribute status { status } & attribute status_text { text } & get_settings_response_scanner_settings } get_settings_response_scanner_settings = element scanner_settings { get_settings_response_scanner_settings_setting* } get_settings_response_scanner_settings_setting = element setting { text & attribute name { text } } 7.7.3 Example: Get the settings
Client
<get_settings/> <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> 7.8 Command get_usersIn short: Get all users. The client uses the "get_users" command to retrieve the list of user accounts on the Scanner. 7.8.1 Structure
7.8.2 RNC
Command
get_users = element get_users { "" } get_users_response = element get_users_response { attribute status { status } & attribute status_text { text } & get_users_response_user* } get_users_response_user = element user { get_users_response_user_name & get_users_response_user_role & get_users_response_user_hosts } get_users_response_user_name = element name { text } get_users_response_user_role = element role { xsd:token { pattern = "Admin|User" } } get_users_response_user_hosts = element hosts { text & attribute allow { xsd:token { pattern = "0|1|2|3" } } } 7.8.3 Example: Get the users
Client
<get_users/> <get_users_response status="200" status_text="OK"> <user> <name>foobar</name> <role>User</role> <hosts allow="2"/> </user> </get_users_response> 7.9 Command get_versionIn short: Get the OpenVAS Administrator Protocol version. 7.9.1 Structure
7.9.2 RNC
Command
get_version = element get_version { "" } get_version_response = element get_version_response { attribute status { status } & attribute status_text { text } & get_version_response_version } get_version_response_version = element version { text } 7.9.3 Example: Get the version
Client
<get_version/> <get_version_response status="200" status_text="OK"> <version>1.0</version> </get_version_response> 7.10 Command helpIn short: Get the help text. 7.10.1 Structure
7.10.2 RNC
Command
help = element help { attribute format { xsd:token { pattern = "html|HTML|rnc|RNC|text|TEXT|xml|XML" } }? } help_response = element help_response { text & attribute status { status } & attribute status_text { text } & help_response_schema? } help_response_schema = element schema { help_response_schema_protocol } help_response_schema_protocol = element protocol { help_response_schema_protocol_name & help_response_schema_protocol_abbreviation? & help_response_schema_protocol_summary? & help_response_schema_protocol_version? & help_response_schema_protocol_type* & help_response_schema_protocol_command* } help_response_schema_protocol_name = element name { text } help_response_schema_protocol_abbreviation = element abbreviation { text } help_response_schema_protocol_summary = element summary { text } help_response_schema_protocol_version = element version { text } help_response_schema_protocol_type = element type { help_response_schema_protocol_type_name & help_response_schema_protocol_type_summary? & help_response_schema_protocol_type_description? & help_response_schema_protocol_type_pattern } help_response_schema_protocol_type_name = element name { type_name } help_response_schema_protocol_type_summary = element summary { text } help_response_schema_protocol_type_description = element description { text & help_response_schema_protocol_type_description_p* } help_response_schema_protocol_type_description_p = element p { text } help_response_schema_protocol_type_pattern = element pattern { text } help_response_schema_protocol_command = element command # type command_definition { command_definition_name & command_definition_summary? & command_definition_description? & ( ( command_definition_pattern & command_definition_response ) | ( command_definition_type & command_definition_ele* ) ) & command_definition_example* } 7.10.3 Example: Get the help text
Client
<help/> <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> 7.10.3 Example: Get the OAP schema
Client
<help format="XML"/> <help_response status="200" status_text="OK"> <schema format="XML" extension="xml" content_type="text/xml"> <protocol> <name>OpenVAS Administrator Protocol</name> <abbreviation>OAP</abbreviation> <summary> The "administrator" protocol of the Open Vulnerability Assessment System </summary> <version>1.0</version> <type> <name>base64</name> <summary>Base64 encoded data</summary> <pattern>xsd:base64Binary</pattern> </type> ... <command> <name>authenticate</name> <summary>Authenticate with the Administrator</summary> <description> <p> The client uses the authenticate command to authenticate with the Administrator. </p> <p> The client normally executes this command at the beginning of each connection. The only commands permitted before authentication are get_version and commands. </p> </description> <pattern> <e>credentials</e> </pattern> <ele> <name>credentials</name> <pattern> <e>username</e> <e>password</e> </pattern> <ele> <name>username</name> <summary>The login name of the user</summary> <pattern>text</pattern> </ele> <ele> <name>password</name> <summary>The user's password</summary> <pattern>text</pattern> </ele> </ele> <response> <pattern> <attrib> <name>status</name> <type>status</type> <required>1</required> </attrib> <attrib> <name>status_text</name> <type>text</type> <required>1</required> </attrib> </pattern> </response> <example> <summary>Authenticate with a good password</summary> <request> <authenticate> <credentials> <username>sally</username> <password>secret</password> </credentials> </authenticate> </request> <response> <authenticate_response status="200" status_text="OK"/> </response> </example> ... </command> ... </protocol> </schema> </help_response> 7.11 Command modify_authIn short: Modify the authentication methods. The client uses the "modify_auth" command to modify the authentication methods. 7.11.1 Structure
7.11.2 RNC
Command
modify_auth = element modify_auth { modify_auth_group } modify_auth_group = element group { modify_auth_group_auth_conf_setting* } modify_auth_group_auth_conf_setting = element auth_conf_setting { attribute key { text } & attribute value { text } } modify_auth_response = element modify_auth_response { attribute status { status } & attribute status_text { text } } 7.11.3 Example: Modify a single setting for an authentication method
Client
<modify_auth> <group name="Foo"> <auth_conf_setting key="Bar" value="Baz"/> </group> </modify_auth> <modify_auth_response status="200" status_text="OK"/> 7.12 Command modify_userIn short: Modify a user. The client uses the "modify_user" command to modify an user account on the OpenVAS server. 7.12.1 Structure
7.12.2 RNC
Command
modify_user = element modify_user { modify_user_name & modify_user_password? & modify_user_role & modify_user_hosts? } modify_user_name = element name { text } modify_user_hosts = element hosts { text & attribute allow { boolean }? } modify_user_password = element password { text } modify_user_role = element role { xsd:token { pattern = "Administrator|User" } } modify_user_response = element modify_user_response { attribute status { status } & attribute status_text { text } } 7.12.3 Example: Modify a user
Client
<modify_user> <name>Foobar</name> <password modify="0"/> <role>Admin</role> <hosts allow="0"/> </modify_user> <modify_user_response status="200" status_text="OK"/> 7.13 Command sync_feedIn short: Synchronize with an NVT feed. The client uses the "sync_feed" command to request a synchronization with the NVT feed service the Administrator uses. 7.13.1 Structure
7.13.2 RNC
Command
sync_feed = element sync_feed { "" } sync_feed_response = element sync_feed_response { attribute status { status } & attribute status_text { text } } 7.13.3 Example: Sync the feed
Client
<sync_feed/> <sync_feed_response status="202" status_text="OK, request submitted"/>
This file was automatically generated.
|