Create Sensor Tags
Endpoint URL: https://<your server>/rest/tagging/process_tags
Endpoint URI: tagging/process_tags
Action: POST
Creates tags for a specific sensor or group of sensors. This creates a tag that does not already exist.
This request is available from versions 18.0 and later.
You must be assigned the System Admin role and Sensor Admin L1 role (if your Cybereason environment uses sensor grouping) to send requests to this endpoint URL.
Note
Ensure that you have logged into the Cybereason platform. For details, see Log in with the API.
Request Headers
You must add an Content-Type:application/json header with the request.
Note
If you are using cURL, add the authorization cookie details or the path to the file with cookie details with every request.
Request Body
Input: JSON
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
{
"entities": {
"<machine identifier>": {
"tags": {
"<tag type>": {
"value": "<value>",
"operation": "SET"
}
},
"entityType": "MACHINE"
}
}
}
Request Parameters
URL/URI parameters: none
Request Body Parameters: You must provide each of the following required parameters:
Field |
Type |
Description |
|---|---|---|
“machine FQDN” |
Float |
The fully qualified domain name of the machine, or the machine name on which the sensor is located. |
“tag type” |
String |
The name of the tag to add. Possible values for the tag include:
|
value |
String |
The value for the select tag type.
|
operation |
String |
The operation to perform for the tag. Possible values include:
|
entityType |
String |
The type of item to which the tag is being applied. Enter MACHINE for this parameter. |
Note
The parameters used in this request are the same as the requests to update or delete sensor tags.
Response Status Codes
This request can return the following status codes:
200: Success OK or an error message saying why
400: Error with description for incorrect domain name for a sensor or missing tag name
403: Forbidden - permissions are not correct for the current user
422: Unprocessible entity - the format is correct but the content is not present
Response Success Schema
The response contains the following fields:
Field |
Type |
Description |
|---|---|---|
<machine name> |
String |
The FQDN or machine name of the sensor machine specified in the request |
results |
Array |
A collection of the changes for this operation |
<tag name> |
String |
The exact tag name updated. Possible values for the tag include:
|
oldValue |
String or Boolean (for Critical Asset tags) |
The previous value for the tag. When creating tags, this value is empty. |
newValue |
String or Boolean (for Critical Asset tags) |
The new value for the tag. |
operation |
String |
The operation performed on the tag. For creating and updating tags, this value is SET. For deleting tags, this value is REMOVE. |
success |
Boolean |
Indicates whether the operation succeeded or not. |
failReason |
String |
The reason the create, update, or delete operation failed. |
entityType |
String |
The type of item to which the tag was applied. Returns MACHINE. |
Response Failure Schema
A 200 error code with an error message describing the error.
Important Response Fields
Important information is found in these fields:
results object: This object contains the results of the sensor tag creation. Each machine to which you applied tags has this object. Ensure that the tags you updated are included in this object.
oldValue: The previous value for the sensor tag.
newValue: The update value for the sensor tag.
success: A boolean value indicating whether the update of the sensor tag succeeded. If the tag updates successfully, this value is true.
failReason: The reason the sensor tag update did not succeed.
Example: Create sensor tags
Request
curl --request POST \
--url https://12.34.56.78/rest/tagging/process_tags \
--header 'Content-Type:application/json' \
--data '{
"entities": {
"mock_4geNz66cpecC1eF2J": {
"tags": {
"DEPARTMENT": {
"value":"HR",
"operation":"SET"
},
"LOCATION": {
"value":"USA",
"operation":"SET"
},
"DEVICE TYPE": {
"value":"Windows",
"operation":"SET"
},
"CRITICAL ASSET": {
"value":"true",
"operation":"SET"
}
},
"entityType":"MACHINE"
}
}
}'
Response
{
"entities": {
"mock_4geNz66cpecC1eF2J": {
"results": {
"Department": {
"oldValue": "",
"newValue": "Docs",
"operation": "SET",
"success": true,
"failReason": ""
},
"Device-Type": {
"oldValue": "",
"newValue": "Mac",
"operation": "SET",
"success": true,
"failReason": ""
},
"Critical-Asset": {
"oldValue": "",
"newValue": "false",
"operation": "SET",
"success": true,
"failReason": ""
},
"Location": {
"oldValue": "",
"newValue": "USA",
"operation": "SET",
"success": true,
"failReason": ""
}
},
"entityType": "MACHINE"
}
}
}
Request
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
Use this request body:
{
"entities": {
"mock_4geNz66cpecC1eF2J": {
"tags": {
"DEPARTMENT": {
"value": "HR",
"operation": "SET"
},
"LOCATION": {
"value": "USA",
"operation": "SET"
},
"DEVICE TYPE": {
"value": "Windows",
"operation": "SET"
},
"CRITICAL ASSET": {
"value": "true",
"operation": "SET"
}
},
"entityType": "MACHINE"
}
}
}
Response
{ "entities": { "mock_4geNz66cpecC1eF2J": { "results": { "Department": { "oldValue": "", "newValue": "Docs", "operation": "SET", "success": true, "failReason": "" }, "Device-Type": { "oldValue": "", "newValue": "Mac", "operation": "SET", "success": true, "failReason": "" }, "Critical-Asset": { "oldValue": "", "newValue": "false", "operation": "SET", "success": true, "failReason": "" }, "Location": { "oldValue": "", "newValue": "USA", "operation": "SET", "success": true, "failReason": "" } }, "entityType": "MACHINE" } } }
Request
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
import requests
import json
# Login information
username = "[email protected]"
password = "mypassword"
server = "yourserver.com"
port = "443"
data = {
"username": username,
"password": password
}
headers = {"Content-Type": "application/json"}
base_url = "https://" + server + ":" + port
login_url = base_url + "/login.html"
session = requests.session()
login_response = session.post(login_url, data=data, verify=True)
print (login_response.status_code)
print (session.cookies.items())
# Request URL
endpoint_url = "/rest/tagging/process_tags"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
machine_name = "mock_4geNz66cpecC1eF2J"
department_tag = "Docs"
location_tag = "USA"
device_type_tag = "Mac"
critical_asset_tag = "false"
tags = json.dumps({"entities":{machine_name:{"tags":{"DEPARTMENT":{"value":department_tag,"operation":"SET"},"LOCATION":{"value":location_tag,"operation":"SET"},"DEVICE TYPE":{"value":device_type_tag,"operation":"SET"},"CRITICAL ASSET":{"value":critical_asset_tag,"operation":"SET"}},"entityType":"MACHINE"}}})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=tags, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
{ "entities": { "mock_4geNz66cpecC1eF2J": { "results": { "Department": { "oldValue": "", "newValue": "Docs", "operation": "SET", "success": true, "failReason": "" }, "Device-Type": { "oldValue": "", "newValue": "Mac", "operation": "SET", "success": true, "failReason": "" }, "Critical-Asset": { "oldValue": "", "newValue": "false", "operation": "SET", "success": true, "failReason": "" }, "Location": { "oldValue": "", "newValue": "USA", "operation": "SET", "success": true, "failReason": "" } }, "entityType": "MACHINE" } } }
Example: Create sensor tags for multiple sensors
Request
curl --request POST \
--url https://12.34.56.78/rest/tagging/process_tags \
--header 'Content-Type:application/json'
--data '{
"entities": {
"mock_4geNz66cpecC1eF2J": {
"tags": {
"DEPARTMENT": {
"value":"HR",
"operation":"SET"
},
"LOCATION": {
"value":"USA",
"operation":"SET"
},
"DEVICE TYPE": {
"value":"Windows",
"operation":"SET"
},
"CRITICAL ASSET": {
"value":"true",
"operation":"SET"
}
},
"entityType":"MACHINE"
},
"mock_4heNz77cpecC1eF7J": {
"tags": {
"DEPARTMENT": {
"value": "HR",
"operation": "SET"
},
"LOCATION": {
"value": "USA",
"operation": "SET"
},
"DEVICE TYPE": {
"value": "Windows",
"operation": "SET"
},
"CRITICAL ASSET": {
"value": "true",
"operation": "SET"
}
},
"entityType": "MACHINE"
}
}
}'
Response
{
"entities": {
"mock_4geNz66cpecC1eF2J": {
"results": {
"Department": {
"oldValue": "",
"newValue": "Docs",
"operation": "SET",
"success": true,
"failReason": ""
},
"Device-Type": {
"oldValue": "",
"newValue": "Mac",
"operation": "SET",
"success": true,
"failReason": ""
},
"Critical-Asset": {
"oldValue": "",
"newValue": "false",
"operation": "SET",
"success": true,
"failReason": ""
},
"Location": {
"oldValue": "",
"newValue": "USA",
"operation": "SET",
"success": true,
"failReason": ""
}
},
"entityType": "MACHINE"
}
}
}
Request
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
Use this request body:
{
"entities": {
"mock_4geNz66cpecC1eF2J": {
"tags": {
"DEPARTMENT": {
"value": "HR",
"operation": "SET"
},
"LOCATION": {
"value": "USA",
"operation": "SET"
},
"DEVICE TYPE": {
"value": "Windows",
"operation": "SET"
},
"CRITICAL ASSET": {
"value": "true",
"operation": "SET"
}
},
"entityType": "MACHINE"
},
"mock_4heNz77cpecC1eF7J": {
"tags": {
"DEPARTMENT": {
"value": "HR",
"operation": "SET"
},
"LOCATION": {
"value": "USA",
"operation": "SET"
},
"DEVICE TYPE": {
"value": "Windows",
"operation": "SET"
},
"CRITICAL ASSET": {
"value": "true",
"operation": "SET"
}
},
"entityType": "MACHINE"
}
}
}
Response
{ "entities": { "mock_4geNz66cpecC1eF2J": { "results": { "Department": { "oldValue": "", "newValue": "Docs", "operation": "SET", "success": true, "failReason": "" }, "Device-Type": { "oldValue": "", "newValue": "Mac", "operation": "SET", "success": true, "failReason": "" }, "Critical-Asset": { "oldValue": "", "newValue": "false", "operation": "SET", "success": true, "failReason": "" }, "Location": { "oldValue": "", "newValue": "USA", "operation": "SET", "success": true, "failReason": "" } }, "entityType": "MACHINE" }, "mock_4heNz77cpecC1eF7J": { "results": { "Department": { "oldValue": "", "newValue": "Docs", "operation": "SET", "success": true, "failReason": "" }, "Device-Type": { "oldValue": "", "newValue": "Mac", "operation": "SET", "success": true, "failReason": "" }, "Critical-Asset": { "oldValue": "", "newValue": "false", "operation": "SET", "success": true, "failReason": "" }, "Location": { "oldValue": "", "newValue": "USA", "operation": "SET", "success": true, "failReason": "" } }, "entityType": "MACHINE" } } }
Request
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
import requests
import json
# Login information
username = "[email protected]"
password = "mypassword"
server = "yourserver.com"
port = "443"
data = {
"username": username,
"password": password
}
headers = {"Content-Type": "application/json"}
base_url = "https://" + server + ":" + port
login_url = base_url + "/login.html"
session = requests.session()
login_response = session.post(login_url, data=data, verify=True)
print (login_response.status_code)
print (session.cookies.items())
# Request URL
endpoint_url = "/rest/tagging/process_tags"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
machine_name = "mock_4geNz66cpecC1eF2J"
department_tag = "Docs"
location_tag = "USA"
device_type_tag = "Mac"
critical_asset_tag = "false"
tags = json.dumps({"entities":{machine_name:{"tags":{"DEPARTMENT":{"value":department_tag,"operation":"SET"},"LOCATION":{"value":location_tag,"operation":"SET"},"DEVICE TYPE":{"value":device_type_tag,"operation":"SET"},"CRITICAL ASSET":{"value":critical_asset_tag,"operation":"SET"}},"entityType":"MACHINE"}}})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=tags, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
{ "entities": { "mock_4geNz66cpecC1eF2J": { "results": { "Department": { "oldValue": "", "newValue": "Docs", "operation": "SET", "success": true, "failReason": "" }, "Device-Type": { "oldValue": "", "newValue": "Mac", "operation": "SET", "success": true, "failReason": "" }, "Critical-Asset": { "oldValue": "", "newValue": "false", "operation": "SET", "success": true, "failReason": "" }, "Location": { "oldValue": "", "newValue": "USA", "operation": "SET", "success": true, "failReason": "" } }, "entityType": "MACHINE" }, "mock_4heNz77cpecC1eF7J": { "results": { "Department": { "oldValue": "", "newValue": "Docs", "operation": "SET", "success": true, "failReason": "" }, "Device-Type": { "oldValue": "", "newValue": "Mac", "operation": "SET", "success": true, "failReason": "" }, "Critical-Asset": { "oldValue": "", "newValue": "false", "operation": "SET", "success": true, "failReason": "" }, "Location": { "oldValue": "", "newValue": "USA", "operation": "SET", "success": true, "failReason": "" } }, "entityType": "MACHINE" } } }