Install OX Runtime Sensor on AWS ECS Terraform

Deploy the OX Runtime Sensor as an ECS Daemon service, one task per EC2 container instance, using the provided Terraform module. The API key is managed using AWS Secrets Manager.

Prerequisites

• ECS cluster backed by EC2 instances (not Fargate) with Linux kernel v5.10 and later

• Terraform v1.3 and later

• AWS credentials with permissions for ECS, IAM, CloudWatch Logs, and Secrets Manager

• An OX API key.

Step 1: Configure the AWS provider

Add the AWS provider to your Terraform configuration:

provider "aws" {
  region  = "<AWS_REGION>"   # e.g. "us-east-1"
  profile = "<AWS_PROFILE>"  # omit if using environment credentials or an IAM role
}

Step 2: Configure the Terraform module

Add the module to your Terraform configuration. The tarball URL is provided by OX Security and has the sensor image, registry, and API endpoint already baked in.

1. Provide the API key directly. The module creates the Secrets Manager secret.

module "ox_runtime_sensor" {
  source = "https://charts.cloud.ox.security/terraform/aws-ecs-sensor-latest.tar.gz"

  # Required
  ecs_cluster_name = "<ECS_CLUSTER_NAME>"
  ox_api_key       = "<API_KEY>"

  # Optional — shown in OX UI and attached to every event
  # ox_cluster_name     = "<CLUSTER_NAME>"    # defaults to ecs_cluster_name if omitted
  # ox_cloud_provider   = "aws"                # default, no need to change for ECS
  # ox_cloud_region     = "<AWS_REGION>"       # auto-detected from AWS provider
  # ox_cloud_account_id = "<AWS_ACCOUNT_ID>"   # auto-detected from AWS caller identity
}

1. (Alternative) Bring your own secret. If you manage secrets externally (for example, using External Secrets Operator or a shared secret store), pass the ARN instead.

module "ox_runtime_sensor" {
  source = "https://charts.cloud.ox.security/terraform/aws-ecs-sensor-latest.tar.gz"

  ecs_cluster_name      = "<ECS_CLUSTER_NAME>"
  create_secret         = false
  ox_api_key_secret_arn = "<SECRET_ARN>"

  # Optional — shown in OX UI and attached to every event
  # ox_cluster_name     = "<CLUSTER_NAME>"    # defaults to ecs_cluster_name if omitted
  # ox_cloud_provider   = "aws"                # default, no need to change for ECS
  # ox_cloud_region     = "<AWS_REGION>"       # auto-detected from AWS provider
  # ox_cloud_account_id = "<AWS_ACCOUNT_ID>"   # auto-detected from AWS caller identity
}

Pinning a specific version: Replace latest with the versioned filename (for example, aws-ecs-sensor-v0.20250401.1.tar.gz). OX Security publishes the full version history at https://charts.cloud.ox.security/terraform/.

Step 3: Apply

terraform init
terraform plan
terraform apply

Terraform creates:

• An ECS task definition with the required Linux capabilities and volume mounts

• A Daemon service (one task per EC2 instance in the cluster)

• An IAM task execution role with secretsmanager:GetSecretValue permission

• A CloudWatch log group for sensor logs (configurable)

Step 4: Connect to OX Runtime Sensor

Configuration reference

Variable	Required	Default	Description
ecs_cluster_name	yes	—	Name of the ECS cluster to deploy into (max 35 characters)
ox_api_key	yes (when create_secret = true)	—	OX API key. The module creates a Secrets Manager secret from this value
ox_api_key_secret_arn	yes (when create_secret = false)	—	ARN of an existing Secrets Manager secret containing the OX API key
create_secret	no	true	Set to false to use an existing Secrets Manager secret via ox_api_key_secret_arn
ox_cluster_name	no	same as ecs_cluster_name	Label shown in the OX UI. Set this if you want a friendlier or different name
ox_cloud_provider	no	aws	Cloud provider label injected into every event
ox_cloud_region	no	auto-detected from AWS provider	AWS region injected into every event
ox_cloud_account_id	no	auto-detected from AWS caller identity	AWS account ID injected into every event
cloudwatch_logs_enabled	no	true	Create a CloudWatch log group and forward sensor logs
cloudwatch_log_retention_days	no	7	Log retention in days (0 = never expire)
host_network	no	true	Use host network mode (required for IMDSv2 access)

Uninstall

terraform destroy