English | Deutsch
Home »

OAP: OpenVAS Administrator Protocol

Version: 1.1

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
  5. Data Type Details
  6. Element Details
  7. Command Details

1 Summary of Data Types

base64
Base64 encoded data.
boolean
A true or false value.
boolean_atoi
A true or false value, after conversion to an integer.
ctime
A date and time, in the C ctime format.
type_name
A name of a data type.
integer
An integer.
levels
A string that may include the characters h, m, l, g and d.
name
A name.
oid
An Object Identifier (OID).
sort_order
A string describing an order for sorting.
status
The success or failure status of a command.
task_status
A task run status.
task_trend
The trend of results for a task.
threat
A threat level.
time_unit
A unit of time.
uuid
A Universally Unique Identifier (UUID).
uuid_or_empty
A Universally Unique Identifier (UUID), or the empty string.

2 Summary of Elements

c
A reference to a command.
e
A reference to an element.
r
A reference to a response.
o
An optional pattern item.
g
A group of pattern items.
any
Pattern item indicating "any number of".
pattern
The pattern element of a command or command descendant.
command_definition
Definition of a command in OAP describing HELP command.
sources
List of authentication sources associated to a user.

3 Summary of Commands

authenticate
Authenticate with the Administrator.
commands
Run a list of commands.
create_user
Create a user.
delete_user
Delete a user.
describe_auth
Describe a auth.
describe_feed
Describe the NVT feed.
get_settings
Get all settings.
get_users
Get all users.
get_version
Get the OpenVAS Administrator Protocol version.
help
Get the help text.
modify_auth
Modify the authentication methods.
modify_user
Modify a user.
sync_feed
Synchronize with an NVT feed.

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 Details

5.1 Data Type base64

In short: Base64 encoded data.

5.1.1 RNC

base64 = xsd:base64Binary

5.2 Data Type boolean

In 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 RNC

boolean = text

5.3 Data Type boolean_atoi

In 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 RNC

boolean_atoi = text

5.4 Data Type ctime

In 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 RNC

ctime = text

5.5 Data Type type_name

In short: A name of a data type.

5.5.1 RNC

type_name = xsd:string - xsd:whitespace

5.6 Data Type integer

In short: An integer.

5.6.1 RNC

integer = xsd:integer

5.7 Data Type levels

In short: A string that may include the characters h, m, l, g and d.

5.7.1 RNC

levels = xsd:token { pattern = "h?m?l?g?d?" }

5.8 Data Type name

In short: A name.

5.8.1 RNC

name = xsd:string

5.9 Data Type oid

In short: An Object Identifier (OID).

5.9.1 RNC

oid = xsd:token { pattern = "[0-9\.]{1,80}" }

5.10 Data Type sort_order

In short: A string describing an order for sorting.

The string "descending" denotes descending order, anything else means ascending.

5.10.1 RNC

sort_order = text

5.11 Data Type status

In short: The success or failure status of a command.

5.11.1 RNC

status = xsd:token { pattern = "200|201|202|400|401|403|404|409|500|503" }

5.12 Data Type task_status

In short: A task run status.

5.12.1 RNC

task_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_trend

In short: The trend of results for a task.

5.13.1 RNC

task_trend = xsd:token { pattern = "up|down|more|less|same" }

5.14 Data Type threat

In short: A threat level.

5.14.1 RNC

threat = xsd:token { pattern = "High|Medium|Low|Log|Debug" }

5.15 Data Type time_unit

In short: A unit of time.

5.15.1 RNC

time_unit = xsd:token { pattern = "second|minute|hour|day|week|month|year|decade" }

5.16 Data Type uuid

In short: A Universally Unique Identifier (UUID).

5.16.1 RNC

uuid = xsd:token { pattern = "[0-9abcdefABCDEF\-]{1,40}" }

5.17 Data Type uuid_or_empty

In short: A Universally Unique Identifier (UUID), or the empty string.

5.17.1 RNC

uuid_or_empty = xsd:token { pattern = "[0-9abcdefABCDEF\-]{0,40}" }

6 Element Details

6.1 Element c

In short: A reference to a command.

6.1.1 Structure

    6.1.2 RNC

    c
     = element c
         {
           text
         }
    

    6.2 Element e

    In short: A reference to an element.

    6.2.1 Structure

      6.2.2 RNC

      e
       = element e
           {
             text
           }
      

      6.3 Element r

      In short: A reference to a response.

      6.3.1 Structure

        6.3.2 RNC

        r
         = element r
             {
               text
             }
        

        6.4 Element o

        In short: An optional pattern item.

        6.4.1 Structure

          • One of
            • <c>
              A reference to a command.
            • <e>
              A reference to an element.
            • <r>
              A reference to a response.
            • <g>
              A group of pattern items.

        6.4.2 RNC

        o
         = element o
             {
               ( c
                   | e
                   | r
                   | g )
             }
        

        6.5 Element g

        In short: A group of pattern items.

        6.5.1 Structure

          • <c> *
            A reference to a command.
          • <e> *
            A reference to an element.
          • <r> *
            A reference to a response.
          • <o> *
            An optional pattern item.
          • <any> *
            Pattern item indicating "any number of".

        6.5.2 RNC

        g
         = element g
             {
               c*
               & e*
               & r*
               & o*
               & any*
             }
        

        6.6 Element any

        In short: Pattern item indicating "any number of".

        6.6.1 Structure

          • One of
            • <c>
              A reference to a command.
            • <e>
              A reference to an element.
            • <r>
              A reference to a response.
            • <g>
              A group of pattern items.

        6.6.2 RNC

        any
         = element any
             {
               ( c
                   | e
                   | r
                   | g )
             }
        

        6.7 Element pattern

        In 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 Structure

          • <attrib> *
            An attribute.
            • <name>
              • <type>
                • <required>
                • <c> *
                  A reference to a command.
                • <e> *
                  A reference to an element.
                • <r> *
                  A reference to a response.
                • <o> *
                  An optional pattern item.
                • <g> *
                  A group of pattern items.
                • <any> *
                  Pattern item indicating "any number of".
                • <t> ?
                  The type of the text of the element.

                6.7.2 RNC

                pattern
                 = 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_definition

                In short: Definition of a command in OAP describing HELP command.

                6.8.1 Structure

                  • <name>
                    The name of the command.
                    • <summary> ?
                      A summary of the command.
                      • <description> ?
                        A description of the command.
                        • <p> *
                          A paragraph.
                        • One of
                        • <example> *
                          • <summary> ?
                            • <description> ?
                              • <request>
                                Example request.
                                • <response>
                                  Response to example request.

                              6.8.2 RNC

                              command_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*
                                   }
                              

                              6.9 Element sources

                              In short: List of authentication sources associated to a user.

                              6.9.1 Structure

                                • <source> *
                                  The name of the authentication source.

                                6.9.2 RNC

                                sources
                                 = element sources
                                     {
                                       sources_source*
                                     }
                                
                                sources_source
                                 = element source
                                     {
                                       text
                                     }
                                

                                7 Command Details

                                7.1 Command authenticate

                                In 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

                                • Command
                                  • <credentials>
                                    • <username>
                                      The login name of the user.
                                      • <password>
                                        The user's password.
                                    • Response
                                      • @status (status)
                                      • @status_text (text)

                                    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
                                         }
                                    
                                    Response
                                    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>
                                    
                                    Administrator
                                     <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>
                                    
                                    Administrator
                                     <authenticate_response status="400"
                                                            status_text="Authentication failed"/>
                                    

                                    7.2 Command commands

                                    In 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 )*
                                         }
                                    
                                    Response
                                    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_user

                                    In short: Create a user.

                                    The client uses the create_user command to create a new user.

                                    7.3.1 Structure

                                    • Command
                                      • <name>
                                        The name of the user to be created.
                                        • <hosts> ?
                                          User access rules: a textual list of hosts.
                                        • <password> ?
                                          The password for the user.
                                          • <role> ?
                                            The role of the user.
                                          • Response

                                          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|Observer" }
                                               }
                                          
                                          Response
                                          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>
                                          
                                          Administrator
                                           <create_user_response status="201"
                                                                 status_text="OK, resource created"/>
                                          

                                          7.4 Command delete_user

                                          In 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

                                          • Command
                                            • <name>
                                              The name of the user to be deleted.
                                            • Response
                                              • @status (status)
                                              • @status_text (text)

                                            7.4.2 RNC

                                            Command
                                            delete_user
                                             = element delete_user
                                                 {
                                                   delete_user_name
                                                 }
                                            
                                            delete_user_name
                                             = element name
                                                 {
                                                   text
                                                 }
                                            
                                            Response
                                            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"/>
                                            
                                            Administrator
                                             <delete_user_response status="200"
                                                                   status_text="OK"/>
                                            

                                            7.5 Command describe_auth

                                            In 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

                                            • Command
                                                Empty single element.
                                            • Response
                                              • @status (status)
                                              • @status_text (text)
                                              • <group>
                                                Config group.
                                                • @name (text)
                                                • <auth_conf_setting>
                                                  • @key (text)
                                                  • @value (text)

                                            7.5.2 RNC

                                            Command
                                            describe_auth
                                             = element describe_auth
                                                 {
                                                   ""
                                                 }
                                            
                                            Response
                                            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/>
                                            
                                            Administrator
                                             <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_feed

                                            In 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

                                            • Command
                                                Empty single element.
                                            • Response
                                              • @status (status)
                                              • @status_text (text)
                                              • <feed>
                                                • <name>
                                                  The name of the feed.
                                                  • <version>
                                                    The version of the feed.
                                                    • <description>
                                                      A description of the feed.

                                                  7.6.2 RNC

                                                  Command
                                                  describe_feed
                                                   = element describe_feed
                                                       {
                                                         ""
                                                       }
                                                  
                                                  Response
                                                  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/>
                                                  
                                                  Administrator
                                                   <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_settings

                                                  In 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

                                                  • Command
                                                      Empty single element.
                                                  • Response
                                                    • @status (status)
                                                    • @status_text (text)
                                                    • <scanner_settings>
                                                      • <setting> *
                                                        The name of the setting.
                                                        • @name (text)

                                                  7.7.2 RNC

                                                  Command
                                                  get_settings
                                                   = element get_settings
                                                       {
                                                         ""
                                                       }
                                                  
                                                  Response
                                                  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/>
                                                  
                                                  Administrator
                                                   <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_users

                                                  In 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

                                                  • Command
                                                      Empty single element.
                                                  • Response
                                                    • @status (status)
                                                    • @status_text (text)
                                                    • <user> *
                                                      • <name>
                                                        The name of the user.
                                                        • <role>
                                                          The role of the user.
                                                          • <hosts>
                                                            Host access rule for the user.
                                                            • @allow ("0", "1", "2" or "3") 0 forbidden, 1 allowed, 2 all allowed, 3 custom.
                                                          • <sources>
                                                            Sources allowed for authentication for this user.

                                                        7.8.2 RNC

                                                        Command
                                                        get_users
                                                         = element get_users
                                                             {
                                                               ""
                                                             }
                                                        
                                                        Response
                                                        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_sources
                                                             }
                                                        
                                                        get_users_response_user_name
                                                         = element name
                                                             {
                                                               text
                                                             }
                                                        
                                                        get_users_response_user_role
                                                         = element role
                                                             {
                                                               xsd:token { pattern = "Admin|User|Observer" }
                                                             }
                                                        
                                                        get_users_response_user_hosts
                                                         = element hosts
                                                             {
                                                               text
                                                               & attribute allow { xsd:token { pattern = "0|1|2|3" } }
                                                             }
                                                        
                                                        get_users_response_user_sources
                                                         = element sources    # type sources
                                                             {
                                                               sources_source*
                                                             }
                                                        

                                                        7.8.3 Example: Get the users

                                                        Client
                                                         <get_users/>
                                                        
                                                        Administrator
                                                         <get_users_response status="200"
                                                                             status_text="OK">
                                                           <user>
                                                             <name>foobar</name>
                                                             <role>User</role>
                                                             <hosts allow="2"/>
                                                             <sources>
                                                               <source>file</source>
                                                             </sources>
                                                           </user>
                                                         </get_users_response>
                                                        

                                                        7.9 Command get_version

                                                        In short: Get the OpenVAS Administrator Protocol version.

                                                        7.9.1 Structure

                                                        • Command
                                                            Empty single element.
                                                        • Response
                                                          • @status (status)
                                                          • @status_text (text)
                                                          • <version>

                                                          7.9.2 RNC

                                                          Command
                                                          get_version
                                                           = element get_version
                                                               {
                                                                 ""
                                                               }
                                                          
                                                          Response
                                                          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/>
                                                          
                                                          Administrator
                                                           <get_version_response status="200"
                                                                                 status_text="OK">
                                                             <version>1.0</version>
                                                           </get_version_response>
                                                          

                                                          7.10 Command help

                                                          In short: Get the help text.

                                                          7.10.1 Structure

                                                          • Command
                                                            • @format ("html", "HTML", "rnc", "RNC", "text", "TEXT", "xml" or "XML") Required help format.
                                                          • Response
                                                            • @status (status)
                                                            • @status_text (text)
                                                            • <schema> ?
                                                              • <protocol>
                                                                • <name>
                                                                  The full name of the protocol.
                                                                  • <abbreviation> ?
                                                                    The abbreviated name of the protocol.
                                                                    • <summary> ?
                                                                      A summary of the protocol.
                                                                      • <version> ?
                                                                        The version number of the protocol.
                                                                        • <type> *
                                                                          A data type.
                                                                          • <name>
                                                                            The name of the data type.
                                                                            • <summary> ?
                                                                              A summary of the data type.
                                                                              • <description> ?
                                                                                A description of the data type.
                                                                                • <p> *
                                                                                  A paragraph.
                                                                                • <pattern>
                                                                                  The RNC pattern for the data type.
                                                                                • <command> *
                                                                                  A command.

                                                                            7.10.2 RNC

                                                                            Command
                                                                            help
                                                                             = element help
                                                                                 {
                                                                                   attribute format { xsd:token { pattern = "html|HTML|rnc|RNC|text|TEXT|xml|XML" } }?
                                                                                 }
                                                                            
                                                                            Response
                                                                            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/>
                                                                            
                                                                            Administrator
                                                                             <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"/>
                                                                            
                                                                            Administrator
                                                                             <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_auth

                                                                            In short: Modify the authentication methods.

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

                                                                            7.11.1 Structure

                                                                            • Command
                                                                              • <group>
                                                                                • <auth_conf_setting> *
                                                                                  A setting to modify.
                                                                                  • @key (text)
                                                                                  • @value (text)
                                                                            • Response
                                                                              • @status (status)
                                                                              • @status_text (text)

                                                                            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 }
                                                                                 }
                                                                            
                                                                            Response
                                                                            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>
                                                                            
                                                                            Administrator
                                                                             <modify_auth_response status="200"
                                                                                                   status_text="OK"/>
                                                                            

                                                                            7.12 Command modify_user

                                                                            In short: Modify a user.

                                                                            The client uses the "modify_user" command to modify an user account on the OpenVAS server.

                                                                            7.12.1 Structure

                                                                            • Command
                                                                              • <name>
                                                                                The name of the user to be modified.
                                                                                • <password> ?
                                                                                  The password for the user.
                                                                                  • <role>
                                                                                    The role of the user.
                                                                                    • <hosts> ?
                                                                                      User access rules: a textual list of hosts.
                                                                                    • <sources> ?
                                                                                      List of authentication sources for this user (if omitted, no changes).
                                                                                    • Response
                                                                                      • @status (status)
                                                                                      • @status_text (text)

                                                                                    7.12.2 RNC

                                                                                    Command
                                                                                    modify_user
                                                                                     = element modify_user
                                                                                         {
                                                                                           modify_user_name
                                                                                           & modify_user_password?
                                                                                           & modify_user_role
                                                                                           & modify_user_hosts?
                                                                                           & modify_user_sources?
                                                                                         }
                                                                                    
                                                                                    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|Observer" }
                                                                                         }
                                                                                    
                                                                                    modify_user_sources
                                                                                     = element sources    # type sources
                                                                                         {
                                                                                           sources_source*
                                                                                         }
                                                                                    
                                                                                    Response
                                                                                    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>
                                                                                    
                                                                                    Administrator
                                                                                     <modify_user_response status="200"
                                                                                                           status_text="OK"/>
                                                                                    

                                                                                    7.13 Command sync_feed

                                                                                    In 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

                                                                                    • Command
                                                                                        Empty single element.
                                                                                    • Response
                                                                                      • @status (status)
                                                                                      • @status_text (text)

                                                                                    7.13.2 RNC

                                                                                    Command
                                                                                    sync_feed
                                                                                     = element sync_feed
                                                                                         {
                                                                                           ""
                                                                                         }
                                                                                    
                                                                                    Response
                                                                                    sync_feed_response
                                                                                     = element sync_feed_response
                                                                                         {
                                                                                           attribute status { status }
                                                                                           & attribute status_text { text }
                                                                                         }
                                                                                    

                                                                                    7.13.3 Example: Sync the feed

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