OSP: Open Scanner ProtocolVersion: 1.2 The Open Scanner Protocol. Contents
1 Summary of Data Types
2 Summary of Elements
3 Summary of Commands
4 Data Types Details4.1 Data Type booleanIn short: 0 or 1. 4.1.1 RNCboolean = xsd:token { pattern = "[01]" }
4.2 Data Type epoch_timeIn short: A date, in unix format. 4.2.1 RNCepoch_time = integer
4.3 Data Type integerIn short: An integer. 4.3.1 RNCinteger = integer
4.4 Data Type statusIn short: Status code describing the result of a command. 4.4.1 RNCstatus = xsd:token { pattern = "[1-5][0-9][0-9]" }
4.5 Data Type stringIn short: A string. 4.5.1 RNCstring = text
4.6 Data Type uuidIn short: A Universally Unique Identifier (UUID). 4.6.1 RNCuuid = xsd:token { pattern = "[0-9abcdefABCDEF\-]{1,40}" }
4.7 Data Type vt_idIn short: Identifier for a vulnerability test. 4.7.1 RNCvt_id = xsd:token { pattern = "[0-9a-zA-Z_\-.:]{1,80}" }
5 Element Details5.1 Element credentialIn short: A credential consisting of type, service, port, username and password.. 5.1.1 Structure5.1.2 RNCcredential
= 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_paramsIn short: Contains elements that represent scanner specific parameters. 5.2.1 Structure
5.2.2 RNCscanner_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 targetsIn short: List of targets. 5.3.1 Structure
5.3.2 RNCtargets
= element targets
{
target
}
5.3.3 Example: Two targets <targets>
<target>...</target>
<target>...</target>
</targets>
5.4 Element targetIn short: A scan target consisting of hosts, a port selection and credentials. 5.4.1 Structure
5.4.2 RNCtarget
= element target
{
target_hosts
& target_ports
& target_credentials
& target_exclude_hosts
& target_finished_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
{
}
target_finished_hosts
= element finished_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>
<finished_hosts>192.168.1.1-3</finished_hosts>
</target>
5.5 Element vt_groupIn short: Collection of Vulnerability Test. 5.5.1 Structure
5.5.2 RNCvt_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_selectionIn short: Contains elements that represent a Vulnerability Test or a collection of Vulnerability Tests to be executed and their parameters. 5.6.1 Structure5.6.2 RNCvt_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_singleIn short: Elements that represent Vulnerability Tests. 5.7.1 Structure5.7.2 RNCvt_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_valueIn short: Vulnerability Test parameter. 5.8.1 Structure
5.8.2 RNCvt_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 Details6.1 Command helpIn short: Get the help text. 6.1.1 Structure
6.1.2 RNChelp
= element help
{
attribute format { xsd:token { pattern = "xml|text" } }?
}
6.1.3 Example: Get the help text
Client
<help format="xml"/>
<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_performanceIn short: Return performan information from an external program. 6.2.1 Structure
6.2.2 RNCget_performance
= element get_performance
{
attribute start { int }?
& attribute end { int }?
& attribute titles { text }?
}
6.2.3 Example:
Client
<get_performance start="0"
titles="mem"/>
<help_response status="200"
status_text="OK">Some output.</help_response>
6.3 Command get_scansIn short: Get the stored scans. 6.3.1 Structure
6.3.2 RNCget_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"/>
<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_scanIn short: Delete a finished scan. 6.4.1 Structure6.4.2 RNCdelete_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"/>
<delete_scan_response status_text="OK"
status="200"/>
6.5 Command get_versionIn short: Return various versions. 6.5.1 Structure
6.5.2 RNCget_version
= element get_version
{
""
}
6.5.3 Example: Get protocol, scanner and daemon versions
Client
<get_version/>
<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_detailsIn short: Return scanner description and parameters. 6.6.1 Structure
6.6.2 RNCget_scanner_details
= element get_scanner_details
{
""
}
6.6.3 Example: Get scanner details
Client
<get_scanner_details/>
<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_vtsIn short: Return information about vulnerability tests, if offered by scanner. 6.7.1 Structure
6.7.2 RNCget_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/>
<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"/>
<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>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">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"/>
<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>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">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"/>
<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"/>
<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_scanIn short: Start a new scan. 6.8.1 Structure
6.8.2 RNCstart_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>
<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>
<finished_hosts>192.168.1.1-3</finished_hosts>
</target>
</targets>
</start_scan>
<start_scan_response status_text="OK"
status="200">
<id>2f616d53-595f-4785-9b97-4395116ca118</id>
</start_scan_response>
6.9 Command stop_scanIn short: Stop a currently running scan. 6.9.1 Structure6.9.2 RNCstop_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"/>
<stop_scan_response status_text="OK"
status="200"/>
7 Summary of Scanner Parameters Types
8 Compatibility Changes in Version 1.28.1 Change in GET_VTSIn short: command added. Added new command to retrieve information about vulnerability tests a scanner might offer. 8.2 Change in START_SCANIn 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_SCANIn 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_SCANIn short: parallel attribute added. Added optional attribute parallel to specify the number of simultaneous scans to be run. 8.5 Change in GET_PERFORMANCEIn short: Command added. Added new command to get performance from an external program.
This file was automatically generated.
|