REST APIs for 23.2

Security administrators use this API to view how many workloads are ransomware protection ready and then assess the degree of protection in their whole system. This schema supplies the required information to run the Ransomware Dashboard:

Sample Response for reports/risk_summary_get

{
   "ransomware":{
	"num_total_workloads":98,
	"num_protected_workloads":22,
	"workload_protection_by_severity":{
	  "low":{
		"protected_workload_count":2,
		"unprotected_workload_count":8
	   },
	   "medium":{
		"protected_workload_count":3,
		"unprotected_workload_count":6
	   },
	  "high":{
		"protected_workload_count":2,
		"unprotected_workload_count":8
	   },
	   "critical":{
		"protected_workload_count":3,
		"unprotected_workload_count":6
	   }
			},
   "workload_protection_by_port_type":{
	"admin":{
	   "protected_workload_count":2,
	   "unprotected_workload_count":8
	},
	"legacy":{
	   "protected_workload_count":3,
	   "unprotected_workload_count":6
	}
   },
   "ransomware_protection_coverage_percent":56,
   "last_updated_at":"2023-01-21 23:32:42.679673"
   }
}

This schema is referenced from reports_risk_summary_get.schema.json to supply the number of protected and unprotected ports for a specified risk level:

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "required": [
	"num_protected_ports",
	"num_unprotected_ports"
  ],
   "properties": {
	"num_protected_ports": {
	   "description": "Number of protected ports for this risk level, across all protection ready workloads",
	   "type": "integer"
	   },
	"num_unprotected_ports": {
	   "description": "Number of unprotected ports for this risk level, across all protection ready workloads",
	   "type": "integer"
	}
   }
}

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "array",
   items": {
	"type": "object",
	"required": [
	   "property"
	],
	"properties": {
	   "property": {
		"description": "The property for which time series data is requested.",
		"type": "string",
		"enum": [
		   "num_managed_workloads"
		]
	},
	"resolution": {
		"type": "string",
		"description": "The granularity for the time series data. E.g. day, week, month, quarter",
		"enum": [
		   "day",
		   "week",
		   "month",
		   "quarter"
		],
	   "default": "day"
	},
	"max_results": {
	   "type": "integer",
	   "default": 5
	}
    }
  }
}

This schema supplies the granularity of the time series data.

The API reports_time_series_statistics_post includes the property num_managed_workloads, which is requested by the payload. The resolution might be day, week, month, and quarter, which defines what the UI will show.

The default value is "day".

This API specifies the time series data about the protected workloads, such as the start and end date of the protection period.

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "array",
   "items": {
	"type": "object",
	"required": [
	   "property",
	   "time_series"
	],
	"properties": {
	   "property": {
		"description": "The property for which data has been requested.",
		   "type": "string"
		},
	   "time_series": {
		"type": "array",
		"items": {
		"type": "object",
		"required": [
		   "start_date",
		   "end_date"
	   ],
		"properties": {
		   "start_date": {
		      "description": "The start date of the time period.",
			"type": "string",
			"format": "date-time"
		   },
		  "end_date": {
		      "description": "The end date of the time period.",
		      "type": "string",
		      "format": "date-time"
		  },
		  "count": {
		      "description": "The integer count on the end date of this period.",
		      "type": "integer"
		  },
		  "unit": {
		      "description": "The unit of the value returned.",
		      "type": "string"
		}
	   }
      }
}

Sample Request Body for reports_time_series_statistics_post_response

[
    {
	"property": "num_managed_workloads",
	"resolution": "week",
	"max_results": 4
    }
]

Response for reports_time_series_statistics_post_response

A week starts Monday and ends Sunday and the VEN count is from Sunday of that week. The last week could be a partial week hence the count will be of the last day.

The last month could be a partial month, and hence the count will be from the last day.

This Public Stable API was changed to support the Ransomware Dashboard in the following way:

{
 "properties": {
   "risk_summary": {
	"description": "Risk Summary for this workload",
	"type": "object",
	"required": [
	   "ransomware"
	],
	"properties": {
	   "ransomware": {
		"type": [
		   "object",
		   "null"
		],
		"required": [
		   "workload_exposure_severity",
		   "ransomware_protection_percent",
		   "last_updated_at"
		],
		"properties": {
		   "workload_exposure_severity": {
			"description": "Exposure severity of the workload",
			"type": "string"
			},
		   "ransomware_protection_percent": {
			"description": "Ransomware protection percentage for this workload",
			"type": "number"
			},
		   "last_updated_at": {
			"description": "The time at which the ransomware stats are last computed at",
			"type": "string",
			"format": "date-time"
			}
		}
	}
}

This API, which supplies the risk details, you can see in action on the Workloads page, tab Ransomware Protection.

In addition to the organization admin, the users who have access to the workload can view the ransomware protection details for that workload, or how many risky ports are protected and how many risky ports are not protected.

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
	"risk_details": {
	"type": "object",
	"required": [
	   "ransomware"
	],
	"ransomware": {
	   "type": [
		"object",
		"null"
	   ],
	   "properties": {
	      "details": {
		"type": "array",
		"items": {
		   "$ref": "workload_ransomware_services.schema.json"
		}
	   },
	   "last_updated_at": {
		"description": "The time at which the protection stats were last computed at",
		"type": "string",
		"format": "date-time"
	   }
      }
}

Sample Response for workloads_risk_details_get

{
   "risk_details":{
	"ransomware":{
	   "services":[
	      {
		"href":"/api/v2/orgs/8/workloads/23131cf5-1d70-42de-9242-39055338d0ef",
		"name":"SSH",
		"port":22,
		"protocol":17,
		"severity":"low",
		"port_status":"listening",
		"protection_state":"unprotected",
		"active_policy":"allowed",
		"draft_policy":"blocked",
		"recommendation":"add_boundary"
	   },
	   {
		"href":"/api/v2/orgs/8/workloads/23131cf5-1d70-42de-9242-39055338d0ef",
		"name":"SSH",
		"port":22,
		"protocol":6,
		"severity":"high",
		"port_status":"listening",
		"protection_state":"protected",
		"active_policy":"allowed",
		"draft_policy":"blocked",
		"recommendation":"has_draft_policy_needs_provisioning"
	   }
	],
	"last_updated_at":"2023-01-21 23:32:42.679673"
	}
   }
}

Sample Responses for workloads_risk_details_get when the evaluation concludes there is no risk for the workload.

When the results are not yet computed

{
   "risk_details":{
	"ransomware": null
   }
}

The full response looks as follows:

[
   {
	"property":"num_managed_workloads",
	"time_series":[
	   {
		"start_date":"2022-10-31",
		"end_date":"2022-11-2",
		"count":120
	   },
	   {
		"start_date":"2022-10-24",
		"end_date":"2022-10-30",
		"count":115
	   },
	   {
		"start_date":"2022-10-17",
		"end_date":"2022-10-23",
		"count":110
	   },
	   {
		"start_date":"2022-10-10",
		"end_date":"2022-10-16",
		"count":100
	   }
	]
   }
]

workload_ransomware_services

This schema is referenced from workloads_risk_details_get to supply the required service data:

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "required": [
	 "href",
	  "port",
	  "protocol",
	  "severity",
	  "port_status",
	  "protection_state",
	  "active_policy",
	  "draft_policy"
	],
   "properties": {
      "href": {
	   "description": "Reference of the service",
	   "type": "string"
	},
      "name": {
	   "description": "Name of the service",
	   "type": "string"
	},
	"port": {
	   "description": "Port Number",
	   "type": "integer",
	   "minimum": 0,
	   "maximum": 65535
	},
	"proto": {
	   "description": "Protocol Number",
	   "type": "integer"
	},
	"severity": {
	   "description": "Severity of this service",
	   "type": "string",
	   "enum": [
	      "low",
	      "medium",
	      "high",
	      "critical"
	   ]
	},
       "category": {
	   "description": "Category of this service",
	   "type": "string",
	   "enum": [
	      "admin",
	      "legacy"
	   ]
      },
	"port_status": {
	   "description": "Status of the port on the workload",
	   "type": "string",
	   "enum": 	
             "listening",
	      "inactive"
	      ]
	   },
	"protection_state": {
	   "description": "Protection state of this service",
	   "type": "string",
	   "enum": [
	       "unprotected",
	       "protected_open",
	       "protected_closed"
	      ]
	},
	"active_policy": {
	      "description": "Active Policy that applies to this port",
	      "type": "string",
	      "enum": [
		  "allowed",
		  "allowed_across_boundary",
		  "blocked_by_boundary",
		 "blocked_no_rule"
	      ]
	   },
	  "draft_policy": {
	      "description": "Draft Policy that applies to this port",
	      "type": "string", 
             "enum": [
		   "allowed",
		   "allowed_across_boundary",
		   "blocked_by_boundary",
		   "blocked_no_rule"
		]
	   },
	   "recommendation": {
		"description": "Recommendation for this port based on enforcement state, allow and deny rules and active/draft rule",
		"type": "string",
		"enum": [
		   "add_boundary",
		   "has_draft_policy_needs_provisioning"
		]
	    }
      }
}

This Public Stable API was changed to include a new property num_assets_requiring_ransomware_protection.

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
	"href": {
	   "description": "Org Setting URI",
	   "type": "string",
	   "format": "uri"
	},
	"num_assets_requiring_ransomware_protection": {
	   "description": "number of assets that need ransomware protection for this org",
	   "type": [
		 "integer",
		  "null"
	   ]
	},
		======================================

This Public Stable API was changed to include a new property num_assets_requiring_ransomware_protection, which provides a number of assets that need ransomware protection in a specific organization (1 - 9999999). Number of assets is between one and 9999999.

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "additionalProperties": false,
   "properties": {
	  "num_assets_requiring_ransomware_protection": {
		"description": "number of assets that need ransomware protection for this org",
		"type": "integer",
		"minimum": 1,
		"maximum": 9999999
		===================================