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
`hashType`	Number	No	the algorithm used to obtain the hash. Possible values: `1` - SHA256, `2` - MD5
`hashList`	Array	No	An array containing several hashes. All hashes must be of the type specified by the `hashType` parameter.
`companyId`	String	Yes	The ID of the company to which the Blocklist item belongs.
`sourceInfo`	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
`companyId`	String	Yes	When set, the method lists only the items in the Blocklist for the company with the provided ID.
`page`	Number	Yes	The results page number. The default value is 1.
`perPage`	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 - MD5
hash, 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
`hashItemId`	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
`endpointId`	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
`endpointId`	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
`type`	Number	Yes	The type of rule to create. Possible values: `1` - Detection, `2` - Exclusion
`companyId`	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.
`name`	String	No	The name of the rule to be created.
`description`	String	Yes	The description of the rule.
`tags`	Array	Yes	The list of associated tags. The tag list is an array of strings.
`settings`	Array	No	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 a `field`, a `relation` and a `value`. Note For more information on the possible values of `criteria list` objects, refer to Detections and exclusions
`returnRuleId`	Boolean	Yes	Indicates if the request will return the ID of the new rule. Possible values: `true`, will return the ID of the newly created rule, if the request is successful. `false`, will not return the ID of the newly created rule. Instead, it will return a Boolean value. Default value: `False`.

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
`page`	Number	No	The results page number. The default value is 1.
`perPage`	Number	No	The number of items displayed in a page. The upper limit is 100 items per page. Default value:30 items per page
`companyId`	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.
`type`	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 displayed
pagesCount - the total number of available pages
perPage - the total number of returned items per page
items - 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 a field, a relation and a value.
    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
`type`	Number	No	The type of the rule to be deleted. Possible values: 1 - Detection, 2 - Exclusion
`ruleId`	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
`type`	String	No	The type of the target incident. Possible values: `incidents` - incidents generated as a result of a new Root Cause Analysis (RCA) being displayed under the Incidents section of GravityZone Control Center. You can find these incidents under the Endpoint Incidents or Detected Threats tabs. `extendedIncidents` - These incidents can be found in the Incidents page in GravityZone Control Center, under the Extended Incidents tab.
`incidentId`	String	No	The ID of the incident, obtained from the Event Push details. The value corresponds to the `incident_id` parameter from New Incident event types.
`note`	String	No	The text to be included in the note. Note If 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
`type`	String	No	The type of the target incident. Possible values: `incidents` - incidents generated as a result of a new Root Cause Analysis (RCA) being displayed under the Incidents section of GravityZone Control Center. You can find these incidents under the Endpoint Incidents or Detected Threats tabs. `extendedIncidents` - These incidents can be found in the Incidents page in GravityZone Control Center, under the Extended Incidents tab.
`incidentId`	String	No	The ID of the incident, obtained from the Event Push details. The value corresponds to the `incident_id` parameter from New Incident event types.
`status`	Integer	No	The status to be assigned to the incident. Possible values: `1` - open `2` - investigating `3` - closed `4` - false positive

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
}

In this section:

Incidents

addToBlocklist

Parameters

Return value

Example

getBlocklistItems

Parameters

Return value

Example

removeFromBlocklist

Parameters

Return value

Example

createIsolateEndpointTask

Parameters

Return value

Example

createRestoreEndpointFromIsolationTask

Parameters

Return value

Example

createCustomRule

Parameters

Note

Detections and exclusions

Note

Return value

Example

getCustomRulesList

Parameters

Return value

Note

Detections and exclusions

Note

Example

deleteCustomRule

Parameters

Return value

Example

updateIncidentNote

Parameters

Note

Return value

Examples

changeIncidentStatus

Parameters

Return value

Note

Example

Search results