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
type
tags
context
template
createdTime
modifiedTime
repositories
ipCount
assetDataFields
typeFields
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
type
tags
context
template
createdTime
modifiedTime
repositories
ipCount
assetDataFields
typeFields
viewableIPs

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