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:

ini [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:

bash 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:

```ini [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:

ini [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.
*Currently, this backend only supports sending detection events that originate from AWS to Security Hub |

• Manual Deployment

| AWS backend | | AWS_SQS | Pushes events to AWS SQS | Coming Soon | AWS SQS backend | | Azure | Pushes events to Azure Log Analytics |

• Deployment to AKS

| Azure backend | | CloudTrail Lake | Pushes events to AWS CloudTrail Lake |

• Deployment to EKS
• Manual Deployment

| CloudTrail Lake backend | | GCP | Pushes events to GCP Security Command Center |

• Deployment to GKE (using marketplace)
• Deployment to GKE (manual)

| 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

   bash 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

   bash 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

   bash 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.5 on PyPI are broken and will not install correctly. Please ensure you install version 3.2.5 or higher from PyPI.

1. Install the package:

   bash python3 -m pip install 'falcon-integration-gateway>3.2.5'

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:

   ```ini [main] backends = GENERIC

   [events] olderthandays_threshold = 5

   [logging] level = DEBUG

   [falcon] cloudregion = us-1 clientid = ABCD clientsecret = ABCD applicationid = my-generic-id ```

3. Run the application:

bash python3 -m fig

Updating the FIG from PyPI

To update the FIG package from PyPI, run:

bash 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:

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

2. Install the python dependencies:

   bash 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:

   bash 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:

```bash 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:

bash 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.