Manage Sensor Groups
In this tutorial, we will explain, step-by-step, how to use the API to create and manage sensor groups and assign sensors to these groups.
In this tutorial, we will use a scenario where you create different groups for geographic regions in your organization.
You must have the System Admin and Sensor Admin L1 role for assigned groups added for your Cybereason user to perform these commands.
When managing your organization’s sensors, you may want to automate the process of sensor group creation to expedite their creation. You can use the API to manage sensor group creation.
In this topic:
Create the request to add a sensor group
Note
The request body is the same regardless of how you run the request (such as a cURL command, in a REST API client, or Python script).
Ensure you log in to the Cybereason platform with the API. For details, see Log in with the API.
In your REST API client, open a new tab/file.
In the relevant field, enter the URL for the request:
https://<your server address>/rest/groups
For example, in Postman, you enter the URL here:
Ensure that the method for the request is set to POST. (This may be the default for your REST API client, but if not, ensure that you select it.)
For the Headers, in the Key column, add a Content-Type header.
In the Value columnm, add the value application/json.
For example, in Postman, your header will look like this:
Navigate to the section to add your request body. In Postman, for example, this is the Body tab.
In the Body tab, ensure that you have set your client editor to add raw JSON content. In Postman, for example, ensure that Raw is selected.
In the request body edit area, enter an open and closed bracket {}. This is the standard syntax for JSON.
You are now ready to add the objects and key/value pairs that build the request body.
Inside the brackets, add this template request body:
{ "name":"<your group name>", "description":"<your description for the group>", "groupAssignRule":{ "ruleType":"<rule criteria>", "ruleOperator":"<operator>", "ruleValues":["value"] }, "policyId":"<policy ID>" }
You will fill in this request part by part in the next section.
In the request body, for the name key, for the your group name placeholder value, enter USA.
{ "name":"**USA**", "description":"<your description for the group>", "groupAssignRule":{ "ruleType":"<rule criteria>", "ruleOperator":"<operator>", "ruleValues":["value"] }, "policyId":"<policy ID>" }
For the description key, for the your description for the group placeholder value, enter group for machines in USA.
{ "name":"USA", "description":"**group for machines in USA**", "groupAssignRule":{ "ruleType":"<rule criteria>", "ruleOperator":"<operator>", "ruleValues":["value"] }, "policyId":"<policy ID>" }
Leave the groupAssignRule object and policyId key with the template values. You will work with these objects and keys in the next section.
Update the request to add automatic assignment criteria for a group
In addition, as part of the group creation, you can specify criteria by which the Cybereason platform will automatically assign sensors to groups. Then, as a result, after creating sensor groups, you do not need to manually add sensors to groups.
For the rule assignment criteria, you have a number of different choices to use to determine how the sensor should be assigned to a group, including organizationalUnit, machineName, internalIpAddress, or externalIpAddress. In this example, we are going to use the Organizational Unit (organizationalUNit) identifier for the assignment criteria.
In the request body, in the groupAssignRule object, in the ruleType key, for the rule criteria placeholder value, update the value to organizationalUnit.
{ "name":"USA", "Description":"group for machines in USA", "groupAssignRule":{ "ruleType":"**organizationalUnit**", "ruleOperator":"<operator>", "ruleValues":["value"] }, "policyId":"<policy ID>" }
For each assignment criteria in the ruleType key, you must add a corresponding operator for the criteria type. Because the organizationalUnit is a string value, you should choose a string operator.
Below the ruleType key, for the ruleOperator key, for the operator placeholder value, enter ContainsIgnoreCase.
{ "name":"USA", "Description":"group for machines in USA", "groupAssignRule":{ "ruleType":"organizationalUnit", "ruleOperator":"**ContainsIgnoreCase**", "ruleValues":["value"] }, "policyId":"<policy ID>" }
Finally, you must add a value by which to filter. You can provide any string value for the organizationalUnit criteria.
In the ruleValues key array, for the value placeholder, enter USA.
{ "name":"USA", "Description":"group for machines in USA", "groupAssignRule":{ "ruleType":"organizationalUnit", "ruleOperator":"ContainsIgnoreCase", "ruleValues":["**USA**"] }, "policyId":"<policy ID>" }
In addition to automate assignment criteria, you can also specify a sensor policy to assign to all sensors assigned to a group. To do this, you must add the unique identifier used by the Cybereason platform for a policy in the request body.
For the policyId key, for the policy ID placeholder value, update the value to c75adb73-22b9-43a5-8362-92270c61770f.
{ "name":"USA", "Description":"group for machines in USA", "groupAssignRule":{ "ruleType":"organizationalUnit", "ruleOperator":"ContainsIgnoreCase", "ruleValues":["value"] }, "policyId":"**c75adb73-22b9-43a5-8362-92270c61770f**" }
If you are using this tutorial to create groups in your production environment, you may need to update this value for a real policy ID.
In your client machine, run the request.
If your request is successful, the response will contain the unique group ID the Cybereason platform uses for the group.
{ "groupId":"f7249383-9bd2-4420-91aa-f0c8ff806a93" }
Assign a sensor to a group
After you have created a group, you are able to assign sensors to the group.
In your REST API client, open another new tab/file.
In the relevant field, enter the URL for the request:
https://<your server address>/rest/sensors/actions/addToGroup
Ensure that the method for the request is set to POST.
For the Headers, for the Key column, add a Content-Type header.
In the Value column, add the value application/json.
In the Body tab, ensure that you have set your client editor to enable you to add raw JSON content.
In the request body edit area, add this template request body:
{ "sensorsIds":["<sensor ID>"], "argument":"<group ID>" }
For this request, you specify the the individual sensors to add to the group. In the request body, for the sensorsIds key, for the placeholder sensor ID value, add 5ad31a2ce4b0e623bab9b9ae:PYLUMCLIENT_DEMO_DEMO1WIN7X64_005056AAA5F2 (a fictitious sensor ID).
{ "sensorsIds":["**5ad31a2ce4b0e623bab9b9ae:PYLUMCLIENT_DEMO_DEMO1WIN7X64_005056AAA5F2**"], "argument":"<group ID>" }
If you are using this tutorial to add a sensor to a group in your production environment, you may need to update this value for a real sensor ID.
You can add multiple sensors in the same request. Add a comma between each sensor ID value.
In addition, in the request body, you must specify the group to which to add the sensor. In the argument key, for the group ID placeholder value, update the value to 20000000-0000-0000-0000-000000000000 (a fictitious group ID).
{ "sensorsIds":["5ad31a2ce4b0e623bab9b9ae:PYLUMCLIENT_DEMO_DEMO1WIN7X64_005056AAA5F2"], "argument":"**20000000-0000-0000-0000-000000000000**" }
In your client machine, run your request.
The response, if successful, will contain details on the number of sensors:
{ "numberOfSensorsMatchedCriteria":1, "numberOfSensorsAssigned":1 }
Next steps
Now that you understand how to create a group and assign sensors, you can incorporate this into your sensor automation workflow.