Initial Module

.github/ISSUE_TEMPLATE/BUG.md

@@ -0,0 +1,24 @@
+---
+name: Bug Report
+about: Report a Bug
+
+---
+
+**Describe the bug**  
+What issue did you experience? More detail the better! 
+
+**Reproducing the Bug**  
+Steps to reproduce the behavior:
+1. Using terraform version x.y.z
+2. With module version a.b.c
+3. Provider versions... 1,2,3
+4. Error looks like: <insert screenshot / copy terraform error>
+
+**Expected Behavior**  
+Describe the expected behavior.
+
+**Screenshots**  
+If applicable, add screenshots, obfuscated tf state files, etc... to help explain your issue.
+
+**Any Additional Context**  
+Add any other context about the bug that will help us troubleshoot the issue.

.github/ISSUE_TEMPLATE/FEATURE.md

@@ -0,0 +1,18 @@
+---
+name: Feature Request
+about: Suggest an feature for this project
+
+---
+
+**Is your feature request related to an ongoing bug?**  
+Please provide a clear description of the challenge you're facing.
+
+**Propose a solution**  
+Outline a solution you may have to the challenge and any tests / evidence that may help us better
+decide to take it on! 
+
+**What alternatives have you tried or considered?**  
+Outline any alternatives to the solution you're proposing in a clear and concise way.
+
+**Any additional context**  
+Add any other context or screenshots about the feature request here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+# Description
+
+Include an overview of the change and which issue it addresses. Please also include relevant
+motivation and context. List any dependencies that are required for this change.
+
+Associated it with an existing issue, i.e. - "Fixes issue #12345"
+
+## Type of change
+
+Please delete options that are not relevant.
+
+- [ ] Bug Fix
+- [ ] New Feature
+- [ ] This change requires a documentation update
+
+# How Has This Been Tested?
+
+Describe the tests that you ran to verify your changes. Provide instructions so they can be
+reproduced. Please also list any relevant details for your test configuration

.github/workflows/fmt:check.yml

@@ -0,0 +1,25 @@
+---
+name: Terraform Validation
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  terraform:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: "1.8.2"
+      - name: Terraform fmt
+        run: task fmt:check

.gitignore

@@ -0,0 +1,6 @@
+.idea**
+**/.terraform/**
+*.tfstate.*
+*.tfstate
+**.terraform*
+**tfplan**

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Corelight, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,2 +1,45 @@
 # terraform-aws-sensor
+
 Terraform for Corelight's AWS Cloud Sensor Deployment.
+
+<img src="docs/overview.png" alt="overview">
+
+## Usage
+```terraform
+
+module "sensor" {
+  source = "github.com/corelight/terraform-aws-sensor"
+
+  auto_scaling_availability_zones = ["<first az>", "<second az>"]
+  aws_key_pair_name = "<key pair name>"
+
+  # Request access to Corelight sensor AMI from you Account Executive
+  corelight_sensor_ami_id = "<sensor AMI ID>"
+  license_key = "<your Corelight sensor license key>"
+  management_subnet_id = "<management subnet>"
+  monitoring_subnet_id = "<monitoring subnet>"
+  sensor_api_password = "<password for the sensor api>"
+  vpc_id = "<vpc where the sensor auto scale group is deployed>"
+
+  # (Optional) Fleet Subnet
+  fleet_subnet_id = "<subnet fleet is deployed in>"
+
+  # (Optional) Enrichment Bucket - ASG should have an instance 
+  # profile when using cloud enrichment
+  enrichment_bucket_name = "<cloud enrichment s3 bucket name>"
+  enrichment_bucket_region = "<cloud enrichment s3 bucket region>"
+}
+```
+
+### Deployment
+
+The variables for this module all have default values that can be overwritten
+to meet your naming and compliance standards.
+
+Deployment examples can be found [here](examples).
+
+## License
+
+The project is licensed under the [MIT][] license.
+
+[MIT]: LICENSE

Taskfile.yml

@@ -0,0 +1,13 @@
+---
+version: "3"
+
+tasks:
+  fmt:
+    desc: Reformat your configuration in the standard style
+    cmds:
+      - terraform fmt -recursive .
+
+  fmt:check:
+    desc: Check if the input is formatted
+    cmds:
+      - terraform fmt -recursive -check -diff .

auto_scale_group.tf

@@ -0,0 +1,48 @@
+resource "aws_autoscaling_group" "sensor_asg" {
+  name             = var.sensor_asg_name
+  min_size         = 1
+  max_size         = 5
+  desired_capacity = 1
+
+  launch_template {
+    name    = aws_launch_template.sensor_launch_template.name
+    version = aws_launch_template.sensor_launch_template.latest_version
+  }
+
+  availability_zones        = var.auto_scaling_availability_zones
+  target_group_arns         = [aws_lb_target_group.health_check.arn]
+  health_check_type         = "EC2"
+  health_check_grace_period = 300
+  termination_policies      = ["OldestInstance"]
+  protect_from_scale_in     = false
+}
+
+resource "aws_autoscaling_policy" "sensor_autoscale_policy" {
+  name                   = var.sensor_asg_auto_scale_policy_name
+  autoscaling_group_name = aws_autoscaling_group.sensor_asg.name
+
+  policy_type     = "StepScaling"
+  adjustment_type = "ChangeInCapacity"
+  step_adjustment {
+    metric_interval_lower_bound = 0
+    scaling_adjustment          = 1
+  }
+}
+
+resource "awscc_cloudwatch_alarm" "sensor_asg_high_cpu_alarm" {
+  statistic           = "Average"
+  threshold           = 70
+  alarm_description   = "Scale out if CPU > 70% for 2 minutes"
+  evaluation_periods  = 2
+  period              = 60
+  comparison_operator = "GreaterThanThreshold"
+  namespace           = "AWS/EC2"
+  alarm_actions       = [aws_autoscaling_policy.sensor_autoscale_policy.arn]
+  dimensions = [
+    {
+      name  = "AutoScalingGroupName"
+      value = "SensorAutoScalingGroup"
+    }
+  ]
+  metric_name = "CPUUtilization"
+}

data.tf

@@ -0,0 +1,54 @@
+data "aws_vpc" "provided" {
+  id = var.vpc_id
+}
+
+data "aws_subnet" "monitoring_subnet" {
+  id = var.monitoring_subnet_id
+}
+
+data "aws_subnet" "management_subnet" {
+  id = var.management_subnet_id
+}
+
+data "aws_subnet" "fleet_subnet" {
+  count = var.fleet_subnet_id == "" ? 0 : 1
+  id    = var.fleet_subnet_id
+}
+
+data "cloudinit_config" "config" {
+  gzip          = false
+  base64_encode = true
+
+  part {
+    content_type = "text/cloud-config"
+    content = templatefile("${path.module}/templates/sensor_init.tpl",
+      {
+        api_password   = var.sensor_api_password
+        sensor_license = var.license_key
+        mon_int        = "eth0"
+        mgmt_int       = "eth1"
+      }
+    )
+    filename = "sensor-build.yaml"
+  }
+}
+
+data "cloudinit_config" "config_with_enrichment" {
+  gzip          = false
+  base64_encode = true
+
+  part {
+    content_type = "text/cloud-config"
+    content = templatefile("${path.module}/templates/sensor_init_with_enrichment.tpl",
+      {
+        api_password   = var.sensor_api_password
+        sensor_license = var.license_key
+        mon_int        = "eth0"
+        mgmt_int       = "eth1"
+        bucket_name    = var.enrichment_bucket_name
+        bucket_region  = var.enrichment_bucket_region
+      }
+    )
+    filename = "sensor-build.yaml"
+  }
+}

examples/deployment/main.tf

@@ -0,0 +1,37 @@
+locals {
+  vpc_id                   = "<vpc where resources are deployed>"
+  monitoring_subnet        = "<monitoring subnet id>"
+  management_subnet        = "<management subnet id>"
+  sensor_ssh_key_pair_name = "<name of the ssh key in AWS used to access the sensor EC2 instances>"
+  sensor_ami_id            = "<sensor ami id from Corelight>"
+  license                  = "<your corelight sensor license key>"
+  tags = {
+    terraform : true,
+    purpose : "Corelight"
+  }
+}
+
+module "sensor" {
+  source = "github.com/corelight/terraform-aws-sensor"
+
+  auto_scaling_availability_zones = ["us-east-1a"]
+  aws_key_pair_name               = local.sensor_ssh_key_pair_name
+  corelight_sensor_ami_id         = local.sensor_ami_id
+  license_key                     = local.license
+  management_subnet_id            = local.management_subnet
+  monitoring_subnet_id            = local.monitoring_subnet
+  sensor_api_password             = "<password for the sensor api>"
+  vpc_id                          = local.vpc_id
+
+  tags = local.tags
+}
+
+module "bastion" {
+  source = "github.com/corelight/terraform-aws-sensor//modules/bastion"
+
+  bastion_key_pair_name = "<AWS ssh key pair name for the bastion host>"
+  subnet_id             = "<subnet with public ssh access>"
+  vpc_id                = local.vpc_id
+
+  tags = local.tags
+}

examples/deployment/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">=1.3.2"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5"
+    }
+  }
+}

launch_template.tf

@@ -0,0 +1,37 @@
+resource "aws_launch_template" "sensor_launch_template" {
+  name = var.sensor_launch_template_name
+
+  instance_type = var.sensor_launch_template_instance_type
+  image_id      = var.corelight_sensor_ami_id
+  key_name      = var.aws_key_pair_name
+  ebs_optimized = false
+
+  network_interfaces {
+    device_index         = 0
+    network_interface_id = aws_network_interface.monitoring_nic.id
+  }
+
+  network_interfaces {
+    device_index         = 1
+    network_interface_id = aws_network_interface.management_nic.id
+  }
+
+  user_data = var.enrichment_bucket_name == "" ? data.cloudinit_config.config.rendered : data.cloudinit_config.config_with_enrichment.rendered
+
+  tags = var.tags
+}
+
+resource "aws_network_interface" "monitoring_nic" {
+  subnet_id       = data.aws_subnet.monitoring_subnet.id
+  security_groups = [aws_security_group.monitoring.id]
+
+  tags = merge(var.tags, { name : var.monitoring_nic_name })
+}
+
+resource "aws_network_interface" "management_nic" {
+  subnet_id       = data.aws_subnet.management_subnet.id
+  security_groups = [aws_security_group.management.id]
+
+  tags = merge(var.tags, { name : var.management_nic_name })
+}
+