> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/ox-integrations/3rd-party-integrations/cloud-security/aws/aws-with-terraform.md).

# 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](#integrating-ox-with-a-single-aws-account)
* [Multiple accounts managed through AWS Organizations](#integrating-ox-with-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:

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

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

```bash
terraform init
```

4. To deploy the integration, run:

```bash
terraform apply -var="external_id=YOUR_EXTERNAL_ID"
```

5. Review the planned changes and enter `yes` when prompted.

When the deployment completes, Terraform displays the generated `ox_role_arn`.

6. To connect AWS in OX, go to **Settings > Connectors**, and select **AWS**.
7. Paste the `ox_role_arn` value.
8. 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.

{% hint style="info" %}
Deploying the Terraform configuration to the management account is required.
{% endhint %}

**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:

```bash
terraform init
```

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

```bash
terraform workspace new account-111111111111

terraform apply -var="external_id=YOUR_EXTERNAL_ID"
```

Repeat this step for each member account.

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

```bash
terraform workspace new management-account

terraform apply -var="external_id=YOUR_EXTERNAL_ID"
```

When the deployment completes, Terraform displays the generated `ox_role_arn`.

5. To connect AWS in OX, go to **Settings > Connectors**, and select **AWS**.
6. Paste the `ox_role_arn` generated by the management account deployment.
7. Select **Connect**.

The AWS Organization is connected to OX.<br>

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.

```bash
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:

```bash
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:

```bash
terraform destroy
```

Repeat for each member account and the management account.

{% hint style="info" %}
Make sure the selected Terraform workspace matches the AWS account configured in your credentials.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ox.security/ox-integrations/3rd-party-integrations/cloud-security/aws/aws-with-terraform.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.