Skip to main content

getBlocklistItems

This method lists all the hashes that are present in a blocklist.

Important

This method has been updated to version 1.2. For information applicable to version 1.0, refer to this section.

Version 1.0 only returns hash type blocklist rules.

Parameters

Parameter

Description

Included in request

Type

Values

companyId

The ID of the company to which the Blocklist item belongs to.

Optional

String

Must be a valid company ID that the user has access to managing.

Default value: the company the API key used to make the request belongs to.

page

The number of the results page currently displayed.

Mandatory

Integer

Default value: 1

perPage

The number of items displayed in a page.

Mandatory

Integer

Possible values: 1 - 100.

Default value: 30

Return value

This method returns an Object containing information regarding existing blocklist rules. The returned object contains:

Attribute

Type

Description

total

Integer

The total number of rules returned by the request.

page

Integer

The number of the page currently being displayed.

perPage

Integer

The number of results being displayed per page.

pagesCount

Integer

The total number of pages that the request returned.

items

Object

The list of existing rules associated to th target company.

id

String

The ID of the item.

type

String

The types of entities included in the list.

Possible values:

  • hash

  • application path

  • connection rule

source

Object

Provides information on how the item was added to the list.

type

String

Indicates the type of the source from where the entry originated.

Possible values:

  • Incident

  • Import

  • Manual.

description

String

The description given to this item when added to the list.

company

Object

Provides information on the company that the list belongs to.

id

String

The ID of the company.

name

String

The name of the company the list belongs to.

owner

Object

Provides information on the GravityZone user that created the rule.

id

String

The ID of the GravityZone user.

username

String

The email address of the user.

created

Timestamp

The date and time when this item was added to the blocklist.

details

Object

Contains information regarding the rule. For information on the settings included in the object refer to addToBlocklist.

Examples

Request

{
  "params": {
	"companyId": "65fd7506e2354158650c7c32",
	"page": 1,
	"perPage": 100
  },
  "jsonrpc": "2.0",
  "method": "getBlocklistItems",
  "id": "5087eab8-b74f-4a3e-85b3-4271e85890d5"
}

Response

A response for type = hash:

{
  "params": {
	"companyId": "65fd7506e2354158650c7c32",
	"page": 1,
	"perPage": 100
  },
  "jsonrpc": "2.0",
  "method": "getBlocklistItems",
  "id": "5087eab8-b74f-4a3e-85b3-4271e85890d5"
}

A response for type = connection:

{
 "id": "5087eab8-b74f-4a3e-85b3-4271e85890d5",
 "jsonrpc": "2.0",
 "result": {
  "total": 10,
  "page": 1,
  "perPage": 100,
  "pagesCount": 1,
  "items": [
   {
    "_id": "6613aa73a0946f3422083d6d",
    "type": "connection",
    "source": {
     "type": "manual",
     "description": null
    },
    "company": {
     "id": "65fd7506e2354158650c7c32",
     "name": "distributor"
    },
    "owner": {
     "id": "65fd5d5aee5bd304a40d429e",
     "userName": "[email protected]"
    },
    "created": "2024-04-08T11:27:31",
    "details": {
     "remoteAddress": {
      "any": true,
      "portRange": "300-400"
     },
     "localAddress": {
      "any": false,
      "ipMask": "10.10.10.10/32",
      "portRange": "300-400"
     },
     "directlyConnected": {
      "enable": true,
      "remoteMac": "AA:AA:AA:AA:AA:AA;CC:CC:CC:CC:CC:CC;BB:BB:BB:BB:BB:BB"
     },
     "protocol": "any",
     "hash": null,
     "path": null,
     "commandLine": "format C:\\",
     "ipVersion": "any",
     "direction": "both",
     "ruleName": "rule 1#"
    }
   },
   {
    "_id": "6613aa73a0946f3422083d6e",
    "type": "connection",
    "source": {
     "type": "manual",
     "description": null
    },
    "company": {
     "id": "65fd7506e2354158650c7c32",
     "name": "distributor"
    },
    "owner": {
     "id": "65fd5d5aee5bd304a40d429e",
     "userName": "[email protected]"
    },
    "created": "2024-04-08T11:27:31",
    "details": {
     "remoteAddress": {
      "any": false,
      "ipMask": "10.10.10.12/32",
      "portRange": "300-400"
     },
     "localAddress": {
      "any": true,
      "portRange": "300-400"
     },
     "directlyConnected": {
      "enable": true,
      "remoteMac": "AA:AA:AA:AA:AA:AA;CC:CC:CC:CC:CC:CC;BB:BB:BB:BB:BB:BB"
     },
     "protocol": "ICMP",
     "hash": "13f6331c638b68d4e7eab6ea60da5473",
     "path": "C:\\test.exe",
     "commandLine": "format C:\\",
     "ipVersion": "IPV4",
     "direction": "inbound",
     "ruleName": "rule 1#"
    }
   }
  ]
 }
}

A response for type = path:

{
  "params":  {
    "companyId":  "65fd7506e2354158650c7c32",
    "type":  'path',
    "rules":  [
      {
        'note':  'test',
        'details':  {
          'path': "C:\\aaa.exe"
        }
      },
      {
        'note':  'test',
        'details':  {
          'path':  "C:\\test.exe"
        }
      },
    ],
    "recursive":  true
  },
  "jsonrpc":  "2.0",
  "method":  "addToBlocklist",
  "id":  "5087eab8-b74f-4a3e-85b3-4271e85890d5"
}

Version 1.0

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
       }
  }
In this section: