Skip to main content

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
}