Skip to main content

REST APIs for 24.2.20 and 24.2.10

Ransomware Protection Dashboard APIs

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

Multiple APIs are used to manage Ransomware Dashboard features and to generate reports about protection statistics:

Risk Summary APIs

Risk summary APIs are the following:

  • GET /api/v2/orgs/:xorg_id/app_groups/:app_group_id/risk_details

This API is added under specific app_groups to represent the name and os_platforms of the ransomware service.

This API is referencing the schema workloads_by_exposure:

  • workloads_by_exposure

The schema workloads_by_exposure describes the number of workloads with one or more critically risky services as its highest risk. It is also used by the API risk_summary_get.

  • GET /api/v2/orgs/1/app_groups/risk_summary

This API, added under app_groups, returns a ransomware risk summary for each app group.

This API is referencing the common schema workload_exposure_severity:

  • common workload_exposure_severity

The common schema workload_exposure_severity describes exposed ransomware severity for a workload.

  • 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

  • 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 with 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.

  • 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

Information about the operating systems has been added for the ransomware service: Windows and Linux.

  • settings_get

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

  • settings_put

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

Risky Services APIs

The new widget for the Ransomware Dashboard displays risky services and their protection coverage scores.

  • GET /api/v2/orgs/:xorg_id/sec_policy/:pversion/services

The API now contains the property average_protection_percent, which is the average amount of ransomware protection percentages for all service ports in the service.

To include the needed data in response to this request from the UI, the query parameter include_ransomware_protection_percent is used and set to true to include the average percentage data.

Summary Reports

The APIs used to generate summary reports are:

  • reports_risk_summary_ransomware_timeseries_statistics_post

  • reports_risk_summary_ransomware_timeseries_statistics_post_response.

  • reports_risk_summary_get

  • reports_time_series_statistics_post

  • reports_time_series_statistics_post_response

  • 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.

Payloads for this API can be such as the following:

[{"property":"num_workloads_by_exposure","resolution":"day"}]

[{"property":"ransomware_protection_coverage_percent","resolution":"day"}]

  • reports_risk_summary_ransomware_timeseries_statistics_post_response

This API gives the start and end date of the period.

  • 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

The property risky_ports_by_category was added to support the widget "Risky ports by type" in the UI.

Four required properties are added for the ransomware objects:

  • top_risky_applications

  • top_risky_services

  • num_risky_services

  • num_unenforced_workloads

  • 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.

Other APIs that support Summary Reports

  • report_schedules_post

  • report_schedules_put

  • reports_schedules_get

  • report_templates_get

  • reports_get

APIs referencing ransomware_risk_report_params through the property report_parameters
  • 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

  • num_workloads_by_exposure: Number of workloads by exposure

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

  • 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.

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
		}
	}
]
See also: