TechDoc Portal

OPEN SCANNER PROTOCOL (OSP)
Version 22.04 – Greenbone OS 22.04


Contents

  1. Summary of Data Types
  2. Summary of Elements
  3. Summary of Commands
  4. Data Type Details
  5. Element Details
  6. Command Details
  7. Summary of Scanner Parameters Types
  8. Compatibility Changes in Version 22.04

1 Summary of Data Types

boolean
0 or 1.
epoch_time
A date, in Unix format.
integer
An integer.
status
Status code describing the result of a command.
string
A string.
uuid
A Universally Unique Identifier (UUID).
vt_id
Identifier for a vulnerability test.

2 Summary of Elements

credential
A credential consisting of type, service, port, username and password..
scanner_params
Contains elements that represent scanner specific parameters.
targets
List of targets.
target
A scan target consisting of hosts, a port selection and credentials.
vt_group
Collection of Vulnerability Test.
vt_selection
Contains elements that represent a Vulnerability Test or a collection of Vulnerability Tests to be executed and their parameters.
vt_single
Elements that represent Vulnerability Tests.
vt_value
Vulnerability Test parameter.

3 Summary of Commands

help
Get the help text.
get_performance
Return performance information from an external program.
get_scans
Get a stored scan in buffer.
delete_scan
Delete a finished scan.
get_version
Return various versions.
check_feed
Perform sync feed self test and check lockfile status.
get_scanner_details
Return scanner description and parameters.
get_vts
Return information about vulnerability tests, if offered by scanner.
start_scan
Start a new scan.
stop_scan
Stop a currently running scan.
get_memory_usage
Return memory usage information of the osp daemon.

4 Data Types Details

4.1 Data Type boolean

In short: 0 or 1.

4.1.1 RNC

boolean = xsd:token { pattern = "[01]" }
    

4.2 Data Type epoch_time

In short: A date, in Unix format.

4.2.1 RNC

epoch_time = integer
    

4.3 Data Type integer

In short: An integer.

4.3.1 RNC

integer = integer
    

4.4 Data Type status

In short: Status code describing the result of a command.

4.4.1 RNC

status = xsd:token { pattern = "[1-5][0-9][0-9]" }
    

4.5 Data Type string

In short: A string.

4.5.1 RNC

string = text
    

4.6 Data Type uuid

In short: A Universally Unique Identifier (UUID).

4.6.1 RNC

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

4.7 Data Type vt_id

In short: Identifier for a vulnerability test.

4.7.1 RNC

vt_id = xsd:token { pattern = "[0-9a-zA-Z_\-.:]{1,80}" }
    

5 Element Details

5.1 Element credential

In short: A credential consisting of type, service, port, username and password..

5.1.1 Structure

    • @type (string)
    • @service (string)
    • @port (string)
    • <username>
      • <password>
        • <private>
          • <priv_username>
            • <priv_password>
              • <community>
                • <auth_algorithm>
                  • <privacy_password>
                    • <privacy_algorithm>

                    5.1.2 RNC

                    credential
                         = element credential
                             {
                               attribute type { string }
                               & attribute service { string }
                               & attribute port { string }?
                               & credential_username
                               & credential_password
                               & credential_private
                               & credential_priv_username
                               & credential_priv_password
                               & credential_community
                               & credential_auth_algorithm
                               & credential_privacy_password
                               & credential_privacy_algorithm
                             }
                        
                        credential_username
                         = element username
                             {
                               text
                             }
                        
                        credential_password
                         = element password
                             {
                               text
                             }
                        
                        credential_private
                         = element private
                             {
                               file
                             }
                        
                        credential_priv_username
                         = element priv_username
                             {
                               text
                             }
                        
                        credential_priv_password
                         = element priv_password
                             {
                               text
                             }
                        
                        credential_community
                         = element community
                             {
                               text
                             }
                        
                        credential_auth_algorithm
                         = element auth_algorithm
                             {
                               text
                             }
                        
                        credential_privacy_password
                         = element privacy_password
                             {
                               text
                             }
                        
                        credential_privacy_algorithm
                         = element privacy_algorithm
                             {
                               text
                             }
                        

                    5.1.3 Example: SSH Credential with username + password authentication and port

                     <credential type="up"
                                     service="ssh"
                                     port="22">
                           <username>scanuser</username>
                           <password>mypass</password>
                         </credential>
                        

                    5.1.3 Example: SSH Credential with username + SSH Key authentication and port

                     <credential type="usk"
                                     service="ssh"
                                     port="22">
                           <username>scanuser</username>
                           <password>keypass</password>
                           <private>/path/to/ssh/keyfile</private>
                         </credential>
                        

                    5.1.3 Example: SSH Credential with elevated privileges

                     <credential type="up"
                                     service="ssh"
                                     port="22">
                           <username>scanuser</username>
                           <password>mypass</password>
                           <priv_username>root</priv_username>
                           <priv_password>rootpw</priv_password>
                         </credential>
                        

                    5.1.3 Example: ESXi Credential with username + password authentication

                     <credential type="up"
                                     service="smb">
                           <username>smbuser</username>
                           <password>mypass</password>
                         </credential>
                        

                    5.1.3 Example: SNMP Credentials

                     <credential type="snmp"
                                     service="snmp">
                           <username>smbuser</username>
                           <password>mypass</password>
                           <community>public</community>
                           <auth_algorithm>md5</auth_algorithm>
                           <privacy_password>privpass</privacy_password>
                           <privacy_algorithm>aes</privacy_algorithm>
                         </credential>
                        

                    5.2 Element scanner_params

                    In short: Contains elements that represent scanner specific parameters.

                    5.2.1 Structure

                      • <e>
                        (string)
                        Element that represents a scanner specific parameters.

                      5.2.2 RNC

                      scanner_params
                           = element scanner_params
                               {
                                 scanner_params_e
                               }
                          
                          scanner_params_e
                           = element e    # type string
                               {
                               }
                          

                      5.2.3 Example: scanner_params

                       <scanner_params>
                             <target_port>443</target_port>
                             <use_https>1</use_https>
                             <profile>fast_scan</profile>
                           </scanner_params>
                          

                      5.3 Element targets

                      In short: List of targets.

                      5.3.1 Structure

                        • <target>
                          A scan target consisting of hosts, a port selection and credentials.

                      5.3.2 RNC

                      targets
                           = element targets
                               {
                                 target
                               }
                          

                      5.3.3 Example: Two targets

                       <targets>
                             <target>...</target>
                             <target>...</target>
                           </targets>
                          

                      5.4 Element target

                      In short: A scan target consisting of hosts, a port selection and credentials.

                      5.4.1 Structure

                        • <hosts>
                          (string)
                          One or many hosts. The list is comma-separated. Each entry can be a IP address, a CIDR notation, a hostname, a IP range. IPs can be v4 or v6.
                          • <ports>
                            (string)
                            A list of ports that is the same for the given hosts.
                            • <credentials>
                              One or many credentials containing the credential for the given hosts.
                              • <credential>
                                A credential consisting of type, service, port, username and password..
                            • <exclude_hosts>
                              (string)
                              One or many hosts to exclude. The list is comma-separated. Each entry can be a IP address, a CIDR notation, a hostname, a IP range. IPs can be v4 or v6. Each wrapper must handle the exclude hosts.
                              • <finished_hosts>
                                (string)
                                One or many finished hosts to exclude when the client resumes a task. The list is comma-separated. Each entry can be an IP address, a CIDR notation, a hostname, a IP range. IPs can be v4 or v6. The listed hosts will be set as finished before starting the scan. Each wrapper must handle the finished hosts.
                                • <alive_test_ports>
                                  (string)
                                  Dedicated port list for alive detection. Used for TCP-SYN and TCP-ACK ping when Boreas (scanner preference test_alive_hosts_only) is enabled. If no port list is provided ports 80, 137, 587, 3128, 8081 are used as defaults.
                                  • One of
                                    • <alive_test>
                                      (integer)
                                      Alive test type to be performed against the target.
                                      • <alive_test_methods>
                                        Alive test methods to be performed against the target.
                                        • <icmp>
                                          (boolean)
                                          ICMP ping.
                                          • <tcp_syn>
                                            (boolean)
                                            TCP-SYN ping.
                                            • <tcp_ack>
                                              (boolean)
                                              TCP-ACK ping.
                                              • <arp>
                                                (boolean)
                                                ARP ping.
                                                • <consider_alive>
                                                  (boolean)
                                                  Consider the target to be alive.
                                              • <reverse_lookup_unify>
                                                (string)
                                                If multiple IP addresses resolve to the same DNS name the DNS name will only get scanned once.
                                                • <reverse_lookup_only>
                                                  (string)
                                                  Only scan IP addresses that can be resolved into a DNS name.

                                                5.4.2 RNC

                                                target
                                                     = element target
                                                         {
                                                           target_hosts
                                                           & target_ports
                                                           & target_credentials
                                                           & target_exclude_hosts
                                                           & target_finished_hosts
                                                           & target_alive_test_ports
                                                           & ( target_alive_test
                                                               | target_alive_test_methods )
                                                           & target_reverse_lookup_unify
                                                           & target_reverse_lookup_only
                                                         }
                                                    
                                                    target_hosts
                                                     = element hosts    # type string
                                                         {
                                                         }
                                                    
                                                    target_ports
                                                     = element ports    # type string
                                                         {
                                                         }
                                                    
                                                    target_credentials
                                                     = element credentials
                                                         {
                                                           credential
                                                         }
                                                    
                                                    target_exclude_hosts
                                                     = element exclude_hosts    # type string
                                                         {
                                                         }
                                                    
                                                    target_finished_hosts
                                                     = element finished_hosts    # type string
                                                         {
                                                         }
                                                    
                                                    target_alive_test
                                                     = element alive_test    # type integer
                                                         {
                                                         }
                                                    
                                                    target_alive_test_methods
                                                     = element alive_test_methods
                                                         {
                                                           target_alive_test_methods_icmp
                                                           target_alive_test_methods_tcp_syn
                                                           target_alive_test_methods_tcp_ack
                                                           target_alive_test_methods_arp
                                                           target_alive_test_methods_consider_alive
                                                         }
                                                    
                                                    target_alive_test_methods_icmp
                                                     = element icmp    # type boolean
                                                         {
                                                         }
                                                    
                                                    target_alive_test_methods_tcp_syn
                                                     = element tcp_syn    # type boolean
                                                         {
                                                         }
                                                    
                                                    target_alive_test_methods_tcp_ack
                                                     = element tcp_ack    # type boolean
                                                         {
                                                         }
                                                    
                                                    target_alive_test_methods_arp
                                                     = element arp    # type boolean
                                                         {
                                                         }
                                                    
                                                    target_alive_test_methods_consider_alive
                                                     = element consider_alive    # type boolean
                                                         {
                                                         }
                                                    
                                                    target_alive_test_ports
                                                     = element alive_test_ports    # type string
                                                         {
                                                         }
                                                    
                                                    target_reverse_lookup_only
                                                     = element reverse_lookup_only    # type string
                                                         {
                                                         }
                                                    
                                                    target_reverse_lookup_unify
                                                     = element reverse_lookup_unify    # type string
                                                         {
                                                         }
                                                    

                                                5.4.3 Example: Target without credentials

                                                 <target>
                                                       <hosts>example.org</hosts>
                                                       <ports>T:22,U:5060</ports>
                                                       <alive_test>0</alive_test>
                                                       <alive_test_ports>22,80,123</alive_test_ports>
                                                       <reverse_lookup_only>0</reverse_lookup_only>
                                                       <reverse_lookup_unify>0</reverse_lookup_unify>
                                                     </target>
                                                    

                                                5.4.3 Example: Target with two credentials

                                                 <target>
                                                       <hosts>192.168.1.0/24</hosts>
                                                       <ports>1,2,3,80,443</ports>
                                                       <credentials>
                                                         <credential>...</credential>
                                                         <credential>...</credential>
                                                       </credentials>
                                                       <exclude_hosts>192.168.1.10-15</exclude_hosts>
                                                       <finished_hosts>192.168.1.1-3</finished_hosts>
                                                     </target>
                                                    

                                                5.5 Element vt_group

                                                In short: Collection of Vulnerability Test.

                                                5.5.1 Structure

                                                5.5.2 RNC

                                                vt_group
                                                     = element vt_group
                                                         {
                                                           attribute filter { string }
                                                         }
                                                    

                                                5.5.3 Example: VT group filtered by family name

                                                 <vt_group filter="family=general"/>
                                                    
                                                 <vt_group filter="family=debian"/>
                                                    

                                                5.6 Element vt_selection

                                                In short: Contains elements that represent a Vulnerability Test or a collection of Vulnerability Tests to be executed and their parameters.

                                                5.6.1 Structure

                                                  • <vt_single>
                                                    Elements that represent Vulnerability Tests.
                                                  • <vt_group>
                                                    Collection of Vulnerability Test.

                                                5.6.2 RNC

                                                vt_selection
                                                     = element vt_selection
                                                         {
                                                           vt_single
                                                           & vt_group
                                                         }
                                                    

                                                5.6.3 Example: VT with parameters and VT group

                                                 <vt_selection>
                                                       <vt_single id="1.3.6.1.4.1.25623.1.0.10662">
                                                         <vt_value id="XYZ JKL">200</vt_value>
                                                         <vt_value id="ABC">yes</vt_value>
                                                       </vt_single>
                                                       <vt_single id="1.3.6.1.4.1.25623.1.0.10330"/>
                                                       <vt_single id="1.3.6.1.4.1.25623.1.0.100034"/>
                                                       <vt_group filter="family=general"/>
                                                       <vt_group filter="family=debian"/>
                                                     </vt_selection>
                                                    

                                                5.7 Element vt_single

                                                In short: Elements that represent Vulnerability Tests.

                                                5.7.1 Structure

                                                  • @id (vt_id) Identifier for a vulnerability test.
                                                  • <vt_value>
                                                    Vulnerability Test parameter.

                                                5.7.2 RNC

                                                vt_single
                                                     = element vt_single
                                                         {
                                                           attribute id { vt_id }
                                                           & vt_value
                                                         }
                                                    

                                                5.7.3 Example: VT with parameters

                                                 <vt_single id="1.3.6.1.4.1.25623.1.0.10662">
                                                       <vt_value id="XYZ JKL">200</vt_value>
                                                       <vt_value id="ABC">yes</vt_value>
                                                     </vt_single>
                                                    
                                                 <vt_single id="1.3.6.1.4.1.25623.1.0.10330"/>
                                                    

                                                5.8 Element vt_value

                                                In short: Vulnerability Test parameter.

                                                5.8.1 Structure

                                                5.8.2 RNC

                                                vt_value
                                                     = element vt_value
                                                         {
                                                           string
                                                           & attribute id { string }
                                                         }
                                                    

                                                5.8.3 Example: Parameters for a single VT

                                                 <vt_value id="XYZ JKL">200</vt_value>
                                                    
                                                 <vt_value id="ABC">yes</vt_value>
                                                    

                                                6 Command Details

                                                6.1 Command help

                                                In short: Get the help text.

                                                6.1.1 Structure

                                                • Command
                                                  • @format ("xml" or "text") Help format.
                                                • Response
                                                  • @status (status)
                                                  • @status_text (text)

                                                6.1.2 RNC

                                                help
                                                     = element help
                                                         {
                                                           attribute format { xsd:token { pattern = "xml|text" } }?
                                                         }
                                                    

                                                6.1.3 Example: Get the help text

                                                Client
                                                 <help format="xml"/>
                                                    
                                                Server
                                                 <help_response status_text="OK"
                                                                    status="200">
                                                       <delete_scan>
                                                         <attributes>
                                                           <scan_id>ID of scan to delete</scan_id>
                                                         </attributes>
                                                         <elements/>
                                                         <description>Delete a finished scan</description>
                                                       </delete_scan>
                                                       <help>
                                                         <attributes>
                                                           <format>Help format. Could be text or xml</format>
                                                         </attributes>
                                                         <elements/>
                                                         <description>Print the commands help</description>
                                                       </help>
                                                       <get_version>
                                                         <attributes/>
                                                         <elements/>
                                                         <description>Return various versions</description>
                                                       </get_version>
                                                       <check_feed>
                                                         <attributes/>
                                                         <elements/>
                                                         <description>Perform sync feed self test and check lockfile status</description>
                                                       </check_feed>
                                                       <stop_scan>
                                                         <attributes>
                                                           <scan_id>ID of scan stop.</scan_id>
                                                         </attributes>
                                                         <elements/>
                                                         <description>Stop a currently running scan.</description>
                                                       </stop_scan>
                                                       <get_scanner_details>
                                                         <attributes/>
                                                         <elements/>
                                                         <description>Return scanner description and parameters</description>
                                                       </get_scanner_details>
                                                       <start_scan>
                                                         <attributes>
                                                           <scan_id>Optional UUID value to set as scan ID</scan_id>
                                                           <target>Target hosts to scan in a comma-separated list</target>
                                                           <ports>Ports list to scan as comma-separated list</ports>
                                                           <parallel>Optional number of parallel scans to run</parallel>
                                                         </attributes>
                                                         <elements>
                                                           <scanner_params>
                                                             <profile>Scan profile</profile>
                                                             <target_port>Target port</target_port>
                                                             <use_https>Use HTTPS</use_https>
                                                             <w3af_timeout>w3af scan timeout</w3af_timeout>
                                                           </scanner_params>
                                                         </elements>
                                                         <description>Start a new scan</description>
                                                       </start_scan>
                                                       <stop_scan>
                                                         <attributes>
                                                           <scan_id>ID of scan to stop</scan_id>
                                                         </attributes>
                                                         <description>Stop a currently running scan</description>
                                                       </stop_scan>
                                                       <get_scans>
                                                         <attributes>
                                                           <scan_id>Mandatory ID of a specific scan to get</scan_id>
                                                           <details>Whether to return the full scan report</details>
                                                           <progress>Whether to return a detailed progress information</progress>
                                                           <pop_results>Whether to remove the fetched results</pop_results>
                                                           <max_results>
                                                             Maximum number of results to fetch. Only considered if pop_results is enabled. Default = None, which means that all available results are returned
                                                           </max_results>
                                                         </attributes>
                                                         <elements/>
                                                         <description>List the scans in buffer</description>
                                                       </get_scans>
                                                       <get_performance>
                                                         <description>Return system report</description>
                                                         <elements/>
                                                         <attributes>
                                                           <title>Name of report.</title>
                                                           <start>Time of first data point in report.</start>
                                                           <end>Time of last data point in report.</end>
                                                         </attributes>
                                                       </get_performance>
                                                     </help_response>
                                                    

                                                6.2 Command get_performance

                                                In short: Return performance information from an external program.

                                                6.2.1 Structure

                                                • Command
                                                  • @start (int) Interval start.
                                                  • @end (int) Interval end.
                                                  • @titles (text) Interval title to get.
                                                • Response
                                                  • @status (status)
                                                  • @status_text (text)

                                                6.2.2 RNC

                                                get_performance
                                                     = element get_performance
                                                         {
                                                           attribute start { int }?
                                                           & attribute end { int }?
                                                           & attribute titles { text }?
                                                         }
                                                    

                                                6.2.3 Example:

                                                Client
                                                 <get_performance start="0"
                                                                      titles="mem"/>
                                                    
                                                Server
                                                 <help_response status="200"
                                                                    status_text="OK">Some output.</help_response>
                                                    

                                                6.3 Command get_scans

                                                In short: Get a stored scan in buffer.

                                                6.3.1 Structure

                                                • Command
                                                  • @scan_id (uuid) Scan UUID.
                                                  • @details (boolean) Whether to get full scan reports.
                                                  • @progress (boolean) Whether to return a detailed progress information.
                                                  • @pop_results (boolean) Whether to remove the fetched results.
                                                  • @max_results (int) Maximum number of results to fetch. Only considered if pop_results is enabled. Default = None, which means that all available results are returned.
                                                • Response

                                                6.3.2 RNC

                                                get_scans
                                                     = element get_scans
                                                         {
                                                           attribute scan_id { uuid }?
                                                           & attribute details { boolean }?
                                                           & attribute progress { boolean }?
                                                           & attribute pop_results { boolean }?
                                                           & attribute max_results { int }?
                                                         }
                                                    

                                                6.3.3 Example: Get a scan report summary

                                                Client
                                                 <get_scans scan_id="f14747d3-a4d7-4e79-99bb-a0a1276cb78c"
                                                                details="1"
                                                                pop_results="0"/>
                                                    
                                                Server
                                                 <get_scans_response status_text="OK"
                                                                         status="200">
                                                       <scan id="9750f1f8-07aa-49cc-9c31-2f9e469c8f65"
                                                             target="192.168.1.252"
                                                             end_time="1432824234"
                                                             progress="100"
                                                             status="finished"
                                                             start_time="1432824206">
                                                         <results>
                                                           ...
                                                           <result host="192.168.1.252"
                                                                   hostname=""
                                                                   severity="2.5"
                                                                   port="443/tcp"
                                                                   test_id=""
                                                                   name="Path disclosure vulnerability"
                                                                   type="Alarm">
                                                             The URL: "https://192.168.1.252/" has a path disclosure vulnerability which discloses "/var/www/phpinfo.php" ...
                                                           </result>
                                                         </results>
                                                       </scan>
                                                     </get_scans_response>
                                                    

                                                6.3.3 Example: Get a scan report summary

                                                Client
                                                 <get_scans scan_id="f14747d3-a4d7-4e79-99bb-a0a1276cb78c"
                                                                details="1"
                                                                pop_results="1"
                                                                max_results="1"/>
                                                    
                                                Server
                                                 <get_scans_response status_text="OK"
                                                                         status="200">
                                                       <scan id="9750f1f8-07aa-49cc-9c31-2f9e469c8f65"
                                                             target="192.168.1.252"
                                                             end_time="1432824234"
                                                             progress="100"
                                                             status="finished"
                                                             start_time="1432824206">
                                                         <results>
                                                           <result host="192.168.1.252"
                                                                   hostname=""
                                                                   severity="2.5"
                                                                   port="443/tcp"
                                                                   test_id=""
                                                                   name="Path disclosure vulnerability"
                                                                   type="Alarm">
                                                             The URL: "https://192.168.1.252/" has a path disclosure vulnerability which discloses "/var/www/phpinfo.php" ...
                                                           </result>
                                                         </results>
                                                       </scan>
                                                     </get_scans_response>
                                                    

                                                6.3.3 Example: Get a scan progress summary

                                                Client
                                                 <get_scans scan_id="f14747d3-a4d7-4e79-99bb-a0a1276cb78c"
                                                                details="0"
                                                                progress="1"/>
                                                    
                                                Server
                                                 <get_scans_response status="200"
                                                                         status_text="OK">
                                                       <scan end_time="0"
                                                             id="f14747d3-a4d7-4e79-99bb-a0a1276cb78c"
                                                             progress="17"
                                                             start_time="1592316467"
                                                             status="running"
                                                             target="192.168.56.100, 127.0.0.1">
                                                         <progress>
                                                           <host name="127.0.0.1">2</host>
                                                           <host name="192.168.56.100">32</host>
                                                           <overall>17</overall>
                                                           <count_alive>0</count_alive>
                                                           <count_dead>0</count_dead>
                                                           <count_excluded>0</count_excluded>
                                                           <count_total>2</count_total>
                                                         </progress>
                                                       </scan>
                                                     </get_scans_response>
                                                    

                                                6.4 Command delete_scan

                                                In short: Delete a finished scan.

                                                6.4.1 Structure

                                                • Command
                                                  • @scan_id (uuid) Scan UUID.
                                                • Response
                                                  • @status (status)
                                                  • @status_text (text)

                                                6.4.2 RNC

                                                delete_scan
                                                     = element delete_scan
                                                         {
                                                           attribute scan_id { uuid }?
                                                         }
                                                    

                                                6.4.3 Example: Delete a scan successfully

                                                Client
                                                 <delete_scan scan_id="013587e3-b4d7-8e79-9ebb-90a2133c338c"/>
                                                    
                                                Server
                                                 <delete_scan_response status_text="OK"
                                                                           status="200"/>
                                                    

                                                6.5 Command get_version

                                                In short: Return various versions.

                                                6.5.1 Structure

                                                • Command
                                                    Empty single element.
                                                • Response
                                                  • @status (status)
                                                  • @status_text (text)
                                                  • <protocol>
                                                    • <name>
                                                      • <version>
                                                      • <daemon>
                                                        • <name>
                                                          • <version>
                                                          • <scanner>
                                                            • <name>
                                                              • <version>
                                                              • <vts>
                                                                • <name>
                                                                  • <version>
                                                                    • <home>
                                                                      • <vendor>

                                                                    6.5.2 RNC

                                                                    get_version
                                                                         = element get_version
                                                                             {
                                                                               ""
                                                                             }
                                                                        

                                                                    6.5.3 Example: Get protocol, scanner and daemon versions

                                                                    Client
                                                                     <get_version/>
                                                                        
                                                                    Server
                                                                     <get_version_response status_text="OK"
                                                                                               status="200">
                                                                           <protocol>
                                                                             <version>1.0</version>
                                                                             <name>OSP</name>
                                                                           </protocol>
                                                                           <daemon>
                                                                             <version>generic version</version>
                                                                             <name>generic ospd</name>
                                                                           </daemon>
                                                                           <scanner>
                                                                             <version>1.6.0.4</version>
                                                                             <name>w3af</name>
                                                                           </scanner>
                                                                           <vts>
                                                                             <version>202112070837</version>
                                                                             <vendor>Greenbone Networks GmbH</vendor>
                                                                             <home>https://www.greenbone.net/en/feed-comparison/</home>
                                                                             <name>Greenbone Security Feed</name>
                                                                           </vts>
                                                                         </get_version_response>
                                                                        

                                                                    6.6 Command check_feed

                                                                    In short: Perform sync feed self test and check lockfile status.

                                                                    6.6.1 Structure

                                                                    • Command
                                                                        Empty single element.
                                                                    • Response
                                                                      • @status (status)
                                                                      • @status_text (text)
                                                                      • <feed>
                                                                        • <lockfile_in_use>
                                                                          • <self_test_exit_error>
                                                                            • <self_test_error_msg>

                                                                          6.6.2 RNC

                                                                          check_feed
                                                                               = element check_feed
                                                                                   {
                                                                                     ""
                                                                                   }
                                                                              

                                                                          6.6.3 Example: Perform sync feed self test and check lockfile status

                                                                          Client
                                                                           <check_feed/>
                                                                              
                                                                          Server
                                                                           <check_feed_response status_text="OK"
                                                                                                    status="200">
                                                                                 <feed>
                                                                                   <lockfile_in_use>0</lockfile_in_use>
                                                                                   <self_test_exit_error>0</self_test_exit_error>
                                                                                   <self_test_error_msg/>
                                                                                 </feed>
                                                                               </check_feed_response>
                                                                              

                                                                          6.7 Command get_scanner_details

                                                                          In short: Return scanner description and parameters.

                                                                          6.7.1 Structure

                                                                          • Command
                                                                            • @list_all (boolean) List all available scanner parameters. Not only those visible to the client..
                                                                          • Response
                                                                            • @status (status)
                                                                            • @status_text (text)
                                                                            • <description>
                                                                              • <scanner_params>
                                                                                • <scanner_param> *
                                                                                  • @id (string)
                                                                                  • @type (string)
                                                                                  • <name>
                                                                                    • <description>
                                                                                      • <default>
                                                                                        • <mandatory>

                                                                                    6.7.2 RNC

                                                                                    get_scanner_details
                                                                                         = element get_scanner_details
                                                                                             {
                                                                                               attribute list_all { boolean }?
                                                                                             }
                                                                                        

                                                                                    6.7.3 Example: Get scanner details

                                                                                    Client
                                                                                     <get_scanner_details/>
                                                                                        
                                                                                    Server
                                                                                     <get_scanner_details_response status_text="OK"
                                                                                                                       status="200">
                                                                                           <description>...</description>
                                                                                           <scanner_params>
                                                                                             <scanner_param id="profile"
                                                                                                            type="selection">
                                                                                               <name>Scan profile</name>
                                                                                               <description>
                                                                                                 Scan profiles are predefined set of plugins and customized configurations.
                                                                                               </description>
                                                                                               <default>
                                                                                                 fast_scan|fast_scan|audit_high_risk|full_audit|OWASP_TOP10|bruteforce|empty_profile|web_infrastructure|full_audit_spider_man|sitemap
                                                                                               </default>
                                                                                             </scanner_param>
                                                                                             <scanner_param id="http_request_status"
                                                                                                            type="boolean">
                                                                                               <name>Show HTTP request status</name>
                                                                                               <description>Whether to show the HTTP request's status in results</description>
                                                                                               <default>0</default>
                                                                                             </scanner_param>
                                                                                             <scanner_param id="dry_run"
                                                                                                            type="boolean">
                                                                                               <name>Dry Run</name>
                                                                                               <description>Whether to dry run scan.</description>
                                                                                               <default>0</default>
                                                                                             </scanner_param>
                                                                                             <scanner_param id="http_request_headers"
                                                                                                            type="boolean">
                                                                                               <name>Show HTTP request headers</name>
                                                                                               <description>Whether to show the HTTP request's headers in results</description>
                                                                                               <default>0</default>
                                                                                             </scanner_param>
                                                                                             <scanner_param id="http_response_status"
                                                                                                            type="boolean">
                                                                                               <name>Show HTTP response status</name>
                                                                                               <description>Whether to show the HTTP response's status in results</description>
                                                                                               <default>0</default>
                                                                                             </scanner_param>
                                                                                             <scanner_param id="seed_path"
                                                                                                            type="string">
                                                                                               <name>Seed path</name>
                                                                                               <description>Path to start with</description>
                                                                                               <default>/</default>
                                                                                             </scanner_param>
                                                                                             <scanner_param id="debug_mode"
                                                                                                            type="boolean">
                                                                                               <name>Debug Mode</name>
                                                                                               <description>Whether to get extra scan debug information.</description>
                                                                                               <default>0</default>
                                                                                             </scanner_param>
                                                                                             <scanner_param id="target_port"
                                                                                                            type="integer">
                                                                                               <name>Target port</name>
                                                                                               <description>Port on target host to scan</description>
                                                                                               <default>80</default>
                                                                                             </scanner_param>
                                                                                             <scanner_param id="use_https"
                                                                                                            type="boolean">
                                                                                               <name>Use HTTPS</name>
                                                                                               <description>Whether the target application is running over HTTPS</description>
                                                                                               <default>0</default>
                                                                                             </scanner_param>
                                                                                           </scanner_params>
                                                                                         </get_scanner_details_response>
                                                                                        

                                                                                    6.8 Command get_vts

                                                                                    In short: Return information about vulnerability tests, if offered by scanner.

                                                                                    6.8.1 Structure

                                                                                    • Command
                                                                                      • @vt_id (vt_id) Identifier for vulnerability test.
                                                                                      • @filter (string) Filter to get a sub group of a VT collection.
                                                                                      • @details (string) Return more details about vulnerability tests, if offered by the scanner.
                                                                                      • @version_only (boolean) Return only feed information.
                                                                                    • Response
                                                                                      • @status (status)
                                                                                      • @status_text (text)
                                                                                      • <vts>
                                                                                        • @vts_version (text)
                                                                                        • @feed_vendor (text)
                                                                                        • @feed_home (text)
                                                                                        • @feed_name (text)
                                                                                        • @total (integer)
                                                                                        • @sha256_hash (text)
                                                                                        • <vt> *
                                                                                          • @id (vt_id)
                                                                                          • <name>
                                                                                            • <creation_time>
                                                                                              .
                                                                                            • <modification_time>
                                                                                              .
                                                                                            • <params>
                                                                                            • <refs>
                                                                                            • <dependencies>
                                                                                              • <dependency>
                                                                                            • <summary>
                                                                                              • <impact>
                                                                                                • <affected>
                                                                                                  • <insight>
                                                                                                    • <solution>
                                                                                                      • @type (string) Solution type, for example "VendorFix".
                                                                                                      • @method (string) Solution method, for example "DebianAPTUpgrade".
                                                                                                    • <detection>
                                                                                                      • <severities>
                                                                                                        • <severity> *
                                                                                                          • @type (string)
                                                                                                          • <origin>
                                                                                                            (string)
                                                                                                            Optional reference to the origin of the severity.
                                                                                                            • <date>
                                                                                                              (string)
                                                                                                              Optional timestamp in seconds since epoch. Defaults to VT creation date.
                                                                                                              • <value>
                                                                                                                (string)
                                                                                                                The actual value, the format must correspond with the type.
                                                                                                            • <custom>

                                                                                                        6.8.2 RNC

                                                                                                        get_vts
                                                                                                             = element get_vts
                                                                                                                 {
                                                                                                                   attribute vt_id { vt_id }?
                                                                                                                   & attribute filter { string }?
                                                                                                                   & attribute details { string }?
                                                                                                                   & attribute version_only { boolean }?
                                                                                                                 }
                                                                                                            

                                                                                                        6.8.3 Example: Get only feed information

                                                                                                        Client
                                                                                                         <get_vts version_only="1"/>
                                                                                                            
                                                                                                        Server
                                                                                                         <get_vts_response status="200"
                                                                                                                               status_text="OK">
                                                                                                               <vts vts_version="202112140941"
                                                                                                                    feed_vendor="Greenbone Networks GmbH"
                                                                                                                    feed_home="https://www.greenbone.net/en/feed-comparison/"
                                                                                                                    feed_name="Greenbone Security Feed"
                                                                                                                    total=""
                                                                                                                    sha256_hash="1762240dbd4ad0baf41ad9dcec58863922d63da35ceaa44488a55c3c23c4fcdb"/>
                                                                                                             </get_vts_response>
                                                                                                            

                                                                                                        6.8.3 Example: Get information for all available vulnerability tests

                                                                                                        Client
                                                                                                         <get_vts/>
                                                                                                            
                                                                                                        Server
                                                                                                         <get_vts_response status_text="OK"
                                                                                                                               status="200">
                                                                                                               <vts total="10">
                                                                                                                 <vt id="1.2.3.4.5">
                                                                                                                   <name>Check for presence of vulnerability X</name>
                                                                                                                 </vt>
                                                                                                                 <vt id="ad45h67">
                                                                                                                   <name>Check for presence of vulnerability Y</name>
                                                                                                                 </vt>
                                                                                                               </vts>
                                                                                                             </get_vts_response>
                                                                                                            

                                                                                                        6.8.3 Example: Get information for a single vulnerability test

                                                                                                        Client
                                                                                                         <get_vts vt_id="1.2.3.4.5"/>
                                                                                                            
                                                                                                        Server
                                                                                                         <get_vts_response status_text="OK"
                                                                                                                               status="200">
                                                                                                               <vts total="10">
                                                                                                                 <vt id="1.2.3.4.5">
                                                                                                                   <name>Check for presence of vulnerability X</name>
                                                                                                                   <refs>
                                                                                                                     <ref id="2014-16494"
                                                                                                                          type="fedora"/>
                                                                                                                     <ref id="https://lists.fedoraproject.org/"
                                                                                                                          type="url"/>
                                                                                                                     <ref id="CVE-2014-9116"
                                                                                                                          type="cve"/>
                                                                                                                   </refs>
                                                                                                                   <dependencies>
                                                                                                                     <dependency vt_id="1.3.6.1.4.1.25623.1.0.50282"/>
                                                                                                                   </dependencies>
                                                                                                                   <creation_time>1200603949</creation_time>
                                                                                                                   <modification_time>1567429142</modification_time>
                                                                                                                   <summary>Check the version of App</summary>
                                                                                                                   <affected>App in OS v2</affected>
                                                                                                                   <insight>App is a small but very powerful app.</insight>
                                                                                                                   <solution type="VendorFix">Please Install the Updated Packages.</solution>
                                                                                                                   <detection qod_type="package">
                                                                                                                     Get the installed version with the help of detect NVT and check if the version is vulnerable or not.
                                                                                                                   </detection>
                                                                                                                   <severities>
                                                                                                                     <severity type="cvss_base_v2">
                                                                                                                       <origin>CVE-2014-9116</origin>
                                                                                                                       <date>1200603949</date>
                                                                                                                       <value>AV:N/AC:L/Au:N/C:N/I:N/A:P</value>
                                                                                                                     </severity>
                                                                                                                   </severities>
                                                                                                                 </vt>
                                                                                                               </vts>
                                                                                                             </get_vts_response>
                                                                                                            

                                                                                                        6.8.3 Example: Get information for a filtered collection of vulnerability test without details

                                                                                                        Client
                                                                                                         <get_vts filter="modification_time>201903150834;modification_time<201903150835"
                                                                                                                      details="0"/>
                                                                                                            
                                                                                                        Server
                                                                                                         <get_vts_response status_text="OK"
                                                                                                                               status="200">
                                                                                                               <vts total="10"
                                                                                                                    sent="1">
                                                                                                                 <vt id="1.2.3.4.5">
                                                                                                                   <name>Check for presence of vulnerability X</name>
                                                                                                                   <refs>
                                                                                                                     <ref id="2014-16494"
                                                                                                                          type="fedora"/>
                                                                                                                     <ref id="https://lists.fedoraproject.org/"
                                                                                                                          type="url"/>
                                                                                                                     <ref id="CVE-2014-9116"
                                                                                                                          type="cve"/>
                                                                                                                   </refs>
                                                                                                                   <creation_time>1200603949</creation_time>
                                                                                                                   <modification_time>1567429142</modification_time>
                                                                                                                   <summary>Check the version of App</summary>
                                                                                                                   <affected>App in OS v2</affected>
                                                                                                                   <insight>App is a small but very powerful app.</insight>
                                                                                                                   <solution type="VendorFix">Please Install the Updated Packages.</solution>
                                                                                                                   <detection qod_type="package">
                                                                                                                     Get the installed version with the help of detect NVT and check if the version is vulnerable or not.
                                                                                                                   </detection>
                                                                                                                   <severities>
                                                                                                                     <severity type="cvss_base_v2">
                                                                                                                       <origin>CVE-2014-9116</origin>
                                                                                                                       <date>1200603949</date>
                                                                                                                       <value>AV:N/AC:L/Au:N/C:N/I:N/A:P</value>
                                                                                                                     </severity>
                                                                                                                   </severities>
                                                                                                                 </vt>
                                                                                                               </vts>
                                                                                                             </get_vts_response>
                                                                                                            

                                                                                                        6.8.3 Example: Get information for a vulnerability test with custom data

                                                                                                        Client
                                                                                                         <get_vts vt_id="1.2.3.4.5"/>
                                                                                                            
                                                                                                        Server
                                                                                                         <get_vts_response status_text="OK"
                                                                                                                               status="200">
                                                                                                               <vts total="10">
                                                                                                                 <vt id="1.2.3.4.5">
                                                                                                                   <name>Check for presence of vulnerability X</name>
                                                                                                                   <custom>
                                                                                                                     <my_element>First custom element</my_element>
                                                                                                                     <my_other_element>second custom element</my_other_element>
                                                                                                                   </custom>
                                                                                                                 </vt>
                                                                                                               </vts>
                                                                                                             </get_vts_response>
                                                                                                            

                                                                                                        6.8.3 Example: Get information for a vulnerability test with VT parameters data

                                                                                                        Client
                                                                                                         <get_vts vt_id="1.2.3.4.5"/>
                                                                                                            
                                                                                                        Server
                                                                                                         <get_vts_response status_text="OK"
                                                                                                                               status="200">
                                                                                                               <vts total="10">
                                                                                                                 <vt id="1.2.3.4.5">
                                                                                                                   <name>Check for presence of vulnerability X</name>
                                                                                                                   <params>
                                                                                                                     <param id="timeout"
                                                                                                                            type="integer">
                                                                                                                       <name>Timeout</name>
                                                                                                                       <description>Vulnerability Test Timeout</description>
                                                                                                                       <default>300</default>
                                                                                                                     </param>
                                                                                                                     <param id="scan.udp"
                                                                                                                            type="boolean">
                                                                                                                       <name>Scan UDP</name>
                                                                                                                       <description/>
                                                                                                                       <default>1</default>
                                                                                                                     </param>
                                                                                                                   </params>
                                                                                                                   <refs>
                                                                                                                     <ref type="cve"
                                                                                                                          id="CVE-2010-4480"/>
                                                                                                                     <ref type="url"
                                                                                                                          id="http://www.exploit-db.com/exploits/15699/"/>
                                                                                                                     <ref type="url"
                                                                                                                          id="http://www.vupen.com/english/advisories/2010/3133"/>
                                                                                                                   </refs>
                                                                                                                   <custom>
                                                                                                                     <my_element>First custom element</my_element>
                                                                                                                     <my_other_element>second custom element</my_other_element>
                                                                                                                   </custom>
                                                                                                                 </vt>
                                                                                                               </vts>
                                                                                                             </get_vts_response>
                                                                                                            

                                                                                                        6.9 Command start_scan

                                                                                                        In short: Start a new scan.

                                                                                                        6.9.1 Structure

                                                                                                        • Command
                                                                                                          • @target (string) Target hosts to scan in a comma-separated list.
                                                                                                          • @ports (string) Ports list to scan as comma-separated list.
                                                                                                          • @scan_id (uuid) Optional UUID value to use as scan ID.
                                                                                                          • @parallel (integer) Optional number of parallel scan to run.
                                                                                                          • <scanner_params>
                                                                                                            Contains elements that represent scanner specific parameters.
                                                                                                            • <vt_selection>
                                                                                                              Contains elements that represent a Vulnerability Test or a collection of Vulnerability Tests to be executed and their parameters.
                                                                                                              • <targets>
                                                                                                                Contains elements that represent a target to execute a scan against. If target and port attributes are present this element is not take into account.
                                                                                                              • Response
                                                                                                                • @status (status)
                                                                                                                • @status_text (text)
                                                                                                                • <id>
                                                                                                                  New scan's UUID.

                                                                                                                6.9.2 RNC

                                                                                                                start_scan
                                                                                                                     = element start_scan
                                                                                                                         {
                                                                                                                           attribute target { string }?
                                                                                                                           & attribute ports { string }?
                                                                                                                           & attribute scan_id { uuid }?
                                                                                                                           & attribute parallel { integer }?
                                                                                                                           & start_scan_scanner_params
                                                                                                                           & start_scan_vt_selection
                                                                                                                           & start_scan_targets
                                                                                                                         }
                                                                                                                    
                                                                                                                    start_scan_scanner_params
                                                                                                                     = element scanner_params
                                                                                                                         {
                                                                                                                         }
                                                                                                                    
                                                                                                                    start_scan_vt_selection
                                                                                                                     = element vt_selection
                                                                                                                         {
                                                                                                                         }
                                                                                                                    
                                                                                                                    start_scan_targets
                                                                                                                     = element targets
                                                                                                                         {
                                                                                                                         }
                                                                                                                    

                                                                                                                6.9.3 Example: Start a new scan. Legacy mode

                                                                                                                Client
                                                                                                                 <start_scan target="localhost"
                                                                                                                                 ports="80, 443">
                                                                                                                       <scanner_params>
                                                                                                                         <target_port>443</target_port>
                                                                                                                         <use_https>1</use_https>
                                                                                                                         <profile>fast_scan</profile>
                                                                                                                       </scanner_params>
                                                                                                                     </start_scan>
                                                                                                                    
                                                                                                                Server
                                                                                                                 <start_scan_response status_text="OK"
                                                                                                                                          status="200">
                                                                                                                       <id>2f616d53-595f-4785-9b97-4395116ca118</id>
                                                                                                                     </start_scan_response>
                                                                                                                    

                                                                                                                6.9.3 Example: Start a new scan with multi-targets running simultaneously. Each one has a different port list and one of them has credentials for authenticated scans.

                                                                                                                Client
                                                                                                                 <start_scan parallel="10">
                                                                                                                       <scanner_params>...</scanner_params>
                                                                                                                       <vt_selection>....</vt_selection>
                                                                                                                       <targets>
                                                                                                                         <target>...</target>
                                                                                                                         <target>
                                                                                                                           <hosts>192.168.1.0/24</hosts>
                                                                                                                           <ports>1,2,3,80,443</ports>
                                                                                                                           <credentials>...</credentials>
                                                                                                                           <exclude_hosts>192.168.1.10-15</exclude_hosts>
                                                                                                                           <finished_hosts>192.168.1.1-3</finished_hosts>
                                                                                                                         </target>
                                                                                                                       </targets>
                                                                                                                     </start_scan>
                                                                                                                    
                                                                                                                Server
                                                                                                                 <start_scan_response status_text="OK"
                                                                                                                                          status="200">
                                                                                                                       <id>2f616d53-595f-4785-9b97-4395116ca118</id>
                                                                                                                     </start_scan_response>
                                                                                                                    

                                                                                                                6.10 Command stop_scan

                                                                                                                In short: Stop a currently running scan.

                                                                                                                6.10.1 Structure

                                                                                                                • Command
                                                                                                                  • @scan_id (uuid) ID of scan to stop.
                                                                                                                • Response
                                                                                                                  • @status (status)
                                                                                                                  • @status_text (text)

                                                                                                                6.10.2 RNC

                                                                                                                stop_scan
                                                                                                                     = element stop_scan
                                                                                                                         {
                                                                                                                           attribute scan_id { uuid }?
                                                                                                                         }
                                                                                                                    

                                                                                                                6.10.3 Example: Stop a scan

                                                                                                                Client
                                                                                                                 <stop_scan scan_id="6ec1732c-10e8-448c-90fb-7797ad47ada2"/>
                                                                                                                    
                                                                                                                Server
                                                                                                                 <stop_scan_response status_text="OK"
                                                                                                                                         status="200"/>
                                                                                                                    

                                                                                                                6.11 Command get_memory_usage

                                                                                                                In short: Return memory usage information of the osp daemon.

                                                                                                                6.11.1 Structure

                                                                                                                • Command
                                                                                                                  • @unit (text) Size unit for the memory. b for bytes, kb for kilobytes and mb for megabytes..
                                                                                                                • Response
                                                                                                                  • @status (status)
                                                                                                                  • @status_text (text)

                                                                                                                6.11.2 RNC

                                                                                                                get_memory_usage
                                                                                                                     = element get_memory_usage
                                                                                                                         {
                                                                                                                           attribute unit { text }?
                                                                                                                         }
                                                                                                                    

                                                                                                                6.11.3 Example:

                                                                                                                Client
                                                                                                                 <get_memory_usage unit="kb"/>
                                                                                                                    
                                                                                                                Server
                                                                                                                 <get_memory_usage status="200"
                                                                                                                                       status_text="OK">
                                                                                                                       <processes>
                                                                                                                         <process name="MainProcess"
                                                                                                                                  pid="12345">
                                                                                                                           <rss>127182</rss>
                                                                                                                           <vss>239616</vss>
                                                                                                                           <shared>135168</shared>
                                                                                                                         </process>
                                                                                                                         <process name="Process-1"
                                                                                                                                  pid="23456">...</process>
                                                                                                                       </processes>
                                                                                                                     </get_memory_usage>
                                                                                                                    

                                                                                                                7 Summary of Scanner Parameters Types

                                                                                                                integer
                                                                                                                An integer value.
                                                                                                                string
                                                                                                                A string.
                                                                                                                boolean
                                                                                                                0 or 1.
                                                                                                                selection
                                                                                                                A value out of the | separated values list.
                                                                                                                credential_up
                                                                                                                The username:password of a credential.
                                                                                                                file
                                                                                                                A file's content.
                                                                                                                ovaldef_file
                                                                                                                An ovaldef file's content that is base64 encoded.

                                                                                                                8 Compatibility Changes in Version 22.04

                                                                                                                8.1 Change in CHECK_FEED

                                                                                                                In short: New command to perform a sync feed self test.

                                                                                                                Perform a sync feed self test and check if the lockfile is locked

                                                                                                                8.2 Change in GET_VTS

                                                                                                                In short: Add feed information.

                                                                                                                Include as arguments the feed's vendor, name and home.

                                                                                                                8.3 Change in GET_VERSION

                                                                                                                In short: Add feed information.

                                                                                                                Include as arguments the feed's vendor, name and home.

                                                                                                                8.4 Change in START_SCAN

                                                                                                                In short: Add support for privileged access to target.

                                                                                                                Credential Element got new Elements in case of SSH type. These new Elements allow an additional root access to the target system.

                                                                                                                This file was automatically generated.