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).

tip

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).

tip

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 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.

# 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.

tip

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 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.

note

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.

# 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.

Next Steps

View scanning results in the Lacework Console.
Read FAQs on Agentless Workload Scanning.

Overview​

AWS Organization Integration​

Option 1: Automatic Snapshot Role Integration​

Option 2: Standard Integration​

Verify your Agentless Workload Scanning Integration​

Remove an Agentless Workload Scanning Integration​

Next Steps​