Archive Sensor
Endpoint URL: https://<your server>/rest/sensors/action/archive
Endpoint URI: sensors/action/archive
Action: POST
Archives the selected sensor or group of sensors.
A sensor must be offline or stale to archive the sensor.
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.
{
"sensorIds": [
"<sensorIDs>"
],
"argument": "<reason for archive>"
}
Request Parameters
URL/URI parameters: none
Request Body Parameters: You must provide the following REQUIRED parameters:
sensorIds: A string value. The unique pylum ID values for the sensor or sensors to archive.
argument: A string value. The reason for archiving the sensor or sensors.
Response Status Codes
This request can return the following status codes:
200: Success OK with a success or failure message.
204: Content Empty - the selected sensor is not available for archive
400: The arguments for the request are not valid
Response Success Schema
The response includes:
Field |
Type |
Description |
---|---|---|
batchID |
Integer |
The ID for the operation. You may need this number for other operations with the API. |
actionType |
Enum |
The action taken on the sensor. Possible values include:
|
actionArguments |
String |
The arguments passed for the operation. |
globalStats |
Array |
Collection of items about the operation. For details about this object, see globalStatsObject. |
finalState |
Boolean |
Indicates whether the sensor is in the state indicated by the operation. |
totalNumberOfProbes |
Integer |
How many sensors were affected by the current operation |
initiatorUser |
String |
The user name of the user who performed this operation. |
startTime |
Timestamp |
The start time of the operation. |
aborterUser |
String |
The user name of the user who aborted the operation. This field only exists if the operation was aborted. |
abortTime |
Timestamp |
The time (in epoch) when the operation was aborted. This field only exists if the operation was aborted. |
abortTimeout |
Boolean |
Indicates whether there is a timeout value for timing out the request to abort. |
abortHttpStatusCode |
String |
The code sent by the server to abort the operation. This field only exists if the operation was aborted. |
Response Failure Schema
A 400 error with details on the invalid arguments
Important Response Fields
Important information is found in these fields:
batchID: The operation identifier for the sensor operation.
actionType: The type of sensor operation. For this request to archive a sensor, this should report Archive.
stats object: This object contains details on the final result of the operation for the sensors included in the batch. View the different fields available in this object and the number of sensors to which this status applied.
totalNumberOfProbes:* The total number of sensors to which this operation applied.
Example: Archive a sensor
Request
curl --request POST \
--url https://12.34.56.78/rest/sensors/action/archive \
--header 'Content-Type:application/json' \
--data '{"sensorsIds": ["58ae74fae4b06dca39c1d4bc:PYLUMCLIENT_ORG1-PROD_WINTEST-PC_005056A104F9"],"argument": "Needed again"}'
Response
{
"batchId": 605064018,
"actionType": "Archive",
"actionArguments": null,
"globalStats": {
"stats": {
"FailedSending": 0,
"InvalidState": 0,
"ProbeRemoved": 0,
"TimeoutSending": 0,
"Pending": 0,
"ChunksRequired": 0,
"MsiFileCorrupted": 0,
"SendingMsi": 0,
"NewerInstalled": 0,
"MsiSendFail": 0,
"partialResponse": 0,
"EndedWithSensorTimeout": 0,
"FailedSendingToServer": 0,
"GettingChunks": 0,
"Aborted": 0,
"Started": 0,
"InProgress": 0,
"Disconnected": 0,
"Failed": 0,
"Timeout": 0,
"EndedWithTooManyResults": 0,
"AlreadyUpdated": 0,
"EndedWithTooManySearches": 0,
"Succeeded": 0,
"NotSupported": 0,
"EndedWithUnknownError": 0,
"None": 1,
"Primed": 0,
"EndedWithInvalidParam": 0,
"UnknownProbe": 0,
"AbortTimeout": 0,
"UnauthorizedUser": 0
}
},
"finalState": false,
"totalNumberOfProbes": 1,
"initiatorUser": "[email protected]",
"startTime": 1523875125179,
"aborterUser": null,
"abortTime": 0,
"abortTimeout": false,
"abortHttpStatusCode": null
}
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:
{
"sensorsIds": [
"5a1ab4fee4b01de92dfb1324:PYLUMCLIENT_INTERNAL_WIN_XP_0050568A4A6A",
"5a128362730e099c0c989ff8:PYLUMCLIENT_INTERNAL_WIN7_9402796814482809200"
],
"argument": "Sensors are no longer used"
}
Response
{
"batchId": 605064018,
"actionType": "Archive",
"actionArguments": null,
"globalStats": {
"stats": {
"FailedSending": 0,
"InvalidState": 0,
"ProbeRemoved": 0,
"TimeoutSending": 0,
"Pending": 0,
"ChunksRequired": 0,
"MsiFileCorrupted": 0,
"SendingMsi": 0,
"NewerInstalled": 0,
"MsiSendFail": 0,
"partialResponse": 0,
"EndedWithSensorTimeout": 0,
"FailedSendingToServer": 0,
"GettingChunks": 0,
"Aborted": 0,
"Started": 0,
"InProgress": 0,
"Disconnected": 0,
"Failed": 0,
"Timeout": 0,
"EndedWithTooManyResults": 0,
"AlreadyUpdated": 0,
"EndedWithTooManySearches": 0,
"Succeeded": 0,
"NotSupported": 0,
"EndedWithUnknownError": 0,
"None": 1,
"Primed": 0,
"EndedWithInvalidParam": 0,
"UnknownProbe": 0,
"AbortTimeout": 0,
"UnauthorizedUser": 0
}
},
"finalState": false,
"totalNumberOfProbes": 1,
"initiatorUser": "[email protected]",
"startTime": 1523875125179,
"aborterUser": null,
"abortTime": 0,
"abortTimeout": false,
"abortHttpStatusCode": null
}
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/sensors/action/archive"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
sensor_id = "58ae74fae4b06dca39c1d4bc:PYLUMCLIENT_INTERNAL_CYBERSETUP7X64_005056A13A24"
archive_reason = "Sensors are no longer needed"
query = json.dumps({"sensorsIds":[sensor_id],"argument":archive_reason})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=query, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
{ "batchId": 605064018, "actionType": "Archive", "actionArguments": null, "globalStats": { "stats": { "FailedSending": 0, "InvalidState": 0, "ProbeRemoved": 0, "TimeoutSending": 0, "Pending": 0, "ChunksRequired": 0, "MsiFileCorrupted": 0, "SendingMsi": 0, "NewerInstalled": 0, "MsiSendFail": 0, "partialResponse": 0, "EndedWithSensorTimeout": 0, "FailedSendingToServer": 0, "GettingChunks": 0, "Aborted": 0, "Started": 0, "InProgress": 0, "Disconnected": 0, "Failed": 0, "Timeout": 0, "EndedWithTooManyResults": 0, "AlreadyUpdated": 0, "EndedWithTooManySearches": 0, "Succeeded": 0, "NotSupported": 0, "EndedWithUnknownError": 0, "None": 1, "Primed": 0, "EndedWithInvalidParam": 0, "UnknownProbe": 0, "AbortTimeout": 0, "UnauthorizedUser": 0 } }, "finalState": false, "totalNumberOfProbes": 1, "initiatorUser": "[email protected]", "startTime": 1523875125179, "aborterUser": null, "abortTime": 0, "abortTimeout": false, "abortHttpStatusCode": null }