Getting Started

A guide to installing and using Surveyor.

Contents

• Contents
• Prerequisites
• Install Surveyor
• Save your Carbon Black® API credentials
• Save your Microsoft Defender for Endpoint API credentials
• Save your SentinelOne API Credentials
• Run Surveyor
• Surveyor Nuances

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

We recommend updating local clones of Surveyor to point to the new repository URL:

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

Save your Carbon Black® API credentials

To use Surveyor with Carbon Black EDR products, you need to save your credential files. For in-depth instructions on creating and populating your API credentials, check the cbapi repository.

Copy your credentials from the Carbon Black portal and save them to one of the following locations:

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

If your EDR platform is VMware Carbon Black EDR (formerly known as Carbon Black Response), name your credential file credentials.response. If your platform is VMware Carbon Black Cloud Enterprise, name the file credentials.psc.

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

Save your Microsoft Defender for Endpoint API credentials

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

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

Detailed instructions on creating and saving these credentials can be found here. Tip: Be sure to enable AdvancedQuery.Read.All in the API permissions.

Save your credentials in an INI file like the following:

[default]
tenantId=<ID>
appId=<ID>
appSecret=<key>

When you run Surveyor, specify the path of the INI file with the --creds option. Note that unless otherwise specified with --profile, Surveyor uses the credentials and URL provided by the [default] header.

Save your SentinelOne API Credentials

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

• API Key for user with permission to execute Deep Visibility queries
• URL of your SentinelOne server

Save your configuration information in an INI file as follows:

[profile_name_here]
url=<URL>
token=<API KEY>

Alternatively, you can omit the token field and specify your API token via the environment variable S1_TOKEN.

When you run Surveyor, specify the path of the INI file with the --creds option (e.g. py surveyor.py s1 --creds s1_creds.ini). Note that unless otherwise specified with --profile, Surveyor uses the credentials and URL provided by the [default] header.

Run Surveyor

Surveyor comes with over a dozen pre-defined definition files you can use to query your environment. To Run Surveyor, run the following at the command line:

./surveyor.py --deffile <definition file>

Note that Surveyor attempts to query Carbon Black Response by default. To query VMware Carbon Black Cloud Enterprise, specify the --threathunter flag. To query Microsoft Defender for Endpoint, specify the --defender flag.

Use the --defdir flag to run Surveyor against an entire directory of definition files at once:

./surveyor.py --defdir <directory>

Check your working directory for an output file named survey.csv. You can pass the --output flag to change the location of this CSV file.

If you don't want to run an entire definition file, you can specify the --query flag to run only one query:

./surveyor.py --query '<query>`

Ensure that the query mimics the syntax of the GUI. For example, Carbon Black Response 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"'

For additional help, specify the --help flag:

./surveyor.py --help

Surveyor Nuances

• SentinelOne site and account IDs specified in the command line take precedence over what is found in the configuration file.