From 7419459f88ca756f95a6c2843cff3f2d0224e873 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Thu, 19 Oct 2023 15:50:52 -0400 Subject: [PATCH 1/2] docs: adding manual deployment for aws backend --- README.md | 2 +- docs/aws/manual/README.md | 199 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+), 1 deletion(-) create mode 100644 docs/aws/manual/README.md diff --git a/README.md b/README.md index 46b39ad..75f4afb 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ FIG requires the following API scopes at a minimum: | Backend | Description | Deployment Guide(s) | General Guide(s) | |:--------|:------------|:--------------------|:-------------------| -| AWS | Pushes events to AWS Security Hub | *Coming Soon* | [AWS backend](fig/backends/aws) | +| AWS | Pushes events to AWS Security Hub | | [AWS backend](fig/backends/aws) | | AWS_SQS | Pushes events to AWS SQS | *Coming Soon* | [AWS SQS backend](fig/backends/aws_sqs) | | Azure | Pushes events to Azure Log Analytics | | [Azure backend](fig/backends/azure) | | Chronicle | Pushes events to Google Chronicle | | [Chronicle backend](fig/backends/chronicle) | diff --git a/docs/aws/manual/README.md b/docs/aws/manual/README.md new file mode 100644 index 0000000..4f974d1 --- /dev/null +++ b/docs/aws/manual/README.md @@ -0,0 +1,199 @@ +# AWS Security Hub Manual Deployment Guide + +This guide will walk you through the steps to manually deploy the Falcon Integration Gateway on +an AWS EC2 instance as a Python application. + +## Prerequisites + +- Falcon API Credentials with the following API scopes: + - **Event streams**: [Read] + - **Hosts**: [Read] +- Have appropriate AWS permissions to: + - Create EC2 instances + - Create IAM roles/policies + - Access Security Hub + +## Deployment Steps + +### 1. Create an Instance Profile + +This will be used to grant the EC2 instance access to the Security Hub and EC2 API's. + +> :exclamation: If you already have an instance profile that you would like to use, just ensure the role has the appropriate permissions and skip to step 2. + +#### 1.1 Create a policy + +1. Navigate to the [IAM Policies](https://console.aws.amazon.com/iam/home#/policies) page +1. Click the **Create policy** button +1. Select the **JSON** tab +1. Paste the following policy into the editor: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ec2:DescribeInstances", + "ec2:DescribeRegions", + "securityhub:GetFindings" + ], + "Resource": "*" + }, + { + "Effect": "Allow", + "Action": "securityhub:BatchImportFindings", + "Resource": "arn:aws:securityhub:*:*:product/crowdstrike/crowdstrike-falcon" + } + ] + } + ``` + +1. Click the **Next** button +1. Give it a name (e.g. `FIG-SecurityHub-Access-Policy`) and click the **Create policy** button + +#### 1.2 Create a role + +1. Navigate to the [IAM Roles](https://console.aws.amazon.com/iam/home#/roles) page +1. Click the **Create role** button +1. Select **Custom trust policy** and paste the following policy into the editor: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Service": "ec2.amazonaws.com" + }, + "Action": "sts:AssumeRole" + } + ] + } + ``` + +1. Click the **Next** button +1. Search for the policy you created in the previous step (e.g. `FIG-SecurityHub-Access-Policy`) and select it +1. Click the **Next** button +1. Give it a name (e.g. `FIG-SecurityHub-Access-Role`) and click the **Create role** button + +### 2. Create an EC2 Instance (Linux) + +This step is completely up to you. You can use the AWS console, CLI, or any other method you prefer to create an EC2 instance. Just make sure you select the instance profile you created in the previous step +and that you have access to the instance via SSH. + +For the purposes of this guide, we will be using the latest Amazon Linux 2023 AMI. + +> If you have an existing instance that you would like to use, just ensure the instance has instance profile you created in the previous step and skip to step 3. + +#### 2.1 Create an EC2 instance + +1. Navigate to the [EC2 Instances](https://console.aws.amazon.com/ec2/v2/home#Instances) page +1. Click the **Launch Instance** button + 1. Fill out the instance details as you see fit + 1. Under **Advanced details** + 1. Select the instance profile you created in the previous step +1. Click the **Launch instance** button + +### 3. Install the FIG + +Connect to your EC2 instance via SSH and follow the steps below to install the FIG. + +#### 3.1 Ensure the following packages are installed + +- Python 3.6+ +- pip +- git + +```bash +sudo dnf install python3 python3-pip git +``` + +> Use the package manager for your distro to ensure these packages are installed. + +#### 3.1 Install the FIG + +1. Clone the repository + + ```bash + git clone https://github.com/CrowdStrike/falcon-integration-gateway.git + ``` + +1. Change to the FIG directory + + ```bash + cd falcon-integration-gateway + ``` + +1. Install the python dependencies. + + ```bash + pip install -r requirements.txt + ``` + +#### 3.2 Configure the FIG + +There are two different ways that you can configure the FIG to use the AWS backend. +You can either use the `config/config.ini` file or you can use environment variables. + +> Refer to the [configuration options](../../../config/config.ini) available to the application +> and backend. + +##### 3.2.1 Configure the FIG using the `config/config.ini` file + +1. Modify the `config/config.ini` file and set the following minimum values: + + ```ini + [main] + backends = AWS + + [falcon] + cloud_region = + client_id = + client_secret = + + [aws] + region = + ``` + +##### 3.2.2 Configure the FIG using environment variables + +1. Set the following minimum environment variables: + + ```bash + export FIG_BACKENDS=AWS + export FALCON_CLOUD_REGION= + export FALCON_CLIENT_ID= + export FALCON_CLIENT_SECRET= + export AWS_REGION= + ``` + +#### 3.3 Run the FIG + +1. Run the application + + ```bash + python3 -m fig + ``` + +1. Verify output + + ```bash + 2023-10-18 16:45:43 fig MainThread INFO Starting Falcon Integration Gateway 3.1.10 + 2023-10-18 16:45:43 fig MainThread INFO AWS Backend is enabled. + 2023-10-18 16:45:43 fig MainThread INFO Enabled backends will only process events with types: {'DetectionSummaryEvent'} + 2023-10-18 16:45:44 fig cs_stream INFO Opening Streaming Connection + 2023-10-18 16:45:44 fig cs_stream INFO Established Streaming Connection: 200 OK + ... + ... + ``` + +### 4. Verify in Security Hub + +As events are processed by the FIG, they will be sent to Security Hub. You can verify this by following the steps below. + +1. Navigate to the [Security Hub](https://console.aws.amazon.com/securityhub/home) page +1. Click the **Findings** tab +1. Add a filter for **Product name** and enter **CrowdStrike Falcon** From a7bf9f72492ccdb5093ca9890420d528790efd12 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Thu, 19 Oct 2023 15:51:15 -0400 Subject: [PATCH 2/2] fix: incorrect env var for falcon client id --- config/config.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/config.ini b/config/config.ini index 1d4b016..b5c3ae9 100644 --- a/config/config.ini +++ b/config/config.ini @@ -34,7 +34,7 @@ # Uncomment to provide Falcon Cloud. Alternatively, use FALCON_CLOUD_REGION env variable. #cloud_region = us-1 -# Uncomment to provide OAuth Secret. Alternatively, use FALCON_CLIENT_SECRET env variable. +# Uncomment to provide OAuth Secret. Alternatively, use FALCON_CLIENT_ID env variable. #client_id = ABCD # Uncomment to provide OAuth Secret. Alternatively, use FALCON_CLIENT_SECRET env variable.