Ransomware Protection Dashboard APIs

The Ransomware Dashboard is powered by the two main APIs: time_series and risk_summary.

For more details, see Ransomware Dashboard.

Risk SummaryAPIs

Ransomware Dashboard APIs that evaluate the risk from ransomware attacks are :

• reports_risk_summary_ransomware_timeseries_statistics_post
• reports/risk_summary_get
• num_protected_unprotected_ports

Time Series APIs

New APIs for the Ransomware Dashboard that are dedicated to reporting about ransomware events are:

• reports_time_series_statistics_post
• reports_time_series_statistics_post_response

Workloads APIs Changed for Ransomware

• workloads_get

  The object risk_summary

• workloads_risk_details_get

  The object risk_details

Reference for workloads_risk_details_get

Settings APIs Changed for Ransomware

• settings_get

  Poperty num_assets_requiring_ransomware_protection

• settings_put

  Poperty num_assets_requiring_ransomware_protection

Security Policy Changed for Ransomware

• sec_policy_services_post
• sec_policy_services_put
• sec_policy_services_get

These Security Policy APIs are explained in the topic Services.Services

List of APIs

reports_risk_summary_ransomware_timeseries_statistics_post

This API is used to show the time series data:

• Number of managed workloads
• Percent of the ransomware protection coverage
• Number of workloads by exposure

Data is presented with the granularity of day, week, month, and quarter, where the default is day.

reports/risk_summary_get

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:

• Number of total workloads
• Number of protected workloads
• Number of risky ports by the severity of their risk exposure (low, medium, high, and critical)
• Workload protection by the port type (admin and legacy)
• Ransomware protection coverage percent
• Date when the status was last updated

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"
   }
}

In release 23.5, this API was changed so that the property risky_ports_by_category was added to support the widget "Risky ports by type" in the UI.

     "risky_ports_by_category": {
	  "description": "Risky ports by Port type",
	  "type": "object",
	   "properties": {
		"admin": {
			"$ref": "num_protected_unprotected_ports.schema.json"
		},
		"legacy": {
			"$ref": "num_protected_unprotected_ports.schema.json"
		}
	}
}		

num_protected_unprotected_ports

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"
	}
   }
}		

reports_time_series_statistics_post

This schema supplies the granularity of the time series data.

The API reports_time_series_statistics_post includes these properties:

• 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".
• ransomware_protection_coverage_percent: Percent of the ransomware protection coverage (added in release 23.5)
• num_workloads_by_exposure: Number of workloads by exposure (added in release 23.5)

Data is presented with the granularity of day, week, month, and quarter, where the default is day.

{
	"$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",
		   "ransomware_protection_coverage_percent",
		   "num_workloads_by_exposure"
		   ]
		},

reports_time_series_statistics_post_response

This API specifies the time series data about the protected workloads.

Previously, the schema contained the integer count on the end date of the counted period. This item was removed:

"count": {
	   "description": "The integer count on the end date of this period.",
	   "type": "integer"
	   },
	"unit": {
	   "description": "The unit of the value returned.",
	   "type": "string"        
          },

Starting from the release 23.5, this API gives the percentage of the end date of the counted period.

It is referencing the schema num_workloads_by_exposure_time_series.

 "data": {
   "oneOf": [
   {
	"$ref": "../../../agent/schema/v2/num_workloads_by_exposure_time_series.schema.json"
   },
   {
	"count": {
		"description": "The integer count on the end date of this period.",
		"type": "integer"
		}
	},
	{
	"percentage": {
		"description": "The percentage on the end date of this period.",
		"type": "number",
		"minumum": 0,
		"maximum": 100
		}
	}
]

workloads_get

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

One new object was added: risk_summary, which explains the risk summary for the workload. This object includes a required object ransomware, which supplies these properties:

• workload_exposure_severity
• ransomware_protection_percent
• last_updated_at

{
 "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"
			}
		}
	}
}

workloads_risk_details_get

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:

• Service location and name
• Service Port and Protocol
• Severity and Protection state of this service
• Status of the port on the workload
• Active and Draft policy that applies to the Port

{
   "$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"
		]
	    }
      }
}

In release 23.5, additional information about the operating systems has been added for the ransomware service: Windows and Linux.

{
	"properties": {
	    "os_platforms": {
		"description": "Operating system for this ransomware service",
		"type": "array",
		"minItems": 1,
		"items": {
		    "type": "string",
		    "enum": [
		    "windows",
		    "linux"
		]
	    }
	}
    }
}

settings_get

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"
	   ]
	},
		======================================

settings_put

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
		===================================