Ransomware Dashboard Reference
This topic contains properties and examples for the Ransomware dashboard.
Ransomware API Details
GET /api/v2/orgs/:xorg_id/app_groups/:app_group_id/risk_details
=====================================
"workload_risk_summary_by_service": {
"description": "Workload risk summary by ransomware service",
"type": "array",
"items": {
"type": "object",
"required": [
"href",
"name",
"os_platforms",
"port",
"protocol",
"severity",
"num_unprotected_workloads",
"num_protected_workloads",
"average_ransomware_service_protection_coverage_percent"
=====================================================This API is referencing the schema workloads_by_exposure:
======================================================
},
"workloads_by_exposure": {
"description": "Workloads of this app group by Ransomware Exposure",
"type": "object",
"$ref": "workloads_by_exposure.schema.json"
},
======================================================
workloads_by_exposure
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"critical": {
"description": "Number of workloads that have 1 or more critically
risky services as its highest risk",
"type": "integer"
},
"high": {
"description": "Number of workloads that have 1 or more high risk
services as its highest risk",
"type": "integer"
},
"medium": {
"description": "Number of workloads that have 1 or more medium risk
services as its highest risk",
"type": "integer"
},
"low": {
"description": "Number of workloads that have 1 or more low risk
services as its highest risk",
"type": "integer"
},
"fully_protected": {
"description": "Number of workloads that have no risky services
and are fully protected",
"type": "integer"
}
}
}GET /api/v2/orgs/1/app_groups/risk_summary
================================
},
"risk_summary": {
"description": "Risk Summary for this app group",
"type": "object",
"required": [
"ransomware"
],
=============================================common workload_exposure_severity
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Exposed ransomware severity for workload",
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low",
"fully_protected"
]
}workloads_get
{
"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": {
"$ref": "../common/workload_exposure_severity.schema.json"
},
"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
{
"$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
{
"$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"
]
}
}
}Additional information about 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
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
New property num_assets_requiring_ransomware_protection provides a number of assets that need ransomware protection in a specific organization (1 - 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
===================================GET /api/v2/orgs/:xorg_id/sec_policy/:pversion/services
=================================
{
"properties": {
"risk_details": {
"properties": {
"ransomware": {
"properties": {
"average_protection_percent": {
"description": "This is the average of ransomware
protection percentage for all
the service ports in this service.",
"type": "number"
}
}
}
}
}
}
=====================================================Example response with the parameter include_ransomware_protection_percent set to true:
[
{
"href": "/orgs/2/sec_policy/draft/services/4852",
"created_at": "2020-01-13T23:31:21.710Z",
"updated_at": "2020-01-13T23:31:21.750Z",
"deleted_at": null,
"created_by": {
"href": "/users/142"
},
"updated_by": {
"href": "/users/142"
},
"deleted_by": null,
"update_type": null,
"name": "IST Common POPv3",
"description": "Post Office Protocol v3",
"description_url": null,
"process_name": null,
"external_data_set": "illumio_segmentation_templates",
"external_data_reference": "1000032 -- Universal - Version 1",
"service_ports": [
{
"port": 110,
"proto": 6
}
],
"risk_details": {
"ransomware": {
"category": "legacy",
"severity": "low",
"os_platforms": [
"linux",
"windows"
],
"average_protection_percent": 0.2
}
}
}
reports_risk_summary_ransomware_timeseries_statistics_post
{
"$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"
]
},
"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
}
}
}
}reports_risk_summary_ransomware_timeseries_statistics_post_response
A sample response of risk_summary:
{
"ransomware": {
"num_total_workloads": 2,
"num_protected_workloads": 0,
"workloads_by_exposure": {
"critical": 2,
"high": 0,
"medium": 0,
"low": 0,
"fully_protected": 0
},
"risky_ports_by_severity": {
"critical": {
"num_protected_ports": 0,
"num_unprotected_ports": 6
},
"high": {
"num_protected_ports": 0,
"num_unprotected_ports": 8
},
"medium": {
"num_protected_ports": 0,
"num_unprotected_ports": 20
},
"low": {
"num_protected_ports": 0,
"num_unprotected_ports": 14
}
},
"risky_ports_by_category": { ---- New section
"admin": {
"num_protected_ports": 0,
"num_unprotected_ports": 26
},
"legacy": {
"num_protected_ports": 0,
"num_unprotected_ports": 22
}
},
"ransomware_protection_coverage_percent": 0.0,
"last_updated_at": "2023-11-27T22:08:09Z"
}
}A sample response of ransomware_timeseries_statistics with ransomware_protection_coverage_percent
[
{
"property": "ransomware_protection_coverage_percent",
"time_series": [
{
"start_date": "2023-11-27",
"end_date": "2023-11-27",
"data": {
"percentage": 59.67
}
},
{
"start_date": "2023-11-26",
"end_date": "2023-11-26",
"data": {
"percentage": 56.0
}
},
{
"start_date": "2023-11-25",
"end_date": "2023-11-25",
"data": {
"percentage": 23.8
}
},
{
"start_date": "2023-11-24",
"end_date": "2023-11-24",
"data": {
"percentage": 23.0
}
},
{
"start_date": "2023-11-23",
"end_date": "2023-11-23",
"data": {
"percentage": 5.0
}
}
]
}
]A sample response of ransomware_timeseries_statistics with num_workloads_by_exposure:
[
{
"property": "num_workloads_by_exposure",
"time_series": [
{
"start_date": "2023-11-27",
"end_date": "2023-11-27",
"data": {
"critical": 2,
"high": 0,
"medium": 0,
"low": 0,
"fully_protected": 0
}
},
{
"start_date": "2023-11-26",
"end_date": "2023-11-26",
"data": {
"critical": 2,
"high": 0,
"medium": 0,
"low": 0,
"fully_protected": 0
}
},
{
"start_date": "2023-11-25",
"end_date": "2023-11-25",
"data": {
"critical": 2,
"high": 0,
"medium": 0,
"low": 0,
"fully_protected": 0
}
},
{
"start_date": "2023-11-24",
"end_date": "2023-11-24",
"data": {
"critical": 2,
"high": 0,
"medium": 0,
"low": 0,
"fully_protected": 0
}
},
{
"start_date": "2023-11-23",
"end_date": "2023-11-23",
"data": {
"critical": 2,
"high": 0,
"medium": 0,
"low": 0,
"fully_protected": 0
}
}
]
}
]reports_risk_summary_get
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"
}
}
}Four required properties are added for the ransomware object:
"required": [
"ransomware"
],
"properties": {
"ransomware": {
"type": [
"object",
"null"
],
"required": [
"num_total_workloads",
"num_protected_workloads",
"workloads_by_exposure",
"risky_ports_by_severity",
"risky_ports_by_category",
"top_risky_applications",
"top_risky_services",
"num_risky_services",
"num_unenforced_workloads",
"last_updated_at"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"
}
}
}APIs that support Summary Reports
report_schedules_post
report_schedules_put
reports_schedules_get
report_templates_get
reports_get
These five APIs are referencing ransomware_risk_report_params through the property report_parameters:
report_parameters: {
"description": "Any specific parameters required for this report template",
"type": "object",
"anyOf": [
{
"$ref": "executive_summary_report_params.schema.json"
},
{
"$ref": "traffic_flow_report_params.schema.json"
},
{
"$ref": "explorer_report_params.schema.json"
},
{
"$ref": "ves_report_params.schema.json"
},
{
"$ref": "ransomware_risk_report_params.schema.json"
}
]
}reports_time_series_statistics_post
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.
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
}
}
]