Update Item Reputations

Companies and researchers discover new malicious items (such as processes, files, and the like), and update existing threat intel sources on an ongoing basis. In addition, every company also learns more about potentially malicious or benign items in their environments based on their own analysis of incidents. Therefore, you must continually update the reputation information on your Cybereason platform to ensure your reputation list meets your needs and your threat intelligence knowledge.

This topic provides a step by step example of how you can use the API to update reputations based on information you learn from threat intelligence or your own analysis.

Step 1: Plan your updates

Before you start assembling your request, ask the following:

• What are the item keys (file hash, IP address, or domain name) to update?

• What is the reputation status you want to set - are you adding the files to the blacklist or whitelist?

• Do you want to prevent these items from running on machines in your organization?

Answering these questions will enable you to construct the request correctly.

Step 2: Build your request parameters

For the purposes of this example, we will add the following file hash, IP address, and domain to the blacklist:

• File hash: e1112174b6dcc6bed54e0e34d8at272715e73d74

• IP address: 12.34.56.78

• Domain name: example.com

To construct the request, you must provide values for the following parameters:

• keys: An array that contains the values to update, separated by commas. In this example, this is the file hash value, IP address, and domain name. We will add all three together as the value for this parameter. For example, your keys array might resemble the following array.

  “keys”: [“e1112174b6dcc6bed54e0e34d8at272715e73d74”,”12.34.56.78”,”example.com”]

• maliciousType: An enum value that instructs the platform whether to add the item to the blacklist or whitelist. The value for this parameter can be either whitelist or blacklist.

• prevent: An optional parameter that instructs the platform whether to use Application Control to prevent a file from running on a machine. This parameter is not used for IP address or Domain name items. Possible values are true and false.

• remove: A boolean value that specifies whether to update the existing reputation or create a new one in parallel. A value of true updates the existing reputation. A value of false creates a new reputation in parallel.

Step 3: Build the API request

Use the relevant cURL commmand, request body example, or Python script. In this example, we are using a stand-in address for a Cybereason server (myserver.com). If you use this request, replace this address with your actual server address.

All Python examples are formatted for Python version 3.0 and higher, up to the latest Python version. If you are using versions of Python earlier than 3.0, ensure you manually remove parentheses for the print statements in this sample. For example, the print (response.content) statement updates to print response.content.

CURLRESTPython

curl --request POST \
        --url http://myserver.com/rest/classification/update \
        --header 'Content-Type:application/json' \
        --data '{
                    [
                        {
                            "keys": [
                                        "e1112174b6dcc6bed54e0e34d8at272715e73d74",
                                        "12.34.56.78",
                                        "example.com"
                                    ],
                            "maliciousType": "blacklist",
                            "prevent": "true",
                            "remove": "true"
                        }
                    ]
                }'

View the examples above the required parameters for the request, including the file hash, IP address, and domain name to block. In addition, you can see the other parameters, including the reputation to set, the Application Control status, and whether to overwrite the existing reputation.

Step 4: Run your request and generate the response

In the command line, REST API client, or IDE, run the command or script that contains the request. After a few seconds, the Cybereason API returns a response.

Step 5: Examine the response

Unlike some other API requests, the Cybereason API does not return data with the response, that specifies whether the update was successful.

To determine if the update was successful, locate the outcome field. If the field contains success, the update was successful. If the field contains operation failed, try your API request again.