Latest Version: 1.1 - Release Date: 11/06/2024
This project integrates CrowdStrike Falcon Insight XDR and VMRay FinalVerdict / TotalInsight. It equips customers with extra intel regarding the threats detected by CrowdStrike Falcon Insight XDR on their endpoints. Depending on the configuration, the Connector collects unique SHA256 hash values from:
- Detections
- Quarantines
It then downloads and submits respective samples into the VMRay Analyzer for detonation and deep dynamic analysis. After the submission, it retrieves the verdict and IOC values from VMRay and updates Detection and Quarantine Objects, creates IOC, and contains (quarantines) machine if needed.
The connector supports the following VMRay products:
- Final Verdict
- Total Insight
app # Main project directory
├─── config # Configuration directory
│ └─── __init__.py
│ └─── crowdstike_conf.py # CrowdStrike configuration file
│ └─── general_conf.py # General configuration file
│ └─── crowdstike_conf.py # VMRay configuration file
├─── downloads # Directory for extracted binaries
├─── lib # Library directory
│ └─── __init__.py
│ └─── CrowdStrike.py # Crowdstrike API functions
│ └─── VMRay.py # VMRay API functions
│ └─── Sample.py # Sample class for controlling the samples
├─── log # Log directory for connector
└─── cs-connector.log # Log file for connector
└─── __init__.py
└─── connector.py # Main connector application
└─── requirements.txt # Python library requirements
└─── log # Log directory for Docker volume
- Python >3.10 with required packages (Required Packages)
- CrowdStrike Falcon Insight XDR
- VMRay Analyzer
- Docker (optional)
Clone the repository into a local folder.
git clone https://github.com/vmray/crowdstrike-falcon.git
Install the requirements.
pip install -r requirements.txt
Edit the vmray_conf.py general_conf.py crowdstrike_conf.pyfiles and update with your configurations.
- Create a Custom Access Level with the permissions below with a web interface for API at Create API section. (
Support and Resources > API client and keys
)
Scope | Read | Write |
---|---|---|
Alerts | ☑️ | ☑️ |
Detections | ☑️ | ☑️ |
Hosts | ☑️ | ☑️ |
Host groups | ☑️ | ☑️ |
Incidents | ☑️ | ☑️ |
IOC Management | ☑️ | ☑️ |
IOCs (Indicators of Compromise) | ☑️ | ☑️ |
On-demand scans (ODS) | ☑️ | ☑️ |
Quarantined Files | ☑️ | ☑️ |
Sample uploads | ☑️ | ☑️ |
User management | ☑️ | ☑️ |
- Edit the
CrowdStrikeConfig
class in crowdstrike_conf.py file
Configuration Item | Description | Default |
---|---|---|
CLIENT_ID |
Client ID | None |
CLIENT_SECRET |
Client Secret | None |
BASE_URL |
CrowdStrike Cloud base url | https://api.us-2.crowdstrike.com |
DOWNLOAD_DIR |
Directory path for sample downloads | downloads |
SELECTED_DATA_SOURCES |
Selected CrowdStrike data source | [DATA_SOURCE.DETECT , DATA_SOURCE.QUARANTINE ] |
USER_UUID |
User UUID for case creation | |
COMMMENT_TO_DETECTION |
Update Detection with a comment [True /False ] |
True |
COMMENT_TO_QUARANTINE |
Update Quarantine with a comment [True /False ] |
True |
CONTAIN_HOST |
Contain host machine if a detection or quarantine file affects it [True /False ] |
False |
CREATE_CASE |
Create a Case if a detection or quarantine files when the VMRay verdict hits one of CREATE_CASE_LEVELS | False |
CREATE_CASE_LEVELS |
Case Creation level list from VMRay verdict | [ VERDICT.SUSPICIOUS/ VERDICT.MALICIOUS] |
CASE_USERS |
User uuid that connector can open case RECOMMENDATION: Create a user for connector and follow the cases | |
FIND_ANOTHER_HOST |
Find another host with same IOC | False |
FIND_ANOTHER_HOST_LEVELS |
Find another host with an IOC. level list from VMRay verdict | [ VERDICT.SUSPICIOUS/ VERDICT.MALICIOUS] |
ADD_THREAT_CLASSIFICATION |
Add comment to Detection with found threat's classification | True |
ADD_THREAT_NAME |
Add comment to Detection with found threat's name | True |
-
Create API Key with web interface. (
Analysis Settings > API Keys
) -
Edit the
VMRayConfig
class in vmray_conf.py file.
Configuration Item | Description | Default |
---|---|---|
API_KEY_TYPE |
Enum for VMRay API Key Type [REPORT /VERDICT ] |
REPORT |
API_KEY |
API Key | |
URL |
URL of VMRay instance | https://eu.cloud.vmray.com |
ConnectorName |
User Agent string for VMRay Api requests | CrowdStrikeCloudConnector |
SSL_VERIFY |
Enable or disable certificate verification [True /False ] |
True |
SUBMISSION_COMMENT |
Comment for submitted samples | Sample from VMRay CarbonBlack Connector |
SUBMISSION_TAGS |
Tags for submitted samples | CrowdStrike |
ANALYSIS_TIMEOUT |
Timeout for submission analyses as seconds | 120 |
ANALYSIS_JOB_TIMEOUT |
Max job count for submissions | 600 |
DEFAULT_ANALYZER_MODE |
Analyzer mode for normal samples | reputation_static_dynamic |
RESUBMIT |
Resubmission status which has been already analyzed by VMRay [True /False ] |
False |
RESUBMISSION_VERDICTS |
Selected verdicts to resubmit evidences | [malicious, suspicious] |
- Edit the
GeneralConfig
class in general_conf.py file.
Configuration Item | Description | Default |
---|---|---|
LOG_FILE_PATH |
Connector log file path | cs-connector.log |
LOG LEVEL |
Logging verbosity level | DEBUG |
SELECTED_VERDICTS |
Selected verdicts to process and report back to CrowdStrike Cloud | malicious |
TIME_SPAN |
Time span between script iterations as seconds | 10800 |
RUNTIME_MODE |
Runtime mode for script | DOCKER |
You can start the connector with the command line after completing the configurations. You need to set RUNTIME_MODE
as RUNTIME_MODE.CLI
in the GeneralConfig
. Also, you can create a cron job for continuous processing.
python connector.py
You can create and start a Docker image with Dockerfile after completing the configurations. You need to set RUNTIME_MODE
as RUNTIME_MODE.DOCKER
in the GeneralConfig
.
docker build -t cs_connector .
docker run -d -v $(pwd)/log:/app/log -t cs_connector
After running the Docker container, you can see connector logs in the log directory on your host machine.