Search for Files
When you find a potentially suspicion or known malicious file in your environment, you may want to find exactly what machines in your environment have this file. You can use the File Search APIs to help you find files on any machine in your environment with a Cybereason sensor installed.
Follow these steps to search for files:
Step 1: Define what you are searching for
Before you begin your search, make sure you understand what you want to search for:
What is the name of the file to find? Is it always a constant name or is there a wildcard pattern that can find similar ones?
Can you search for the file by one of its hashes
Is this file always found in a specific directory? (This is a tactic used by attackers who use specific directories as part of their attack.)
Do you suspect this file is located only on specific machines?
Depending on your answers, add different filters to the file search request to narrow the search.
Step 2: Build your API request
For the purposes of this example, we will look for a specific file name, ShadowCopy.exe in the C:/Temp folder.
When you build the API file search request, you have a number of available fields. This template below shows all possible filter fields:
{
"sensorsIds": ["<sensor ID>"],
"filters": [
{
"fieldName": "<filter parameter>",
"operator": "<operator>",
"values": "<value>"
}
],
"fileFilters": [
{
"fieldName": "<field>",
"values": [
"value1",
"value2"
]
"operator": "<operator>"
}
],
"yaraName": "<Yara file name>"
}
You can add filters for:
A specific Sensor
A charateristic of a machine, such as a specific operating system
A machine
A file name, file creation time, or file modification time
A file path
For more details on all the available options, see Perform a Live File Search Request.
In this example, we need to add the following parameters:
The fileFilters object. This object contains the parameters for the file name and the folder in which to search.
A fieldName parameter in the fileFilters object. The value of this parameter is set to fileName. The values object will contain the value ShadowCopy.exe as the filename for which we will search.
An additional fieldName parameter. The value of this parameter will be set to paths for the search folder. The values object for this parameter is set to C:Temp.
Add the information for these parameters and create the relevant cURL command, 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.
curl --request POST \
--url https://myserver.com/rest/sensors/action/fileSearch \
--header 'Content-Type: application/json' \
--data '{"filters":[],"fileFilters":[{"fieldName":"fileName","values":["ShadowCopy.exe"],"operator":"ContainsIgnoreCase"}, {"fieldName":"paths","values":["C:\Temp"],"operator":"ContainsIgnoreCase"}]}'
Use this request body:
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:
{
"filters":[],
"fileFilters": [
{
"fieldName":"fileName",
"values":["ShadowCopy.exe"],
"operator":"ContainsIgnoreCase"
},
{
"fieldName":"paths",
"values":["C:\Temp"],
"operator":"ContainsIgnoreCase"
}
]
}
Note
The code in this sample is repeated in the second sample below. You do not need to run the script now but it is used here to help you understand how you build the 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 json
import requests
username = "<user name>"
password = "<password>"
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_1 = "rest/sensors/action/fileSearch"
api_url_1 = base_url + endpoint_url_1
# These are the variables that represent different fields in the request.
file_name = "ShadowCopy.exe"
file_path = "C:\\Temp"
query = json.dumps({"filters":[],"fileFilters":[{"fieldName":"fileName","values":[file_name],"operator":"ContainsIgnoreCase"},{"fieldName":"paths","values":[file_path],"operator":"ContainsIgnoreCase"}]})
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))
Step 3: Run your request and evaluate 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 4: Find the batch number in the response
When you run the file search request, the Cybereason platform initiates a file search operation and performs the search on the relevant sensors. The file search request responds with a batch number with details about the file search operation.
Find this batch number in the batchId response parameter to use in the next step to retrieve the actual results.
Example Response
{
"batchId": -1312043715,
"actionType": "FileSearchStart",
"actionArguments": {
"@class": "com.cybereason.configuration.models.FileSearchParameters",
"filters": [
{
"fieldName": "fileName",
"values": [
"ShadowAttack.exe"
],
"operator": "Equals"
}
],
"maxAnswers": 20
},
"globalStats": {
"stats": {
"Pending": 0,
"partialResponse": 0,
"AbortTimeout": 0,
"EndedWithSensorTimeout": 0,
"UnauthorizedUser": 0,
"FailedSendingToServer": 0,
"GettingChunks": 0,
"NewerInstalled": 0,
"SendingMsi": 0,
"None": 52,
"MsiSendFail": 0,
"EndedWithInvalidParam": 0,
"Failed": 0,
"InProgress": 0,
"Disconnected": 0,
"Aborted": 0,
"FailedSending": 0,
"MsiFileCorrupted": 0,
"UnknownProbe": 0,
"NotSupported": 0,
"Primed": 0,
"ChunksRequired": 0,
"ProbeRemoved": 0,
"Started": 0,
"EndedWithTooManySearches": 0,
"TimeoutSending": 0,
"InvalidState": 0,
"Timeout": 0,
"EndedWithUnknownError": 0,
"AlreadyUpdated": 0,
"EndedWithTooManyResults": 0,
"Succeeded": 0
}
},
"finalState": false,
"totalNumberOfProbes": 52,
"initiatorUser": "[email protected]",
"startTime": 1524400763922,
"aborterUser": null,
"abortTime": 0,
"abortTimeout": false,
"abortHttpStatusCode": null
}
Step 5: Send the API request for the results
With the batch number for the file search request, retrieve the results with another API request.
Note
If you repeat a file search with the same criteria, you can start with this step instead of starting the file search request from the first step.
Add the information for these parameters and create the relevant cURL command, 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.
curl --request GET \
--url https://myserver.com/rest/sensors/action/fileSearch/-1312043715 \
--header 'Content-Type: application/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.
import json
import requests
username = "<user name>"
password = "<password>"
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 to start the file search operation
endpoint_url_1 = "rest/sensors/action/fileSearch"
api_url_1 = base_url + endpoint_url_1
# These are the variables that represent different fields in the first request.
file_name = "ShadowCopy.exe"
file_path = "C:\\Temp"
query = json.dumps({"filters":[],"fileFilters":[{"fieldName":"fileName","values":[file_name],"operator":"ContainsIgnoreCase"},{"fieldName":"paths","values":[file_path],"operator":"ContainsIgnoreCase"}]})
api_response_1 = session.request("POST", api_url, data=query, headers=headers)
your_response+1 = json.loads(api_response_1.content)
batch_id = your_response_1['batchId']
print (batch_id)
# Request URL to retrieve file search details
endpoint_url_2 = "rest/sensors/action/fileSearch/"
api_url_2 = base_url + endpoint_url_2 + str(batch_id)
# These are the variables that represent different fields in the second request.
api_response_2 = session.request("GET", api_url, headers=headers)
your_response_2 = json.loads(api_response_2.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Step 6: Run your request for the results
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 7: Evaluate the results in the response
The response for this second request contains both details on the file search request and the results of the file search:
The batchActionInfo object contains the details on the file search operation.
The data object contains the file search results.
Look at the fields in the data object to find where this file is located in your environment.
Example Response
{
"batchId": -1312043715,
"actionType": "FileSearchStart",
"actionArguments": {
"@class": "com.cybereason.configuration.models.FileSearchParameters",
"filters": [
{
"fieldName": "fileName",
"values": [
"ShadowAttack.exe"
],
"operator": "Equals"
}
],
"maxAnswers": 20
},
"globalStats": {
"stats": {
"Pending": 0,
"partialResponse": 0,
"AbortTimeout": 0,
"EndedWithSensorTimeout": 0,
"UnauthorizedUser": 0,
"FailedSendingToServer": 0,
"GettingChunks": 0,
"NewerInstalled": 0,
"SendingMsi": 0,
"None": 52,
"MsiSendFail": 0,
"EndedWithInvalidParam": 0,
"Failed": 0,
"InProgress": 0,
"Disconnected": 0,
"Aborted": 0,
"FailedSending": 0,
"MsiFileCorrupted": 0,
"UnknownProbe": 0,
"NotSupported": 0,
"Primed": 0,
"ChunksRequired": 0,
"ProbeRemoved": 0,
"Started": 0,
"EndedWithTooManySearches": 0,
"TimeoutSending": 0,
"InvalidState": 0,
"Timeout": 0,
"EndedWithUnknownError": 0,
"AlreadyUpdated": 0,
"EndedWithTooManyResults": 0,
"Succeeded": 0
}
},
"finalState": false,
"totalNumberOfProbes": 52,
"initiatorUser": "[email protected]",
"startTime": 1524400763922,
"aborterUser": null,
"abortTime": 0,
"abortTimeout": false,
"abortHttpStatusCode": null
}{
"batchActionInfo": {
"batchId":-1312043715,
"actionType":"FileSearchStart",
"filters":[
{
"fieldName":"fileName",
"values": ["ShadowAttack.exe"],
"operator":"Equals"
}
],
"globalStats": {
"stats": {
"Pending":0,
"partialResponse":0,
"AbortTimeout":0,
"EndedWithSensorTimeout":0,
"UnauthorizedUser":0,
"FailedSendingToServer":0,
"GettingChunks":0,
"NewerInstalled":0,
"SendingMsi":0,
"None":0,
"MsiSendFail":0,
"EndedWithInvalidParam":0,
"Failed":0,
"InProgress":0,
"Disconnected":0,
"Aborted":0,
"FailedSending":0,
"MsiFileCorrupted":0,
"UnknownProbe":0,
"NotSupported":0,
"Primed":43,
"ChunksRequired":0,
"ProbeRemoved":0,
"Started":0,
"EndedWithTooManySearches":0,
"TimeoutSending":0,
"InvalidState":0,
"Timeout":0,
"EndedWithUnknownError":0,
"AlreadyUpdated":0,
"EndedWithTooManyResults":0,
"Succeeded":9
}
},
"finalState":false,
"totalNumberOfProbes":52,
"initiatorUser":"[email protected]",
"startTime":1524400763922,
"aborterUser":null,
"abortTime":0,
"wasAborted":false,
"answersNumber":0
},
"data":[]
}