Skip to content

Commit

Permalink
feat(SecurityHub): manual deployment guide (#257)
Browse files Browse the repository at this point in the history
* docs(SecurityHub): initial guide for the manual deployment

This guide is to help illustrate the pieces required for the Security Hub integration. Currently we only had
a Terraform and Cloudformation guide to help automate the process of setting up the integration, but some users
prefer to set things up manually.

* docs(SecurityHub): updated names and added handler name change

* chore: add words to wordlist

For SecurityHub manual doc updates

* fix: add gh warning to better emphasize message

* docs(SecurityHub): better wording and admonition support

Based on feedback from @redhatrises

* docs(Securityhub): use amazon linux 2

* docs(Securityhub): update readme to include FIG alternative
  • Loading branch information
carlosmmatos authored Oct 30, 2023
1 parent 63b92b2 commit 36e8d7d
Show file tree
Hide file tree
Showing 3 changed files with 347 additions and 5 deletions.
7 changes: 7 additions & 0 deletions .github/wordlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -407,3 +407,10 @@ IOM
agentless
nslookup
centric
redrive
SSL
runtimes
chmod
githubusercontent
tmp
wget
20 changes: 15 additions & 5 deletions Security-Hub/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,11 @@
# AWS Security Hub Integration

## :warning: Transition to a more Simplified AWS Security Hub Integration :warning:

We would like to introduce the [Falcon Integration Gateway](https://github.com/CrowdStrike/falcon-integration-gateway) application as a simplified solution for AWS Security Hub integration. Unlike this project which requires creating multiple AWS resources, the Falcon Integration Gateway streamlines this process, making it easier and more straightforward. We invite you to explore and transition to the Falcon Integration Gateway for your AWS Security Hub integration needs. Documentation and setup instructions can be found [here](https://github.com/CrowdStrike/falcon-integration-gateway/blob/main/docs/aws/manual/README.md).

---

This solution publishes detections identified by CrowdStrike Falcon for instances
residing within Amazon Web Services (AWS) to AWS Security Hub.

Expand All @@ -20,7 +27,7 @@ There are several benefits to this architecture:
+ Easily scalable depending upon need
+ Can be deployed quickly

### Architecture
### Architecture
This solution consists of three primary components
+ Python application running within AWS for ingesting detections from the CrowdStrike API
> This application is sometimes referred to as _fig_, and may contain references to this which reflects the legacy solution name.
Expand All @@ -45,7 +52,7 @@ This solution consists of three primary components
+ [Installing via Terraform](terraform)
+ [Installing manually](manual-install.md)

The service application is intended to be deployed as a service on a Linux instance.
The service application is intended to be deployed as a service on a Linux instance.
The solution can be run stand-alone, but is not recommended for production deployments.

### Required CrowdStrike API access
Expand All @@ -65,15 +72,15 @@ There are six required parameters that must be defined in order for the Falcon I
+ `app_id` - A unique string value that describes the name of the application you are connecting to Falcon. Most string values are supported.
+ `severity_threshold` - An integer representing the threshold for detections you want published to AWS Security Hub.
+ `sqs_queue_name` - Name of the SQS queue to publish detections to. This must reside in the region specified below.
+ `region` - The region we will be publishing to in AWS Security Hub. This will need to match the region the SQS queue resides in. For deployments leveraging SSM, this parameter does not need to be specified.
+ `region` - The region we will be publishing to in AWS Security Hub. This will need to match the region the SQS queue resides in. For deployments leveraging SSM, this parameter does not need to be specified.

The seventh parameter is not required and defaults to __True__.
+ `confirm_provider` [__NOT REQUIRED__] - Should the service application only submit detections that have AWS listed as the service provider?

> Even though detections are published to AWS Security Hub within a single AWS region, they represent detections for instances found within _all_ AWS regions.
#### Using AWS Systems Manager _Parameter Store_
By default, service application configuration parameters are stored within AWS Systems Manager _Parameter Store_ but can be overridden by using a config.json file.
By default, service application configuration parameters are stored within AWS Systems Manager _Parameter Store_ but can be overridden by using a config.json file.

> SSM Parameter Store parameters are _case-sensitive_ and must reside within the same region as the FIG instance you are configuring. Please note the naming convention of the parameters displayed below, as the variable names must match exactly. (All upper case, spaces are underscores, precursed with "**FIG_**").
Expand Down Expand Up @@ -115,6 +122,9 @@ $ sudo systemctl status fig
This should result in a display similar to the following:
![FIG service status](images/fig-service-status-example.png)

> [!NOTE]
> For newer versions of OS's such as Amazon Linux 2023, you may need to restart the `fig` service if it is not started.
### Log files
+ `fig-service.log` - The application service log contains debug information related to the startup of the service and loading of credentials. Review this log for failures related to the starting and stopping of the service application.
+ `{app_id}_{partition_number}.log` - Each stream opened by the application has it's own rotating log that contains details regarding the detections discovered. Review this log to confirm detections are being discovered within the event stream and are properly formatted / meeting severity threshold requirements. This file is named after the value used for the __*app_id*__ parameter and the partition number.
Expand All @@ -125,7 +135,7 @@ Your current position within the event stream is referred to as your _offset_. T
You can read this file to find your position within the event stream. If you wish to reset your positions in the event stream, remove this file.

### Lambda debugging
When your lambda function was created, basic logging was enabled to CloudTrail as a stand-alone log group, named after the name of your lambda function. Successful submissions and regular events are tracked in this log.
When your lambda function was created, basic logging was enabled to CloudTrail as a stand-alone log group, named after the name of your lambda function. Successful submissions and regular events are tracked in this log.

If you wish to increase log verbosity, you may do so by creating the __DEBUG__ environmental variable on your lambda.

Expand Down
Loading

0 comments on commit 36e8d7d

Please sign in to comment.