This driver provides functions to allow you to query a Cybereason instance.
Authentication for the Cybereason data provider is handled by specifying credentials directly in the connect call or specifying the credentials in MSTICPy config file.
For more information on how to create new user with approapriate roles and permissions, follow the product documentation: User Roles and Permissions and API Guide.
Once you created user account with the appropriate roles, you will require the following details to specify while connecting: - TenantId = "instance". As this is a cloud-based solution, each customer has its dedicated instance. FQDN will be formatted as: "<instance>.cybereason.net" - ClientId = "account" (account to connect to Cybereason instance) - ClientSecret = "yoursecret" (secret for the client specified in ClientId)
Once you have details, you can specify it in msticpyconfig.yaml
as shown in below example
Cybereason:
Args:
TenantId: instance
ClientId: account
ClientSecret: yoursecret
You can instantiate a data provider for Cybereason by specifying the credentials in connect or if left blank details from your MSTICPy config file will be used. If the details are correct and authentication is successful, it will show connected.
cybereason_prov = QueryProvider('Cybereason')
cybereason_prov.connect(TenantId=<instance>, ClientId=<id>, ClientSecret=<secret>)
connected
Upon connecting to the Cybereason data environment, we can take a look what query options available to us by running QUERY_PROVIDER.list_queries()
For more information, see data_acquisition/dataproviders:getting help for a query
.
This will display all the saved searches from the connected cybereason instance and also pre-built custom queries to do common operations such as list datatypes, list saved searches, alerts, audittrail informaion.
cybereason_prov.list_queries()
['Connection.list_connections_from_process', 'Host.find_hosts', 'Process.find_process_by_commandLine', 'Process.find_process_by_pid', 'Process.find_process_by_suspicions']
In order to get help for specific query , you can execute QUERY_PROVIDER.<QueryName>?
.
For more information, see Getting Help for a query <DataProviders:getting-help-for-a-query>
cybereason_prov.Connection.list_connections_from_process?
Query: list_connections_from_process Data source: Cybereason Search for process with a specific suspicion
- customFields: list (optional)
List of fields to output (default value is: ['elementDisplayName', 'direction', 'ownerMachine', 'ownerProcess', 'serverPort', 'serverAddress','portType', 'aggregatedReceivedBytesCount', 'aggregatedTransmittedBytesCount', 'remoteAddressCountryName', 'dnsQuery', 'accessedByMalwareEvidence', 'domainName', 'isExternalConnection', 'remoteAddressInternalExternalLocal', 'calculatedCreationTime', 'endTime' ])
- end: datetime (optional)
Query end time
- hostname: list
Hostname where the process is running
- pid: list
Command to search for
- start: datetime (optional)
Query start time (default value is: -7)
- timeFeatureId: str (optional)
Time boundary (default value is: startFeatureId)
- timefield: str (optional)
Field to use for time (default value is: creationTime)
If you want to print the query prior to executing, pass ‘print’ as an argument
cybereason_prov.Connection.list_connections_from_process('print', hostname="hostname", pid=42)
- '{
- "queryPath" : [
- {
"requestedType": "Process", "filters":[ { "facetName": "applicablePid", "values":[ 42 ], "filterType":"Equals" }, { "facetName": "ownerMachine", "values":[ "hostname" ], "filterType":"Equals" }, { "facetName": "creationTime", "values": [ 1643011155594, 1643615955594 ], "filterType":"Between" } ], "connectionFeature": { "elementInstanceType": "Process", "featureName": "connections" }
}, { "requestedType": "Connection", "filters":[], "isResult": true }
], "customFields": [ "elementDisplayName","direction","ownerMachine","ownerProcess", "serverPort","serverAddress","portType","aggregatedReceivedBytesCount", "aggregatedTransmittedBytesCount","remoteAddressCountryName","dnsQuery", "accessedByMalwareEvidence","domainName","isExternalConnection", "remoteAddressInternalExternalLocal","calculatedCreationTime","endTime" ]
}'
If you have set the arguments and then would like to validate the query, use below example
cybereason_prov.Connection.list_connections_from_process('print',
hostname="hostname",
pid=42
start=-10,
end=-2
)
- ' {
- "queryPath" : [
- {
"requestedType": "Process", "filters":[ { "facetName": "applicablePid", "values":[ 42 ], "filterType":"Equals" }, { "facetName": "ownerMachine", "values":[ "hostname" ], "filterType":"Equals" }, { "facetName": "creationTime", "values": [ 1642752424307, 1643443624308 ], "filterType":"Between" } ], "connectionFeature": { "elementInstanceType": "Process", "featureName": "connections" }
}, { "requestedType": "Connection", "filters":[], "isResult": true }
], "customFields": ["elementDisplayName","direction","ownerMachine","ownerProcess", "serverPort","serverAddress","portType","aggregatedReceivedBytesCount", "aggregatedTransmittedBytesCount","remoteAddressCountryName","dnsQuery", "accessedByMalwareEvidence","domainName","isExternalConnection", "remoteAddressInternalExternalLocal","calculatedCreationTime","endTime" ]
}'
In order to run pre-defined query, call the provider followed by the query name. Pre-defined queries can be run with either values specified as arguments or run with default arguments.
For more information , refer to the documentation Running a pre-defined query <data_acquisition/dataproviders:running a pre-defined query>
cybereason_prov.Connection.list_connections_from_process('print',
hostname="hostname",
pid=42
start=-10,
end=-2
)
remoteAddressCountryName | aggregatedReceivedBytesCount | endTime | portType | accessedByMalwareEvidence | group | elementDisplayName | aggregatedTransmittedBytesCount | isExternalConnection | serverAddress | serverPort | calculatedCreationTime | direction | ownerMachine.Machine | ownerMachine.Process | dnsQuery.DnsQueryResolvedDomainToIp | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 | France | 1235 | 2021-12-20 07:01:21 | SERVICE_HTTP | false | 6d0da6b2-e909-411a-95b7-3869f9147919 | 10.11.12.13:53154 > 1.2.3.4:80 | 314 | false | > 1.2.3.4 | 80 | 2021-12-20 07:01:20 | OUTGOING | hostname | process.exe | external.domain.tld > 1.2.3.4 |
1 row × 16 columns
You can also create your own query and run it via the Cybereason provider using this syntax: QUERY_PROVIDER.exec_query(<query_text>)
For more information, check documentation data_acquisition/dataproviders:running an ad hoc query
cybereason_query = '''
{
"queryPath" : [
{
"requestedType": "Connection",
"filters":[],
"isResult": true
}
]
}
'''
df = cybereason_prov.exec_query(cybereason_query)
df.head()
remoteAddressCountryName | aggregatedReceivedBytesCount | endTime | portType | accessedByMalwareEvidence | group | elementDisplayName | aggregatedTransmittedBytesCount | isExternalConnection | serverAddress | serverPort | calculatedCreationTime | direction | ownerMachine.Machine | ownerMachine.Process | dnsQuery.DnsQueryResolvedDomainToIp | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 | France | 1235 | 2021-12-20 07:01:21 | SERVICE_HTTP | false | 6d0da6b2-e909-411a-95b7-3869f9147919 | 10.11.12.13:53154 > 1.2.3.4:80 | 314 | false | > 1.2.3.4 | 80 | 2021-12-20 07:01:20 | OUTGOING | hostname | process.exe | external.domain.tld > 1.2.3.4 |