Get Security Alerts
Get a list of security alerts.
Rate limiting: 60 times per minute
Query Parameters
- customerid string required
The customer ID to which the API call is directed
- type string
A field that specifies the alert type as policy_alert
- resolved string
A filter to retrieve only active alerts (resolved=no, the default) or resolved alerts (resolved=yes)
- offset integer
In addition to the pagelength parameter, offset gets items on subsequent pages. For example, if the page length of your first request is 100, you get the first 100 alerts. To get the next 100, add offset=100 to your second request. This skips the first 100 alerts and gets the next 100 starting from 101.
- pagelength integer
The number of items in one response; that is, in one page. The default page length for alerts is 1000 and the maximum is 1000. Setting a shorter length improves response times.
- stime string
The start of a time range for alerts to retrieve. For example, stime=2021-10-6T07:00Z. (It’s unnecessary to set etime=now or etime=<time> because it is always treated as now.)
- sortdirection string
The direction in which returned alerts are organized: ascending order asc (oldest to newest) or descending order desc (newest to oldest, the default)
- sortfield string
The device attribute to use for sorting. date and severityNumber are supported as the following value and the value types are string and integer respectively. The default way to sort alerts is by date in descending order.
- updatedCreatedAfter date-time
Optional field setting the start of a time range for retrieving alerts that have been created in DB or updated.
- 200
- 4XX
- 5XX
Successful Response (We only show some important fields here.)
- application/json
- Schema
- Example (from schema)
- securityAlertsResponseExample
Schema
- total integer
The number of security alerts matching the request
items object[]
An array containing security alerts
Array [resolved stringWhether the alert has been resolved (yes) or not (no)
siteid stringThe ID number that IoT Security assigns to the site for internal use
trafficDirection stringThe direction of the traffic on the device that triggered the alert; “inbound” if the device is a server and “outbound” if it’s a client
siteName stringThe name of the site where the alert occurred
date stringThe alert detection date
deviceid stringThe MAC address or IP address of a device
name stringThe alert name
severity stringThe severity level of an alert: high, medium, low, info
severityNumber integerThe severity number matching the severity level: high = 4, medium = 3, low = 2, info = 1
type stringThe type of alert
description stringThe alert description
tenantid stringThe internal customer ID
zb_ticketid stringThe unique ticket ID
id stringThe alert ID. This is the ID to use when resolving an alert through the API.
profile stringThe device profile to which the alert belongs
profile_vertical stringThe industry vertical for the profile such as Medical, IT Devices, and Office
category stringThe device category to which the alert belongs
hostname stringThe hostname of the device to which the alert belongs
reason_history stringThe history of actions taken to investigate and resolve the alert
serviceLevel string(For MSSP only) The level of service for an MSSP customer as defined by the MSSP owner; for example: Tier 1, Tier 2, Tier 3; or Platinum, Gold, Silver.
]deviceTags object
A list of device tags
id object
The ID numbers of user-defined tags
deviceid stringdeviceid is the Key for the DeviceTagMapping
tagIdList arrayList of Tag IDs
allTags object[]
List of Tagtype-TagValue pairs for the Device
Array [tagType stringThe key for a user-defined tag
tagValue stringThe value of the tag key for a user-defined tag
tagId stringThe ID of a user-defined tag
]
{
"total": 0,
"items": [
{
"resolved": "string",
"siteid": "string",
"trafficDirection": "string",
"siteName": "string",
"date": "string",
"deviceid": "string",
"name": "string",
"severity": "string",
"severityNumber": 0,
"type": "string",
"description": "string",
"tenantid": "string",
"zb_ticketid": "string",
"id": "string",
"profile": "string",
"profile_vertical": "string",
"category": "string",
"hostname": "string",
"reason_history": "string",
"serviceLevel": "string"
}
],
"deviceTags": {
"id": {
"deviceid": "string",
"tagIdList": [
null
],
"allTags": [
{
"tagType": "string",
"tagValue": "string",
"tagId": "string"
}
]
}
}
}
{
"total": 1,
"items": [
{
"resolved'": "no",
"date'": "2020-05-12T01:23:10.630Z",
"deviceid'": "18:65:90:cd:88:0d",
"name'": "zingcloud alert bg job integration test at 1589246590630",
"severity'": "high",
"severityNumber'": 4,
"type'": "policy_alert",
"description'": "The baseline policy defines a criteria to match normal connections between devices in two different networks or device groups. It is a positive detection if connections outside of this definition are observed.",
"tenantid'": "acmecorp",
"zb_ticketid": "alert-hNMleG1nW",
"id": "5eb9fa8127b736d82bf7840a",
"profile": "Macintosh-MacPro",
"category": "Personal Computer",
"hostname": "cntl-201-2",
"internal_hostname": "cntl-201-2",
"siteid": "0",
"serviceLevel'": "",
"reason_history": [],
"msg'": {
"severity": "high",
"description": "The baseline policy defines criteria to match normal connections between devices in two different networks or device groups. It is a positive detection if connections outside of this definition are observed.",
"name": "zingcloud alert bg job integration test at 1589246590630",
"id": "hNMleG1nW",
"ruleid": "5a26f169c8272f0b00c5ef1a",
"zb_ticketid": "alert-hNMleG1nW",
"hostname": "unknown"
}
}
],
"deviceTags": {
"00:0e:dd:51:aa:f2": {
"deviceid": "00:0e:dd:51:aa:f2",
"tagIdList": [
"6030135777a1d6fb488e26ad",
"60301332ff1679e9481b62a6",
"602ca12179bc780a2333895d",
"603012a37ebd56bc48921703",
"603012c976a6c0da487530b3",
"PurdueLevel5",
"PurdueLevel4"
],
"allTags": [
{
"tagType": "TestFilter",
"tagValue": "withTagInLocalFilter5",
"tagId": "6030135777a1d6fb488e26ad"
},
{
"tagType": "TestFilter",
"tagValue": "withTagInLocalFilter4",
"tagId": "60301332ff1679e9481b62a6"
}
]
}
}
}
Client Error Response
- application/json
- Schema
- Example (from schema)
- Bad Request
- Forbidden access
- Too many requests
Schema
- code string
STATUS_CODE
- msg string
GENERAL_MESSAGE
{
"code": "string",
"msg": "string"
}
{
"code": 400,
"msg": "Bad Request. This occurs when an HTTP request contains an invalid query string."
}
{
"code": 403,
"msg": "Forbidden access. Either the provided API key is invalid or it does not have the required RBAC permissions to run this API."
}
{
"code": 429,
"msg": "Too many requests. The number of requests for device details for a single device exceeded the rate limit of 180 queries per minute per tenant."
}
Server Error Response
- application/json
- Schema
- Example (from schema)
- securityAlertsResponseExample
Schema
- code string
STATUS_CODE
- msg string
GENERAL_MESSAGE
{
"code": "string",
"msg": "string"
}
{
"code": 500,
"msg": "Internal server error. A unified status for API communication type errors."
}