Open Scanner Protocol (OSP) Version 1.2 - Greenbone OS 6

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 1.2

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 performan information from an external program.
get_scans
Get the stored scans.
delete_scan
Delete a finished scan.
get_version
Return various versions.
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.

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

5.1.2 RNC

credential
     = element credential
         {
           attribute type { string }
           & attribute service { string }
           & attribute port { string }?
           & credential_username
           & credential_password
         }
    
    credential_username
     = element username
         {
           text
         }
    
    credential_password
     = element password
         {
           text
         }
    

5.1.3 Example: Credential with port

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

5.1.3 Example: Credential without port

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

5.2 Element scanner_params

In short: Contains elements that represent scanner specific parameters.

5.2.1 Structure

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

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

5.4.2 RNC

target
     = element target
         {
           target_hosts
           & target_ports
           & target_credentials
           & target_exclude_hosts
         }
    
    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
         {
         }
    

5.4.3 Example: Target without credentials.

 <target>
       <hosts>example.org</hosts>
       <ports>T:22,U:5060</ports>
     </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>
     </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

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

5.7.2 RNC

vt_single
     = element vt_single
         {
           attribute vt_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

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>
       <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>ID of a specific scan to get</scan_id>
           <details>Whether to return the full scan report</details>
           <pop_results>Whether to remove the fetched results</pop_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 performan information from an external program.

6.2.1 Structure

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 the stored scans.

6.3.1 Structure

6.3.2 RNC

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

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.4 Command delete_scan

In short: Delete a finished scan.

6.4.1 Structure

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

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>
     </get_version_response>
    

6.6 Command get_scanner_details

In short: Return scanner description and parameters.

6.6.1 Structure

6.6.2 RNC

get_scanner_details
     = element get_scanner_details
         {
           ""
         }
    

6.6.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.7 Command get_vts

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

6.7.1 Structure

6.7.2 RNC

get_vts
     = element get_vts
         {
           attribute vt_id { vt_id }?
           & attribute filter { string }?
         }
    

6.7.3 Example: Get information for all available vulnerability tests

Client
 <get_vts/>
    
Server
 <get_vts_response status_text="OK"
                       status="200">
       <vts>
         <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.7.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>
         <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>2015-02-15 05:47:27 +0100 (Sun, 15 Feb 2015)</creation_time>
           <modification_time>$Date: 2017-07-10 08:34:32 +0200 (Mon, 10 Jul 2017) $</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">AV:N/AC:L/Au:N/C:N/I:N/A:P</severity>
           </severities>
         </vt>
       </vts>
     </get_vts_response>
    

6.7.3 Example: Get information for a filtered collection of vulnerability test

Client
 <get_vts filter="modification_time>201903150834;modification_time<201903150835"/>
    
Server
 <get_vts_response status_text="OK"
                       status="200">
       <vts>
         <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>2015-02-15 05:47:27 +0100 (Sun, 15 Feb 2015)</creation_time>
           <modification_time>$Date: 2019-03-15 08:34:32 +0200 (Mon, 10 Jul 2017) $</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">AV:N/AC:L/Au:N/C:N/I:N/A:P</severity>
           </severities>
         </vt>
       </vts>
     </get_vts_response>
    

6.7.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>
         <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.7.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>
         <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.8 Command start_scan

In short: Start a new scan.

6.8.1 Structure

6.8.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.8.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.8.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>
         </target>
       </targets>
     </start_scan>
    
Server
 <start_scan_response status_text="OK"
                          status="200">
       <id>2f616d53-595f-4785-9b97-4395116ca118</id>
     </start_scan_response>
    

6.9 Command stop_scan

In short: Stop a currently running scan.

6.9.1 Structure

6.9.2 RNC

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

6.9.3 Example: Stop a scan

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

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 1.2

8.1 Change in GET_VTS

In short: command added.

Added new command to retrieve information about vulnerability tests a scanner might offer.

8.2 Change in START_SCAN

In short: vts optional element added.

Added optional element vts to allow the client to specify a vts list to use for the scan and their parameters.

8.3 Change in START_SCAN

In short: target optional element added.

Added optional element targets to specify different hosts with a different port list and credentials. This is take in account only if target and port attributes are not present in start_scan tag.

8.4 Change in START_SCAN

In short: parallel attribute added.

Added optional attribute parallel to specify the number of simultaneous scans to be run.

8.5 Change in GET_PERFORMANCE

In short: Command added.

Added new command to get performance from an external program.

This file was automatically generated.