Tenable.sc API: Scan

 

/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
*uuid
**name
**description
**status
ipList
type
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
redFont =  field is a JSON object ( e.g. "repository" :{ "id" : <id>, "name" : <name> } )

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,
				"uuid" : "2EAED2D2-DFC7-4CFE-9C94-25CF6481C515"
			},
			{
				"id" : "3",
				"name" : "test2",
				"description" : null,
				"uuid" : "EC81E13E-B3B2-4A51-968D-E94D524B5254"
			},
			{
				"id" : "4",
				"name" : "POSTtest",
				"description" : "This is a test for POST",
				"uuid" : "2EAED2D2-DFC7-4CFE-9C94-25CF6481C515"
			}
		],
		"manageable" : [
			{
				"id" : "2",
				"name" : "test",
				"description" : null,
				"uuid" : "2EAED2D2-DFC7-4CFE-9C94-25CF6481C515"
			},
			{
				"id" : "3",
				"name" : "test2",
				"description" : null,
				"uuid" : "EC81E13E-B3B2-4A51-968D-E94D524B5254"
			{
				"id" : "4",
				"name" : "POSTtest",
				"description" : "This is a test for POST",
				"uuid" : "2EAED2D2-DFC7-4CFE-9C94-25CF6481C515"
			}
		]
	},
	"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: Setting schedule type to "template" means that the scan will not run on a schedule.

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

NOTE #4: 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> DEFAULT "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"
}


schedule type is "ical"

NOTE: The "enabled" field can only be set to "false" for schedules of type "ical". For all other schedules types, "enabled" is set to "true".

...
	"schedule" : {
		"start" : <string> (This value takes the iCal format),
		"repeatRule" : <string> (This value takes the repeat rule format),
		"enabled" : <string> "false" | "true" DEFAULT "true"
	}
...
Example Response
Expand
{	
	"type" : "regular",
	"response" : {	
		"id" : "4",
		"name" : "POSTtest",
		"description" : "This is a test for POST",
		"ipList" : "",
		"type" : "policy",
		"policyID" : "1000002",
		"pluginID" : "-1",
		"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" : "",
			"enabled" : "true",
			"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",
			"uuid" : "29F2B9E1-ADE9-4550-B63C-CEA1423E52FC"
		},
		"pluginPrefs" : [],
		"creator" : {	
			"id" : "1",
			"username" : "head3",
			"firstname" : "",
			"lastname" : "",
			"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
		"lastname" : ""
		},
		"owner" : {	
			"id" : "1",
			"username" : "head3",
			"firstname" : "",
			"lastname" : "",
			"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
		},
		"repository" : {
			"id" : "2",
			"name" : "test",
			"description" : "test",
			"type" : "Local",
			"dataFormat" : "IPv4",  
			"uuid" : "A2FF7E13-2C0E-470E-A3C9-E077FE065A54"
		},
		"ownerGroup" : {	
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		},
		"uuid" : "29F2B9E1-ADE9-4550-B63C-CEA1423E52FC"
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1406815242
}

/scan/{id}

/scan/{uuid}

Methods
GET

Gets the Scan associated with {id} or {uuid}.

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
*uuid
**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

redFont =  field is a JSON object ( e.g. "repository" :{ "id" : <id>, "name" : <name> } )

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" : "",
			"enabled" : "true",
			"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",
			"uuid" : "2E950182-08B6-4737-830B-4ACC8F6B92F9"
		},
		"policyPrefs" : [],
		"repository" : {
			"id" : "2",
			"name" : "test",
			"description" : "test",
			"type" : "Local",
			"dataFormat" : "IPv4",  
			"uuid" : "A2FF7E13-2C0E-470E-A3C9-E077FE065A54"
		},
		"ownerGroup" : {
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		},
		"creator" : {
			"id" : "1",
			"username" : "head3",
			"firstname" : "",
			"lastname" : "",
			"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
		},
		"owner" : {
			"id" : "1",
			"username" : "head3",
			"firstname" : "",
			"lastname" : "",
			"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
		},
		"uuid" : "29F2B9E1-ADE9-4550-B63C-CEA1423E52FC"
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1406828664
}

PATCH

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

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

Request Parameters

(All fields are optional)

See /scan::POST for parameters.

Example Response
See /scan/{id}::GET

DELETE

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

Request Parameters

None

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

/scan/{id}/copy

/scan/{uuid}/copy

Methods

POST

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

Request Parameters
Expand
{
 	"name" : <string>,
	"targetUser" : {
		"id" : <number> | "uuid" : <string>
	}
}
Example Response
Expand
{
	"type" : "regular",
	"response" : {
		"scan" : {
			"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" : "",
				"enabled" : "true",
				"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",
				"uuid" : "2E950182-08B6-4737-830B-4ACC8F6B92F9"
			},
			"policyPrefs" : [],
			"repository" : {
				"id" : "2",
				"name" : "test",
				"description" : "test",
				"type" : "Local",
				"dataFormat" : "IPv4", 
				"uuid" : "A2FF7E13-2C0E-470E-A3C9-E077FE065A54"
			},
			"ownerGroup" : {
				"id" : "0",
				"name" : "Full Access",
				"description" : "Full Access group"
			},
			"creator" : {
				"id" : "1",
				"username" : "head3",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
			},
			"owner" : {
				"id" : "1",
				"username" : "head3",
				"firstname" : "",
				"lastname" : "",
				"uuid" : :"96F2AD1B-1B83-462E-908A-84E6054F6B64"
			},
			"uuid" : "29F2B9E1-ADE9-4550-B63C-CEA1423E52FC"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1406750971
}

/scan/{id}/launch

/scan/{uuid}/launch

Methods
POST

Launches the Scan associated with {id} or {uuid}.

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",
			"scanID" : "2",
			"resultsSyncID" : -1,
			"jobID" : "143301",
			"repositoryID" : "1",
			"name" : "test",
			"description" : "",
			"details" : "Plugin #",
			"status" : "Queued",
			"downloadFormat" : "v2",
			"dataFormat" : "IPv4",
			"resultType" : "active",
			"id" : "3"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1407510276
}