Skip to content

Getting Started

Jump to bottom
Cori Smith edited this page Jun 20, 2023 · 12 revisions

A guide to installing and using Surveyor.

Contents

Prerequisites

You need the following to use Surveyor:

  • Python 3.9+. You can download the latest version of Python here.

Install Surveyor

You can download Surveyor directly from GitHub:

git clone https://github.com/redcanaryco/surveyor.git

To install Surveyor, navigate to the Git repository and run the setup script:

cd surveyor
python setup.py

The repo URL has recently changed so if you have an older local clone, we recommend updating your local copy to point to the new repository URL:

git remote set-url origin https://github.com/redcanaryco/surveyor

Set Up Credentials

VMware Carbon Black EDR

To use Surveyor with VMware Carbon Black EDR, you need to save your API credentials to a file. For in-depth instructions, check the cbapi repository.

The credential file must be in one of the following locations:

  • /etc/carbonblack/
  • ~/.carbonblack/
  • /[current working directory]/.carbonblack/

Save your credentials in a file named credentials.response. The file can contain multiple API credentials but each section must have a unique profile name and formatted like the following:

[PROFILE_NAME_HERE]
url=URL
token=API_KEY

Unless otherwise specificed with the --profile parameter, Surveyor uses the credentials and URL provided by the [default] header.

When you run Surveyor, the path of the credential file is automatically found and doesn't need to be specified at run time.

VMware Carbon Black Cloud Enterprise EDR

To use Surveyor with VMware Carbon Black Cloud Enterprise EDR, you need to save your API credentials to a file. For in-depth instructions, check out cbc-python-sdk.

Tip: Be sure to set the access level to API when generating the token.

The credential file must be in one of the following locations:

  • /etc/carbonblack/
  • ~/.carbonblack/
  • /[current working directory]/.carbonblack/

Save your credentials in a file named credentials.psc or credentials.cbc. The file can contain multiple API credentials but each section must have a unique profile name and formatted like the following:

[PROFILE_NAME_HERE]
url=URL
token=API_KEY/API_ID
org_key=ORG_KEY

Unless otherwise specificed with the --profile parameter, Surveyor uses the credentials and URL provided by the [default] header.

When you run Surveyor, the path of the credential file is automatically found.

Microsoft Defender for Endpoint

To use Surveyor with Microsoft Defender for Endpoint, you need the following information:

  • tenantId
  • appId
  • appSecret Note: This is your application key.

OR

  • token (that is already generated by an external system/process)

Detailed instructions on creating and saving these credentials can be found here.

Tip: Be sure to enable AdvancedQuery.Read.All in the API permissions.

There is no required filename or file path for this credential INI file.

The file can contain multiple API credentials but each section must have a unique profile name and formatted like the following:

[PROFILE_NAME_HERE]
tenantId=TENANT_ID
appId=APP_ID
appSecret=APP_SECRET

OR

[PROFILE_NAME_HERE]
token=TOKEN_STRING

When you run Surveyor, specify the path of the INI file with the --creds option.

python surveyor.py YOUR_QUERY_PARAMETERS dfe --creds PATH_TO_CRED_FILE

Unless otherwise specificed with the --profile parameter, Surveyor uses the credentials provided by the [default] header.

SentinelOne

To use Surveyor with SentinelOne, you need the following information from SentinelOne:

  • API Key for user with permission to execute Deep Visibility queries and/or PowerQuery searches
  • URL of your SentinelOne server

There is no required filename or file path for this credential INI file.

The file can contain multiple API credentials but each section must have a unique profile name and formatted like the following:

[PROFILE_NAME_HERE]
url=URL
token=API KEY
site_id=SITE_ID
account_id=ACCOUNT_ID

Cortex XDR

To use Surveyor with Cortex XDR, you need the following information from Cortex:

  • API Key and API Key ID for user with permission to execute XQL searches
  • Auth Type of your API key. When generating your API key, you'll need to choose either Standard or Advanced authentication. Surveyor supports both.
  • URL of your Cortex XDR API. When generating your API key, you'll be given an FQDN which should then be formatted as https://api-fqdnHERE before saving in the credential file.

Information on how to generate an API key can be found here: https://cortex-panw.stoplight.io/docs/cortex-xdr/3u3j0e7hcx8t1-get-started-with-cortex-xdr-ap-is

There is no required filename or file path for this credential INI file.

The file can contain multiple API credentials but each section must have a unique profile name and formatted like the following:

[PROFILE_NAME_HERE]
url=URL
api_key=API KEY
api_key_id=API_KEY_ID
auth_type=STANDARD_OR_ADVANCED

When you run Surveyor, specify the path of the INI file with the --creds option

python surveyor.py YOUR_QUERY_PARAMETERS cortex --creds PATH_TO_CRED_FILE

Unless otherwise specificed with the --profile parameter, Surveyor uses the credentials and URL provided by the [default] header.

Run Surveyor

The Surveyor command line has two sections: query parameters and the EDR-specific parameters

Example:

python surveyor.py YOUR_QUERY_PARAMETERS EDR_KEYWORD EDR_PARAMETERS

Query Parameters

Surveyor comes with over a dozen pre-defined definition files you can use to query your environment. Definition files are a collection of queries that are written in a vendor-agnostic syntax so they can be used on any supported EDR platform.

It also supports user-defined queries or IOC hunts.

By default, Surveyor queries all available data. However, there are predefined filters (e.g. specific hostname/username, time filters, etc.) you can add alongside your search.

To view available parameters, specify the --help flag:

python surveyor.py --help

Syntax for a Single Definition File

python surveyor.py --deffile FULL_PATH_TO_DEFINITION_FILE

Syntax for Multiple Definition Files

If you want to run multiple definition files, collect them into a single directory and use the --defdir parameter

python surveyor.py --defdir FULL_PATH_TO_DEFINITION_DIRECTORY

Syntax for a User-Defined Query

If you need more flexibility in the query language or need to perform an ad-hoc search, you can run a single query using the --query parameter.

Note the query parameter mimics the syntax of the EDR's GUI. For example, Carbon Black EDR queries will be of the form process_name:explorer.exe AND username:joebob whereas SentinelOne queries would look like FilePath containsCIS "explorer.exe" AND Username containsCIS "joebob"

python surveyor.py --query USER_DEFINED_QUERY

Syntax for an IOC Hunt

If you have a list of IOCs, you can provide a file of newline-delimited values for hunting.

Note that all IOCs values must be the same type: IP, domain, or MD5

python surveyor.py --iocfile FULL_PATH_TO_IOC_FILE --ioctype IOC_TYPE

EDR-Specific Parameters

Surveyor attempts to query Carbon Black EDR by default. If you want to use a different EDR, you'll need to specify that using one of the keywords below:

Full Name EDR Keyword
Cortex XDR cortex
Microsoft Defender for Endpoint dfe
SentinelOne s1
VMware Carbon Black EDR cbr
VMware Carbon Black Cloud Enterprise EDR cbc

To view available EDR parameters, specify the --help flag as show below:

python surveyor.py EDR_KEYWORD --help

View Results

By default, results are saved to a file named survey.csv in your working directory.

You can specify a prefix for the output file using the --prefix parameter.

Alternatively, you can pass the --output parameter to change the location of the CSV file or use the parameter --no-file to only output results to the terminal.

Clone this wiki locally