Tenable Security Center API: ARC

 

/arc

Methods
GET

Gets the list of ARCs

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
**running
**status
**result
**policyStatements*
creator
owner
groups

ownerGroup
targetGroup

lastUpdateTime
lastCompletedUpdateTime
lastComplianceUpdateTime
createdTIme
modifiedTIme
focusFilters
schedule

canUse
canManage
order
activated

Legend

* = always comes back

** = comes back if fields list not specified on GET all
* = policyStatements field on /arc::GET will return a minimal set of Policy Statement fields. This includes the fields: id, label, baseStatus, compliantStatus, drilldownStatus, and displayType

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

Request Parameters

None

Filter Parameters

usable - The response will be an object containing an array of usable ARCs. By default, both usable and manageable objects are returned.
manageable - The response will be an object containing all manageable ARCs. By default, both usable and manageable objects are returned.
activated - the response returns an 'usable' object containing an array of objects with only activated ARCs for the session user. This is not compatible with usable and/or manageable filters.

Example Response
Expand
{
	"type" : "regular",
	"response" : {
		"usable" : [
			{
				"running" : "false",
				"id" : "1",
				"name" : "POST TEST",
				"description" : "",
				"policyStatements" : [
					{
						"id" : "1",
						"label" : "label",
						"baseStatus" : "0",
						"compliantStatus" : "0",
						"drilldownStatus" : "0",
						"displayType" : "state"
					}
				],
				"result" : "fail",
				"status" : 0
			}
		],
		"manageable" : [
			{
				"running" : "false",
				"id" : "1",
				"name" : "POST TEST",
				"description" : "",
				"policyStatements" : [
					{
						"id" : "1",
						"label" : "label",
						"baseStatus" : "0",
						"compliantStatus" : "0",
						"drilldownStatus" : "0",
						"displayType" : "state"
					}
				],
				"result" : "fail",
				"status" : 0
			}
		]
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1413315427
}

POST

Adds an ARC

NOTE #1: ARC add will automatically "prepare" the files for its Assets.

NOTE #2: *For valid filternames based on queryType or combination asset format, see /query::POST.

Request Parameters
Expand
{
	"name" : <string>,
	"order" : <number>,
	"description" : <string> DEFAULT "",
    "schedule" : {
        "type" : <string> "ical" | "never",
 
		type "ical"
		-----------
        "start" : <string> (This value takes the iCal format),
        "repeatRule" : <string> (This value takes the repeat rule format)
    },
	"ownerID" : <number> DEFAULT (Session User ID),
	"policyStatements" : [
		{
			"label" : <string>,
			"queryType" : <string> "vuln" | "lce",
			"conditionalName" : <string> "hosts" | "ports" | "records",
			"conditionalOperator" : <string> "Any" | "No" | "All" | ">" | "<" | ">=" | "<=",
			"displayType" : <string> "percentage" | "ratio" | "state",
			"baseFilters" : [
				{
					"filterName" : <string> (valid Query filterName based on queryType),
					"value : (Format depends on filter's "filterName" parameter)
					"operator" : <string> (Options depend on filter's "filterName" parameter*)
				}
			] DEFAULT [],
			"compliantFilters" : [
				{
					"filterName" : <string> (valid Query filterName based on queryType),
					"value : (Format depends on filter's "filterName" parameter)
					"operator" : <string> (Options depend on filter's "filterName" parameter*)
				}
			],
			"drilldownFilters" : [
				{
					"filterName" : <string> (valid Query filterName based on queryType),
					"value : (Format depends on filter's "filterName" parameter)
					"operator" : <string> (Options depend on filter's "filterName" parameter*)
				}
			],


			"conditionalOperator" is ">" | "<" | ">=" | "<="
			------------------------------------------------
			"conditionalValue" : <number>
		}...
	],
	"focusFilters" : [
		{
			"operator" : <string> ">" | "<" | ">=" | "<=" | "=",
			"filterName" : <string> "asset" | "repository" | "ip",


			"filterName" is "asset" and "operator" is "~"
			---------------------------------------------
			"value" : {
				(combination asset*)
			}


			"filterName" is "asset" and "operator" is not "~"
			-------------------------------------------------
			"value" : {
				"id" : <number>
			}

			"filterName" is "repository"
			----------------------------
			"value" : [
				{
					"id" : <number>
				}...
			]

			"filterName" is "ip"
			--------------------
			"value" : <string> (valid IP or IP list)
		}...
	] OPTIONAL
	...
}
Example Response
Expand
{
	"type" : "regular",
	"response" : {
		"id" : "1",
		"name" : "POST TEST",
		"description" : "",
		"running" : "false",
		"lastUpdateTime" : "1648781875",
		"lastCompletedUpdateTime" : "1648781875",
		"lastComplianceUpdateTime" : "1648781875",
		"createdTime" : "1648781858",
		"modifiedTime" : "1648781858",
		"focusFilters" : [
			{
				"filterName" : "ip",
				"operator" : "=",
				"value" : "172.26.20.0"
			}
		],
		"order" : "0",
		"activated" : "true",
		"groups" : [],
		"policyStatements" : [
			{
				"id" : "1",
				"arcID" : "1",
				"label" : "POST TEST Label",
				"baseFilters" : [
					{
						"filterName" : "ip",
						"operator" : "=",
						"value" : "172.26.20.0"
					}
				],
				"compliantFilters" : [
					{
						"filterName" : "repository",
						"operator" : "=",
						"value" : {
							"id" : "24",
							"name" : "IPv4 Repo",
							"description" : "",
							"type" : "Local",
							"uuid" : "FC6B1EF4-A899-4AAD-9AEB-43A6D5DD01C2"
						}
					}
				],
				"drilldownFilters" : [
					{
						"filterName" : "asset",
						"operator" : "=",
						"value" : {
							"id" : "9",
							"name" : "Linux Hosts",
							"description" : "The operating system detected has Linux installed.",
							"uuid" : "2DF066B8-F310-44BB-B6BE-BC6D5BDEE0AB"
						}
					}
				],
				"baseStatus" : "0",
				"compliantStatus" : "0",
				"drilldownStatus" : "0",
				"conditionalName" : "hosts",
				"conditionalOperator" : "All",
				"conditionalValue" : "",
				"displayType" : "ratio",
				"result" : "pass",
				"resultOutput" : "{\"x\":\"0\",\"y\":\"0\"}",
				"queryType" : "vuln",
				"drilldownQuery" : {
					"id" : "1640"
				}
			}
		],
		"result" : "pass",
		"status" : 0,
		"schedule" : {
			"id" : "123",
			"type" : "ical",
			"start" : "TZID=America\/New_York:20220331T230000",
			"repeatRule" : "FREQ=DAILY;INTERVAL=1",
			"nextRun" : 1648782000 
		},
		"canUse" : "true",
		"canManage" : "true",
		"creator" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "Security Manager",
			"lastname" : "",
			"uuid" : "48F26F3B-6A79-4153-96DB-4C63D1BF3D46"
		},
		"owner" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "Security Manager",
			"lastname" : "",
			"uuid" : "48F26F3B-6A79-4153-96DB-4C63D1BF3D46"
		},
		"ownerGroup" : {
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1413315326
}

/arc/{id}

Methods
GET

Gets the ARC 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
**running
**status
**result
**policyStatements*
creator
owner
groups

ownerGroup
targetGroup

lastUpdateTime
lastCompletedUpdateTime
lastComplianceUpdateTime
createdTIme
modifiedTIme
focusFilters
schedule

canUse
canManage
order
activated

Legend

* = always comes back

** = comes back if fields list not specified on GET all
* = policyStatements field on /arc/{id}::GET will return all Policy Statement fields

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" : "POST TEST",
		"description" : "",
		"running" : "false",
		"lastUpdateTime" : "1648781875",
		"lastCompletedUpdateTime" : "1648781875",
		"lastComplianceUpdateTime" : "1648781875",
		"createdTime" : "1648781858",
		"modifiedTime" : "1648781858",
		"focusFilters" : [
			{
				"filterName" : "ip",
				"operator" : "=",
				"value" : "172.26.20.0"
			}
		],
		"order" : "0",
		"activated" : "true",
		"groups" : [],
		"policyStatements" : [
			{
				"id" : "1",
				"arcID" : "1",
				"label" : "POST TEST Label",
				"baseFilters" : [
					{
						"filterName" : "ip",
						"operator" : "=",
						"value" : "172.26.20.0"
					}
				],
				"compliantFilters" : [
					{
						"filterName" : "repository",
						"operator" : "=",
						"value" : {
							"id" : "24",
							"name" : "IPv4 Repo",
							"description" : "",
							"type" : "Local",
							"uuid" : "FC6B1EF4-A899-4AAD-9AEB-43A6D5DD01C2"
						}
					}
				],
				"drilldownFilters" : [
					{
						"filterName" : "asset",
						"operator" : "=",
						"value" : {
							"id" : "9",
							"name" : "Linux Hosts",
							"description" : "The operating system detected has Linux installed.",
							"uuid" : "2DF066B8-F310-44BB-B6BE-BC6D5BDEE0AB"
						}
					}
				],
				"baseStatus" : "0",
				"compliantStatus" : "0",
				"drilldownStatus" : "0",
				"conditionalName" : "hosts",
				"conditionalOperator" : "All",
				"conditionalValue" : "",
				"displayType" : "ratio",
				"result" : "pass",
				"resultOutput" : "{\"x\":\"0\",\"y\":\"0\"}",
				"queryType" : "vuln",
				"drilldownQuery" : {
					"id" : "1640"
				}
			}
		],
		"result" : "pass",
		"status" : 0,
		"schedule" : {
			"id" : "123",
			"type" : "ical",
			"start" : "TZID=America\/New_York:20220331T230000",
			"repeatRule" : "FREQ=DAILY;INTERVAL=1",
			"nextRun" : 1648782000 
		},
		"canUse" : "true",
		"canManage" : "true",
		"creator" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "Security Manager",
			"lastname" : "",
			"uuid" : "48F26F3B-6A79-4153-96DB-4C63D1BF3D46"
		},
		"owner" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "Security Manager",
			"lastname" : "",
			"uuid" : "48F26F3B-6A79-4153-96DB-4C63D1BF3D46"
		},
		"ownerGroup" : {
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1413315326
}

PATCH

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

Request Parameters

NOTE #1: All PolicyStatements and FocusFilters must be provided or they will be removed.

NOTE #2: Order can only be specified if the ARC has been activated (it is activated automatically on add, but this could apply to shares).

(All fields are optional)

See /arc::POST for parameters.

Activating/Deactivating Shared ARCs

A user may call this endpoint for an ARC shared to them. They will only be able to activate, change order, or deactivate a shared ARC. They may only use the following Parameters:

Expand
{
	"activated":"<boolean>",
	"order":"<number>" (required if activated is "true")
}
Example Response
See /arc/{id}::GET

DELETE

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

Request Parameters

None

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

/arc/import

Methods

 

POST

Imports an ARC Template

Request Parameters
Expand
{
	"filename":"<string>",
	"order":"<number>" (optional)
}
Example Response
See /arc/{id}::GET

/arc/{id}/export

Methods

 

POST

Exports the ARC associated with {id}.

Request Parameters
Expand
{
	"exportType":"(full|cleansed|placeholders|templates)"
}
Example Response
Expand
<?xml version="1.0" encoding="UTF-8"?>
<arcTemplate>
    <scVersion>5.0.0</scVersion>
    <name>ARC with Assets</name>
    <description>lkasdjflaskdj</description>
    <focusFilters>YToxOntpOjA7YTozOntzOjEwOiJmaWx0ZXJOYW1lIjtzOjc6ImFzc2V0SUQiO3M6ODoib3BlcmF0b3IiO3M6MToifiI7czo1OiJ2YWx1ZSI7YTozOntzOjg6Im9wZXJhdG9yIjtzOjEyOiJpbnRlcnNlY3Rpb24iO3M6ODoib3BlcmFuZDEiO3M6MTA6Ii0xOlVua25vd24iO3M6ODoib3BlcmFuZDIiO3M6MTA6Ii0xOlVua25vd24iO319fQ==</focusFilters>
    <policyStatements>
        <policyStatement>
            <label>PS</label>
            <displayType>state</displayType>
            <definition>YTo2OntzOjExOiJiYXNlRmlsdGVycyI7YToxOntpOjA7YTozOntzOjEwOiJmaWx0ZXJOYW1lIjtzOjI6ImlwIjtzOjg6Im9wZXJhdG9yIjtzOjE6Ij0iO3M6NToidmFsdWUiO3M6NzoiMS4xLjEuMSI7fX1zOjE2OiJjb21wbGlhbnRGaWx0ZXJzIjthOjE6e2k6MDthOjM6e3M6MTA6ImZpbHRlck5hbWUiO3M6MTM6ImJhc2VDVlNTU2NvcmUiO3M6ODoib3BlcmF0b3IiO3M6MToiPSI7czo1OiJ2YWx1ZSI7czozOiIyLTMiO319czoxNjoiZHJpbGxkb3duRmlsdGVycyI7YToxOntpOjA7YTozOntzOjEwOiJmaWx0ZXJOYW1lIjtzOjU6ImNjZUlEIjtzOjg6Im9wZXJhdG9yIjtzOjE6Ij0iO3M6NToidmFsdWUiO3M6NDoiMTIzMSI7fX1zOjE1OiJjb25kaXRpb25hbE5hbWUiO3M6NToiaG9zdHMiO3M6MTk6ImNvbmRpdGlvbmFsT3BlcmF0b3IiO3M6MzoiQWxsIjtzOjE2OiJjb25kaXRpb25hbFZhbHVlIjtzOjA6IiI7fQ==</definition>
        </policyStatement>
    </policyStatements>
    <schedule>FREQ=DAILY;INTERVAL=1</schedule>
</arcTemplate>

/arc/{id}/copy

Methods
POST

Copies an existing ARC associated with {id}, depending on access and permissions.

Request Parameters
Expand
{
	"name": <string>,
	"description": <string> (optional)
}
Example Response
See /arc/{id}::GET

/arc/{id}/refresh

Methods

POST

Refreshes the Assurance Report Card associated with {id}.

Request Parameters

None

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

/arc/{id}/share

Methods
POST

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

Request Parameters
Expand
{
	"groups": 
		[
			{<group ID record>},
			...
		]
}

Every call to /arc/{id}/share will completely replace the groups that are shared to, with the groups you provide.

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