AWS SSM Distributor

This Terraform module automates the deployment and maintenance of the CrowdStrike Falcon Sensor across AWS EC2 instances using AWS Systems Manager (SSM) Distributor.

View on GitHub

Key Features

• Multi-region deployment using AWS Provider v6 resource-level region support
• Automated sensor deployment via AWS Systems Manager State Manager
• Multi-platform support (Linux and Windows)
• Flexible credential storage (Parameter Store or Secrets Manager)
• Customer-managed KMS encryption support per region
• Configurable deployment schedules

Note

This module creates a State Manager association in each specified region that runs periodically to ensure all EC2 instances have the Falcon sensor installed and up to date.

Pre-requisites

Generate API Keys

CrowdStrike API keys are required to use this module. It is highly recommended that you create a dedicated API client with only the required scopes.

1. In the CrowdStrike console, navigate to Support and resources > API Clients & Keys. Click Add new API Client.
2. Add the following required scopes:

Scope Name	Permission	Description
Sensor Download	Read	Required to download sensor installation packages

3. Click Add to create the API client. The next screen will display the API CLIENT ID, SECRET, and BASE URL. You will need the CLIENT ID and SECRET for this module.

   picture

   

Note

This page is only shown once. Make sure you copy CLIENT ID and SECRET to a secure location.

SSM Distributor Package

Ensure the CrowdStrike Falcon Sensor Distributor package is available in your AWS regions. The module validates package availability automatically in each specified region.

SSM Agent on EC2 Instances

Ensure the AWS Systems Manager Agent is installed and running on all target EC2 instances. Most AWS-provided AMIs include the SSM Agent by default.

Note

This module automatically creates an IAM role for SSM automation with the necessary permissions to deploy and manage the Falcon sensor. You can optionally specify a permissions boundary if required by your organization’s policies.

Scheduling

The association runs on a schedule defined by cron_schedule_expression. The default schedule is cron(0 2 ? * * *) which runs daily at 2 AM UTC.

You can customize the schedule by updating the cron_schedule_expression parameter:

cron_schedule_expression = "cron(0 2 ? * * *)" # Daily at 2 AM UTC

Event Driven Execution

This association will run automatically upon initial deployment of the module and subsequent changes.

State Manager also runs the association after any of the following activity occurs on a target node:

• A managed node comes online for the first time.
• A managed node comes online after missing a scheduled association run.
• A managed node comes online after being stopped for more than 30 days.

Preventing associations from running when a target changes

To prevent an association from running automatically upon deployment and when a target changes, you can set apply_only_at_cron_interval = true. When enabled, the association will only run at the scheduled cron interval.

This is useful when you prefer strict control over when sensors are deployed to reduce cost and avoid automatic deployments outside your maintenance windows.

For more information about scheduling options and when associations are automatically applied, review the AWS Systems Manager State Manager documentation.

Usage

terraform {
  required_version = ">= 1.0.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.0.0"
    }
  }
}

variable "falcon_client_id" {
  type        = string
  sensitive   = true
  description = "Falcon API Client ID"
}

variable "falcon_client_secret" {
  type        = string
  sensitive   = true
  description = "Falcon API Client Secret"
}

locals {
  regions                     = ["us-east-1", "us-west-2"]
  falcon_cloud                = "us-1"
  action                      = "Install" # or "Uninstall"
  secret_storage_method       = "ParameterStore"
  cron_schedule_expression    = "cron(0 2 ? * * *)"
  apply_only_at_cron_interval = false
  linux_package_version       = ""
  windows_package_version     = ""
  create_kms_key              = false
}

provider "aws" {
  region = "us-east-1"
}

module "crowdstrike_distributor" {
  source = "CrowdStrike/ssm-distributor/aws"

  # Multi-region deployment
  regions = local.regions

  # CrowdStrike credentials
  falcon_cloud         = local.falcon_cloud
  falcon_client_id     = var.falcon_client_id
  falcon_client_secret = var.falcon_client_secret

  # Action: Install or Uninstall
  action = local.action

  # Credential storage
  secret_storage_method = local.secret_storage_method

  # Deployment schedule
  cron_schedule_expression    = local.cron_schedule_expression
  apply_only_at_cron_interval = local.apply_only_at_cron_interval

  # Package versions (optional - leave empty for latest)
  linux_package_version   = local.linux_package_version
  windows_package_version = local.windows_package_version

  # Encryption (optional)
  create_kms_key = local.create_kms_key

  # Tags
  tags = {
    Environment = "production"
    Team        = "security"
  }
}

Requirements

Name	Version
terraform	>= 1.0.0
aws	>= 6.0.0

Providers

Name	Version
aws	6.36.0

Resources

Name	Type
aws_iam_role.ssm_assume_role	resource
aws_iam_role_policies_exclusive.ssm_assume_role	resource
aws_iam_role_policy.secrets_access	resource
aws_iam_role_policy_attachments_exclusive.ssm_assume_role	resource
aws_kms_alias.distributor_key_alias	resource
aws_kms_key.distributor_key	resource
aws_secretsmanager_secret.distributor_secret	resource
aws_secretsmanager_secret_version.distributor_secret_version	resource
aws_ssm_association.sensor_deploy	resource
aws_ssm_parameter.falcon_client_id	resource
aws_ssm_parameter.falcon_client_secret	resource
aws_ssm_parameter.falcon_cloud	resource
aws_iam_policy_document.secrets_access	data source
aws_iam_policy_document.ssm_assume_role	data source
aws_partition.current	data source
aws_ssm_document.falcon_sensor_deploy	data source

Inputs

Name	Description	Type	Default	Required
action	Action to perform: ‘Install’ to install the Falcon sensor, or ‘Uninstall’ to remove it.	string	"Install"	no
apply_only_at_cron_interval	By default, when you create a new association, the system runs it immediately and then according to the schedule you specified. Set this to true to prevent the association from running immediately after creation or when a target comes online. The association will only run at the scheduled cron interval.	bool	false	no
association_max_concurrency	Maximum number of instances that can run the association at the same time.	string	"50%"	no
association_max_errors	Maximum number of errors allowed before stopping the association execution.	string	"0"	no
association_name_prefix	Prefix for the SSM association name. The region name will be appended automatically (e.g., ‘prefix-us-east-1’).	string	""	no
create_kms_key	Whether to create a customer-managed KMS key for encryption. Defaults to false to use AWS managed keys.	bool	false	no
cron_schedule_expression	The cron schedule expression for the AWS State Manager association. Defaults to daily at 2 AM UTC.	string	"cron(0 2 ? * * *)"	no
falcon_client_id	The Client ID of the Falcon API Credentials	string	n/a	yes
falcon_client_id_ssm_parameter_name	The name of the SSM parameter that will be created to store the Falcon API Client ID.	string	"/CrowdStrike/Falcon/ClientId"	no
falcon_client_secret	The Client Secret of the Falcon API Credentials	string	n/a	yes
falcon_client_secret_ssm_parameter_name	The name of the SSM parameter that will be created to store the Falcon API Client Secret.	string	"/CrowdStrike/Falcon/ClientSecret"	no
falcon_cloud	The Falcon Cloud Region to use.	string	n/a	yes
falcon_cloud_ssm_parameter_name	The name of the SSM parameter that will be created to store the Falcon Cloud Region.	string	"/CrowdStrike/Falcon/Cloud"	no
iam_role_name	Name of the IAM role that will be created for SSM automation. This is a global resource.	string	"CrowdStrikeSSMAutomationRole"	no
kms_key_alias	Alias for the KMS key when create_kms_key is true.	string	"crowdstrike-distributor"	no
kms_key_id	ID of an existing KMS key to use for encryption. If not provided and create_kms_key is false, AWS managed keys will be used.	string	null	no
linux_installer_params	The parameters to pass to the Linux installer at install time.	string	""	no
linux_package_version	The version of the CrowdStrike Falcon Sensor package to install on Linux. Example 7.0.4.2333, installs N-1 version if no version is specified.	string	""	no
permissions_boundary	Optional permissions boundary ARN to apply to the IAM role.	string	null	no
regions	List of AWS regions where CrowdStrike Falcon Sensor will be deployed. The module will create regional resources in each specified region.	list(string)	n/a	yes
secret_storage_method	The method to use for storing the Falcon API credentials. Defaults to SSM.	string	"ParameterStore"	no
secrets_manager_secret_name	The name of the Secrets Manager secret that will be created to store the Falcon API credentials.	string	"CrowdStrike/Falcon/Distributor"	no
ssm_document_name	The name of the SSM document to use for sensor deployment. Defaults to the official CrowdStrike document.	string	"CrowdStrike-FalconSensorDeploy"	no
tags	A map of tags to apply to all resources created by this module.	map(string)	{}	no
windows_installer_params	The parameters to pass to the Windows installer at install time.	string	""	no
windows_package_version	The version of the CrowdStrike Falcon Sensor package to install on Windows. Example 7.0.4.2333, installs N-1 version if no version is specified.	string	""	no

Outputs

Name	Description
action	The action being performed (Install or Uninstall)
association_max_concurrency	Maximum concurrency setting for the SSM association
association_max_errors	Maximum errors setting for the SSM association
association_schedule	The cron schedule expression for the SSM association
deployed_regions	List of regions where the Falcon sensor deployment is configured
falcon_cloud_api_endpoint	The Falcon API endpoint for the configured cloud region
falcon_cloud_region	The Falcon cloud region being used
iam_role_arn	The ARN of the IAM role created for SSM automation
iam_role_id	The ID of the IAM role created for SSM automation
iam_role_name	The name of the IAM role created for SSM automation
kms_key_aliases	Map of region to KMS key alias (if create_kms_key is true)
kms_key_arns	Map of region to KMS key ARN (if create_kms_key is true)
kms_key_ids	Map of region to KMS key ID (if create_kms_key is true)
secret_storage_method	The method used for storing Falcon API credentials
secrets_manager_secret_arns	Map of region to Secrets Manager secret ARN (when using Secrets Manager for credential storage)
secrets_manager_secret_names	Map of region to Secrets Manager secret name (when using Secrets Manager for credential storage)
ssm_association_ids	Map of region to SSM association ID for CrowdStrike Falcon sensor deployment
ssm_association_names	Map of region to SSM association name
ssm_document_names	Map of region to SSM document name used for sensor deployment
ssm_document_versions	Map of region to SSM document version being used
ssm_parameter_falcon_client_id_arns	Map of region to SSM parameter ARN storing the Falcon client ID (when using Parameter Store)
ssm_parameter_falcon_client_id_names	Map of region to SSM parameter name storing the Falcon client ID (when using Parameter Store)
ssm_parameter_falcon_client_secret_arns	Map of region to SSM parameter ARN storing the Falcon client secret (when using Parameter Store)
ssm_parameter_falcon_client_secret_names	Map of region to SSM parameter name storing the Falcon client secret (when using Parameter Store)
ssm_parameter_falcon_cloud_arns	Map of region to SSM parameter ARN storing the Falcon cloud region (when using Parameter Store)
ssm_parameter_falcon_cloud_names	Map of region to SSM parameter name storing the Falcon cloud region (when using Parameter Store)