Tenable Security Center API: Scan

 

/scan

Methods
GET

Gets the list of Scans.

NOTE #1: 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.

NOTE #2 : The Unit of param inactivityTimeout is to be interpreted in seconds.

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
inactivityTimeout

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,
				"status" : "0",
				"uuid" : "2EAED2D2-DFC7-4CFE-9C94-25CF6481C515"
			},
			{
				"id" : "3",
				"name" : "test2",
				"description" : null,
				"status" : "0",
				"uuid" : "EC81E13E-B3B2-4A51-968D-E94D524B5254"
			},
			{
				"id" : "4",
				"name" : "POSTtest",
				"description" : "This is a test for POST",
				"status" : "0",
				"uuid" : "2EAED2D2-DFC7-4CFE-9C94-25CF6481C515"
			}
		],
		"manageable" : [
			{
				"id" : "2",
				"name" : "test",
				"description" : null,
				"status" : "0",
				"uuid" : "2EAED2D2-DFC7-4CFE-9C94-25CF6481C515"
			},
			{
				"id" : "3",
				"name" : "test2",
				"description" : null,
				"status" : "0",
				"uuid" : "EC81E13E-B3B2-4A51-968D-E94D524B5254"
			{
				"id" : "4",
				"name" : "POSTtest",
				"description" : "This is a test for POST",
				"status" : "0",
				"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.

NOTE #5: The Unit of param inactivityTimeout is seconds. And perceived only in intervals of 3600 [1hr]. If any other intermediate values are sent then it is ceiled to next valid step. Ex: 5432 is ceiled to 7200. This is done to keep consistency in the allowed values of dropdown in Frontend. The validation error messages in response too contain Unit in hours too keep it consistent with that shown in Frontend.

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",
	"inactivityTimeout" : <number> "3600" to "432000" STEP 3600 DEFAULT "43200"
}


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" : "100.100.100.100",
		"urlList" : "",
		"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",
		"inactivityTimeout" : "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"
		},
		"canUse" : "true",
		"canManage" : "true",
		"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 #1: 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.

NOTE #2 : The Unit of param inactivityTimeout is to be interpreted in seconds.

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
**urlList
**type
**policy
**plugin
**repository
**canUse
**canManage
**zone
**dhcpTracking
**classifyMitigatedAge
**emailOnLaunch
**emailOnFinish
**timeoutAction
**scanningVirtualHosts
**rolloverType
**createdTime
**modifiedTime
**ownerGroup
**creator
**owner
**reports
**assets
**credentials
**numDependents
**schedule
**policy
**policyPrefs
**maxScanTime
**inactivityTimeout

Legend

* = always comes back

** = comes back if fields list not specified on GET

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" : "100.100.100.100",
		"urlList" : "",
		"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"
		},
		"canUse" : "true",
		"canManage" : "true",
		"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" : "100.100.100.100",
			"urlList" : "",
			"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"
			},
			"canUse" : "true",
			"canManage" : "true",
			"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
}