AWS Terraform Connection

Terraform is an infrastructure-as-code (IaC) tool that automates the provisioning and management of cloud infrastructure.

Use this integration if your organization manages AWS infrastructure with Terraform. Terraform provides an alternative to manually configuring the AWS integration in OX by automatically provisioning the IAM role and permissions required for OX to access your AWS environment and collect cloud security findings securely.

You can use Terraform to connect:

• A single AWS account

• Multiple accounts managed through AWS Organizations

Prerequisites

Before you begin, make sure you have:

Requirement	Description
Terraform version 1.2.0 or later	Required to deploy the Terraform configuration.
AWS credentials with permission to create IAM roles and policies	Required because the Terraform deployment automatically creates the IAM role and policies that OX uses to access your AWS environment.
External ID from OX	Used when creating the connector role.

Integrating OX with a single AWS Account

Use this method to connect a single AWS account.

To connect a single account:

1. Download the Terraform file ox_aws_integration.tf , and save it in an empty directory.

2. Configure AWS credentials for the account you want to connect. Example:

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="eu-west-1"

If you use temporary credentials, also configure AWS_SESSION_TOKEN.

1. To initialize Terraform, open a terminal in the directory that contains the Terraform file and run:

terraform init

1. To deploy the integration, run:

terraform apply -var="external_id=YOUR_EXTERNAL_ID"

1. Review the planned changes and enter yes when prompted.

When the deployment completes, Terraform displays the generated ox_role_arn.

1. To connect AWS in OX, go to Settings > Connectors, and select AWS.

2. Paste the ox_role_arn value.

3. Select Connect.

The AWS account is connected to OX.

Integrating OX with AWS Organizations

Use this method to connect multiple AWS accounts managed through AWS Organizations.

Deploy the Terraform configuration to each existing member account and to the management account. The deployment creates the required IAM role in every account, allowing OX to collect cloud security findings across the organization.

You can extend the integration with additional capabilities, such as Amazon EKS cluster analysis and Amazon ECR repository analysis.

After completing the deployment, connect the AWS Organizations integration in OX using the Role ARN generated for the management account.

The same External ID and IAM role name must be used across all accounts in the organization.

Before You Begin

Deploy the Terraform configuration to:

• Every member account

• The management account

The following values must be identical across all accounts:

• External ID

• IAM role name

Only the AWS credentials change between deployments.

Deploying the Terraform configuration to the management account is required.

To integrate with AWS organization account:

1. Download the Terraform file ox_aws_integration_organization.tf , and save it in an empty directory.

2. To initialize Terraform, open a terminal in the directory that contains the Terraform file, and run:

terraform init

1. For each member account, configure the account's AWS credentials, create a dedicated Terraform workspace, and deploy the integration. For example:

terraform workspace new account-111111111111

terraform apply -var="external_id=YOUR_EXTERNAL_ID"

Repeat this step for each member account.

1. Configure the management account credentials and deploy the integration. For example:

terraform workspace new management-account

terraform apply -var="external_id=YOUR_EXTERNAL_ID"

When the deployment completes, Terraform displays the generated ox_role_arn.

1. To connect AWS in OX, go to Settings > Connectors, and select AWS.

2. Paste the ox_role_arn generated by the management account deployment.

3. Select Connect.

The AWS Organization is connected to OX.

When connecting AWS Organizations, use the role ARN generated by the management account deployment.

Adding new AWS accounts

New AWS accounts added to the organization are not onboarded automatically.

To connect a new account:

1. Configure credentials for the new account.

2. Deploy the Terraform configuration.

3. Use the same External ID and IAM role name used by the existing deployments.

Enable additional AWS monitoring capabilities

By default, the Terraform deployment creates the IAM role required for the AWS integration.

If you also want OX to monitor additional AWS services, configure the corresponding Terraform variables when running the terraform apply command.

Capability	Terraform variable	Default	Description
Monitor Amazon ECR repositories	ecr_monitoring_enabled	true	Grants OX the permissions required to analyze Amazon ECR repositories.
Monitor Amazon EKS clusters	eks_monitoring_enabled	true	Grants OX the permissions required to analyze Amazon EKS clusters.
Use a custom IAM role name	iam_role_name	OxAWSIntegrationRole	Creates the connector role with a custom name instead of the default.

Example:

The following command replaces the terraform apply command shown earlier. It creates the connector role with a custom IAM role name while enabling Amazon EKS and Amazon ECR monitoring.

terraform apply \
  -var="external_id=YOUR_EXTERNAL_ID" \
  -var="iam_role_name=MyOxRole" \
  -var="eks_monitoring_enabled=true" \
  -var="ecr_monitoring_enabled=true"

You can also store these values in a terraform.tfvars file.

Disconnect AWS

Disconnecting a single AWS account

To remove the integration, run:

terraform destroy

Disconnecting AWS Organizations

To disconnect an AWS Organization:

1. Configure credentials for the account.

2. Select the account's Terraform workspace.

3. Run:

terraform destroy

Repeat for each member account and the management account.

Make sure the selected Terraform workspace matches the AWS account configured in your credentials.