-
Notifications
You must be signed in to change notification settings - Fork 61
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #51 from amashinchi-rc/update-readme-per-wiki
Update readme per wiki
- Loading branch information
Showing
1 changed file
with
20 additions
and
82 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,92 +1,30 @@ | ||
| surveyor | ||
| ================ | ||
| # Surveyor | ||
|
|
||
| ## What's New | ||
| - Support for VMWare Cloud Enterprise EDR | ||
| - Ability to specify an output location. | ||
| - Python 3 support only. | ||
| Surveyor is a Python utility that queries Endpoint Detection and Response (EDR) | ||
| products and summarizes the results. Security and IT teams can use Surveyor to | ||
| baseline their environments and identify abnormal activity. | ||
|
|
||
| ## Analyze your endpoints | ||
|
|
||
| ## About | ||
| Surveyor is a Python utility that queries Endpoint Detection and Response products and summarizes the results. It provides security and IT teams with a method for quickly baselining an environment to identify normal and abnormal activity. Surveyor uses both definition files and pre-built queries to run searches across an environment and provide insights into what applications or activities exist within an enterprise, who is using them, and how. | ||
| Surveyor uses both definition files and pre-built queries to run searches across | ||
| an environment and provide insights into what applications or activities exist | ||
| within an enterprise, who is using them, and how. | ||
|
|
||
| EDR user interfaces and REST APIs provide direct access to events and processes and are very useful for real-time threat detection, digital forensics, and incident response (to name a few use cases). Surveyor is intended to provide high-level information about an environment, meeting use cases more closely aligned with inventory maintenance and proactive threat hunting. | ||
| Surveyor currently supports the following EDR platforms: | ||
|
|
||
| Surveyor currently supports the following EDR platforms: | ||
| - Carbon Black (Cb) Enterprise Response | ||
| - VMWare Cloud Enterprise EDR (formerly Carbon Black ThreatHunter) | ||
| - VMware Carbon Black® (Cb) Enterprise Response | ||
| - VMware Carbon Black Cloud Enterprise EDR (formerly Carbon Black ThreatHunter) | ||
| - Microsoft Defender for Endpoint | ||
|
|
||
| More information about surveyor can be found [on this blog post](https://redcanary.com/blog/carbon-black-response-how-tos-surveyor/) | ||
| You can find out more about Surveyor from [this blog post](https://redcanary.com/blog/carbon-black-response-how-tos-surveyor/). | ||
|
|
||
| ## Contributing | ||
| We encourage and welcome all contributions to Surveyor, which accepts two types of contributions: | ||
| - Definition Files | ||
| - New Features | ||
|
|
||
| Please see our [contribution page](https://github.com/redcanaryco/cb-response-surveyor/blob/master/Contributing.md) to learn more about what is accepted for the different types of contributions and how to contribute. | ||
| ## Get started | ||
|
|
||
| ## Getting Started | ||
| - Clone the repository from Github | ||
| ```git clone https://github.com/redcanaryco/surveyor.git``` | ||
| - Change to the surveyor directory | ||
| ```cd surveyor``` | ||
| - Run setup.py to install all the required dependencies | ||
| ```python setup.py``` | ||
| For information about installing and using Surveyor, see the [Getting started](https://github.com/redcanaryco/surveyor/wiki/Getting-started) | ||
| page of the wiki. | ||
|
|
||
| ### Updating Existing Local Git Repos | ||
| - We strongly recommend updating any existing local clones to point to the new repository URL. You can do this by using git remote on the command line: | ||
| ``` git remote set-url origin https://github.com/redcanaryco/surveyor``` | ||
|
|
||
| ## Requirements | ||
| In order to use Surveyor, you will need access to Carbon Black API tokens. Surveyor utilizes the Carbon Black API to run it’s queries against the endpoints in your environment. | ||
|
|
||
| You can find in-depth instructions on how to create and populate your Carbon Black API (cbapi) credentials in the cbapi repo found here: https://github.com/carbonblack/cbapi-python | ||
|
|
||
| Once you have the API token, you should be able to follow these step-by-step instructions: | ||
| * Grab your API token located in your user profile in your Carbon Black portal. | ||
| * Your API token should be stored in one of the following default credential file locations: | ||
| - /etc/carbonblack/ | ||
| - ~/.carbonblack/ | ||
| - /current_working_directory/.carbonblack/ | ||
|
|
||
| Depending on which Carbon Black product you are using, utilize the following naming conventions for your credential files | ||
| - credentials.psc for CB ThreatHunter | ||
| - credentials.response for CB Response | ||
|
|
||
| Unless otherwise specified with the ```--profile``` tag, the credentials and URL provided in the ```[default]``` configuration will be used. | ||
| ```./surveyor.py --profile otheruser --defdir definitions``` | ||
|
|
||
| For ThreatHunter, we have found that the following API permissions work best and return the appropriate results from Surveyor. | ||
| - Create, update, and delete custom watchlists and related reports and IOCs - Read | ||
| - Custom Detections - Feeds - Create,Read,Update,Delete | ||
| - Access and manage configuration settings to forward events - Read | ||
| - Access event and process data; create and cancel searches - Create,Read,Update,Delete | ||
| - Retrieve SHA-256 hash metadata of stored binaries - Read | ||
| - Unified Binary Store - File - Read | ||
|
|
||
| ## Using | ||
| ### Definition Files | ||
| There are over a dozen predefined definition files that can be run out of the box against an environment. Definition files allow you to query an environment for a group of processes and/or hashes at a single time. | ||
| To run Surveyor using a predefined definition file, you’ll want to use the following command: | ||
| ```./surveyor.py --deffile [DEFINITION FILE LOCATION]``` | ||
| Example: ```./surveyor.py --deffile definitions/file-transfer.json``` | ||
|
|
||
| ### Definition Directory | ||
| Using the ```--defdir``` option, you can run Surveyor against an entire directory of definitions at once. | ||
| ```./surveyor.py --defdir definitions``` | ||
|
|
||
| ### Output Location | ||
| The default output file is located in the directory Surveyor is run and titled - survey.csv. You can use the ```--output``` option to specify a different location and name for surveyor output. | ||
|
|
||
| ### Enterprise EDR (ThreatHunter) | ||
| By default surveyor will attempt to use Carbon Black Response to to run it's queries. If you would like to use it against a VMWare Cloud Enterprise EDR environment you must use the ```--threathunter``` option. | ||
| ```./surveyor.py --threathunter --defdir definitions``` | ||
|
|
||
| ### Query | ||
| If there is no current definition file or you want to search for something specific, you can use the ```--query``` option to provide a query. The query should mimic the same syntax that would be used in the GUI query. | ||
| ```./surveyor.py --query 'process_name:explorer.exe AND username:joebob'``` | ||
|
|
||
| ### Profile | ||
| To differentiate between different Carbon Black profiles add the ```--profile``` tag to the command line. | ||
| ```./surveyor.py --profile``` | ||
| ## Contribute to Surveyor | ||
|
|
||
| We encourage and welcome your contributions to Surveyor. For more information, | ||
| see the [Contributing to Surveyor](https://github.com/redcanaryco/surveyor/wiki/Contributing-to-Surveyor) | ||
| page of the wiki. |