Tenable.sc API: Blackout Window

 

/blackout

/blackout API is deprecated and will be phased out in 5.19.0 release, Please use /freeze API instead.

Methods
GET

Gets the list of Blackout Windows.

NOTE #1: Only users in the BlackoutWindow 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 BlackoutWindow 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 BlackoutWindow 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 BlackoutWindow (allIPs, ipList, assets) in the BlackoutWindow 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" : ""
				}
			],
			"active" : "false",
			"creator" : {
				"id" : "1",
				"username" : "blackoutTest",
				"firstname" : "",
				"lastname" : ""
			},
			"owner" : {
				"id" : "1",
				"username" : "blackoutTest",
				"firstname" : "",
				"lastname" : ""
			},
			"repository" : {
				"id" : "29",
				"name" : "Test IPv6",
				"description" : ""
			}
		},
		{
			"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" : "blackoutTest",
				"firstname" : "",
				"lastname" : ""
			},
			"owner" : {
				"id" : "1",
				"username" : "blackoutTest",
				"firstname" : "",
				"lastname" : ""
			},
			"repository" : {
				"id" : -1,
				"name" : "",
				"description" : ""
			}
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1418332032
}

POST

Adds a Blackout 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" : "blackoutTest",
			"firstname" : "",
			"lastname" : ""
		},
		"owner" : {
			"id" : "1",
			"username" : "blackoutTest",
			"firstname" : "",
			"lastname" : ""
		},
		"repository" : {
			"id" : -1,
			"name" : "",
			"description" : ""
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1418327716
}



/blackout/{id}

Methods
GET

Gets the Blackout Window associated with {id}.

NOTE #1: Only users in the BlackoutWindow 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 BlackoutWindow 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 BlackoutWindow 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 BlackoutWindow (allIPs, ipList, assets) in the BlackoutWindow 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" : "blackoutTest",
			"firstname" : "",
			"lastname" : ""
		},
		"owner" : {
			"id" : "1",
			"username" : "blackoutTest",
			"firstname" : "",
			"lastname" : ""
		},
		"repository" : {
			"id" : -1,
			"name" : "",
			"description" : ""
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1418332060
}

PATCH

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

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

Request Parameters

(All fields are optional)

See /blackout::POST for parameters.

Example Response

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

DELETE

Deletes the Blackout 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
}