Skip to content

cloudposse-terraform-components/aws-vanta

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

2 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Project Banner

Latest ReleaseSlack CommunityGet Support

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

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

Tip

πŸ‘½ Use Atmos with Terraform

Cloud Posse uses atmos to easily orchestrate multiple environments using Terraform.
Works with Github Actions, Atlantis, or Spacelift.

Watch demo of using Atmos with Terraform
Example of running atmos to manage infrastructure from our Quick Start tutorial.

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:

  1. Vanta Account: Ensure your Vanta account is active and the AWS integration is initiated in the Vanta dashboard.
  2. 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:

  1. 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
  2. Configure Regions in Vanta: Select all regions where you have resources in the Vanta AWS integration settings
  3. Wait for Initial Scan: Vanta takes up to 2 hours to complete the initial resource scan
  4. 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:

  1. Verify the external ID in defaults.yaml matches the value in the Vanta dashboard
  2. Check the trust policy allows Vanta's scanner roles:
    aws iam get-role --role-name vanta-auditor --query 'Role.AssumeRolePolicyDocument'
  3. 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:

  1. Check if VantaAdditionalPermissions policy is attached
  2. Verify SecurityAudit managed policy is current (AWS updates it automatically)
  3. For the management account, verify VantaManagementAccountPermissions is attached
  4. 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:

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

Important

In Cloud Posse's examples, we avoid pinning modules to specific versions to prevent discrepancies between the documentation and the latest released versions. However, for your own projects, we strongly advise pinning each module to the exact version you're using. This practice ensures the stability of your infrastructure. Additionally, we recommend implementing a systematic approach for updating versions to avoid unexpected changes.

Requirements

Name Version
terraform >= 1.0.0
aws >= 5.0.0

Providers

Name Version
aws >= 5.0.0
terraform n/a

Modules

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

Resources

Name Type
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
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

Inputs

Name Description Type Default Required
account_map 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).
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), {})
})
{
"audit_account_account_name": "",
"aws_partition": "aws",
"full_account_map": {},
"iam_role_arn_templates": {},
"identity_account_account_name": "",
"root_account_account_name": ""
}
no
account_map_component_name The name of the account-map component string "account-map" no
account_map_enabled 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.
bool false no
account_map_tenant The tenant where the account_map component required by remote-state is deployed string "core" no
account_verification_enabled 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.
bool true no
additional_tag_map 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.
map(string) {} no
attributes 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.
list(string) [] no
context 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.
any
{
"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
}
no
delimiter Delimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.
string null no
descriptor_formats 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).
any {} no
enabled Set to false to prevent the module from creating any resources bool null no
environment ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT' string null no
external_id 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.
string n/a yes
global_environment Global environment name string "gbl" no
iam_role_name Name of the IAM role created for Vanta string "vanta-auditor" no
id_length_limit 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.
number null no
label_key_case 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.
string null no
label_order 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.
list(string) null no
label_value_case 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.
string null no
labels_as_tags 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.
set(string)
[
"default"
]
no
management_account_permissions_enabled Enable management account permissions. When true, attaches VantaManagementAccountPermissions policy
to the role for organization-level read access. Only enable for the management (root) account.
bool false no
name 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.
string null no
namespace ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique string null no
privileged true if the default provider already has access to the backend bool false no
regex_replace_chars 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.
string null no
region AWS Region string n/a yes
root_account_stage The stage name for the Organization root (management) account. This is used to lookup account IDs from account names
using the account-map component.
string "root" no
stage ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release' string null no
tags Additional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.
map(string) {} no
tenant ID element _(Rarely used, not included by default)_. A customer identifier, indicating who this instance of a resource is for string null no
vanta_account_ids 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
list(string)
[
"956993596390",
"850507053895",
"654654195764"
]
no

Outputs

Name Description
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)

Related Projects

Check out these related projects.

  • Cloud Posse Terraform Modules - Our collection of reusable Terraform modules used by our reference architectures.
  • Atmos - Atmos is like docker-compose but for your infrastructure

References

For additional context, refer to some of these links.

Tip

Use Terraform Reference Architectures for AWS

Use Cloud Posse's ready-to-go terraform architecture blueprints for AWS to get up and running quickly.

βœ… We build it together with your team.
βœ… Your team owns everything.
βœ… 100% Open Source and backed by fanatical support.

Request Quote

πŸ“š Learn More

Cloud Posse is the leading DevOps Accelerator for funded startups and enterprises.

Your team can operate like a pro today.

Ensure that your team succeeds by using Cloud Posse's proven process and turnkey blueprints. Plus, we stick around until you succeed.

Day-0: Your Foundation for Success

  • Reference Architecture. You'll get everything you need from the ground up built using 100% infrastructure as code.
  • Deployment Strategy. Adopt a proven deployment strategy with GitHub Actions, enabling automated, repeatable, and reliable software releases.
  • Site Reliability Engineering. Gain total visibility into your applications and services with Datadog, ensuring high availability and performance.
  • Security Baseline. Establish a secure environment from the start, with built-in governance, accountability, and comprehensive audit logs, safeguarding your operations.
  • GitOps. Empower your team to manage infrastructure changes confidently and efficiently through Pull Requests, leveraging the full power of GitHub Actions.

Request Quote

Day-2: Your Operational Mastery

  • Training. Equip your team with the knowledge and skills to confidently manage the infrastructure, ensuring long-term success and self-sufficiency.
  • Support. Benefit from a seamless communication over Slack with our experts, ensuring you have the support you need, whenever you need it.
  • Troubleshooting. Access expert assistance to quickly resolve any operational challenges, minimizing downtime and maintaining business continuity.
  • Code Reviews. Enhance your team’s code quality with our expert feedback, fostering continuous improvement and collaboration.
  • Bug Fixes. Rely on our team to troubleshoot and resolve any issues, ensuring your systems run smoothly.
  • Migration Assistance. Accelerate your migration process with our dedicated support, minimizing disruption and speeding up time-to-value.
  • Customer Workshops. Engage with our team in weekly workshops, gaining insights and strategies to continuously improve and innovate.

Request Quote

✨ Contributing

This project is under active development, and we encourage contributions from our community.

Many thanks to our outstanding contributors:

For πŸ› bug reports & feature requests, please use the issue tracker.

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

  1. Review our Code of Conduct and Contributor Guidelines.
  2. Fork the repo on GitHub
  3. Clone the project to your own machine
  4. Commit changes to your own branch
  5. Push your work back up to your fork
  6. Submit a Pull Request so that we can review your changes

NOTE: Be sure to merge the latest changes from "upstream" before making a pull request!

Running Terraform Tests

We use Atmos to streamline how Terraform tests are run. It centralizes configuration and wraps common test workflows with easy-to-use commands.

All tests are located in the test/ folder.

Under the hood, tests are powered by Terratest together with our internal Test Helpers library, providing robust infrastructure validation.

Setup dependencies:

To run tests:

  • Run all tests:
    atmos test run
  • Clean up test artifacts:
    atmos test clean
  • Explore additional test options:
    atmos test --help

The configuration for test commands is centrally managed. To review what's being imported, see the atmos.yaml file.

Learn more about our automated testing in our documentation or implementing custom commands with atmos.

🌎 Slack Community

Join our Open Source Community on Slack. It's FREE for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build totally sweet infrastructure.

πŸ“° Newsletter

Sign up for our newsletter and join 3,000+ DevOps engineers, CTOs, and founders who get insider access to the latest DevOps trends, so you can always stay in the know. Dropped straight into your Inbox every week β€” and usually a 5-minute read.

πŸ“† Office Hours

Join us every Wednesday via Zoom for your weekly dose of insider DevOps trends, AWS news and Terraform insights, all sourced from our SweetOps community, plus a live Q&A that you can’t find anywhere else. It's FREE for everyone!

License

License

Preamble to the Apache License, Version 2.0

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

Trademarks

All other trademarks referenced herein are the property of their respective owners.


Copyright Β© 2017-2026 Cloud Posse, LLC

README footer

Beacon

About

This component provisions the vanta-auditor IAM role for Vanta GRC platform integration

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

No releases published

Packages

 
 
 

Contributors