Tenable Security Center API: Freeze Window

In order to better align with the inclusive language guidelines, The Freeze Window API is the new API endpoint replacing Blackout Window API.

NOTE #1: In 5.18.0 both /blackout and /freeze API are supported and /blackout API is deprecated will be phased out in 5.19.0.

/freeze

Methods

GET

Gets the list of Freeze Windows.

NOTE #1: Only users in the FreezeWindow owner's group may view target details. For users outside of the group: Repository, Assets, ipList, and allIPs will be returned {}, [], "", and "false" respectively.

NOTE #2: If a Repository or Asset associated with a FreezeWindow has been deleted, the ID will be returned as '-1'. If one has been unshared, the ID will be similarly returned as -1, but the name will signify the Asset ID.

NOTE #3: The "status" field represents if the FreezeWindow has been disabled via bad Repository and if it has been degrade via Asset. The "functional" field represents if there are any valid target IPs in the FreezeWindow (allIPs, ipList, assets) in the FreezeWindow owner's context.

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
assets
repository
owner
creator
ipList
allIPs
repeatRule
start
end
duration
enabled
createdTime
modifiedTime
active
ownerGroup
canManage
functional

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" : "20",
			"name" : "3",
			"description" : "",
			"ipList" : "",
			"start" : "TZID=America\/New_York:20141119T235800",
			"end" : "TZID=America\/New_York:20141119T000200",
			"duration" : "-86160",
			"repeatRule" : "FREQ=DAILY;INTERVAL=1",
			"status" : "0",
			"enabled" : "false",
			"createdTime" : "1418327672",
			"modifiedTime" : "1418327672",
			"assets" : [
				{
					"id" : "3",
					"name" : "Test3",
					"description" : "",
                    "uuid": "31075F9E-72E8-4397-AF3B-A3A61427DBE6"				}
			],
			"active" : "false",
			"creator" : {
				"id" : "1",
				"username" : "freezeTest",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "2E2B70F2-3471-428F-82AF-A6905090EAA9"			},
			"owner" : {
				"id" : "1",
				"username" : "freezeTest",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "2E2B70F2-3471-428F-82AF-A6905090EAA9"			},
			"repository" : {
				"id" : "29",
				"name" : "Test IPv6",
				"description" : "",
				"type" : "Local",
				"uuid": "8A547FC6-5FBA-43BB-900E-683F022812CE"			}
		},
		{
			"id" : "21",
			"name" : "4",
			"description" : "",
			"ipList" : "172.26.50.0\/24",
			"start" : "TZID=America\/New_York:20141119T235800",
			"end" : "TZID=America\/New_York:20141119T000200",
			"duration" : "-86160",
			"repeatRule" : "FREQ=DAILY;INTERVAL=1",
			"status" : "0",
			"enabled" : "false",
			"createdTime" : "1418327716",
			"modifiedTime" : "1418327716",
			"assets" : [],
			"active" : "false",
			"creator" : {
				"id" : "1",
				"username" : "freezeTest",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "2E2B70F2-3471-428F-82AF-A6905090EAA9"			},
			"owner" : {
				"id" : "1",
				"username" : "freezeTest",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "2E2B70F2-3471-428F-82AF-A6905090EAA9"			},
			"repository" : {
				"id" : -1,
				"name" : "",
				"description" : "",
				"type" : ""			}
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1418332032
}

POST

Adds a Freeze Window.

NOTE: If 'allIPs' is 'false', an 'ipList' and/or at least one 'assets' parameter must be provided. If 'allIPs' is 'true', the back-end will clear the target (ipList, assets, and repository) fields.

Request Parameters

Expand

{	  
	"name" : <string>,
	"description" : <string> DEFAULT "",
	"repeatRule" : <string> (ical start format) DEFAULT "",
	"start" : <string> (ical start format),
	"end" : <string> (ical end format),
	"repository" : {
		"id" : <number>	} DEFAULT -1 (not set),
	"allIPs" : <string> "false" | "true" DEFAULT "true",
	"enabled" : <string> "false" | "true",
 	allIPs "false"	--------------
	"ipList" : <string> (valid comma-separated IP List format) DEFAULT "",
	"assets" : [
		{
			"id" : <number>		}...
	] DEFAULT []
}

Example Response

Expand

{
	"type" : "regular",
	"response" : {
		"id" : "21",
		"name" : "4",
		"description" : "",
		"repeatRule" : "FREQ=DAILY;INTERVAL=1",
		"start" : "TZID=America\/New_York:20141119T235800",
		"end" : "TZID=America\/New_York:20141119T000200",
		"duration" : "-86160",
		"enabled" : "false",
		"createdTime" : "1418327716",
		"modifiedTime" : "1418327716",
		"ipList" : "192.168.1.0\/24",
		"status" : "0",
		"assets" : [],
		"active" : "false",
		"creator" : {
			"id" : "1",
			"username" : "freezeTest",
			"firstname" : "",
			"lastname" : "",
			"uuid" : "2E2B70F2-3471-428F-82AF-A6905090EAA9"		},
		"owner" : {
			"id" : "1",
			"username" : "freezeTest",
			"firstname" : "",
			"lastname" : "",
			"uuid" : "2E2B70F2-3471-428F-82AF-A6905090EAA9"		},
		"repository" : {
			"id" : -1,
			"name" : "",
			"description" : "",
            "type": ""		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1418327716
}

/freeze/{id}

Methods

GET

Gets the Freeze Window associated with {id}.

NOTE #1: Only users in the FreezeWindow owner's group may view target details. For users outside of the group: Repository, Assets, ipList, and allIPs will be returned {}, [], "", and "false" respectively.

NOTE #2: If a Repository or Asset associated with a FreezeWindow has been deleted, the ID will be returned as '-1'. If one has been unshared, the ID will be similarly returned as -1, but the name will signify the Asset ID.

NOTE #3: The "status" field represents if the FreezeWindow has been disabled via bad Repository and if it has been degrade via Asset. The "functional" field represents if there are any valid target IPs in the FreezeWindow (allIPs, ipList, assets) in the FreezeWindow owner's context.

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
assets
repository
owner
creator
ipList
allIPs
repeatRule
start
end
duration
enabled
createdTime
modifiedTime
active
ownerGroup
canManage
functional

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" : "21",
		"name" : "4",
		"description" : "",
		"repeatRule" : "FREQ=DAILY;INTERVAL=1",
		"start" : "TZID=America\/New_York:20141119T235800",
		"end" : "TZID=America\/New_York:20141119T000200",
		"duration" : "-86160",
		"enabled" : "false",
		"createdTime" : "1418327716",
		"modifiedTime" : "1418327716",
		"ipList" : "192.168.1.0\/24",
		"status" : "0",
		"assets" : [],
		"active" : "false",
		"creator" : {
			"id" : "1",
			"username" : "freezeTest",
			"firstname" : "",
			"lastname" : "",
            "uuid": "2E2B70F2-3471-428F-82AF-A6905090EAA9"		},
		"owner" : {
			"id" : "1",
			"username" : "freezeTest",
			"firstname" : "",
			"lastname" : "",
            "uuid": "2E2B70F2-3471-428F-82AF-A6905090EAA9"		},
		"repository" : {
			"id" : -1,
			"name" : "",
			"description" : "",
            "type": ""		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1418332060
}

PATCH

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

NOTE: Users that are not in the same group as the FreezeWindow owner can ONLY patch non-target fields (i.e. name, description, and enabled).

Request Parameters

(All fields are optional)

See /freeze::POST for parameters.

Example Response

See /freeze/{id}::GET for example response.

DELETE

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

Request Parameters

None

Example Response

Expand

{
	"type" : "regular",
	"response" :	"",
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1403040206
}