Agentless Workload Scanning for AWS - Organization Integration (Terraform)
Overview
This article describes how to integrate your AWS organization with Lacework's Agentless Workload Scanning.
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).
See Lacework Terraform Module for Agentless Workload Scanning on AWS for all available Terraform integration options and additional deployment examples.
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 per region.
- 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).
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.
Use the example below for your
versions.tf
file:terraform {
required_version = ">= 0.15.0"
required_providers {
lacework = {
source = "lacework/lacework"
version = "~> 1.0"
}
}
}The Scanning account is the AWS account where the scanning infrastructure will be installed. A Scanning account is created for each region. This can be a Security account or Audit account.
In this example, two regions have been configured:
us-west-1
andus-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.# Set your Lacework profile here. With the Lacework CLI, use
# `lacework configure list` to get a list of available profiles.
provider "lacework" {
profile = "lw_agentless"
}
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
}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
}Run
terraform init
to initialize the working directory (containing the Terraform files).Run
terraform plan
and review the changes that will be applied.Once satisfied with the changes that will be applied, run
terraform apply
to execute Terraform.
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 per region.
- 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.
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.
Use the example below for your
versions.tf
file:terraform {
required_version = ">= 0.15"
required_providers {
lacework = {
source = "lacework/lacework"
version = "~> 1.0"
}
}
}Here the Scanning account is the AWS account where the scanning infrastructure will be installed. A Scanning account is created for each region. This can be a Security account or Audit account.
In this example, two regions have been configured:
us-west-1
andus-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.
noteYou must update and rerun this Terraform module if you want to integrate any new AWS Accounts that have been added to the AWS Organization.
# Set your Lacework profile here. With the Lacework CLI, use
# `lacework configure list` to get a list of available profiles.
provider "lacework" {
profile = "lw_agentless"
}
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"
}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 Organization 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
}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
}Run
terraform init
to initialize the working directory (containing the Terraform files).Run
terraform plan
and review the changes that will be applied.Once satisfied with the changes that will be applied, run
terraform apply
to execute Terraform.
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.
- In Settings > Integrations > Cloud accounts, find the integration that you would like to remove.
- 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.