Scan REST Reference

/scan

Methods
GET

Gets the list of Scans.

NOTE: Although a Scan's Schedule 'dependentID' is stored as the schedule ID of the object a scan is dependent upon in the database, it is sent from and returned to the user as the ID of the actual scan object.

Fields Parameter
 Expand

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

    ?fields=<field>,...

Allowed Fields

*id
**name
**description
**status

ipList
type
policy
plugin
repository
zone
dhcpTracking
classifyMitigatedAge
emailOnLaunch
emailOnFinish
timeoutAction
scanningVirtualHosts
rolloverType
createdTime
modifiedTime
ownerGroup
creator
owner
reports
assets
credentials
numDependents
schedule
policy
policyPrefs
maxScanTime 

Legend

* = always comes back

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

None

Expand Parameters

credentials

Filter Parameters

usable - The response will be an object containing an array of usable Scans. By default, both usable and manageable objects are returned.
manageable - The response will be an object containing all manageable Scans.. By default, both usable and manageable objects are returned. 

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"usable" : [
			{
				"id" : "2",
				"name" : "test",
				"description" : null
			},
			{
				"id" : "3",
				"name" : "test2",
				"description" : null
			},
			{
				"id" : "4",
				"name" : "POSTtest",
				"description" : "This is a test for POST"
			}
		],
		"manageable" : [
			{
				"id" : "2",
				"name" : "test",
				"description" : null
			},
			{
				"id" : "3",
				"name" : "test2",
				"description" : null,
			{
				"id" : "4",
				"name" : "POSTtest",
				"description" : "This is a test for POST"
			}
		]
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1406828340
}

POST

Adds a Scan, depending on access and permissions.

NOTE #1: A Blackout Window must not be in effect

NOTE #2: If the field schedule frequency is "dependent", the field type cannot be "template"

NOTE #3: Although a Scan's Schedule 'dependentID' is stored as the schedule ID of the object a scan is dependent upon in the database, it is sent from and returned to the user as the ID of the actual scan object.

Request Parameters
 Expand
{
	"name" : <string>,
	"type" : <string> "plugin" | "policy",
	"description" : <string> DEFAULT "",
	"repository" : {
		"id" : <number>
	},
	"zone" : {
		"id" : <number> DEFAULT "0" (All Zones)
	},
	"dhcpTracking" : <string> DEFAULT "false",
	"classifyMitigatedAge" : <number> DEFAULT "0",
	"schedule" : {
		"type" : "dependent" | "ical" | "never" | "rollover" | "template" <string> DEFAULT "template",
	},
	"reports" : [
		{
			"id" : <number>,
			"reportSource" : <string> "cumulative" | "patched" | "individual" | "lce" | "archive" | "mobile"
		}...
	] DEFAULT [],
	"assets" : [
		{
			"id" : <number>
		}...
	] DEFAULT [],
	"credentials" : [
		{
			"id" : <number>
		}...
	] DEFAULT [],
	"emailOnLaunch" : <string> "false" | "true" DEFAULT "false",
	"emailOnFinish" : <string> "false" | "true" DEFAULT "false",
	"timeoutAction" : <string> "discard" | "import" | "rollover" DEFAULT "import",
	"scanningVirtualHosts" : <string> "false" | "true" DEFAULT "false",
	"rolloverType" : <string> "nextDay" | "template" DEFAULT "template",
	"ipList" : <string> DEFAULT "" (valid IP),
	"maxScanTime" : <number> DEFAULT "3600"
}

type is "policy"

NOTE: The context of the policy associated with "id" is not passed here, but whether it is a context policy determines whether the pluginID parameter is required.

...
	"policy" : {
		"id" : <number>
	}
 
	policy is not context "" (Empty)
	--------------------------------
	"pluginID" : <number>
...

type is "plugin"

...
	"pluginID" : <number>
...

 

schedule type is "ical"

...
	"schedule" : {
		"start" : <string> (This value takes the iCal format),
		"repeatRule" : <string> (This value takes the repeat rule format)
	}
...
Example Response
 Expand
{	
	"type" : "regular",
	"response" : {	
		"id" : "4",
		"creatorID" : "1",
		"ownerID" : "1",
		"name" : "POSTtest",
		"description" : "This is a test for POST",
		"ipList" : "",
		"type" : "policy",
		"policyID" : "1000002",
		"pluginID" : "-1",
		"repositoryID" : "2",
		"zoneID" : "-1",
		"dhcpTracking" : "false",
		"classifyMitigatedAge" : "0",
		"emailOnLaunch" : "false",
		"emailOnFinish" : "false",
		"timeoutAction" : "import",
		"scanningVirtualHosts" : "false",
		"rolloverType" : "template",
		"status" : "0",
		"createdTime" : "1406815242",
		"modifiedTime" : "1406815242",
		"maxScanTime" : "3600",
		"ownerGID" : "0",
		"reports" : [],
		"assets" : [],
		"credentials" : [],
		"numDependents" : "0",
		"schedule" : {
			"id" : "17",
			"dependentID" : "14",
			"objectType" : "scan",
			"type" : "dependent",
			"start" : "",
			"repeatRule" : "",
			"nextRun" : 0,
			"dependent" : {
				"id" : "14",
				"name" : "Daily IP Scan",
				"description" : "",
				"status" : "1024"
			}
		},
		"policy" : {	
			"id" : "1000002",
			"name" : "POST TEST",
			"description" : "Test of post for use with scan post test"
		},
		"pluginPrefs" : [],
		"creator" : {	
			"id" : "1",
			"username" : "head3",
			"firstname" : "",
		"lastname" : ""
		},
		"owner" : {	
			"id" : "1",
			"username" : "head3",
			"firstname" : "",
			"lastname" : ""
		},
		"repository" : {
			"id" : "2",
			"name" : "test",
			"description" : "test"
		},
		"ownerGroup" : {	
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1406815242
}

/scan/{id}

Methods
GET

Gets the Scan associated with {id}.

NOTE: Although a Scan's Schedule 'dependentID' is stored as the schedule ID of the object a scan is dependent upon in the database, it is sent from and returned to the user as the ID of the actual scan object.

Fields Parameter
 Expand

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

    ?fields=<field>,...

Allowed Fields

*id
**name
**description
**status

ipList
type
policy
plugin
repository
zone
dhcpTracking
classifyMitigatedAge
emailOnLaunch
emailOnFinish
timeoutAction
scanningVirtualHosts
rolloverType
createdTime
modifiedTime
ownerGroup
creator
owner
reports
assets
credentials
numDependents
schedule
policy
policyPrefs
maxScanTime

Legend

* = always comes back

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

None

Expand Parameters

credentials

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"id" : "4",
		"name" : "POSTtest",
		"description" : "This is a test for POST",
		"ipList" : "",
		"type" : "policy",
		"dhcpTracking" : "false",
		"classifyMitigatedAge" : "0",
		"emailOnLaunch" : "false",
		"emailOnFinish" : "false",
		"timeoutAction" : "import",
		"scanningVirtualHosts" : "false",
		"rolloverType" : "template",
		"status" : "0",
		"createdTime" : "1406815242",
		"modifiedTime" : "1406815242",
		"reports" : [],
		"assets" : [],
		"numDependents" : "0",
		"schedule" : {
			"id" : "17",
			"dependentID" : "14",
			"objectType" : "scan",
			"type" : "dependent",
			"start" : "",
			"repeatRule" : "",
			"nextRun" : 0,
			"dependent" : {
				"id" : "14",
				"name" : "Daily IP Scan",
				"description" : "",
				"status" : "1024"
			}
		},
		"policy" : {
			"id" : "1000002",
			"name" : "POST TEST",
			"description" : "Test of post for use with scan post test"
		},
		"policyPrefs" : [],
		"repository" : {
			"id" : "2",
			"name" : "test",
			"description" : "test"
		},
		"ownerGroup" : {
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		},
		"creator" : {
			"id" : "1",
			"username" : "head3",
			"firstname" : "",
			"lastname" : ""
		},
		"owner" : {
			"id" : "1",
			"username" : "head3",
			"firstname" : "",
			"lastname" : ""
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1406828664
}

PATCH

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

NOTE: A Scan's 'type' parameter cannot be changed.

Request Parameters

(All fields are optional)

Example Response

DELETE

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

Request Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"scans" : [
			{
				"id" : "1"
			}
		]
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1406732180
}

/scan/{id}/copy

Methods

POST

Copies the Scan associated with {id}, depending on access and permissions.

Request Parameters
 Expand
{
 	"name" : <string>,
	"targetUser" : {
		"id" : <number>
	}
}
Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"scan" : {
			"id" : "3",
			"creatorID" : "1",
			"ownerID" : "1",
			"name" : "test2",
			"description" : null,
			"ipList" : "",
			"type" : "policy",
			"policyID" : "1000001",
			"pluginID" : null,
			"repositoryID" : "1",
			"zoneID" : "-1",
			"dhcpTracking" : "false",
			"classifyMitigatedAge" : "",
			"emailOnLaunch" : "false",
			"emailOnFinish" : "false",
			"timeoutAction" : "rollover",
			"scanningVirtualHosts" : "false",
			"rolloverType" : "template",
			"status" : "0",
			"createdTime" : "1406750972",
			"modifiedTime" : "1406750972",
			"ownerGID" : "0",
			"reports" : [],
			"assets" : [],
			"credentials" : [],
			"numDependents" : "0",
			"scheduleID" : -1,
			"scheduleDependentID" : -1,
			"scheduleFrequency" : "now",
			"scheduleStart" : "",
			"scheduleRepeatRule" : "",
			"scheduleNextRun" : -1,
			"blackout" : "false",
			"policy" : {"id" : "1000001",
			"name" : "test",
			"description" : null,
			"policyTemplateID" : "",
			"policyProfileName" : "ge",
			"policyTemplateType" : "",
			"creatorID" : "1",
			"ownerID" : "1",
			"context" : null,
			"tags" : "",
			"createdTime" : "",
			"modifiedTime" : "",
			"ownerGID" : "0",
			"targetGID" : "-1",
			"auditFiles" : [],
			"preferences" : [],
			"groups" : []},
			"pluginPrefs" : []
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1406750971
}

/scan/{id}/launch

Methods
POST

Launches the Scan associated with {id}.

Request Parameters

NOTE: "diagnosticTarget" and "diagnosticPassword" are both optional, but must be provided together if present.

 Expand
{
	"diagnosticTarget" : <string> (Valid IP/Hostname),
	"diagnosticPassword" : <string> (Non empty String)
}

 

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"scanID" : "2",
		"scanResult" : {
			"initiatorID" : "1",
			"ownerID" : "1",
			"ownerGID" : "0",
			"scanID" : "2",
			"repositoryID" : "1",
			"jobID" : "143301",
			"name" : "test",
			"description" : null,
			"details" : "Plugin #",
			"status" : "Queued",
			"importStatus" : "No Results",
			"downloadFormat" : "v2",
			"dataFormat" : "IPv4",
			"running" : false,
			"errorDetails" : "",
			"importErrorDetails" : "",
			"totalIPs" : -1,
			"scannedIPs" : 0,
			"startTime" : -1,
			"finishTime" : 0,
			"id" : "3"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1407510276
}