Asset REST Reference

/asset

Methods
GET

Gets the list of Assets. The result is broken up into two lists ("usable" and "manageable").

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
creator
owner
ownerGroup
targetGroup
groups
template
typeFields

type
tags
context
createdTime
modifiedTime
repositories
ipCount
assetDataFields
viewableIPs (requesting this field for all assets may result in slow processing)

Legend

* = always comes back

** = comes back if fields list not specified on GET all 
Template Parameter

This parameter will filter assets based on templates IDs. The IDs must be provided in a comma-separated format:

	?template=<id1>,<id2>...
Filter Parameters

usable - The response will be an object containing an array of usable Assets. By default, both usable and manageable objects are returned.
manageable - The response will be an object containing all manageable Assets. By default, both usable and manageable objects are returned.
excludeAllDefined - If specified, the defined usable assets (currently id=0) will not be returned. This only applies to usable Assets.
excludeWatchlists - If specified, Assets of type 'watchlist' will be excluded from the usable and/or manageable array.

Request Query Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"usable" : [
			{
				"id" : "1",
				"name" : "dnsnameTestPost",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "28",
				"name" : "Test 1",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "29",
				"name" : "Test 2",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "30",
				"name" : "Test 3",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "31",
				"name" : "10287 TEST",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "32",
				"name" : "TEST",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "33",
				"name" : "test",
				"description" : "",
				"status" : "0"
			}
		],
		"manageable" : [
			{
				"id" : "1",
				"name" : "dnsnameTestPost",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "26",
				"name" : "Test",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "27",
				"name" : "Test2",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "28",
				"name" : "Test 1",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "29",
				"name" : "Test 2",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "30",
				"name" : "Test 3",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "31",
				"name" : "10287 TEST",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "32",
				"name" : "TEST",
				"description" : "",
				"status" : "0"
			},
			{
				"id" : "33",
				"name" : "test",
				"description" : "",
				"status" : "0"
			}
		]
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1412273607
}

POST

Adds an Asset.

NOTE #1: If a template ID is provided:

  • The template associated with the provided ID will be retrieved and used as the default values for the Asset. These values can be overwritten.
  • The 'name' will be handled by the back-end, and would default to the template name. If that name already exists for an Asset with the creatorID of the session user, it would default the name to the name plus the next-lowest integer for that user i.e. "templateName(2)"

NOTE #2: The "prepare" parameter should be set to the string "false" if this Asset pertains to an ARC that will be subsequently created. ARC add will automatically "prepare" the files for this Asset, regardless.

Request Parameters
 Expand
{
	"type" : <string> "combination" | "dnsname" | "dnsnameupload" | "dynamic" | "ldapquery" | "static" | "staticeventfilter" | "staticvulnfilter" | "templates" | "upload" | "watchlist" | "watchlisteventfilter" | "watchlistupload",
	"ownerID" : <number> DEFAULT {sessionUserID},
	"prepare" : <string> "true" | "false" DEFAULT "true"
...
}
type not "uploadmultiple"
...
	"name" : <string>,
	"description" : <string> DEFAULT "",
	"context" : <string> DEFAULT "",
	"tags" : <string> DEFAULT "" (not "Any" | "None",
	"assetDataFields" : [
		{
			"fieldName" : <string> DEFAULT "" (if fieldValue not empty),
			"fieldValue" : <string> DEFAULT "" (if fieldName not empty)
		}...
	] OPTIONAL,
	"template" : {
		"id" : <number>
	} OPTIONAL,
...

type "uploadmultiple" | "dnsnameupload" | "upload" | "watchlistupload"

...
	"filename" : <string>
...

type "combination"

NOTE: The assets you reference in the operators cannot be of type "combination" | "watchlist"

...
	"combinations" : {
		"operator" : <string> "complement" | "difference" | "intersection" | "union",
		"operand1" : { 
			"id" : <number> (asset ID) 
		} | <combinationRecord>,
		
		operator not "complement"
		-------------------------
		operand2 : { 
			"id" : <number> (asset ID) 
		} | <combinationRecord>
	}
...

type "dynamic"

...
	"rules": {
		"operator" : <string> "all" | "any",
		"children" : [
			{
				"type" : <string> "clause" | "group",
 
				child type "clause"
				-------------------
				"operator" : <string> "contains" | "eq" | "lt" | "lte" | "ne" "gt" | "gte" | "regex" | "pcre",
				"filterName" : <string> "dns" | "exploitAvailable" | "exploitFrameworks" | "firstseen" | "mac" | "os" | "ip" | "lastseen" | "netbioshost" | "netbiosworkgroup" | "pluginid" | "plugintext" | "port" | "severity" | "sshv1" | "sshv2" | "tcpport" | "udpport" | "xref",
				"pluginIDConstraint" : <string> (integer or comma-separated range) DEFAULT -1 (NOT_SET),
 
				filterName "pluginid" | "severity"
				--------------------------------------
				"value" : { 
					"id" : <number> 
				},
 
				filterName not "pluginid" & not "severity"
				------------------------------------------
				"value" : <string>,
 
				child type "group"
				------------------
				(attributes of "rules", aggregate)
			}...
		]
	}
...

type "dnsname"

...
	"definedDNSNames" : <string>
...

type "ldapquery"

NOTE: Session user must have permission to create LDAP Assets

...
	"definedLDAPQuery" : {
		"searchString" : <string>,
		"searchBase" : <string>,
		"ldap" : {
			"id" : <string>
		}
	}
...

type "upload" | "watchlistupload" | "static"

...
	"definedIPs" : <string>
...

type "static" | "watchlist" | "upload" | "watchlistupload" | "staticeventfilter" | "staticvulnfilter" | "watchlisteventfilter" | "uploadmultiple"

...
	"excludeManagedIPs" : <string> "true" | "false" OPTIONAL
...

type "staticeventfilter" | "staticvulnfilter" | "watchlisteventfilter"

...
	"filters" = [
		{
			"filterName" : <string>,
			"value" : <string>,
			"operator" : <string>
		}
	]
...

type "staticeventfilter" | "watchlisteventfilter"

...
	"tool" : "sumip",
	"sourceType" : <string> "archive" | "lce",
	"startOffset" : <number> DEFAULT 0,
	"endOffset" : <number> DEFAULT 9223372036854775807 (PHP_INT_MAX),
	"view" : <string>,
	"lce" : {
		"id" : <number>

	}
...

type "staticvulnfilter"

...
	"tool" : <string> "iplist" | "listmailclients" | "listos" | "listsshservers" | "listservices" | "listsoftware" | "listwebclients" |  "listwebservers" (internally forced to tool "iplist" with appropriate Plugin ID filter),
	"sourceType" : "cumulative" | "individual" | "patched" DEFAULT "",
	"startOffset" : <number> OPTIONAL,
	"endOffset" : <number> OPTIONAL,
	"sortField" : <string> OPTIONAL (must accompany sortDir),
	"sortDir" : <string> "ASC" | "DESC" OPTIONAL (must accompany sortField)
...

type "staticvulnfilter", sourceType "individual"

...
	"view" : <string>,
	"scanID" : <number>
...
Example Response
 Expand
{
	"type" : "regular",
	"response" : [
		{
			"id" : "2",
			"creatorID" : "1",
			"ownerID" : "1",
			"name" : "test asset",
			"type" : "dynamic",	
			"description" : "description",
			"tags" : "",
			"context" : "",
			"status" : "0",
			"templateID" : "35",
			"createdTime" : "1401903765",
			"modifiedTime" : "1401903765",
			"ownerGID" : "0",
			"targetGID" : "-1",
			"typeFields" : {
				"rules" : {
					"operator" : "any",
					"children" : [
						{
							"filterName" : "severity",
							"operator" : "eq",
							"value" : "1",
							"pluginIDConstraint" : "-1",
							"type" : "clause"
						}
					],
					"type" : "group"
				}
			},
			"ipCount":[
			    {
			        "repositoryID":"2",
			        "ipCount":"0",
			        "ips":[
						"192.168.1.0-192.168.1.255"
			        ],
			        "repository":{
						"id":"2",
			            "name":"QA Range",
			            "description":""
			        }
			    },
				...
			],
			"assetDataFields":[],
			"groups" : [],
			"canUse" : "true",
			"canManage" : "true",
			"creator" : {
				"id" : "1",
				"username" : "orghead",
				"firstname" : "test",
				"lastname" : "User"
			},
			"owner" : {
				"id" : "1",
				"username" : "orghead",
				"firstname" : "test",
				"lastname" : "User"
			},
			"ownerGroup" : {
				"id" : "0",
				"name" : "Full Access",
				"description" : "Full Access group"
			},
			"targetGroup" : {
				"id" : -1,
				"name" : "",
				"description" : ""
			}
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1401903765
}

/asset/{id}

Methods
GET

Gets the Asset associated with {id}.

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
creator
owner
ownerGroup
targetGroup
groups
template
typeFields
viewableIPs 

type
tags
context
createdTime
modifiedTime
repositories
ipCount
assetDataFields

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" : "33",
		"name" : "test",
		"type" : "combination",
		"description" : "",
		"tags" : "",
		"context" : "",
		"status" : "0",
		"templateID" : "-1",
		"createdTime" : "1412171859",
		"modifiedTime" : "1412171859",
		"typeFields" : {
			"combinations" : {
				"operator" : "intersection",
				"operand1" : {
					"id" : "28",
					"name" : "Test 1",
					"description" : ""
				},
				"operand2" : {
					"id" : "29",
					"name" : "Test 2",
					"description" : ""
				}
			}
		},
		"repositories" : [
			{
				"ipCount" : "0",
				"repository" : {
					"id" : "17",
					"name" : "New Fields Repo",
					"description" : ""
				}
			},
			{
				"ipCount" : "0",
				"repository" : {
					"id" : "18",
					"name" : "New Rep 1",
					"description" : ""
				}
			},
			{
				"ipCount" : "0",
				"repository" : {
					"id" : "19",
					"name" : "New Rep 2",
					"description" : ""
				}
			},
			{
				"ipCount" : "0",
				"repository" : {
					"id" : "20",
					"name" : "New Rep 3",
					"description" : ""
				}
			},
			{
				"ipCount" : "0",
				"repository" : {
					"id" : "21",
					"name" : "New Rep 4",
					"description" : ""
				}
			},
			{
				"ipCount" : "0",
				"repository" : {
					"id" : "22",
					"name" : "New Rep 5",
					"description" : ""
				}
			},
			{
				"ipCount" : "0",
				"repository" : {
					"id" : "23",
					"name" : "New Rep 6",
					"description" : ""
				}
			},
			{
				"ipCount" : "0",
				"repository" : {
					"id" : "24",
					"name" : "New Rep 7",
					"description" : ""
				}
			}
		],
		"ipCount" : 0,
		"groups" : [],
		"assetDataFields" : [],
		"viewableIPs" : [
			{
				"repository" : {
					"id" : "37",
					"name" : "ag repo1"
				},
				"ipList" : "192.168.1.1\n",
				"ipCount" : "1"
			},
			{
				"repository" : {
					"id" : "38",
					"name" : "jm ipv4"
				},
				"ipList" : "192.168.1.1\n",
				"ipCount" : "1"
			},
			{
				"repository" : {
					"id" : "39",
					"name" : "ipv6 rep"
				},
				"ipList" : "",
				"ipCount" : "0"
			}
		],
		"creator" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "Security Manager",
			"lastname" : ""
		},
		"owner" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "Security Manager",
			"lastname" : ""
		},
		"ownerGroup" : {
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		},
		"targetGroup" : {
			"id" : -1,
			"name" : "",
			"description" : ""
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1412273575
}

PATCH

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

Request Parameters

(All fields are optional)

See /asset::POST for parameters.

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

DELETE

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

Request Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : [
		{
			"id" : "1",
			"targetGID: : -1,
			"name" : "Name String"
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1401911117
}

/asset/import

POST

Imports an Asset specified by a previously uploaded, plain text XML file.

NOTE: The filename field should contain the value of the same parameter passed back on */file/upload::POST*.

Request Parameters
 Expand
{
	"filename" : <string>,
	"name" : <string> OPTIONAL
}
Example Response
 Expand
{
	"type" : "regular",
	"response" : [
		{
			"id" : "37",
			"creatorID" : "1",
			"ownerID" : "1",
			"name" : "LDAP query IMPORTED",
			"description" : "description",
			"type" : "ldapquery",
			"tags" : "",
			"context" : "",
			"status" : "0",
			"templateID" : "-1",
			"createdTime" : "1402582394",
			"modifiedTime" : "1402582394",
			"ownerGID" : "0",
			"targetGID" : "-1",
			"typeFields" : {
				"definedLDAPQuery" : {
					"searchBase" : "DC=target,DC=tenablesecurity,DC=com",
					"searchString" : "(objectclass=Computer)"
				}
			},
			"ipCount" : "",
			"groups" : [],
			"assetDataFields" : [],
			"canUse" : "true",
			"canManage" : "true",
			"creator" : {
				"id" : "1",
				"username" : "testorg",
				"firstname" : "first",
				"lastname" : "last"
			},
			"owner" : { 
				"id" : "1",
				"username" : "testorg",
				"firstname" : "first",
				"lastname" : "last"
			},
			"ownerGroup" : {
				"id" : "0",
				"name" : "Full Access",
				"description" : "Full Access group"
			},
			"targetGroup" : {
				"id" : -1,
				"name" : "",
				"description" : ""
			}
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402582394
}

/asset/{id}/export

GET

Exports the Asset associated with {id} as plain text XML.

Request Parameters

None

Example Response
 Expand
<?xml version="1.0" encoding="UTF-8"?>
<assets>
	<asset>
		<scVersion>5.0.0</scVersion>
		<name>Bad Credentials</name>
		<description>test</description>
		<type>dynamic</type>
		<templateID>35</templateID
<definition>YToyOntzOjU6InJ1bGVzIjthOjM6e3M6ODoib3BlcmF0b3IiO3M6MzoiYW55IjtzOjg6ImNoaWxkcmVuIjthOjI6e2k6MDthOjU6e3M6MTA6ImZpbHRlck5hbWUiO3M6ODoicGx1Z2luaWQiO3M6ODoib3BlcmF0b3IiO3M6MjoiZXEiO3M6NToidmFsdWUiO3M6NToiMjQ3ODYiO3M6MTg6InBsdWdpbklEQ29uc3RyYWludCI7czoyOiItMSI7czo0OiJ0eXBlIjtzOjY6ImNsYXVzZSI7fWk6MTthOjU6e3M6MTA6ImZpbHRlck5hbWUiO3M6ODoicGx1Z2luaWQiO3M6ODoib3BlcmF0b3IiO3M6MjoiZXEiO3M6NToidmFsdWUiO3M6NToiMjE3NDUiO3M6MTg6InBsdWdpbklEQ29uc3RyYWludCI7czoyOiItMSI7czo0OiJ0eXBlIjtzOjY6ImNsYXVzZSI7fX1zOjQ6InR5cGUiO3M6NToiZ3JvdXAiO31zOjE1OiJhc3NldERhdGFGaWVsZHMiO2E6MDp7fX0=</definition>
	</asset>
</assets>

/asset/{id}/refresh

POST

Starts an on-demand recalculation of the Asset files associated with {id}, minus any LDAP querying or Hostname resolution. This includes the Accessible Asset files of Asset {id} and any, affected Defining Assets files.

NOTE: This can only be called by Administrators.

Request Parameters
 Expand
{
	"orgID" : <number>,
	"repIDs" : [
		{
			"id" : <number>
		}...
	]
}
Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"orgID" : 26,
		"repIDs" : [
			{
				"id" : 110
			}
		],
		"id" : 20
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402579901
}

/asset/testLDAPQuery

POST

Tests an LDAP query, depending on access and permissions.

Note: This endpoint is restricted to users of role 1 (Admin)

Request Parameters
 Expand
{
	"definedLDAPQuery" : {
		"searchBase" : <string> (valid dn),
		"searchString" : <string> (valid search),
		"ldap" : {
			"id" : <string>
		}
	}
}
Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"hostnames" : [ 
			"system1.target.domain.com",
			"system2.target.domain.com",
			"system3.target.domain.com"
		]
	}
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402579901
}

/asset/{id}/share

Methods
POST

Shares the Asset associated with {id}, depending on access and permissions

Request Parameters
 Expand
{
	"groups" : [
		{
			"id" : <number>
		}...
	]
}
Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"id" : "1",
		"creatorID" : "1",
		"ownerID" : "1",
		"name" : "dnsnameTestPost",
		"type" : "dnsname",
		"description" : "",
		"tags" : "",
		"context" : "",
		"status" : "0",
		"templateID" : "1",
		"createdTime" : "1407773915",
		"modifiedTime" : "1407773915",
		"ownerGID" : "0",
		"targetGID" : "-1",
		"definedDNSNames" : "1",
		"repositories" : "",
		"assetDataFields" : [],
		"canUse" : "true",
		"canManage" : "true",
		"creator" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "Security Manager",
			"lastname" : ""
		},
		"owner" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "Security Manager",
			"lastname" : ""
		},
		"ownerGroup" : {
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		},
		"targetGroup" : {
			"id" : -1,
			"name" : "",
			"description" : ""
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1409086057
}

/asset/tag

Methods
GET

Gets the full list of unique Asset tags

Request Parameters

none

Example Response
 Expand
{
	"type" : "regular",
	"response" : [
		"Tag1",
		"Tag2",
		"Tag3"
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1461093219
}