Skip to main content

addToBlocklist

Use this method to set up one or more rules that you can use in adding items to blocklists.

Important

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

Version 1.0 is only compatible with 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 and has a license that includes access to the blocklist feature.

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

type

Indicates the type of rules you want to create.

Mandatory

String

Possible values:

  • hash

  • path

  • connection

rules

Contains the list of rules you want to create and their assigned settings.

Mandatory

Array of objects

You can only add rules that match the type specified in the type parameter.

Refer to rules.

recursive

Indicates if the rules will be applied recursively to all companies managed by the target company.

Default value: true

Optional

Boolean

No additional requirements.

Objects

rules

Parameter

Description

Included in request

Type

Values

note

Provide a description for this specific set of rules.

Optional

String

No additional requirements.

details

Identifies a specific rule and its settings.

Mandatory

Object

Refer to details.

details

Parameters available when type = hash:

Parameter

Description

Included in request

Type

Values

algorithm

The algorithm used to obtain the hash.

Mandatory

String

Possible values:

  • sha256

  • md5

hash

The hash associated to the file you want to block.

Mandatory

String

The hash value must conform to the format specified in the algorithm parameter.

Parameters available when type = connection:

Parameter

Description

Included in request

Type

Values

ruleName

The name under which the rule will be listed in the rules table (for example, the name of the application the rule applies to).

Mandatory

String

No additional requirements.

commandLine

If included, the rule applies only when an application is opened by using the Windows command line interface with the specified command.

Optional

String

No additional requirements.

protocol

If included, the rule applies only if a specific IP protocol is used by the connection.

Optional

String

Possible values:

  • any

  • TCP

  • UDP

  • etc.

You can find a full list of protocols here.

direction

If included, the rule applies only to connections of a specific direction.

Optional

String

Possible values:

  • inbound

  • outbound

  • both

ipVersion

If included, the rule applies only to connections to or from a specific IP type.

Optional

String

Possible values:

  • any

  • IPv4

  • IPv6

localAddress

If included, the rule applies only to connections to or from specific local network addresses.

Optional

Object

Refer to localAddress.

remoteAddress

If included, the rule applies only to connections to or from specific remote addresses.

Optional

Object

Refer to remoteAddress.

directlyConnected

If enabled, the rule applies only to connections to or from specific Mac addresses.

Optional

Object

Refer to directlyConnected.

Parameters available when type = path:

Parameter

Description

Included in request

Type

Values

path

All applications that are launched from the specified path are blocked.

Mandatory

String

No additional requirements.

localAddress

This object is only available if type = connection.

Parameter

Description

Included in request

Type

Values

any

If false, only connections originating from the addresses specified under the ipMask setting are blocked.

If true, all connections are blocked, regardless of IP address.

Mandatory

Boolean

No additional requirements.

ipMask

If any = false, only connections to or from the addresses specified under this setting are blocked.

Optional

String

The value can be in an IP or an IP/mask format.

portRange

If a range is used, only connections made through ports between these two values are blocked.

If specific ports are used, only connections made through ports are blocked.

Optional

String

No additional requirements.

remoteAddress

This object is only available if type = connection.

Parameter

Description

Included in request

Type

Values

any

If false, only connections originating from the addresses specified under the ipMask setting are blocked.

If true, all connections are blocked, regardless of IP address.

Mandatory

Boolean

No additional requirements.

ipMask

If any = false, only connections to or from the addresses specified under this setting are blocked.

Optional

String

The value can be in an IP or an IP/mask format.

portRange

If a range is used, only connections made through ports between these two values are blocked.

If specific ports are used, only connections made through ports are blocked.

Optional

String

No additional requirements.

directlyConnected

This object is only available if type = connection.

Parameter

Description

Included in request

Type

Values

any

Indicates if this option is enabled.

Mandatory

Boolean

No additional requirements.

remoteMac

Only connections from the specified Mac addresses are allowed.

Mandatory

String

Must be in a valid Mac address format.

Return value

Attribute

Type

Description

result

Boolean

Indicates if the operation was successful.

Error messages

Code

Message

Details

-32602

Invalid params

      "details": "Validation exception: The hash 1e0905327f443c54aa617e2ff323067c985428e5566886f2aa8296cddfe6ddf9d is not a valid string representation of the SHA256 hashing algorithm"
      "details": "Multiple errors encountered",
      "errors": [
        {
          "companyId": "65fd7506e2354158650c7c32",
          "companyName": "P1",
          "message": "Limit exceeded"
        },
        {
          "companyId": "65fd7506e2354158650c7c33",
          "companyName": "C1",
          "message": "Limit exceeded"
        }

Examples

Request

Request when type = hash:

{
  "params": {
    "companyId": "65fd7506e2354158650c7c32",
    "type": "hash",
    "rules": [
      {
        "note": "test",
        "details": {
          "algorithm": "sha256",
          "hash": "1e0905327f443c54aa617e2ff323067c985428e5566886f2aa8296cddfe6ddf9"
        }
      },
      {
        "details": {
          "algorithm": "md5",
          "hash": "13f6331c638b68d4e7eab6ea60da5473"
        }
      }
    ],
    "recursive": false
  },
  "jsonrpc": "2.0",
  "method": "addToBlocklist",
  "id": "5087eab8-b74f-4a3e-85b3-4271e85890d5"
}

Request when type = connection:

{
  "params":  {
    "companyId":  "65fd7506e2354158650c7c32",
    "type":  'connection',
    "rules":  [
      {
        'note':  'test',
        'details':  {
          'ruleName':  'rule  1#',
          'commandLine':  'format  C:\\',
          'protocol':  'any',
          'direction':  'both',
          'ipVersion':  'any',
          'localAddress':  {
            'any':  false,
            'ipMask':  '10.10.10.10/32',
            'portRange':  '300-400'
          },
          'remoteAddress':  {
            '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'
          },
        }
      },
      {
        'note':  'test',
        'details':  {
          'ruleName':  'rule  1#',
          'path':  'C:\\test.exe',
          'commandLine':  'format  C:\\',
          'hash':  '13f6331c638b68d4e7eab6ea60da5473',
          'protocol':  'ICMP',
          'direction':  'inbound',
          'ipVersion':  'IPV4',
          'localAddress':  {
            'any':  false,
	    'ipMask':  '10.10.10.12/32'
            'portRange':  '300-400'
          },
          'remoteAddress':  {
            'any':  false,
            'ipMask':  '10.10.10.12/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'
          },
          }
      },
    ],
    "recursive":  true
  },
  "jsonrpc":  "2.0",
  "method":  "addToBlocklist",
  "id":  "5087eab8-b74f-4a3e-85b3-4271e85890d5"
}

Request when 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"
}

Response

{
  "id": "5087eab8-b74f-4a3e-85b3-4271e85890d5",
  "jsonrpc": "2.0",
  "result": true
}

Version 1.0

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