Version: Latest

vanta

This component provisions the vanta-auditor IAM role in each AWS account, enabling the Vanta GRC (Governance, Risk, and Compliance) platform to continuously scan AWS resource configurations. Vanta uses this read-only access to map evidence to compliance frameworks (SOC 2, ISO 27001, HIPAA, PCI DSS, GDPR, etc.).

Important: This component only provisions the IAM role and policies on the AWS side. Configuration, administration, and operation of the Vanta platform itself is managed externally.

Component Features

This component is responsible for:

Cross-Account IAM Role: Creates a vanta-auditor IAM role that Vanta's scanner role can assume
Read-Only Access: Attaches the AWS managed SecurityAudit policy for broad read-only security access
Supplemental Permissions: Creates and attaches a VantaAdditionalPermissions custom policy with IAM Identity Center read access and explicit deny on sensitive data (RDS logs, DataPipeline data)
Management Account Support: Optionally attaches VantaManagementAccountPermissions for organization-level reads (only in the root account)
External ID Protection: Uses an external ID in the trust policy to prevent confused deputy attacks
Account Verification: Optional safety check that validates Terraform is running in the correct AWS account

Key Capabilities

Read-Only: Vanta cannot modify any AWS resources — all permissions are read-only or describe/list
Metadata Only: Scans resource configurations and metadata, not application data
Automatic Evidence Collection: Vanta continuously maps AWS configurations to compliance controls
Multi-Framework Support: SOC 2, ISO 27001, HIPAA, PCI DSS, GDPR, and custom frameworks
Audit Trail: All Vanta API calls are logged in CloudTrail as AssumeRole from Vanta's scanner roles

Architecture

The component deploys a simple per-account IAM role with no cross-account dependencies:

                     AWS Organization

   Vanta Platform (scanner roles from multiple Vanta AWS accounts)
        │
        │  sts:AssumeRole (with ExternalId)
        │
        ├──► management account ── vanta-auditor role + SecurityAudit
        │                          + VantaAdditionalPermissions
        │                          + VantaManagementAccountPermissions
        │
        ├──► security account   ── vanta-auditor role + SecurityAudit
        │                          + VantaAdditionalPermissions
        │
        ├──► audit account      ── vanta-auditor role + SecurityAudit
        │                          + VantaAdditionalPermissions
        │
        ├──► network account    ── (same as above)
        ├──► dns account        ── (same as above)
        ├──► automation account ── (same as above)
        ├──► artifacts account  ── (same as above)
        ├──► dev account        ── (same as above)
        ├──► staging account    ── (same as above)
        └──► prod account       ── (same as above)

Why This Architecture?

Per-Account Role: Each account needs its own IAM role because Vanta scans resources per-account
No Delegated Administrator: Unlike GuardDuty/Security Hub, Vanta does not use AWS Organizations delegation
No Cross-Account Dependencies: Each account's role is independent — all accounts can be deployed in parallel
Management Account Extra Policy: Only the root account needs organization-level read access for account enumeration

Vanta Connection Types

When connecting AWS in the Vanta dashboard, there are two options:

Individual Account — Connect one AWS account at a time. You paste each account's role ARN into the Vanta dashboard manually. If new accounts are added to the organization later, they must be connected manually in Vanta.

Organization (recommended) — Connect once using the management account. Vanta automatically discovers all accounts in the AWS Organization and scans them. New accounts added in the future are picked up automatically.

Aspect	Individual Account	Organization
Scope	One account at a time	All accounts in the AWS Organization
Auto-discovery	No — each account connected manually	Yes — new accounts auto-detected
IAM Role/Policies	Identical	Identical
Management Account	No special requirements	Needs `VantaManagementAccountPermissions` for enumeration

What Changes on the AWS Side?

Nothing. Both methods require the same vanta-auditor IAM role in every account (the management account always includes the extra VantaManagementAccountPermissions policy regardless of connection type). The only difference is how the Vanta platform discovers accounts:

Individual: You tell Vanta about each account by pasting the role ARN
Organization: Vanta calls organizations:ListAccounts from the management account role to enumerate all accounts, then assumes the vanta-auditor role in each one

Deployment Model Comparison

Vanta vs Other AWS Security Services

Aspect	Vanta Integration	AWS GuardDuty	AWS Config
Purpose	GRC evidence collection	Threat detection	Configuration compliance
Deployment Approach	Per-account IAM role	Delegated administrator (3 steps)	Per-account with aggregation
Central Account	N/A (Vanta is external SaaS)	Security (delegated administrator)	Security (aggregator)
Organization-Wide	No (per account)	Yes	Yes (conformance packs from root)
Access Type	Read-only (cross-account)	Service-managed	Service-managed

IAM Policies

SecurityAudit (AWS Managed)

ARN: arn:aws:iam::aws:policy/SecurityAudit
Purpose: Broad read-only access to security-relevant configurations across all AWS services
Maintained by: AWS — automatically updated when new services are added
Scope: Describe, Get, List actions across IAM, EC2, S3, RDS, Lambda, ECS, EKS, and many more

VantaAdditionalPermissions (Custom)

Supplements SecurityAudit with Identity Center permissions and denies access to sensitive data:

Statement	Effect	Purpose
VantaIdentityCenterPermissions	Allow	IAM Identity Center scanning
VantaDenyDataAccess	Deny	Block access to sensitive data

VantaManagementAccountPermissions (Custom, root only)

Organization-level read access for the management account:

Statement	Effect	Purpose
VantaManagementAccountPermissions	Allow	Enumerate org structure

Security Considerations

Read-Only Access: All permissions are read-only — Vanta cannot create, modify, or delete any AWS resources
Explicit Deny: Sensitive data actions are explicitly denied, even if SecurityAudit would allow them
External ID: The trust policy requires a matching external ID, preventing confused deputy attacks
Scoped Principal: The trust policy allows only Vanta's scanner roles from specific AWS accounts, not entire accounts
CloudTrail Audit: Every API call from Vanta is logged in CloudTrail
Minimal Permissions: The management account policy only grants organization read access, not administrative permissions

Usage

Stack Level: Global

The following are example snippets for how to use this component.

Default Configuration (`stacks/catalog/aws-vanta/defaults.yaml`)

components:
  terraform:
    aws-vanta/defaults:
      metadata:
        type: abstract
        component: "aws-vanta"
      vars:
        enabled: true
        iam_role_name: "vanta-auditor"
        external_id: "<external-id-from-vanta-dashboard>"
        management_account_permissions_enabled: false

Member Account Configuration (`stacks/catalog/aws-vanta/member-account.yaml`)

import:
  - catalog/aws-vanta/defaults

components:
  terraform:
    aws-vanta:
      metadata:
        component: "aws-vanta"
        inherits:
          - "aws-vanta/defaults"

Management Account Configuration (`stacks/catalog/aws-vanta/management-account.yaml`)

import:
  - catalog/aws-vanta/defaults

components:
  terraform:
    aws-vanta:
      metadata:
        component: "aws-vanta"
        inherits:
          - "aws-vanta/defaults"
      vars:
        management_account_permissions_enabled: true

Prerequisites

Before deploying this component:

Vanta Account: Ensure your Vanta account is active and the AWS integration is initiated in the Vanta dashboard.
Vanta External ID: Obtain the external ID from the Vanta dashboard and configure it in defaults.yaml.

Provisioning

No Dependencies — Deploy All Accounts in Parallel

Unlike other security services, Vanta has no inter-service dependencies. All accounts can be provisioned simultaneously.

# Management account:
atmos terraform apply aws-vanta -s core-gbl-root

# Core tenant:
atmos terraform apply aws-vanta -s core-gbl-security
atmos terraform apply aws-vanta -s core-gbl-audit
atmos terraform apply aws-vanta -s core-gbl-auto
atmos terraform apply aws-vanta -s core-gbl-artifacts
atmos terraform apply aws-vanta -s core-gbl-dns
atmos terraform apply aws-vanta -s core-gbl-network

# Platform tenant:
atmos terraform apply aws-vanta -s plat-gbl-sandbox
atmos terraform apply aws-vanta -s plat-gbl-dev
atmos terraform apply aws-vanta -s plat-gbl-staging
atmos terraform apply aws-vanta -s plat-gbl-prod

Post-Deployment Steps

After all IAM roles are deployed:

Provide Management Account Role ARN to Vanta: Copy the vanta_auditor_role_arn output from the management account deployment and enter it in the Vanta dashboard
Configure Regions in Vanta: Select all regions where you have resources in the Vanta AWS integration settings
Wait for Initial Scan: Vanta takes up to 2 hours to complete the initial resource scan
Verify Connection: Check the Vanta dashboard for successful integration status across all accounts

Troubleshooting

Vanta Cannot Assume Role

Problem: Vanta dashboard shows "Unable to connect" or "Access denied" for an account.

Solution:

Verify the external ID in defaults.yaml matches the value in the Vanta dashboard

Check the trust policy allows Vanta's scanner roles:

aws iam get-role --role-name vanta-auditor --query 'Role.AssumeRolePolicyDocument'

Verify both policies are attached:

aws iam list-attached-role-policies --role-name vanta-auditor

Missing Permissions in Vanta Scan

Problem: Vanta reports incomplete scans or missing evidence for certain services.

Solution:

Check if VantaAdditionalPermissions policy is attached
Verify SecurityAudit managed policy is current (AWS updates it automatically)
For the management account, verify VantaManagementAccountPermissions is attached
Check Vanta's help docs for any newly required permissions

External ID Changed

Problem: Vanta regenerated the external ID and existing roles no longer work.

Solution:

Update external_id in stacks/catalog/aws-vanta/defaults.yaml
Redeploy all accounts

Variables

Required Variables

external_id (string) required: External ID from the Vanta UI used in the IAM role trust policy to prevent confused deputy attacks.
Obtain this value from the Vanta dashboard or from your Vanta consultant.
region (string) required: AWS Region

Optional Variables

account_map optional

Static account map configuration. Only used when account_map_enabled is false.
Map keys use tenant-stage format (e.g., core-security, core-audit, plat-prod).

Type:

object({
full_account_map              = map(string)
audit_account_account_name    = optional(string, "")
root_account_account_name     = optional(string, "")
identity_account_account_name = optional(string, "")
aws_partition                 = optional(string, "aws")
iam_role_arn_templates        = optional(map(string), {})
})

Default value:

{
  "audit_account_account_name": "",
  "aws_partition": "aws",
  "full_account_map": {},
  "iam_role_arn_templates": {},
  "identity_account_account_name": "",
  "root_account_account_name": ""
}

account_map_component_name (string) optional

The name of the account-map component

Default value: "account-map"

account_map_enabled (bool) optional

Enable the account map component. When true, the component fetches account mappings from the
account-map component via remote state. When false (default), the component uses the static account_map variable instead.

Default value: false

account_map_tenant (string) optional

The tenant where the account_map component required by remote-state is deployed

Default value: "core"

account_verification_enabled (bool) optional

Enable account verification. When true (default), the component verifies that Terraform is executing
in the correct AWS account by comparing the current account ID against the expected account from the
account_map based on the component's tenant-stage context.

Default value: true

global_environment (string) optional

Global environment name

Default value: "gbl"

iam_role_name (string) optional

Name of the IAM role created for Vanta

Default value: "vanta-auditor"

management_account_permissions_enabled (bool) optional

Enable management account permissions. When true, attaches VantaManagementAccountPermissions policy
to the role for organization-level read access. Only enable for the management (root) account.

Default value: false

privileged (bool) optional

true if the default provider already has access to the backend

Default value: false

root_account_stage (string) optional

The stage name for the Organization root (management) account. This is used to lookup account IDs from account names
using the account-map component.

Default value: "root"

vanta_account_ids (list(string)) optional

List of Vanta's AWS account IDs used in the IAM role trust policy for cross-account access.
Vanta operates from multiple AWS accounts across regions. All three must be trusted for full
multi-region support. See: https://help.vanta.com/en/articles/11345698-porting-aws-integrations-across-regions

Default value:

[
  "956993596390",
  "850507053895",
  "654654195764"
]

Context Variables

The following variables are defined in the context.tf file of this module and part of the terraform-null-label pattern.

additional_tag_map (map(string)) optional

Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.

Required: No

Default value: { }

attributes (list(string)) optional

ID element. Additional attributes (e.g. workers or cluster) to add to id,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the delimiter
and treated as a single ID element.

Required: No

Default value: [ ]

context (any) optional

Single object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as null to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.

Required: No

Default value:

{
  "additional_tag_map": {},
  "attributes": [],
  "delimiter": null,
  "descriptor_formats": {},
  "enabled": true,
  "environment": null,
  "id_length_limit": null,
  "label_key_case": null,
  "label_order": [],
  "label_value_case": null,
  "labels_as_tags": [
    "unset"
  ],
  "name": null,
  "namespace": null,
  "regex_replace_chars": null,
  "stage": null,
  "tags": {},
  "tenant": null
}

delimiter (string) optional

Delimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.

Required: No

Default value: null

descriptor_formats (any) optional

Describe additional descriptors to be output in the descriptors output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
\{<br/> format = string<br/> labels = list(string)<br/> \}
(Type is any so the map values can later be enhanced to provide additional options.)
format is a Terraform format string to be passed to the format() function.
labels is a list of labels, in order, to pass to format() function.
Label values will be normalized before being passed to format() so they will be
identical to how they appear in id.
Default is {} (descriptors output will be empty).

Required: No

Default value: { }

enabled (bool) optional

Set to false to prevent the module from creating any resources
Required: No

Default value: null

environment (string) optional

ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'
Required: No

Default value: null

id_length_limit (number) optional

Limit id to this many characters (minimum 6).
Set to 0 for unlimited length.
Set to null for keep the existing setting, which defaults to 0.
Does not affect id_full.

Required: No

Default value: null

label_key_case (string) optional

Controls the letter case of the tags keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the tags input.
Possible values: lower, title, upper.
Default value: title.

Required: No

Default value: null

label_order (list(string)) optional

The order in which the labels (ID elements) appear in the id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.

Required: No

Default value: null

label_value_case (string) optional

Controls the letter case of ID elements (labels) as included in id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the tags input.
Possible values: lower, title, upper and none (no transformation).
Set this to title and set delimiter to "" to yield Pascal Case IDs.
Default value: lower.

Required: No

Default value: null

labels_as_tags (set(string)) optional

Set of labels (ID elements) to include as tags in the tags output.
Default is to include all labels.
Tags with empty values will not be included in the tags output.
Set to [] to suppress all generated tags.
Notes:
The value of the name tag, if included, will be the id, not the name.
Unlike other null-label inputs, the initial setting of labels_as_tags cannot be
changed in later chained modules. Attempts to change it will be silently ignored.

Required: No

Default value:

[
  "default"
]

name (string) optional

ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a tag.
The "name" tag is set to the full id string. There is no tag with the value of the name input.

Required: No

Default value: null

namespace (string) optional

ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique
Required: No

Default value: null

regex_replace_chars (string) optional

Terraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.

Required: No

Default value: null

stage (string) optional

ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'
Required: No

Default value: null

tags (map(string)) optional

Additional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.

Required: No

Default value: { }

tenant (string) optional

ID element (Rarely used, not included by default). A customer identifier, indicating who this instance of a resource is for
Required: No

Default value: null

Outputs

vanta_additional_permissions_policy_arn: ARN of the VantaAdditionalPermissions IAM policy
vanta_auditor_role_arn: ARN of the Vanta auditor IAM role
vanta_auditor_role_name: Name of the Vanta auditor IAM role
vanta_management_account_permissions_policy_arn: ARN of the VantaManagementAccountPermissions IAM policy (management account only)

Dependencies

Requirements

terraform, version: >= 1.0.0
aws, version: >= 5.0.0

Providers

aws, version: >= 5.0.0
terraform

Modules

Name	Version	Source	Description
`account_map`	2.0.0	`cloudposse/stack-config/yaml//modules/remote-state`	n/a
`this`	0.25.0	`cloudposse/label/null`	n/a

Resources

The following resources are used by this module:

aws_iam_policy.vanta_additional_permissions (resource)
aws_iam_policy.vanta_management_account_permissions (resource)
aws_iam_role.vanta_auditor (resource)
aws_iam_role_policy_attachment.security_audit (resource)
aws_iam_role_policy_attachment.vanta_additional_permissions (resource)
aws_iam_role_policy_attachment.vanta_management_account_permissions (resource)
terraform_data.account_verification (resource)

Data Sources

The following data sources are used by this module:

aws_caller_identity.current (data source)
aws_iam_policy_document.assume_role (data source)
aws_iam_policy_document.vanta_additional_permissions (data source)
aws_iam_policy_document.vanta_management_account_permissions (data source)
aws_partition.current (data source)

Component Features​

Key Capabilities​

Architecture​

Why This Architecture?​

Vanta Connection Types​

What Changes on the AWS Side?​

Deployment Model Comparison​

Vanta vs Other AWS Security Services​

IAM Policies​

SecurityAudit (AWS Managed)​

VantaAdditionalPermissions (Custom)​

VantaManagementAccountPermissions (Custom, root only)​

Security Considerations​

Usage​

Default Configuration (stacks/catalog/aws-vanta/defaults.yaml)​

Member Account Configuration (stacks/catalog/aws-vanta/member-account.yaml)​

Management Account Configuration (stacks/catalog/aws-vanta/management-account.yaml)​

Prerequisites​

Provisioning​

No Dependencies — Deploy All Accounts in Parallel​

Post-Deployment Steps​

Troubleshooting​

Vanta Cannot Assume Role​

Missing Permissions in Vanta Scan​

External ID Changed​

Variables​

Required Variables​

Optional Variables​

Context Variables​

Outputs​

Dependencies​

Requirements​

Providers​

Modules​

Resources​

Data Sources​

Component Features

Key Capabilities

Architecture

Why This Architecture?

Vanta Connection Types

What Changes on the AWS Side?

Deployment Model Comparison

Vanta vs Other AWS Security Services

IAM Policies

SecurityAudit (AWS Managed)

VantaAdditionalPermissions (Custom)

VantaManagementAccountPermissions (Custom, root only)

Security Considerations

Usage

Default Configuration (`stacks/catalog/aws-vanta/defaults.yaml`)

Member Account Configuration (`stacks/catalog/aws-vanta/member-account.yaml`)

Management Account Configuration (`stacks/catalog/aws-vanta/management-account.yaml`)

Prerequisites

Provisioning

No Dependencies — Deploy All Accounts in Parallel

Post-Deployment Steps

Troubleshooting

Vanta Cannot Assume Role

Missing Permissions in Vanta Scan

External ID Changed

Variables

Required Variables

Optional Variables

Context Variables

Outputs

Dependencies

Requirements

Providers

Modules

Resources

Data Sources