Add Sensor Tags to a Machine Associated with a Malop

If certain machines are frequent targets of attackers, or certain types of machines seem more vulnerable to attack, you can add sensor tags to these machines to help your system admins easily identify and apply specific protection settings to these machines.

You can use the API to automatically add the tags to a machine after at least one Malop occurs on the machine. This topic provides a step by step example of how to extract this information from a Malop and add sensor tags to that machine.

Step 1: Build the request to retrieve Malops

To build this request, you need the following keys:

• requestedType: This key is the Element on which the Cybereason platform generates the Malop. You can set the value to MalopProcess or MalopLogonSession.

  Because the Cybereason platform generates Malops based on MalopProcess and MalopLogonSession Element, you must run separate requests for each Element to retrieve all Malops.

• totalResultLimit: This key is the total number of results. This example uses the default value.

• perGroupLimit: This key is the total number per group. This example uses the default value.

• perFeatureLimit: This key is the total number for the selected Feature. This example uses the default value.

Note

Although version 20.1 and later include a new endpoint to retrieve Malop details (/rest/detection/inbox), you can still use the endpoint (/rest/crimes/unified) in the example below on these versions.

To build the request, replace the placeholders in the relevant cURL command, request body example, or Python script:

CURLREST API ClientPython

curl --request POST \
        --url http://myserver.com/rest/crimes/unified \
        --header 'Content-Type:application/json' \
        --data '{
                                        "totalResultLimit": 10000,
                                        "perGroupLimit": 10000,
                                        "perFeatureLimit": 100,
                                        "templateContext": "OVERVIEW",
                                        "queryPath": [
                                                      {
                                                        "requestedType": "MalopProcess",
                                                        "result": true,
                                                        "filters": null
                                                      }
                                                     ]
                                     }'

Step 2: Run the 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 3: Evaluate the response

When the Cybereason API returns a response for a Malop retrieval request, the data in the response contains many different pieces of data.

However, to add a sensor tag to a machine, you only need to locate the following fields.

Note

The example Python scripts in this topic contain the code to automatically find these values and print them in an easily visible way, so that you do not have to read each line in the response.

• The unique Malop ID. The Malop ID normally begins with 11 and are found throughout the response.

  To find the Malop ID, in the request body, locate the data object, and then locate the resultIdToElementDataMap object. The key that immediately follows these object fields is the Malop ID:

  

• The machine name. Inside the Malop object (which begins with the Malop ID that you found), locate the affectedMachines object and the name key inside this object. This is the machine name for the machine associated with the Malop.

  

Step 4: Build the request to add sensor tags

When you add sensor tags, you will need to add values for a number of keys:

• The machine name. You add sensor tags per machine. To add sensor tags correctly, you must specify the machine name.

• Predefined sensor tag values. The Cybereason platform contains a number of predefined tags, including:

  • Department

  • Location

  • Device type

  • Critical Asset.

  You can add any string value you want for the Department, Location, and Device type tags.

  The Critical Asset tag is a boolean value and therefore requires a True or False value.

• Custom sensor tags. You can also add a tag labeled CUSTOM. Set the value to any string value you need.

To build a request to add a sensor tag, replace the placeholders in the following cURL command, request body example, or Python script with the values that you want:

CURLREST API ClientPython

curl --request POST \
        --url http://myserver.com/rest/tagging/process_tags \
        --header 'Content-Type:application/json' \
        --data '{
                                              "entities": {
                                                "<machine name>": {
                                                  "tags": {
                                                    "DEPARTMENT": {
                                                      "value": "<your value>",
                                                      "operation": "SET"
                                                    },
                                                    "LOCATION": {
                                                      "value": "<your value>",
                                                      "operation": "SET"
                                                    },
                                                    "DEVICE TYPE": {
                                                      "value": "<your value>",
                                                      "operation": "SET"
                                                    },
                                                    "CRITICAL ASSET": {
                                                      "value": "<your value>",
                                                      "operation": "SET"
                                                    },
                                                    "CUSTOM": {
                                                      "value": "<your value>",
                                                      "operation": "SET"
                                                    }
                                                  },
                                                  "entityType": "MACHINE"
                                                }
                                              }
                                            }'

Step 5: Run the request and generate the request body

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 6: Evaluate the response

The response for this request includes several items. The majority of these items repeat the values you entered for the tag in the request.

To verify that the request to add sensor tags to a machine was successful, view the results object and ensure the success field reports true.