diff --git a/terraform/README.md b/terraform/README.md index 90f5ded..e18fd58 100644 --- a/terraform/README.md +++ b/terraform/README.md @@ -9,6 +9,8 @@ across multiple cloud providers. autoscaling sensor within AWS, including `main.tf` and `versions.tf` files for configuration. - **`aws-cloud-enrichment/`**: A Terraform module for setting up cloud enrichment services on AWS. +- **`aws-flow-sensor/`**: (Private Preview) Contains an example deployment of the `terraform-aws-single-sensor` module + with supporting IAM resources - **`azure-cloud-enrichment/`**: Module to configure cloud enrichment capabilities on Azure. - **`azure-scaleset-sensor/`**: Azure Terraform configuration to deploy Corelight diff --git a/terraform/aws-flow-sensor/README.md b/terraform/aws-flow-sensor/README.md new file mode 100644 index 0000000..40130d9 --- /dev/null +++ b/terraform/aws-flow-sensor/README.md @@ -0,0 +1,62 @@ +# Corelight AWS Flow Sensor Deployment (Private Preview) + +This directory provides Terraform code for deploying Corelight's AWS Flow Sensor + +## Overview + +This example uses the [terraform-aws-single-sensor](https://github.com/corelight/terraform-aws-single-sensor) module +to simplify the deployment of the Flow sensor and includes example resources for authorizing it to the VPC Flow s3 bucket. + +## Requirements & Considerations +* A Flow Sensor must be deployed in each AWS account +* The sensor should be deployed similarly to a traditional sensor with a separate management and monitoring subnet +* VPC Flow Logs will only be processed for VPCs with flow log configurations matching the following criteria: + * Log Destination Target is `s3` + * AWS Default (v2) Log Format + * `plain-text` File Format + * `Per Hour Partition` and `Hive Compatible Partitions` are disabled + +## Configuration +Once connected to Fleet, configure the AWS VPC Flow feature (Private Preview) under `Advanced` as follows +* Enable the feature by switching on `cloud_vpc_flow.enable` +* All configurations below begin with `cloud_vpc_flow.` + +| Configuration | Required | Type | Default Region | Purpose | Example | +|---------------------|----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|-------------------------| +| `start_date` | YES | string | N/A | Date to begin processing
flow logs in AWS format | `2025/06/01` | +| `log_level` | NO | string | `info` | The log level of the service | `debug` to troubleshoot | +| `monitored_vpcs` | NO | string | `null` | | `vpc-12345,vpc-54321` | +| `monitored_regions` | NO | string | `us-east-1`
`us-east-2`
`us-west-1`
`us-west-2`
`ap-south-1`
`ap-northeast-1`
`ap-northeast-2`
`ap-northeast-3`
`ap-southeast-1`
`ap-southeast-2`
`ca-central-1`
`eu-central-1`
`eu-west-2`
`eu-west-3`
`eu-north-1`
`sa-east-1` | Regions to enumerate
for compatible
configurations | `us-east-1,us-east-2` | +| `s3_bucket_prefix` | NO | string | `AWSLogs` | VPC flow log s3 object prefix | `AWSLogs` | + +## Limitations +* While a Flow Sensor can read from a s3 bucket that includes VPC Flow logs for multiple accounts, it will only process + logs for the account in which it is deployed. + +## IAM Policy JSON +```json +{ + "Statement": [ + { + "Action": [ + "s3:ListBucket", + "s3:GetObject" + ], + "Effect": "Allow", + "Resource": [ + "arn:aws:s3:::", + "arn:aws:s3:::/*" + ] + }, + { + "Action": [ + "ec2:DescribeVpcs", + "ec2:DescribeFlowLogs" + ], + "Effect": "Allow", + "Resource": "*" + } + ], + "Version": "2012-10-17" +} +``` \ No newline at end of file diff --git a/terraform/aws-flow-sensor/main.tf b/terraform/aws-flow-sensor/main.tf new file mode 100644 index 0000000..629823e --- /dev/null +++ b/terraform/aws-flow-sensor/main.tf @@ -0,0 +1,84 @@ +module "aws_single_sensor" { + source = "github.com/corelight/terraform-aws-single-sensor?ref=v1.0.0" + + instance_name = "" // provide the flow sensor a name + ami_id = "" // Corelight provided AMI ID + aws_key_pair_name = "" // provide an AWS SSH key pair name to associate with the instance + fleet_community_string = "" // provide your fleet instance's community string + iam_instance_profile_name = aws_iam_instance_profile.sensor_profile.name + + // ENIs can be created by the module or provided. See the referenced module for more details + // https://github.com/corelight/terraform-aws-single-sensor + + // -- New ENI Example -- + monitoring_interface_subnet_id = "" // Typically a private subnet + monitoring_security_group_vpc_id = "" // VPC ID of subnet + + management_interface_subnet_id = "" // Typically a public or SSH accessible subnet + management_interface_public_ip = true // (Optional) Set to true if in a public subnet w/ IGW + management_security_group_vpc_id = "" // VPC ID of subnet + + ssh_allow_cidrs = [""] // CIDR range(s) that should be allowed to SSH to the flow sensor + + // provide the fleet configuration from a "New Sensor" + fleet_token = "" + fleet_url = "" + fleet_server_sslname = "" +} + +resource "aws_iam_instance_profile" "sensor_profile" { + // name the EC2 instance profile + name = "" + role = aws_iam_role.flow_role.name +} + +data "aws_iam_policy_document" "flow_policy_data" { + statement { + effect = "Allow" + actions = [ + "s3:ListBucket", + "s3:GetObject" + ] + resources = [ + // provide the flow sensor access to read from the flow log bucket + "arn:aws:s3:::/*", + "arn:aws:s3:::", + ] + } + statement { + effect = "Allow" + actions = [ + "ec2:DescribeVpcs", + "ec2:DescribeFlowLogs" + ] + resources = ["*"] + } +} + +data "aws_iam_policy_document" "ec2_assume_policy" { + statement { + effect = "Allow" + actions = ["sts:AssumeRole"] + principals { + identifiers = ["ec2.amazonaws.com"] + type = "Service" + } + } +} + +resource "aws_iam_policy" "flow_policy" { + // Name the IAM policy + name = "" + policy = data.aws_iam_policy_document.flow_policy_data.json +} + +resource "aws_iam_role" "flow_role" { + // Name the flow sensor IAM role + name = "" + assume_role_policy = data.aws_iam_policy_document.ec2_assume_policy.json +} + +resource "aws_iam_role_policy_attachment" "flow_policy_role_attach" { + policy_arn = aws_iam_policy.flow_policy.arn + role = aws_iam_role.flow_role.id +} diff --git a/terraform/aws-flow-sensor/versions.tf b/terraform/aws-flow-sensor/versions.tf new file mode 100644 index 0000000..afa96e6 --- /dev/null +++ b/terraform/aws-flow-sensor/versions.tf @@ -0,0 +1,8 @@ +terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = "~> 5" + } + } +}