Skip to content

Latest commit

 

History

History
217 lines (146 loc) · 9.9 KB

README.md

File metadata and controls

217 lines (146 loc) · 9.9 KB
Raw

CrowdStrike

falcon-integration-gateway Python Lint Container Build on Quay

Falcon Integration Gateway (FIG) forwards threat detection findings and audit events from the CrowdStrike Falcon platform to the backend of your choice.

Detection findings and audit events generated by CrowdStrike Falcon platform inform you about suspicious files and behaviors in your environment. You will see detections on a range of activities from the presence of a bad file (indicator of compromise (IOC)) to a nuanced collection of suspicious behaviors (indicator of attack (IOA)) occurring on one of your hosts or containers. You can learn more about the individual detections in Falcon documentation.

This project facilitates the export of the individual detections and audit events from CrowdStrike Falcon to third-party security dashboards (so called backends). The export is useful in cases where security operation team workflows are tied to given third-party solution to get early real-time heads-up about malicious activities or unusual user activities detected by CrowdStrike Falcon platform.

API Scopes

API clients are granted one or more API scopes. Scopes allow access to specific CrowdStrike APIs and describe the actions that an API client can perform.

Note

For more information on how to generate an API client, refer to the CrowdStrike API documentation.

FIG requires the following API scopes at a minimum:

  • Event streams: [Read]
  • Hosts: [Read]

Consult the backend guides for additional API scopes that may be required.

Authentication

FIG requires the authentication of an API client ID and client secret, along with its associated cloud region, to establish a connection with the CrowdStrike API.

FIG supports auto-discovery of the Falcon cloud region. If you do not specify a cloud region, FIG will attempt to auto-discover the cloud region based on the API client ID and client secret provided.

Important

Auto-discovery is only available for [us-1, us-2, eu-1] regions.

Direct Configuration

Note

This method is not recommended for production deployments.

You can use the config.ini file to store your API client ID and client secret. The config.ini file should be located in the config directory. To configure authentication, add the following to the config.ini file:

[falcon]
cloud_region = us-1
client_id = YOUR_CLIENT_ID
client_secret = YOUR_CLIENT_SECRET

Environment Variables

You can also provide your API client ID and client secret as environment variables. To do so, set the following environment variables:

export FALCON_CLOUD_REGION=us-1
export FALCON_CLIENT_ID=YOUR_CLIENT_ID
export FALCON_CLIENT_SECRET=YOUR_CLIENT_SECRET

Credential Store

You can use a credential store to securely store your API client ID and client secret. FIG supports the following credential stores:

  • AWS Secrets Manager (secrets_manager)
  • AWS SSM Parameter Store (ssm)

Note

You can use either direct configuration or environment variables to specify the credential store and its associated configurations.

To configure FIG to use a credential store, add the following to the config.ini file:

[falcon]
cloud_region = us-1

[credentials_store]
#store = ssm|secrets_manager

After selecting a credential store, you must provide the necessary configuration for the store. For example, to use AWS Secrets Manager, add the following to the config.ini file:

[secrets_manager]
region = YOUR_AWS_REGION
secrets_manager_secret_name = your/secret/name
secrets_manager_client_id_key = client_id_key_name
secrets_manager_client_secret_key = client_secret_key_name

Configuration

Please refer to the config.ini file for more details on the available options along with their respective environment variables.

Backends w/ Available Deployment Guide(s)

Backend Description Deployment Guide(s) General Guide(s)
AWS Pushes events to AWS Security Hub AWS backend
AWS_SQS Pushes events to AWS SQS Coming Soon AWS SQS backend
Azure Pushes events to Azure Log Analytics Azure backend
Chronicle Pushes events to Google Chronicle Chronicle backend
CloudTrail Lake Pushes events to AWS CloudTrail Lake CloudTrail Lake backend
GCP Pushes events to GCP Security Command Center GCP backend
Workspace ONE Pushes events to VMware Workspace ONE Intelligence Coming Soon Workspace ONE backend
Generic Displays events to STDOUT (useful for dev/debugging) N/A Generic Backend

Alternative Deployment Options

❗ Prior to any deployment, ensure you refer to the configuration options available to the application ❗

Installation to Kubernetes using the helm chart

Please refer to the FIG helm chart documentation for detailed instructions on deploying the FIG via helm chart for your respective backend(s).

With Docker/Podman

To install as a container:

  1. Pull the image

    docker pull quay.io/crowdstrike/falcon-integration-gateway:latest

  2. Run the application in the background passing in your backend CONFIG options as environment variables

    docker run -d --rm \
  -e FALCON_CLIENT_ID="$FALCON_CLIENT_ID" \
  -e FALCON_CLIENT_SECRET="$FALCON_CLIENT_SECRET" \
  -e FALCON_CLOUD_REGION="us-1" \
  -e FIG_BACKENDS=<BACKEND> \
  -e CONFIG_OPTION=CONFIG_OPTION_VALUE \
  quay.io/crowdstrike/falcon-integration-gateway:latest

  3. Confirm deployment

    docker logs <container>

From Git Repository

Note

This method requires Python 3.7 or higher and a python package manager such as pip to be installed on your system.

  1. Clone and navigate to the repository

    git clone https://github.com/CrowdStrike/falcon-integration-gateway.git
cd falcon-integration-gateway

  2. Install the python dependencies.

    pip3 install -r requirements.txt

  3. Modify the ./config/config.ini file with your configuration options or set the associated environment variables.

  4. Run the application

    python3 -m fig

Updating the FIG from the Git Repository

Depending on which configuration method you are using, follow the steps below to update the FIG from the Git repository.

config.ini

If you have made any changes to the config.ini file, you can update the FIG by following these steps:

  1. Make a backup of the config/config.ini file.
  2. Remove the falcon-integration-gateway directory.
  3. Clone and navigate to the repository again.
  4. Install/update the python dependencies.
  5. Update the config/config.ini file with your configuration settings.

    Because the config.ini file may have new changes (ie, new sections or options), it is recommended to reapply your configuration settings from the backup to the new config.ini file.

  6. Run the application.

An example of the process:

cp config/config.ini /tmp/config.ini
cd .. && rm -rf falcon-integration-gateway
git clone https://github.com/CrowdStrike/falcon-integration-gateway.git
cd falcon-integration-gateway
pip3 install --upgrade -r requirements.txt
# Review the new config.ini file and reapply your settings from the backup
python3 -m fig

This method ensures that your configuration settings are preserved while updating the FIG to the latest version.

Environment Variables (only)

If you are only using environment variables to configure the FIG, you can update the FIG by following these steps:

  1. Pull the latest changes from the repository.
  2. Install/update the python dependencies.
  3. Run the application.

An example of the process:

git pull
pip3 install --upgrade -r requirements.txt
python3 -m fig

Developers Guide

Statement of Support

Falcon Integration Gateway (FIG) is a community-driven, open source project designed to forward threat detection findings and audit events from the CrowdStrike Falcon platform to the backend of your choice. While not a formal CrowdStrike product, FIG is maintained by CrowdStrike and supported in partnership with the open source community.