Security model

Purpose of this document

This document explains the security model of HCP Terraform and the security controls available to end users. Additionally, it provides best practices for securely managing your infrastructure with HCP Terraform.

Important concepts

Projects, workspaces, and teams

HCP Terraform organizes infrastructure with workspaces. Workspaces represent a logical security boundary within the organization. Variables, state, SSH keys, and log output are local to a workspace. You can grant teams read, plan, write, admin, or a customized set of permissions within a workspace.

Projects let you group related workspaces in your organization. You can use projects to assign read, write, maintain, admin, or a customized set of permissions to a particular team which grants specific permissions to all workspaces in the project.

Terraform runs - plans and applies

HCP Terraform will provision infrastructure according to your Terraform configuration which you can upload through the VCS-driven, API-driven, or CLI-driven workflows. You can read more about the different workflows here. It’s important to note that HCP Terraform performs all Terraform operations within the same privilege context. Both the plan and apply operations have access to the full workspace variables, state versions, and Terraform configuration.

Terraform state file

HCP Terraform retains the current and all historical state versions for each workspace. Depending on the resources that are used in your Terraform configuration, these state versions may contain sensitive data such as database passwords, resource IDs, etc.

Personas

Organization owners

Members of the owners team have administrator-level privileges within an organization. Members of this team will have access to workspaces, projects, and settings within the organization. This role is intended for users who will perform administrative tasks in your organization.

Workspace and project team members

Teams let you group users within an organization. You can grant teams read, plan, write, admin, or a customized set of permissions, each of which allow them to perform various functions within the workspace. You can also grant teams read, write, maintain, admin, or a customized set of permissions for a project, which grants specific permissions to any workspaces in that project. At a higher level, you can use organization-level privileges, which apply to projects and workspaces across the organization.

Contributors to connected VCS repositories

HCP Terraform executes Terraform configuration from connected VCS repositories. Depending on the configuration, HCP Terraform may automatically trigger Terraform operations when the connected repositories receive new contributions.

Authorization model

Click on the diagram for a larger view.

Workspaces provide a logical security boundary within the organization. Environment variables and Terraform configurations are isolated within a workspace, and access to a workspace is granted on a per-team basis.

All organizations in HCP Terraform contain an “owners” team, which grants admin-level access to the organization and all its workspaces.

All workspaces in an organization belong to a project. You can grant teams read, write, maintain, admin, or a customized set of permissions for the project, which grants specific permissions on on all workspaces within the project. You can also grant teams read, plan, write, admin, or a customized set of permissions for a specific workspace. It’s important to note that, from a security perspective, the plan permission is equivalent to the write permission. The plan permission is provided to protect against accidental Terraform runs but is not intended to stop malicious actors from accessing sensitive data within a workspace. Terraform plan and apply operations can execute arbitrary code within the ephemeral build environment. Both of these operations happen in the same security context with access to the full set of workspace variables, Terraform configuration, and Terraform state.

By default, Teams with read privileges within a workspace can view the workspace's state. You can remove this access by using customized workspace permissions; however, this will only apply to state file access through the API or UI. Terraform must access the state file in order to perform plan and apply operations, so any user with the ability to upload Terraform configurations and initiate runs will transitively have access to the workspaces' state.

State may be shared across workspaces via the remote state access workspace setting.

Terraform configuration files in connected VCS repositories are inherently trusted. Commits to connected repositories will automatically queue a plan within the corresponding workspace. Pull requests to connected repositories will initiate a speculative plan, though this behavior may be disabled via the speculative plan setting on the workspace settings page. HCP Terraform has no knowledge of your VCS's authorization controls and does not associate HCP Terraform user accounts with VCS user accounts — the two should be considered separate identities.

Threat model

HCP Terraform is designed to execute Terraform operations and manage the state file to ensure that infrastructure is reliably created, updated, and destroyed by multiple users of an organization.

The following are part of the HCP Terraform threat model:

Confidentiality and integrity of communication between Terraform clients and HCP Terraform

All communication between clients and HCP Terraform is encrypted end-to-end using TLS. HCP Terraform currently supports TLS version 1.2. HCP Terraform communicates with linked VCS repositories using the Oauth2 authorization protocol. HCP Terraform can also be configured to fetch Terraform modules from private repositories using the SSH protocol with a customer-provided private key.

Confidentiality of state versions, Terraform configurations, and stored variables

As a user, you will entrust HCP Terraform with information that is very sensitive to your organization such as API tokens, your Terraform configurations, and your Terraform state file. HCP Terraform is designed to ensure the confidentiality of this information, it relies on Vault Transit for encrypting workspace variables. Terraform configurations and state are encrypted at rest with uniquely derived encryption keys backed by Vault. You can view how all customer data is encrypted and stored on our data security page.

Enforcement of authentication and authorization policies for data access and actions taken through the UI or API

HCP Terraform enforces authorization checks for all actions taken within the API or through the UI. More information about HCP Terraform workspace-level and organization level permission are available here.

Isolation of Terraform executions

Each Terraform operation (plan and apply) happens in an ephemeral environment that is created immediately before the run and destroyed after it is completed. The build environment is designed to provide isolation between Terraform executions and between HCP Terraform tenants.

Reliability and availability of HCP Terraform

HCP Terraform is spread across multiple availability zones for reliability, we perform regular backups of our production data stores and have a process for recovering in case of a major outage.

What isn’t part of the threat model

Malicious contributions to Terraform configuration in VCS repositories

Commits and pull requests to connected VCS repositories will trigger a plan operation within the workspace. HCP Terraform does not perform any authentication or authorization checks against commits in linked VCS repositories, and cannot prevent malicious Terraform configuration from exfiltrating sensitive data during plan operations. For this reason, it is important to restrict access to connected VCS repositories. Speculative plans for pull requests may be disabled on the workspace settings page.

Malicious Terraform providers or modules

Terraform providers and modules used in your Terraform configuration will have full access to the variables and Terraform state within a workspace. HCP Terraform cannot prevent malicious providers and modules from exfiltrating this sensitive data. We recommend only using trusted modules and providers within your Terraform configuration.

Malicious bypasses of Terraform policies

The policy-as-code frameworks used by the Terraform Policy Enforcement feature are embedded within HCP Terraform and can be used to ensure the infrastructure provisioned using Terraform complies with defined organizational policies. The goal of this feature is to enforce compliance with organizational policies and best practices when provisioning infrastructure using Terraform.

It is important to note that the policy-as-code integration in HCP Terraform should be viewed as a guide or set of guardrails, not a security boundary. It is not designed to prevent malicious actors from executing malicious Terraform configurations or modifying infrastructure.

Malicious or insecure third-party run tasks

Terraform Run Tasks are provided with access to all Terraform configuration and plan data. HCP Terraform does not have the capability to prevent malicious Run Tasks from potentially exfiltrating sensitive data that may be present in either the Terraform configuration or plan.

In order to minimize potential security risks, it is highly recommended to only utilize trusted technology partners for Run Tasks within your Terraform organization and limit the number of users who have been assigned the Manage Run Tasks permission.

Access to sensitive variables or state from Terraform operations

Marking a variable as “sensitive” will prevent it from being displayed in the UI, but will not prevent it from being read by Terraform during plan or apply operations. Similarly, customized workspace permissions allow you to restrict access to workspace state via the UI and API, but will not prevent it from being read during Terraform operations.

Redaction of sensitive variables in Terraform logs

The logs from a Terraform plan or apply operation are visible to any user with at least “read” level access in the associated workspace. While Terraform tries to avoid writing sensitive information to logs, redactions are best-effort. This feature should not be treated as a security boundary, but instead as a mechanism to mitigate accidental exposure. Additionally, HCP Terraform is unable to protect against malicious users who attempt to use Terraform logs to exfiltrate sensitive data.

Recommendations for securely using HCP Terraform

Enforce strong authentication

HCP Terraform supports two factor authentication via SMS or TOTP. Organizations can configure mandatory 2FA for all members in the organization settings. Organizations may choose to configure SSO for their organization.

Minimize the number of users in the owners team

Users of the owners team will have full access to all workspaces within the organization. If SSO is enabled, members of the “Owners” team will still be able to authenticate with their username and password. This group should be reserved for only a small number of administrators, and membership should be audited periodically.

Apply the principle of least privilege to workspace membership

Teams allow you to group users and assign them various privileges within workspaces. We recommend applying the principle of least privilege when creating teams and assigning permissions so that each user within your organization has the minimum required privileges.

Protect API keys

HCP Terraform allows you to create user, team, and organization API tokens. You should take care to store these tokens securely, and rotate them periodically. Vault users can leverage the Terraform Cloud secret backend, which allows you to generate ephemeral tokens.

Control access to source code

By default, commits and pull requests to connected VCS repositories will automatically trigger a plan operation in an HCP Terraform workspace. HCP Terraform cannot protect against malicious code in linked repositories, so you should take care to only grant trusted operators access to these repositories. Workspaces may be configured to enable or disable speculative plans for pull requests to linked repositories. You should disable this setting if you allow untrusted users to open pull requests in connected VCS repositories.

Restrict access to workspace state

Workspaces may be configured to share their state with other workspaces within the organization or globally with the entire organization via the remote state setting. Because workspace state may contain sensitive information, we recommend that you follow the principle of least privilege and only enable state access between workspaces that specifically need information from each other.

Use separate agent pools for sensitive workspaces

You can share HCP Terraform Agents across all workspaces within an organization or scope them to specific workspaces. If multiple workspaces share agent pools, a malicious actor in one of those workspaces could exfiltrate the agent’s API token, access private resources from the perspective of the agent, or modify the agent’s environment, potentially impacting other workspaces. For this reason, we recommend creating separate agent pools for sensitive workspaces and using the agent scoping setting to restrict which workspaces can target each agent pool.

Treat Archivist URLs as secrets

HCP Terraform uses a blob storage service called Archivist for storing various pieces of customer data. Archivist URLs have the origin https://archivist.terraform.io and are returned by various HCP Terraform APIs, such as the state versions API. You do not need to submit a bearer token with each request to call the Archivist API. Instead, Archivist URLs contain a short-term signed authorization token that performs authorization checks. The expiry time depends on the API endpoints you used to generate the Archivist link. As a result, you must treat Archivist URLs as secrets and avoid logging or sharing them.

Use dynamic credentials

Storing static credentials in HCP Terraform increases the inherent risk of a malicious user or a compromised plan or apply operation exposing your credentials. Because static credentials are usually long-lived and exposed in many locations, they are troublesome to revoke and replace.

Using dynamic provider credentials eliminates the need to store static credentials in HCP Terraform, reducing the risk of exposure. Dynamic provider credentials generate new temporary credentials for each operation and expire after that operation completes.