Scanner REST Reference

/scanner

Methods
GET

Gets the list of Scanners.

NOTE: This call will return all Scanners for an Administrator. For an Organization User, it will only return agent-capable Scanners associated with that User's Organization.

Fields Parameter
 Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

Allowed Fields (Admin User)

*id
**name
**description
**status
ip
port
useProxy
enabled
verifyHost
managePlugins
authType
cert
username
password
agentCapable
version
webVersion
admin
msp
numScans
numHosts
numSessions
numTCPSessions
loadAvg
uptime
pluginSet
loadedPluginSet
serverUUID
createdTime
modifiedTime
zones
nessusManagerOrgs

Allowed Fields (Org User)

*id
**name
**description
**status
agentCapable

Legend

* = always comes back

** = comes back if fields list not specified on GET all
Request Query Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : [
		{
			"id" : "12",
			"name" : "Scanner 1",
			"description" : "Copied from QA",
			"status" : "1"
		},
		{
			"id" : "14",
			"name" : "Scanner using Safe Scan Range",
			"description" : "",
			"status" : "16"
		},
		{
			"id" : "15",
			"name" : "mp zone 1 scanner",
			"description" : "Copied from QA",
			"status" : "1"
		},
		{
			"id" : "16",
			"name" : "NessusTest",
			"description" : "Copied From QA",
			"status" : "32"
		},
		{
			"id" : "17",
			"name" : "sc",
			"description" : "",
			"status" : "2"
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1426878501
}

POST

Adds a Scanner.

Request Parameters
 Expand
{
	"name" : <string>,
	"description" : <string> DEFAULT "",
	"authType" : <string> "certificate" | "password" DEFAULT "password",
	"ip" : <string>,
	"port" : <number>,
	"useProxy" : <string> "true" | "false" DEFAULT "false",
	"verifyHost" : <string> "true" | "false" DEFAULT "true",
	"enabled" : <string> "true" | "false" DEFAULT "true",
	"managePlugins" : <string> "true" | "false" DEFAULT "false",
	"agentCapable" : <string> "true" | "false" DEFAULT "false",
	"zones" : [
		{
			"id" : <number>
		}...
	] DEFAULT [],
	"nessusManagerOrgs" : [
		{
			"id" : <number>
		}...
	] DEFAULT []
...
}

authType "certificate"

...
	"cert" : <string>,
	"password" : <string> DEFAULT ""
...

authType "password"

...
	"username" : <string>,
	"password" : <string>
...
Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"id" : "5",
		"name" : "My Active Scanner",
		"description" : "",
		"ip" : "192.168.1.145",
		"port" : "443",
		"useProxy" : "false",
		"enabled" : "true",
		"verifyHost" : "true",
		"managePlugins" : "false",
		"authType" : "password",
		"cert" : null,
		"username" : "nonadmin",
		"password" : "SET",
		"version" : null,
		"webVersion" : null,
		"admin" : "false",
		"msp" : "false",
		"numScans" : "0",
		"numHosts" : "0",
		"numSessions" : "0",
		"numTCPSessions" : "0",
		"loadAvg" : "0.0",
		"uptime" : -1,
		"status" : "8192",
		"pluginSet" : null,
		"loadedPluginSet" : null,
		"serverUUID" : null,
		"createdTime" : "1402435586",
		"modifiedTime" : "1402435586",
		"zones" : [
			{
				"id" : "1",
				"name" : "Big Zone",
				"description" : ""
			}
		],
		"nessusManagerOrgs" : [
			{
				"id" : "1",
				"name" : "Big Org",
				"description" : ""
			}
		]
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402435586
}

/scanner/{id}

Methods
GET

Gets the Scanner associated with {id}.

NOTE: This call will return all Scanners for an Administrator. For an Organization User, it will only return agent-capable Scanners associated with that User's Organization.

Fields Parameter
 Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

Allowed Fields (Admin User)

*id
**name
**description
**status
ip
port
useProxy
enabled
verifyHost
managePlugins
authType
cert
username
password
agentCapable
version
webVersion
admin
msp
numScans
numHosts
numSessions
numTCPSessions
loadAvg
uptime
pluginSet
loadedPluginSet
serverUUID
createdTime
modifiedTime
zones
nessusManagerOrgs

Allowed Fields (Org User)

*id
**name
**description
**status
agentCapable

Legend

* = always comes back

** = comes back if fields list not specified on GET all
Request Query Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"id" : "5",
		"name" : "My Active Scanner",
		"description" : "",
		"ip" : "192.168.1.145",
		"port" : "443",
		"useProxy" : "false",
		"enabled" : "true",
		"verifyHost" : "true",
		"managePlugins" : "false",
		"authType" : "password",
		"cert" : null,
		"username" : "nonadmin",
		"password" : "SET",
		"version" : null,
		"webVersion" : null,
		"admin" : "false",
		"msp" : "false",
		"numScans" : "0",
		"numHosts" : "0",
		"numSessions" : "0",
		"numTCPSessions" : "0",
		"loadAvg" : "0.0",
		"uptime" : -1,
		"status" : "8192",
		"pluginSet" : null,
		"loadedPluginSet" : null,
		"serverUUID" : null,
		"createdTime" : "1402435586",
		"modifiedTime" : "1402435586",
		"zones" : [
			{
				"id" : "1",
				"name" : "Big Zone",
				"description" : ""
			}
		],
		"nessusManagerOrgs" : [
			{
				"id" : "1",
				"name" : "Big Org",
				"description" : ""
			}
		]
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402435871
}


PATCH

Edits the Scanner associated with {id}, changing only the passed in fields.

Request Parameters

(All fields are optional)

Example Response

DELETE

Deletes the Scanner associated with {id}, depending on access and permissions.

Request Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : "",
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402436001
}

/scanner/{id}/testScansQuery

POST

Tests the Scans glob against the API of the Scanner associated with {id}.

Request Parameters
 Expand
{
	"scansGlob" : <string>
	"resultsSync" : {
		"id" : <number>
	} OPTIONAL
}
Example Response
 Expand
{
	"type" : "regular",
	"response" : [
		{
			"name" : "basic agent scan all agents",
			"numResults" : 5
		},
		{
			"name" : "C agent policy compliance scan",
			"numResults" : 4
		},
		{
			"name" : "mp advanced agent scan all plugins plus multiple file contents compliance audits",
			"numResults" : 2
		},
		{
			"name" : "windows agent malware scan",
			"numResults" : 3
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1442351168
}

/scanner/updateStatus

The /scanner/updateStatus resource.

POST

Starts an on-demand Scanner status update.

Request Parameters

None.

Example Response
 Expand

TODO – Rethink what is returned because the status here is not reflective of any updates since the call was made. We may want to return nothing for "response".

{
	"type" : "regular",
	"response" : [
		{
			"id" : "5",
			"name" : "My Active Scanner",
			"description" : "",
			"status" : "8200"
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402435958
}

Expand Items:

  • details

Show type specific details (such as certificate information, etc.)