Incidents
The Incidents API includes the following methods allowing the management of Endpoint and Detection (EDR) features:
addToBlocklist
: adds a new hash to the Blocklist.getBlocklistItems
: lists existing Blocklist items.removeFromBlocklist
: removes a specific entry from the Blocklist.createIsolateEndpointTask
: creates a task to isolate an endpoint.createRestoreEndpointFromIsolationTask
: creates a task to restore an isolated endpoint.createCustomRule
: creates a custom rule.getCustomRulesList
: lists existing custom rule items.deleteCustomRule
: removes a specific custom rule.changeIncidentStatus
: changes the status of a specific incident.updateIncidentNote
: assigns a note to a specific incident.
API url: CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/incidents
addToBlocklist
Use this method to add one or more file hashes to the Blocklist.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| Number | No | the algorithm used to obtain the hash. Possible values: |
| Array | No | An array containing several hashes. All hashes must be of the type specified by the |
| String | Yes | The ID of the company to which the Blocklist item belongs. |
| String | No | A description for the hashes. |
Return value
This method returns a Boolean which is True if the operation was successful.
Example
Request:
{
"id": "0df7568c-59c1-48e0-a31b-18d83e6d9810",
"jsonrpc": "2.0",
"method": "addToBlocklist",
"params": {
"companyId": "5b680f6fb1a43d860a7b23c8",
"hashType" : 2,
"hashList": ["5b7ac19bb1a43dfb107b23c6",
"f696282aa4cd4f614aa995190cf442fe"],
"sourceInfo": "Added from public API"
}
}
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": true }
getBlocklistItems
This method lists all the hashes that are present in the blocklist.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | Yes | When set, the method lists only the items in the Blocklist for the company with the provided ID. |
| Number | Yes | The results page number. The default value is 1. |
| Number | Yes | The number of items displayed in a page. The upper limit is 100 items per page. Default value: 30 items per page. |
Return value
items
- the list of blocklist items. Each entry in the list has the following fields:
id
, the ID of the hash item in the Blocklist.hashType
, the algorithm used to obtain the hash. Possible values:1
- SHA256,2
- MD5hash
, the hash value for a specific file.source
, the source from where the hash entry hash originated. Possible values:1
- Incident,2
- Import,3
- Manual.sourceInfo
, the description of the item, as the user provided when adding the item to the Blocklist.filename
, the name of file corresponding to the hash. This field is only displayed if this information exists.companyId
, the ID of the company associated with this item in the Blocklist.
Example
Request:
{
"params": {
"companyId" : "5b680f6fb1a43d860a7b23c8"
},
"jsonrpc": "2.0",
"method": "getBlocklistItems",
"id": "0df7568c-59c1-48e0-a31b-18d83e6d9810"
}
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": { "items": [ { "companyId": "5b680f6fb1a43d860a7b23c8", "hash": "098f6bcd4621d373cade4e832627b4f6", "hashType": 2, "id": "5b7ac19bb1a43dfb107b23c6", "source": 3, "sourceInfo": "Added from public API" }, { "companyId": "5b680f6fb1a43d860a7b23c8", "filename": "file.txt", "hash": "f696282aa4cd4f614aa995190cf442fe", "hashType": 2, "id": "5b7ac19bb1a43dfb107b23c7", "source": 1, "sourceInfo": "Added from incident 1" } ], "page": 1, "pagesCount": 1, "perPage": 30, "total": 2 } }
removeFromBlocklist
This method removes an item from the Blocklist, identified by its ID.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | the ID of the item in the Blocklist to be deleted |
Return value
This method returns a Boolean which is True if the operation was successful.
Example
Request:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "method": "removeFromBlocklist", "params": { "hashItemId" : "5b680f6fb1a43d860a7b23c1" } }
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": true }
createIsolateEndpointTask
This method creates a task to isolate the specified endpoint.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | The ID of the endpoint to be isolated |
Return value
This method returns a Boolean which is True if the operation was successful.
Example
Request:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "method": "createIsolateEndpointTask", "params": { "endpointId" : "5b680f6fb1a43d860a7b23c1" } }
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": true }
createRestoreEndpointFromIsolationTask
This method creates a task to restore the specified endpoint from isolation.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | the ID of the endpoint to be restored |
Return value
This method returns a Boolean which is True if the operation was successful.
Example
Request:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "method": "createRestoreEndpointFromIsolationTask", "params": { "endpointId" : "5b680f6fb1a43d860a7b23c1" } }
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": true }
createCustomRule
Method to create a custom rule.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| Number | Yes | The type of rule to create. Possible values: |
| String | Yes | The company Id where the attached rule should be created. The default value is the ID of the company linked to the user who generated the API key. |
| String | No | The name of the rule to be created. |
| String | Yes | The description of the rule. |
| Array | Yes | The list of associated tags. The tag list is an array of strings. |
| Array | No | The rule settings. These are the available settings:
NoteFor more information on the possible values of |
| Boolean | Yes | Indicates if the request will return the ID of the new rule. Possible values:
Default value: |
Detections and exclusions
Detection (type =1) | Exclusion (type=2) | Display Name | target | Field | Relation | Validator |
---|---|---|---|---|---|---|
Yes | Yes | Name | process | Process.Name | is |contains| any | string |
Yes | Yes | Path | process | Process.Path | is |contains| any | string |
Yes | Yes | Full Path Name | process | Process.FullPathName | is |contains| any | string |
Yes | Yes | Command Line | process | Process.CommandLine | is |contains| any | string |
Yes | Yes | Parent Name | process | Process.Parent.Name | is |contains| any | string |
Yes | Yes | Parent Path | process | Process.Parent.Path | is |contains| any | string |
Yes | Yes | Paret Full Path Name | process | Process.Parent.FullPathName | is |contains| any | string |
Yes | Yes | Parent Command Line | process | Process.Parent.CommandLine | is |contains| any | string |
Yes | Yes | Name | file | File.Name | is |contains| any | string |
Yes | Yes | Path | file | File.Path | is |contains| any | string |
Yes | Yes | Full Path Name | file | File.FullPathName | is |contains| any | string |
Yes | Yes | Creation Process Name | file | File.CreatedBy.Name | is |contains| any | string |
Yes | Yes | Creation Process Path | file | File.CreatedBy.Path | is |contains| any | string |
Yes | Yes | Creation Process Full Path Name | file | File.CreatedBy.FullPathName | is |contains| any | string |
Yes | Yes | Creation Process Command Line | file | File.CreatedBy.CommandLine | is |contains| any | string |
Yes | Yes | Source IP | connection | Connection.SourceIP | is |contains| any | valid IP |
Yes | Yes | Destination IP | connection | Connection.DestinationIP | is |contains| any | valid IP |
Yes | Yes | Source Port | connection | Connection.SourcePort | is |contains| any | integer between 0 and 65,535 |
Yes | Yes | Destination Port | connection | Connection.DestinationPort | is |contains| any | integer between 0 and 65,535 |
Yes | Yes | Creation Process Name | connection | Connection.Process.Name | is |contains| any | string |
Yes | Yes | Creation Process Path | connection | Connection.Process.Path | is |contains| any | string |
Yes | Yes | Creation Process Full Path Name | connection | Connection.Process.FullPathName | is |contains| any | string |
Yes | Yes | Creation Process Command Line | connection | Connection.Process.CommandLine | is |contains| any | string |
Yes | No | Key | registry | Registry.Key | is |contains| any | string |
Yes | No | Value | registry | Registry.Value | is |contains| any | string |
Yes | No | Creation Process Name | registry | Registry.CreatedBy.Name | is |contains| any | string |
Yes | No | Creation Process Path | registry | Registry.CreatedBy.Path | is |contains| any | string |
Yes | No | Creation Process Full Path Name | registry | Registry.CreatedBy.FullPathName | is |contains| any | string |
Yes | No | Creation Process Command Line | registry | Registry.CreatedBy.CommandLine | is |contains| any | string |
Note
The any
operator implies an array.
Return value
This method returns the ID of the newly created rule or a boolean value which is true
if the creation of the custom rule was successful.
Example
Request:
{ "params": { "companyId": "61827b8036492c2fc0718722", "type": 1, "name": "Detection Rule via API", "description": "description test api", "tags": [ "test", "api", "demo" ], "settings": { "status": 0, "severity": 1, "target": "connection", "criteriaList": [ { "field": "Connection.DestinationPort", "relation": "is", "value": [ "25691" ] }, { "field": "Connection.Process.Name", "relation": "contains", "value": "./network1" }, { "field": "Connection.SourcePort", "relation": "any", "value": [ "22", "23", "24" ] } ] }, "returnRuleId": true }, "jsonrpc": "2.0", "method": "createCustomRule", "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810" }
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": 6372b7a3897aaa77ee021642 }
getCustomRulesList
This method retrieves the Custom Rules list for a specific company.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| Number | No | The results page number. The default value is 1. |
| Number | No | The number of items displayed in a page. The upper limit is 100 items per page. Default value:30 items per page |
| String | No | The ID of the company for which to retrieve the list of custom Rules. The default value is the ID of the company linked to the user who generated the API key. |
| Number | No | The type of rule to return. Possible values: 1 - Detection, 2 - Exclusion |
Return value
This method returns an Array containing information on the custom rules items. The returned object contains:
page
- the current page displayedpagesCount
- the total number of available pagesperPage
- the total number of returned items per pageitems
- the list of custom rules items items. Each entry in the list has the following fields:id
owner
name
companyId
status
tags
settings
- The rule settings. These are the available settings:status
severity
(if Detection Rule)target
(e.g process, connection, file)criteria list
, array of objects. Each object contains afield
, arelation
and avalue
.Note
For more information on the possible values of
criteria list
objects, refer to Detections and exclusions.
Detections and exclusions
Detection (type =1) | Exclusion (type=2) | Display Name | target | Field | Relation | Validator |
---|---|---|---|---|---|---|
Yes | Yes | Name | process | Process.Name | is |contains| any | string |
Yes | Yes | Path | process | Process.Path | is |contains| any | string |
Yes | Yes | Full Path Name | process | Process.FullPathName | is |contains| any | string |
Yes | Yes | Command Line | process | Process.CommandLine | is |contains| any | string |
Yes | Yes | Parent Name | process | Process.Parent.Name | is |contains| any | string |
Yes | Yes | Parent Path | process | Process.Parent.Path | is |contains| any | string |
Yes | Yes | Paret Full Path Name | process | Process.Parent.FullPathName | is |contains| any | string |
Yes | Yes | Parent Command Line | process | Process.Parent.CommandLine | is |contains| any | string |
Yes | Yes | Name | file | File.Name | is |contains| any | string |
Yes | Yes | Path | file | File.Path | is |contains| any | string |
Yes | Yes | Full Path Name | file | File.FullPathName | is |contains| any | string |
Yes | Yes | Creation Process Name | file | File.CreatedBy.Name | is |contains| any | string |
Yes | Yes | Creation Process Path | file | File.CreatedBy.Path | is |contains| any | string |
Yes | Yes | Creation Process Full Path Name | file | File.CreatedBy.FullPathName | is |contains| any | string |
Yes | Yes | Creation Process Command Line | file | File.CreatedBy.CommandLine | is |contains| any | string |
Yes | Yes | Source IP | connection | Connection.SourceIP | is |contains| any | valid IP |
Yes | Yes | Destination IP | connection | Connection.DestinationIP | is |contains| any | valid IP |
Yes | Yes | Source Port | connection | Connection.SourcePort | is |contains| any | integer between 0 and 65,535 |
Yes | Yes | Destination Port | connection | Connection.DestinationPort | is |contains| any | integer between 0 and 65,535 |
Yes | Yes | Creation Process Name | connection | Connection.Process.Name | is |contains| any | string |
Yes | Yes | Creation Process Path | connection | Connection.Process.Path | is |contains| any | string |
Yes | Yes | Creation Process Full Path Name | connection | Connection.Process.FullPathName | is |contains| any | string |
Yes | Yes | Creation Process Command Line | connection | Connection.Process.CommandLine | is |contains| any | string |
Yes | No | Key | registry | Registry.Key | is |contains| any | string |
Yes | No | Value | registry | Registry.Value | is |contains| any | string |
Yes | No | Creation Process Name | registry | Registry.CreatedBy.Name | is |contains| any | string |
Yes | No | Creation Process Path | registry | Registry.CreatedBy.Path | is |contains| any | string |
Yes | No | Creation Process Full Path Name | registry | Registry.CreatedBy.FullPathName | is |contains| any | string |
Yes | No | Creation Process Command Line | registry | Registry.CreatedBy.CommandLine | is |contains| any | string |
Note
The any
operator implies an array.
Example
Request:
{ "params": { "companyId": "61827b8036492c2fc0718722", "type": 1, "page": 1, "perPage": 100 }, "jsonrpc": "2.0", "method": "getCustomRulesList", "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810" }
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": { "total": 1, "page": 1, "perPage": 100, "pagesCount": 1, "items": [ { "id": "6188dfc42a1a0155e84afa57", "name": "testApi1111", "ownerId": "6082afe13cf8082cab49cacb", "description": "description test api", "companyId": "61827b8036492c2fc0718722", "status": 0, "tags": [ "test", "api", "demo" ], "settings": { "status": 0, "target": "connection", "criteriaList": [ { "field": "Connection.DestinationPort", "relation": "is", "value": [ "25691" ] }, { "field": "Connection.Process.Name", "relation": "contains", "value": [ "./network1" ], "operator": "AND" }, { "field": "Connection.SourcePort", "relation": "any", "value": [ "22", "23", "24" ], "operator": "AND" } ], "severity": 1 } } ] } }
deleteCustomRule
Method to delete a custom rule.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| Number | No | The type of the rule to be deleted. Possible values: 1 - Detection, 2 - Exclusion |
| String | No | The Id of the rule to be deleted |
Return value
This method returns a boolean value which is True if the creation of the custom rule was successful.
Example
Request:
{ "params": { "ruleId": "6182a7e26f59d3072a1e8fc5", "type": 1 }, "jsonrpc": "2.0", "method": "deleteCustomRule", "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810" }
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": true }
updateIncidentNote
This method assigns a note to an incident.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | The type of the target incident. Possible values:
|
| String | No | The ID of the incident, obtained from the Event Push details. The value corresponds to the |
| String | No | The text to be included in the note. NoteIf the incident already has a note assigned to it, it will be overwritten. |
Return value
This method returns a Boolean which is True
if the note is assigned successfully and the following object:
data
, an object containing information related to the incident.lastUpdated
- the timestamp for the moment the note is changed.
Examples
Request:
{ "params": { "incidentId" : "621342db44747b408b7edf65", "type" : "extendedIncidents" or "incidents", "note" : "A random note" }, "jsonrpc": "2.0", "method": "updateIncidentNote", "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810" }
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": { "success": true, "data": { "lastUpdated": "2022-04-04T11:53:21+03:00" } } }
changeIncidentStatus
This method changes the status of an incident.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | The type of the target incident. Possible values:
|
| String | No | The ID of the incident, obtained from the Event Push details. The value corresponds to the |
| Integer | No | The status to be assigned to the incident. Possible values:
|
Return value
This method returns a Boolean which is True
if the status of the targeted incident is changed successfully.
Note
This method will still return a True
value if the target incident already had the specified status assigned prior to your request.
Example
Request:
{ "params": { "type" : "incidents", "incidentId": "6245af36b6503a00d07a4e53", "status": 1 }, "jsonrpc": "2.0", "method": "changeIncidentStatus", "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810" }
Response:
{ "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810", "jsonrpc": "2.0", "result": true }