AWS - Integrate Agentless Workload Scanning with Terraform

This integration method uses Terraform.

Overview

This article provides the prerequisites and troubleshooting steps for an Agentless Workload Scanning integration.

Once you have read through the access and resource requirements, complete the integration steps depending on your chosen integration level:

• Single Account Integration
• AWS Organization Integration (two options available)

The Agentless Workload Scanning integration can be configured with Terraform using the lacework_aws_agentless_scanning module.

If you are new to the Lacework Terraform Provider, or Lacework Terraform Modules, read Terraform for Lacework Overview to learn the basics on how to configure the provider.

This module will install global and regional resources. The global resources should be installed once for a Lacework integration. The regional resources should be installed in each region where scanning will occur. Having per-region resources assures that no cross-region traffic occurs.

Access and Resource Requirements

A new VPC and Internet Gateway will be created in each scanning region within a single AWS account. In the AWS Organization integration, only one account is set up to perform scanning (a Scanning account or Security account). This is the only account where a new VPC and Internet Gateway is created.

The target AWS account must have Service Quotas allowing at least one more of these resources to be created in each region selected. One way to verify is to use AWS Trusted Advisor, then the Service limits link on the left and search by keyword "VPC" then expand both VPC and VPC Internet Gateways search results. Make sure at least one more of each can be created in each scanning region.

Integration Requirements

• AWS Account Admin - The account used to run Terraform must have administrative privileges on every AWS account you intend to integrate with Lacework.
• AWS CLI - The Terraform Provider for AWS leverages the configuration from the AWS CLI, and it is recommended the AWS CLI is installed and configured with API Keys for the account being integrated.
• Lacework Administrator - You must have a Lacework account with administrator privileges.
• Lacework CLI - Lacework leverages the configuration from the Lacework CLI. It is recommended the Lacework CLI is installed and configured.
• Terraform - ~> 0.14, ~> 0.15, ~> 1.0, ~> 1.1.

Single Account: Access Requirements

• Access to create ECS clusters, and access to create a VPC, subnets, and Internet Gateway for the ECS cluster.
• IAM to create an ECS task execution role, task role, and an EventBridge role for starting ECS tasks.
• IAM to create a cross-account role that has permissions to read from a newly created S3 bucket and start ECS tasks.
• Access to create CloudWatch Log Groups and Streams.
• Access to create a new S3 bucket.
• Access to create a new secret in AWS Secrets Manager.

Organization: Access Requirements

The access requirements for the scanning account are the same as the requirements for the Single Account integration. See Single Account: Access requirements.

The access requirements for the top-level AWS account are:

• Access to the Organization APIs.
• IAM to create a role to provide the scanning account the ability to list accounts in the organization.
• Access to create an IAM role on each of the accounts mentioned above. This role will have access to create snapshots and optionally decrypt the content.

Module Dependencies

Lacework Terraform modules for AWS Agentless Workload Scanning have the following dependencies that will be installed when running terraform init:

• aws
• random

Agentless Workload Scanning - Terraform Integration Steps

Choose which type of AWS Agentless Workload Scanning integration that you want to perform:

• Option 1: Single Account Integration
• Option 2: AWS Organization Integration

Option 1: Single Account Integration

1. Use the example below for your versions.tf file:

   terraform {
     required_version = ">= 0.15"
   
     required_providers {
       lacework = {
         source  = "lacework/lacework"
         version = "~> 1.0"
       }
     }
   }

2. Use the example below for your main.tf file:

   note

   In this example, two regions have been configured: us-east-1 and us-west-2 (with an alias of usw2). You can configure as many regions as you want for your environment.

   provider "lacework" {}
   
   provider "aws" {
     region = "us-east-1"
   }
   
   provider "aws" {
     alias  = "usw2"
     region = "us-west-2"
   }
   
   // This module will create AWS account "global" resources such as IAM roles, an S3 bucket, and a Secret Manager secret.
   // This will also create a new Cloud Account Integration within the Lacework console.
   module "lacework_aws_agentless_scanning_global" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
   
     global                    = true
     lacework_integration_name = "sidekick_from_terraform"
   }
   
   // The following modules should be included per-region where scanning will occur.
   // This creates an ECS cluster, a VPC and VPC IG for that cluster, and an EventBridge trigger in this region.
   // The trigger will start a periodic Task to snapshot and analyze EC2 volumes in this region.
   
   // Create regional resources in our first region
   module "lacework_aws_agentless_scanning_region" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
   
     regional                = true
     global_module_reference = module.lacework_aws_agentless_scanning_global
   }
   
   // Create regional resources in our second region
   module "lacework_aws_agentless_scanning_region_usw2" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
   
     providers = {
       aws = aws.usw2
     }
   
     regional                = true
     global_module_reference = module.lacework_aws_agentless_scanning_global
     // In this example the default VPC CIDR block is customized for this region.
     vpc_cidr_block          = "10.10.34.0/24"
   }

Custom tags can be applied to add resources using default_tags within the AWS provider. If custom tags are used then those tags will be applied to any resources created by the scanner.

Option 2: AWS Organization Integration

Choose from two options when deploying an AWS organization integration:

• Option 1: Automatic Snapshot Role Integration
  • Use this option if you want to automatically integrate any new AWS accounts that are added into the AWS Organization (post integration).
• Option 2: Standard Integration
  • Use this option if you want to manually integrate any new AWS accounts that are added into the AWS Organization (post integration).

Option 1: Automatic Snapshot Role Integration

For AWS Organization integrations using the automatic snapshot role, add Terraform modules to two AWS accounts:

• Scanning / Security account - Scanning infrastructure will only be installed on this account. This includes a new VPC, Internet Gateway and ECS Cluster.
• Management account for the AWS Organization - A role is installed so that accounts and organizational units (OUs) are enumerated during each scan.
  • Additionally, a CloudFormation StackSet is deployed to the management account that will automatically deploy a snapshot role to the root, or specified Organizational Units (OUs), within the AWS Organization. This snapshot role is used to integrate new AWS accounts that are added to the AWS Organization (post integration).

1. Use the example below for your versions.tf file:

   terraform {
     required_version = ">= 0.15.0"
   
     required_providers {
       lacework = {
         source  = "lacework/lacework"
         version = "~> 1.0"
       }
     }
   }

2. Use the example below for the AWS Scanning account:

   Here the Scanning account is the AWS account where the scanning infrastructure will be installed. This can be a Security account or Audit account.

   info

   In this example, two regions have been configured: us-west-1 and us-west-2. You can configure as many regions as you want for your environment.

   You must also provide the AWS Organization Management account for the AWS Organization and set of organizational units (OUs) that you want to scan.

   provider "lacework" {}
   provider "aws" {
     profile = "scanning-account"
     alias   = "scanning-account-usw1"
     region  = "us-west-1"
   }
   provider "aws" {
     profile = "scanning-account"
     alias   = "scanning-account-usw2"
     region  = "us-west-2"
   }
   // Create global resources, includes lacework cloud integration
   module "lacework_aws_agentless_scanning_global" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
     providers = {
       aws = aws.scanning-account-usw1
     }
     global = true
     organization = {
       monitored_accounts = ["ou-abcd-12345678"]
       management_account = "0001234567890"
     }
     lacework_integration_name = "agentless_org_from_terraform"
   }
   // Create regional resources in our first region
   module "lacework_aws_agentless_scanning_region_usw1" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
     providers = {
       aws = aws.scanning-account-usw1
     }
     regional                = true
     global_module_reference = module.lacework_aws_agentless_scanning_global
   }
   // Create regional resources in our second region
   module "lacework_aws_agentless_scanning_region_usw2" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
     providers = {
       aws = aws.scanning-account-usw2
     }
     regional                = true
     global_module_reference = module.lacework_aws_agentless_scanning_global
   }

3. Use the example below for the AWS Organization Management account:

   provider "aws" {
     profile = "management-account"
     alias   = "management-account-usw1"
     region  = "us-west-1"
   }
   // Create the required role for the management account.
   module "lacework_aws_agentless_management_scanning_role" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
     providers = {
       aws = aws.management-account-usw1
     }
     snapshot_role           = true
     global_module_reference = module.lacework_aws_agentless_scanning_global
   }
   resource "aws_cloudformation_stack_set" "snapshot_role" {
     provider = aws.management-account-usw1
     auto_deployment {
       enabled                          = true
       retain_stacks_on_account_removal = false
     }
     capabilities     = ["CAPABILITY_NAMED_IAM"]
     description      = "Lacework AWS Agentless Workload Scanning Organization Roles"
     name             = "lacework-agentless-scanning-stackset"
     permission_model = "SERVICE_MANAGED"
     parameters = {
       ExternalId         = module.lacework_aws_agentless_scanning_global.external_id
       ECSTaskRoleArn     = module.lacework_aws_agentless_scanning_global.agentless_scan_ecs_task_role_arn
       ResourceNamePrefix = module.lacework_aws_agentless_scanning_global.prefix
       ResourceNameSuffix = module.lacework_aws_agentless_scanning_global.suffix
     }
     template_url = "https://agentless-workload-scanner.s3.amazonaws.com/cloudformation-lacework/latest/snapshot-role.json"
     # Prevent update loop, as per https://github.com/hashicorp/terraform-provider-aws/issues/23464
     lifecycle {
       ignore_changes = [
         administration_role_arn
       ]
     }
   }
   resource "aws_cloudformation_stack_set_instance" "snapshot_role" {
     provider = aws.management-account-usw1
     deployment_targets {
       organizational_unit_ids = ["ou-abcd-12345678"]
     }
     region         = "us-west-1"
     stack_set_name = aws_cloudformation_stack_set.snapshot_role.name
   }

Custom tags can be applied to add resources using default_tags within the AWS provider. If custom tags are used then those tags will be applied to any resources created by the scanner.

Option 2: Standard Integration

For standard AWS Organization integrations, add Terraform modules to three AWS accounts:

• Scanning / Security account - Scanning infrastructure will only be installed on this account. This includes a new VPC, Internet Gateway and ECS Cluster.
• Monitored account(s) - A role is installed that will create snapshots and access snapshot data.
• Management account for the AWS Organization - A role is installed so that accounts and organizational units (OUs) are enumerated during each scan.

1. Use the example below for your versions.tf file:

   terraform {
     required_version = ">= 0.15"
   
     required_providers {
       lacework = {
         source  = "lacework/lacework"
         version = "~> 1.0"
       }
     }
   }

2. Use the example below for the AWS Scanning account:

   Here the Scanning account is the AWS account where the scanning infrastructure will be installed. This can be a Security account or Audit account.

   info

   In this example, two regions have been configured: us-west-1 and us-west-2. You can configure as many regions as you want for your environment.

   You must also provide the AWS Organization Management account for the AWS Organization and set of organizational units (OUs) that you want to scan.

   You must update and rerun this Terraform module if you want to integrate any new AWS Accounts that have been added to the AWS Organization.

   provider "lacework" {}
   
   provider "aws" {
     profile = "scanning-account"
     alias   = "scanning-account-usw1"
     region  = "us-west-1"
   }
   
   provider "aws" {
     profile = "scanning-account"
     alias   = "scanning-account-usw2"
     region  = "us-west-2"
   }
   
   // Create global resources, includes lacework cloud integration
   module "lacework_aws_agentless_scanning_global" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
   
     providers = {
       aws = aws.scanning-account-usw1
     }
   
     global       = true
     organization = {
       // This list may contain account IDs, OUs, or the organization root.
       monitored_accounts = ["1234567890", "ou-abcd"]
       // This account ID must be the AWS organizations "management account".
       // This wil be used to enumerate the accounts and OUs in the list of monitored accounts.
       // This account must also have the snapshot_role installed.
       management_account = "0001234567890"
     }
   
     lacework_integration_name = "agentless_org_from_terraform"
   }
   
   // Create regional resources in our first region
   module "lacework_aws_agentless_scanning_region_usw1" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
   
     providers = {
       aws = aws.scanning-account-usw1
     }
   
     regional                = true
     global_module_reference = module.lacework_aws_agentless_scanning_global
   }
   
   // Create regional resources in our second region
   module "lacework_aws_agentless_scanning_region_usw2" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
   
     providers = {
       aws = aws.scanning-account-usw2
     }
   
     regional                = true
     global_module_reference = module.lacework_aws_agentless_scanning_global
     // In this example the default VPC CIDR block is customized for this region.
     vpc_cidr_block          = "10.10.34.0/24"
   }

3. Use the example below to add the Scanning role to each AWS account that should be scanned or monitored:

   In this example a "Monitored account" is any AWS account that should be scanned by the scanner. The scanner will assume a role in each of these accounts to take snapshots and access snapshot data. If new AWS Accounts are added to the AWS Organzation after integration, add this role for those new accounts that you want to monitor.

   provider "aws" {
     profile = "monitored-account"
     alias   = "monitored-account-usw1"
     region  = "us-west-1"
   }
   
   // Create the required role for the monitored account.
   module "lacework_aws_agentless_monitored_scanning_role" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
   
     providers = {
       aws = aws.monitored-account-usw1
     }
   
     snapshot_role           = true
     global_module_reference = module.lacework_aws_agentless_scanning_global
   }

4. Use the example below for the AWS Organization Management account:

   In this example the following Terraform code is the same as what is used on each Monitored account. This installs the same role into the Management account.

   provider "aws" {
     profile = "management-account"
     alias   = "management-account-usw1"
     region  = "us-west-1"
   }
   
   // Create the required role for the management account.
   module "lacework_aws_agentless_management_scanning_role" {
     source  = "lacework/agentless-scanning/aws"
     version = "~> 0.6"
   
     providers = {
       aws = aws.management-account-usw1
     }
   
     snapshot_role           = true
     global_module_reference = module.lacework_aws_agentless_scanning_global
   }

Custom tags can be applied to add resources using default_tags within the AWS provider. If custom tags are used then those tags will be applied to any resources created by the scanner.

Verify your Agentless Workload Scanning Integration

In the Lacework console, the status of the integration at Settings > Integrations > Cloud accounts will display as Success if all resources are installed correctly. If the periodic scanning encounters an error, the status will display the error details.

Remove an Agentless Workload Scanning Integration

Start in the Lacework console.

1. In Settings > Integrations > Cloud accounts, find the integration that you would like to remove.
2. Toggle the integration State to disabled, or Delete the integration using the actions menu on the right.

Using Terraform, run terraform destroy for the Agentless module.