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 |
---|---|---|---|---|
| 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. |
| Indicates the type of rules you want to create. | Mandatory | String | Possible values:
|
| 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 Refer to |
| Indicates if the rules will be applied recursively to all companies managed by the target company. Default value: | Optional | Boolean | No additional requirements. |
Objects
rules
Parameter | Description | Included in request | Type | Values |
---|---|---|---|---|
| Provide a description for this specific set of rules. | Optional | String | No additional requirements. |
| Identifies a specific rule and its settings. | Mandatory | Object | Refer to |
details
Parameters available when type
= hash
:
Parameter | Description | Included in request | Type | Values |
---|---|---|---|---|
| The algorithm used to obtain the hash. | Mandatory | String | Possible values:
|
| The hash associated to the file you want to block. | Mandatory | String | The hash value must conform to the format specified in the |
Parameters available when type
= connection
:
Parameter | Description | Included in request | Type | Values |
---|---|---|---|---|
| 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. |
| 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. |
| If included, the rule applies only if a specific IP protocol is used by the connection. | Optional | String | Possible values:
You can find a full list of protocols here. |
| If included, the rule applies only to connections of a specific direction. | Optional | String | Possible values:
|
| If included, the rule applies only to connections to or from a specific IP type. | Optional | String | Possible values:
|
| If included, the rule applies only to connections to or from specific local network addresses. | Optional | Object | Refer to |
| If included, the rule applies only to connections to or from specific remote addresses. | Optional | Object | Refer to |
| If enabled, the rule applies only to connections to or from specific Mac addresses. | Optional | Object | Refer to |
Parameters available when type
= path
:
Parameter | Description | Included in request | Type | Values |
---|---|---|---|---|
| All applications that are launched from the specified path are blocked. | Mandatory | String | The path format must match the operating system of the target endpoint. |
localAddress
This object is only available if type
= connection
.
Parameter | Description | Included in request | Type | Values |
---|---|---|---|---|
| If If | Mandatory | Boolean | No additional requirements. |
| If | Optional | String | The value can be in an IP or an IP/mask format. |
| 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 |
---|---|---|---|---|
| If If | Mandatory | Boolean | No additional requirements. |
| If | Optional | String | The value can be in an IP or an IP/mask format. |
| 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 |
---|---|---|---|---|
| Indicates if this option is enabled. | Mandatory | Boolean | No additional requirements. |
| Only connections from the specified Mac addresses are allowed. | Mandatory | String | Must be in a valid Mac address format. |
Return value
Attribute | Type | Description |
---|---|---|
| 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 }
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 }