AWS

The AWS Cloud Account uses a cross-account IAM role to access your AWS infrastructure for resource autodiscovery and log forwarding.

What Formal Discovers

RDS Autodiscovery

Automatically discover PostgreSQL, MySQL, and MongoDB RDS instances and add them as Formal resources.

Redshift Autodiscovery

Discover Redshift clusters and data warehouses.

EKS Autodiscovery

Discover EKS clusters for Kubernetes access control.

EC2 Autodiscovery

Discover EC2 instances for SSH access.

ECS Autodiscovery

Discover ECS clusters, services, and containers for SSH access via the Desktop App.

S3 Bucket Autodiscovery

Discover S3 buckets for access via the Desktop App.

S3 Log Forwarding

Forward Formal Connector logs to S3 buckets for long-term storage and compliance.

Architecture

Formal uses AWS’s Cross-Account IAM Role architecture:

CloudFormation Stack: deploys an IAM role in your AWS account
IAM Role: grants Formal specific, scoped permissions
External ID: a unique identifier that prevents unauthorized access
Role Chaining: Formal uses IAM User → IAM Role → your IAM Role for added security

Supported Regions

The CloudFormation stack can be deployed in:

us-east-1, us-east-2, us-west-1, us-west-2
eu-central-1, eu-west-1, eu-west-2, eu-west-3

The IAM role provides global access, allowing Formal to discover resources across all AWS regions.

Setup

Web Console
Terraform
Terraform (without CloudFormation)

Navigate to Cloud Accounts

Go to Cloud Accounts

Add Integration

Click Add Integration

Select AWS

Choose AWS as your cloud provider

Deploy CloudFormation

Click the provided link to deploy the CloudFormation template in your AWS account.The template creates an IAM role with the necessary permissions.

Configure Permissions

Enable the features you need:

RDS Autodiscovery
Redshift Autodiscovery
EKS Autodiscovery
EC2 Autodiscovery
ECS Autodiscovery
S3 Autodiscovery
S3 Write Access (for log forwarding)

Complete Setup

Once CloudFormation deployment completes, your AWS integration is active.

# 1. Create S3 bucket for logs (optional)
resource "aws_s3_bucket" "formal_logs" {
  bucket = "formal-connector-logs"
}

# 2. Create Formal Cloud Integration
resource "formal_integration_cloud" "aws" {
  name         = "production-aws"
  cloud_region = "us-east-1"
  
  aws {
    template_version              = "1.4.0"  # Pin to specific version
    enable_rds_autodiscovery      = true
    enable_redshift_autodiscovery = true
    enable_eks_autodiscovery      = true
    enable_ec2_autodiscovery      = true
    enable_ecs_autodiscovery      = true
    enable_s3_autodiscovery       = true
    allow_s3_access               = true
    s3_bucket_arn                 = "${aws_s3_bucket.formal_logs.arn}/*"
  }
}

# 3. Deploy CloudFormation Stack
resource "aws_cloudformation_stack" "formal" {
  name          = formal_integration_cloud.aws.aws_formal_stack_name
  template_body = formal_integration_cloud.aws.aws_template_body
  
  parameters = {
    FormalIntegrationId         = formal_integration_cloud.aws.id
    FormalIAMRoleId             = formal_integration_cloud.aws.aws_formal_iam_role
    FormalSNSTopicARN           = formal_integration_cloud.aws.aws_formal_pingback_arn
    EnableRDSAutodiscovery      = formal_integration_cloud.aws.aws_enable_rds_autodiscovery
    EnableRedshiftAutodiscovery = formal_integration_cloud.aws.aws_enable_redshift_autodiscovery
    EnableEKSAutodiscovery      = formal_integration_cloud.aws.aws_enable_eks_autodiscovery
    EnableEC2Autodiscovery      = formal_integration_cloud.aws.aws_enable_ec2_autodiscovery
    EnableECSAutodiscovery      = formal_integration_cloud.aws.aws_enable_ecs_autodiscovery
    EnableS3Autodiscovery       = formal_integration_cloud.aws.aws_enable_s3_autodiscovery
    AllowS3Access               = formal_integration_cloud.aws.aws_allow_s3_access
    S3BucketARN                 = formal_integration_cloud.aws.aws_s3_bucket_arn
  }
  
  capabilities = ["CAPABILITY_NAMED_IAM"]
}

If not using CloudFormation, the IAM role name needs to be pre-declared. This is because the role needs the Formal principal ARN for its trust policy, but the integration needs the role ARN to generate that principal. Since IAM role ARNs are predictable, you can pass the ARN before the role exists, allowing the below example to create both resources in a single apply.

locals {
  formal_integration_role_name = "FormalIntegrationRole"
  s3_log_forwarding_bucket_arn = "arn:aws:s3:::formal-logs-forwarder/*"
}

resource "formal_integration_cloud" "aws" {
  name         = "production-aws"
  cloud_region = "us-east-1"

  aws {
    aws_customer_role_arn = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:role/${locals.formal_integration_role_name}"
    enable_eks_autodiscovery = true
    enable_ec2_autodiscovery = true
    enable_ecs_autodiscovery = true
    enable_rds_autodiscovery = true
    enable_s3_autodiscovery = true
    allow_s3_access = true
    s3_bucket_arn = locals.s3_log_forwarding_bucket_arn
  }
}

resource "aws_iam_role" "formal" {
  name = locals.formal_integration_role_name

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action = "sts:AssumeRole"
        Effect = "Allow"
        Principal = {
          AWS = formal_integration_cloud.aws.aws_formal_iam_role
        }
        Condition = {
          StringEquals = {
            sts:ExternalId = formal_integration_cloud.aws.id
          }
        }
      }
    ]
  })

  inline_policy = {
    name = "FormalIntegrationRolePolicy"
    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [
        {
          Effect = "Allow"
          Action = [
            "sts:GetCallerIdentity",
            "eks:ListClusters",
            "eks:DescribeCluster",
            "ec2:DescribeInstances",
            "ec2:DescribeRegions",
            "ecs:ListClusters",
            "ecs:DescribeClusters",
            "ecs:ListTasks",
            "ecs:DescribeTasks",
            "ecs:ListServices",
            "ecs:DescribeServices",
            "rds:DescribeDBInstances",
            "s3:ListAllMyBuckets",
            "s3:HeadBucket",
          ]
          Resource = ["*"]
        },
        {
          Effect = "Allow"
          Action = [
            "s3:PutObject",
          ]
          Resource = [locals.s3_log_forwarding_bucket_arn]
        }
      ]
    })
  }
}

CloudFormation Parameters

Parameter	Description	Default
`EnableRDSAutodiscovery`	Discover RDS databases (PostgreSQL, MySQL, MongoDB)	`false`
`EnableRedshiftAutodiscovery`	Discover Redshift clusters	`false`
`EnableEKSAutodiscovery`	Discover EKS clusters	`false`
`EnableEC2Autodiscovery`	Discover EC2 instances	`false`
`EnableECSAutodiscovery`	Discover ECS clusters and containers	`false`
`EnableS3Autodiscovery`	Discover S3 buckets	`false`
`AllowS3Access`	Allow log forwarding to S3	`false`
`S3BucketARN`	S3 bucket ARN for logs (if `AllowS3Access` is true)	`""`

Versioning

The CloudFormation template is versioned for stability:

aws {
  template_version = "1.2.0"  # Pin to specific version
  # ...
}

Benefits of version pinning:

Predictable IAM permissions
Controlled feature adoption
Easier compliance auditing
Prevents unexpected changes

Using latest:

aws {
  template_version = "latest"  # Always use newest version
  # ...
}

See the CloudFormation Changelog for version history.

Security

Formal implements multiple security layers:

Role Chaining: IAM User → IAM Role in Formal account → IAM Role in your account
External ID: a unique per-customer identifier that prevents cross-tenant access
Least Privilege: CloudFormation grants only required permissions
Scoped Permissions: enable only the features you need

Example: if you only enable RDS autodiscovery, the IAM role cannot access EKS, EC2, or S3.

Discovered Resources

Once the integration is active, Formal scans your AWS account and creates matching Formal resources:

RDS instance prod-postgres-1 → Formal resource prod-postgres-1
EKS cluster production-eks → Formal resource production-eks
EC2 instance i-abc123 → Formal resource ec2-i-abc123

Discovery is continuous and resource tags sync to Formal. See Resource Autodiscovery for how discovered resources behave and how to override them.

Multiple Accounts

Create a separate integration for each AWS account to keep environments isolated:

# Production account
resource "formal_integration_cloud" "aws_prod" {
  name         = "aws-production"
  cloud_region = "us-east-1"

  aws {
    template_version         = "1.2.0"
    enable_rds_autodiscovery = true
  }
}

# Staging account
resource "formal_integration_cloud" "aws_staging" {
  name         = "aws-staging"
  cloud_region = "us-west-2"

  aws {
    template_version         = "1.2.0"
    enable_rds_autodiscovery = true
  }
}

Troubleshooting

CloudFormation deployment fails

Possible causes:

Insufficient IAM permissions to create roles
Stack name conflict
Region not supported

Solution:

Ensure the deploying user has IAM role creation permissions
Use the unique stack name provided by Formal
Deploy in a supported region

Resources not discovered

Possible causes:

Autodiscovery not enabled for that resource type
Resources in an unsupported region
IAM permissions insufficient

Solution:

Verify the autodiscovery toggle is enabled in the Formal console
Check the resources exist in AWS
Review the CloudFormation IAM role permissions
Wait a few minutes for the initial scan

S3 log forwarding not working

Possible causes:

S3 bucket ARN incorrect
IAM role lacks S3 permissions
Log integration not configured

Solution:

Verify s3_bucket_arn matches the permissions you want to grant on objects (e.g., use a /* suffix for all files)
Ensure allow_s3_access is enabled
Create a Log Integration pointing to this cloud integration

Next Steps

Log Integration

Forward logs to S3

Add Resources

Manually configure discovered resources

Terraform

Manage integrations as code

View Resources

See all autodiscovered resources

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

What Formal Discovers

Architecture

Supported Regions

Setup

CloudFormation Parameters

Versioning

Security

Discovered Resources

Multiple Accounts

Troubleshooting

Next Steps

Log Integration

Add Resources

Terraform

View Resources

​What Formal Discovers

​Architecture

​Supported Regions

​Setup

​CloudFormation Parameters

​Versioning

​Security

​Discovered Resources

​Multiple Accounts

​Troubleshooting

​Next Steps

Log Integration

Add Resources

Terraform

View Resources

What Formal Discovers

Architecture

Supported Regions

Setup

CloudFormation Parameters

Versioning

Security

Discovered Resources

Multiple Accounts

Troubleshooting

Next Steps