falcon-integration-gateway

falcon-integration-gateway

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.

Table of Contents

• Python Compatibility
• API Scopes
• Authentication
  • Direct Configuration
  • Environment Variables
  • Credential Store
• Configuration
• Deployment
  • Backends w/ Available Deployment Guide(s)
  • Alternative Deployment Options
    • Installation to Kubernetes using the helm chart
    • With Docker/Podman
    • From the Python Package Index (PyPI)
    • From Git Repository
• Developers Guide
• Statement of Support

Python Compatibility

[!IMPORTANT] Compatible with Python versions 3.7 through 3.11

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.

Deployment

Backends w/ Available Deployment Guide(s)

Backend	Description	Deployment Guide(s)	General Guide(s)
AWS	Pushes events to AWS Security Hub	<ul><li>Manual Deployment</li></ul>	AWS backend
AWS_SQS	Pushes events to AWS SQS	Coming Soon	AWS SQS backend
Azure	Pushes events to Azure Log Analytics	<ul><li>Deployment to AKS</li></ul>	Azure backend
CloudTrail Lake	Pushes events to AWS CloudTrail Lake	<ul><li>Deployment to EKS</li><li>Manual Deployment</li></ul>	CloudTrail Lake backend
GCP	Pushes events to GCP Security Command Center	<ul><li>Deployment to GKE (using marketplace)</li><li>Deployment to GKE (manual)</li></ul>	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

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

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 the Python Package Index (PyPI)

Falcon Integration Gateway (FIG) is available on the Python Package Index.

[!WARNING] Falcon Integration Gateway (FIG) versions below 3.2.3 on PyPI are broken and will not install correctly. Please ensure you install version 3.2.3 or higher from PyPI.

1. Install the package:

    python3 -m pip install falcon-integration-gateway
   

2. Once installed, create a configuration file or set your environment variables according to the CONFIG options before running the application. Example config.ini for the GENERIC backend:

    [main]
    backends = GENERIC
   
    [events]
    older_than_days_threshold = 5
   
    [logging]
    level = DEBUG
   
    [falcon]
    cloud_region = us-1
    client_id = ABCD
    client_secret = ABCD
    application_id = my-generic-id
   

3. Run the application:

   python3 -m fig
   

Updating the FIG from PyPI

To update the FIG package from PyPI, run:

python3 -m pip install falcon-integration-gateway --upgrade

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:

    python3 -m pip 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.

This site is open source. Improve this page.