Tenable Security Center API: Dashboard Component

/dashboard/{dID}/component

Methods
GET

Gets the Dashboard Components associated with dashboard {dID}.

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
tabID
componentID
componentType
column
order
running
lastUpdatedTime
lastCompletedUpdateTime
createdTime
modifiedTime
schedule
definition
data

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

Example Response
Expand 
{
	"type" : "regular",
	"response" : [
		{
			"id" : "1",
			"name" : "Dashboard Component",
			"description" : "test",
			"tabID" : "1",
			"componentType" : "table",
			"column" : "1",
			"order" : "1",
			"status" : null,
			"running" : "false",
			"lastUpdatedTime" : "",
			"lastCompletedUpdateTime" : "",
			"createdTime" : "",
			"modifiedTime" : "",
			"definition" : {
				"allDataSources" : [
					{
						"id" : "161",
						"queryID" : "81",
						"querySourceType" : "cumulative",
						"querySourceID" : null,
						"querySourceView" : null,
						"sortColumn" : "score",
						"sortDirection" : "desc",
						"iteratorID" : "-1",
						"dataID" : "44",
						"context" : "report",
						"resultStyle" : "list"					}
				],
				"styleID" : "-1",
				"columns" : [
					{
						"name" : "ip"					},
					{
						"name" : "score"					},
					{
						"name" : "severityLow"					},
					{
						"name" : "severityMedium"					},
					{
						"name" : "severityHigh"					},
					{
						"name" : "severityCritical"					}
				],
				"dataPoints" : "10",
				"displayDataPoints" : "10",
				"dataSource" : {
					"id" : "161",
					"queryID" : "81",
					"querySourceType" : "cumulative",
					"querySourceID" : null,
					"querySourceView" : null,
					"sortColumn" : "score",
					"sortDirection" : "desc",
					"iteratorID" : "-1",
					"dataID" : "44",
					"context" : "report",
					"resultStyle" : "list"				}
			},
			"schedule" : [],
			"data" : -1,
			"queryStatus" : [
				{
					"id" : "1",
					"name" : "",
					"description" : """,
					"status" : "0"				}
			]
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1414081560
}

POST

Adds a Dashboard Component to dashboard {dID}.

NOTE: If a template ID is provided:

  • The template associated with the provided ID will be retrieved and used as the default values for the Dashboard Component.
  • The template ID provided must be a "component" (not a "collection")
  • The 'name' isn't enforced as unique and, therefore, there is no automation for modifying the name field automatically.
  • Templates do not specify an order and/or column. These fields are still required.
  • For non-matrix components, a schedule must be provided. For matrix components, there are some conversion issues with templates that are currently being discussed.
Request Parameters
Expand 
{
	"name" : <string>,
	"template" : {
		"id" : <number>	} OPTIONAL,
	"description" : <string> DEFAULT "",
	"type" : <string> "barChart" | "stackedBarChart" | pieChart" | "table" | "areaChart" | "lineChart" | "enhancedAreaChart" | "enhancedLineChart" | "matrix",
	"column" : <number>,
	"order" : <number>,
	"parentJob" : <number> OPTIONAL,
	...
}

type is "stackedBarChart" | "barChart" | "pieChart" | "table":

NOTE: For information on valid Query object format, see /query::POST. 

{
	...
	"schedule" : {
		"type" : <string> "dependent" | "ical" | "never" | "rollover" | "template"	},
	"definition" : {
		"columns" : [
			{
				"name" : <string>			}...
		],
		"labelColumns" : <string>,
		"dataSource" : {
			"queryID" : <number> OPTIONAL,
			"querySourceType" : "querySourceType" : "alert" | "lce" | "mobile" | "ticket" | "user" | "vuln" (needs verification),
			"querySourceID" : <number>,
			"querySourceView" : <string>,
			"sortColumn" : <string>,
			"sortDirection" : <string>,
			"iteratorID" : <number> DEFAULT "-1" (not set)
			
			queryID is not provided
			-----------------------
			"query" : <query object>		}
	}
	...
}

type is "areaChart" | "lineChart" | "enhancedAreaChart" | "enhancedLineChart"

NOTE: For information on valid Query object format, see /query::POST. 

{
	...
	"schedule" : {
		"type" : <string> "dependent" | "ical" | "never" | "rollover" | "template"	},
	"definition" : {
		"lines" : [
			{
				"dataSource" : {
					"queryID" : <number> OPTIONAL
						"queryID" : <number> OPTIONAL,
						"querySourceType" : "alert" | "lce" | "mobile" | "ticket" | "user" | "vuln" (needs verification),
						"querySourceID" : <number>,
						"querySourceView" : <string>,
						"sortColumn" : <string>,
						"sortDirection" : <string>,
						"iteratorID" : <number> DEFAULT "-1" (not set)
					
					queryID is not provided
					-----------------------
					"query" : <query object>				}
			}...
		]
	}
	...
}

type is "matrix"

NOTE: For information on valid Query object format, see /query::POST. 

{
	...
	"definition" : {
		"rows" : <number>,
		"columns" : <number>,
		"title" : <string>,
		"stripType" : <string>,
		"rowLabels" : [
			{
				"text" : <string>			}...
		],
		"columnLabels" : [
			{
				"text" : <string>			}...
		],
		"clusters" : [
			{
				"schedule" : {
					"type" : <string> "dependent" | "ical" | "never" | "rollover" | "template"				},
				"strips" : <string> (comma separated list of numbers indicating columns affected by the new schedule)
			}...
		],
		"cells" : [
			{
				"conditionals" : [
					{
						"conditionalName" : <string>,
						"conditionalOperator" : <string>,
						"conditionalValue" : <string>,
						"outputType" : <string>,
						"outputColors" : <string>,
						"outputText" : <string>					}...
				],
				"dataSource" : {
					"queryID" : <number> OPTIONAL
					"querySourceType" : "alert" | "lce" | "mobile" | "ticket" | "user" | "vuln" (needs verification),
					"querySourceID" : <number>,
					"querySourceView" : <string>,
					"sortColumn" : <string>,
					"sortDirection" : <string>,
					"iteratorID" : <number> DEFAULT "-1" (not set)
					queryID is not provided
					-----------------------
					"query" : <query object>				},
				"baseDataSource" : {
					"queryID" : <number> OPTIONAL
					"querySourceType" : "alert" | "lce" | "mobile" | "ticket" | "user" | "vuln" (needs verification),
					"querySourceID" : <number>,
					"querySourceView" : <string>,
					"sortColumn" : <string>,
					"sortDirection" : <string>,
					"iteratorID" : <number> DEFAULT "-1" (not set)
					
					queryID is not provided
					-----------------------
					"query" : <query object>				} OPTIONAL
			}...
		]
	}
	...
}

Schedule type is "ical"

NOTE: Applies to all types of Components. The schedule object for type matrix is located in the definition clusters. Othwerwise, the object is located in the base component. 

{
	...
	"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" : "2",
		"name" : "testPOSTComponent",
		"description" : "",
		"tabID" : "1",
		"componentID" : "13",
		"componentType" : "barChart",
		"column" : "1",
		"order" : "2",
		"status" : "32768",
		"running" : "false",
		"lastUpdatedTime" : "-1",
		"lastCompletedUpdateTime" : "-1",
		"createdTime" : "1414095212",
		"modifiedTime" : "1414095212",
		"definition" : {
			"styleID" : "-1",
			"columns" : [
				{
					"name" : "Column Name"				}
			],
			"labelColumns" : "label",
			"dataPoints" : "9223372036854775807",
			"dataSource" : {
				"id" : "232",
				"queryID" : "1",
				"querySourceType" : "cumulative",
				"querySourceID" : null,
				"querySourceView" : null,
				"sortColumn" : "id",
				"sortDirection" : "ASC",
				"iteratorID" : "-1",
				"dataID" : "94",
				"context" : "",
				"resultStyle" : "list"			}
		},
		"schedule" : {
			"type" : "never",
			"start" : "",
			"repeatRule" : ""		},
		"data" : -1
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1414095212
}

/dashboard/{dID}/component/{cID}

Methods
GET

Gets the Dashboard Component associated with dashboard {dID} and component {cID}.

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
tabID
componentID
componentType
column
order
running
lastUpdatedTime
lastCompletedUpdateTime
createdTime
modifiedTime
schedule
definition
data
queryStatus 

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

Example Response
Expand 
{
	"type" : "regular",
	"response" : {
		"id" : "1",
		"name" : "Component",
		"description" : "test",
		"tabID" : "1",
		"componentID" : "1",
		"componentType" : "table",
		"column" : "1",
		"order" : "1",
		"status" : "0",
		"running" : "false",
		"lastUpdatedTime" : "1414440714",
		"lastCompletedUpdateTime" : "1414440714",
		"createdTime" : "",
		"modifiedTime" : "",
		"definition" : {
			"styleID" : "-1",
			"columns" : [
				{
					"name" : "ip"				},
				{
					"name" : "score"				},
				{
					"name" : "severityLow"				},
				{
					"name" : "severityMedium"				},
				{
					"name" : "severityHigh"				},
				{
					"name" : "severityCritical"				}
			],
			"dataPoints" : "10",
			"displayDataPoints" : "10",
			"dataSource" : {
				"id" : "161",
				"queryID" : "81",
				"querySourceType" : "cumulative",
				"querySourceID" : null,
				"querySourceView" : null,
				"sortColumn" : "score",
				"sortDirection" : "desc",
				"iteratorID" : "-1",
				"dataID" : "44",
				"context" : "report",
				"resultStyle" : "list"			}
		},
		"schedule" : {
			"id" : -1,
			"type" : "now",
			"start" : "",
			"repeatRule" : "",
			"nextRun" : -1
		},
		"data" : -1,
		"queryStatus" : [
			{
				"id" : "1",
				"name" : "",
				"description" : """,
				"status" : "0"			}
		]
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1414440824
}

PATCH

Edits the Dashboard associated with dashboard {dID} and component {cID}, changing only the passed in fields.

NOTE #1: If no definition parameter is passed, the original definition is maintained. If a definition parameter is passed (even an empty array), the old definition is recreated.

NOTE #2: Only users in the same group as the owner (and with proper permissions) can make modifications to a component. Users in another group (with proper permissions), however, can change the order and column.

Request Parameters

(All fields are optional)

See /dashboard/{dID}/component::POST for parameters.

Example Response

See /dashboard/{dID}/component/{cID}::GET 

DELETE

Deletes the Dashboard associated with dashboard {dID} and component {cID}, depending on access and permissions

Request Parameters

None

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

/dashboard/{dID}/component/{cID}/copy

Methods

POST

Refreshes the Dashboard Component associated with dashboard {dID} and component {cID}.

Request Parameters
Expand 
{
	"name" : <string>,
	"targetTabID" : <number> DEFAULT <tabID>	...
}

(Additional fields are optional)

See /dashboard/{dID}/component::POST for parameters.

Example Response
Expand 
{
	"type" : "regular",
	"response" : {
		"id" : "45",
		"name" : "Test 11\/10 12",
		"description" : "This component provides a list of infected hosts that have been identified with plugin 74442.  The systems identified in this table are most likely compromised and should be immediately removed from the network.  The next step would be to follow an incident response policy and determine if an incident needs to be declared.  Additionally, a forensic analysis should be considered to determine the extent of the compromise.  The table uses the IP Summary tool and is sorted based on repository, and displays the IP Address, NetBIOS Name, FQDN, and OS CPE string.",
		"tabID" : "47",
		"componentID" : "449",
		"componentType" : "table",
		"column" : "1",
		"order" : "2",
		"status" : "32768",
		"running" : "false",
		"lastUpdatedTime" : "-1",
		"lastCompletedUpdateTime" : "-1",
		"createdTime" : "1415635146",
		"modifiedTime" : "1415635146",
		"definition" : {
			"allDataSources" : [
				{
					"id" : "888",
					"queryID" : "541",
					"querySourceType" : "cumulative",
					"querySourceID" : null,
					"querySourceView" : null,
					"sortColumn" : "ip",
					"sortDirection" : "desc",
					"iteratorID" : "-1",
					"dataID" : "676",
					"context" : "dashboard",
					"resultStyle" : "list"				}
			],
			"styleID" : "-1",
			"columns" : [
				{
					"name" : "ip"				},
				{
					"name" : "netbiosName"				},
				{
					"name" : "dnsName"				},
				{
					"name" : "osCPE"				}
			],
			"dataPoints" : "100",
			"displayDataPoints" : "8",
			"dataSource" : {
				"id" : "888",
				"queryID" : "541",
				"querySourceType" : "cumulative",
				"querySourceID" : null,
				"querySourceView" : null,
				"sortColumn" : "ip",
				"sortDirection" : "desc",
				"iteratorID" : "-1",
				"dataID" : "676",
				"context" : "dashboard",
				"resultStyle" : "list"			}
		},
		"schedule" : {
			"id" : "164",
			"type" : "ical",
			"start" : "TZID=America\/New_York : 20140815T140000",
			"repeatRule" : "FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,SA",
			"nextRun" : 1416078000
		},
		"data" : -1
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1415635146
}

/dashboard/{dID}/component/{cID}/refresh

Methods
POST

Refreshes the Dashboard Component associated with dashboard {dID} and component {cID}.

Request Parameters

None

Example Response
Expand 
{
	"type" : "regular",
	"response" : {
		"id" : "1",
		"name" : "Component",
		"description" : "test",
		"tabID" : "1",
		"componentID" : "1",
		"componentType" : "table",
		"column" : "1",
		"order" : "1",
		"status" : "0",
		"running" : "false",
		"lastUpdatedTime" : "1414440714",
		"lastCompletedUpdateTime" : "1414440714",
		"createdTime" : "",
		"modifiedTime" : "",
		"definition" : {
			"styleID" : "-1",
			"columns" : [
				{
					"name" : "ip"				},
				{
					"name" : "score"				},
				{
					"name" : "severityLow"				},
				{
					"name" : "severityMedium"				},
				{
					"name" : "severityHigh"				},
				{
					"name" : "severityCritical"				}
			],
			"dataPoints" : "10",
			"displayDataPoints" : "10",
			"dataSource" : {
				"id" : "161",
				"queryID" : "81",
				"querySourceType" : "cumulative",
				"querySourceID" : null,
				"querySourceView" : null,
				"sortColumn" : "score",
				"sortDirection" : "desc",
				"iteratorID" : "-1",
				"dataID" : "44",
				"context" : "report",
				"resultStyle" : "list"			}
		},
		"schedule" : {
			"id" : -1,
			"type" : "now",
			"start" : "",
			"repeatRule" : "",
			"nextRun" : -1
		},
		"data" : -1
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1414440824
}