← Back to blog
Securing Terraform State Files with Onboardbase

Securing Terraform State Files with Onboardbase

authors photo
Written by Dante Lex
Sunday, October 29th 2023

Terraform stands out as one of the most reliable Infrastructure as Code (IaC) tools to provision and manage cloud resources: just write a few lines in a Terraform configuration file and spin up cloud services in minutes in any cloud provider.

But this ease-of-use also brings security challenges: a leak of your Terraform state files could reveal sensitive information, bring your infrastructure down, and ultimately hurt your reputation as a company. All it takes is an overworked colleague, and a single bad git commit.

In this article, I’ll demonstrate how to protect your Terraform state files at rest and in transit using Onboardbase’s command line interface tool in five minutes without compromising the developer experience for your entire devops team.

But why should I download another tool, Dante?? you might ask. I already use Hashicorp Vault.

As I’ll explain in a minute, Hashicorp Vault only solves a part of the problem. Onboardbase is a 360° solution that goes beyond the devops team to integrate requirements from your entire IT department. Just read on, and you’ll understand right away.

The Problem

After writing your Terraform configuration file, you’ll run terraform apply, and a new Terraform state file will automatically map your cloud resources to your configuration file.

This state file is a JSON file that contains sensitive information about your cloud resources, like IP addresses, passwords, or access keys. It’s an internal state file that should never be tempered with or shared with anyone outside your devops team.

In a modern development team, managing this file can raise a few issues:

  • Your devops teammates will need to have access to up-to-date state files to make changes.
  • They will need a single source of truth to avoid state conflicts.
  • The state file is a plain text file containing sensitive information, so it should be encrypted.
  • Only devops team members should have write access to the state file, but other developers might need read access to run code in staging environments, so you’ll need some sort of access control feature.

In other words, protecting Terraform state files is a complex problem that goes beyond Hashicorp Vault’s features: the install process has lots of additional configuration steps, you’ll need to manage encryption keys, and it’s not designed for broad team collaboration.

A solution like Onboardbase is a better fit for the job: it’s a command line interface tool that’s easy to install, synced with a web-based app for easy collaboration, and that can be used for everything related to secure devops best practices from securing Terraform state files to managing API keys, environments variables, and other developer secrets.

Solution Overview

Onboardbase is a DevSecOps platform to secure your entire development workflow with end-to-end encryption and collaborative workflows. You can use the CLI to encrypt and decrypt Terraform state files and manage access control policies. You can also use the web app to monitor usage and prevent leaks in real-time:

Onboardbase dashboard

Using a simple Git workflow, you can encrypt your Terraform state files locally and share them with your devops team via a secure URL. You can also decrypt them locally to make changes and re-encrypt them automatically:

  1. Create a dedicated Git repository for your Terraform configuration.
  2. Add state files to your .gitignore file to prevent accidental commits.
  3. Use Onboardbase CLI to encrypt your locally generated state files.
  4. Push these encrypted files to your Git repository.
  5. Other developers can simply decrypt the files locally via Onboardbase using a single URL and the decryption key. No need to clone the entire repository. Write access would require merge approval.
  6. You can use the same URL as a Terraform backend to store your cloud configurations.

Step-by-Step Guide

1. Installation

Getting started with Onboardbase takes a minute. Install the CLI in one command line, and you’re ready to secure your Terraform state file:

npm i -g @onboardbase/cli@latest

You can also get the CLI for MacOS, Linux, Windows, etc. Follow the 2-minutes installation steps in the docs.

2. Encrypting the state file

Onboardbase allows you to encrypt your Terraform state file locally in a single command:

onboardbase tf:encrypt --enc-key "your encryption key" --file "path to your terraform.tfstate file"

The --enc-key argument allows you to specify the encryption key you want to use. All it takes is a simple passphrase. By default, the CLI uses your device’s fingerprint key so it’s only useful for local development.

The --file defaults to terraform.tfstate.

3. Decrypting the state file

The decyption command is similar:

onboardbase tf --enc-key "The encryption key you used to encrypt your tfstate file" --file "path to your terraform.tfstate file" -- "Your Terraform command"

When you use the onboardbase tf command, the Onboardbase CLI will automatically decrypt the Terraform state file and re-encrypt it afterward. You can specify an optional Terraform command to run after decrypting the state file. For example, you can run terraform init to initialize your Terraform project with the decrypted state file.

This automatic encryption/decryption feature is meant to prevent any potential leak by manual tempering.

4. Encrypting/Decrypting via URL

For staging or production use, you can access encrypted state files via URLs. If you use Github Actions, for example, you could generate an artifact containing your encrypted state file and make it downloadable via URL. To get the list of downloadable artifacts:

gh api "/repos/{owner}/{repo}/actions/artifacts"

You can then use the onboardbase tf command to decrypt the file locally via standard input -:

curl -s GITHUB_ARTIFACT_URL | onboardbase tf --enc-key "your encryption key" --file "-" -- "terraform init"

When you pass an external encrypted URL to the onboardbase tf command, the CLI decrypts the file, writes it to the Terraform folder, and deletes it after use.

5. Protecting your encryption keys

The only remaining pain point is how to protect your encryption keys. You can’t store them in your Git repository because they would be accessible to anyone with read access to your repository. You can’t store them in your CI/CD environment variables either because they would be accessible to anyone with access to your CI/CD environment.

Fortunately, Onboardbase doubles as a secret vault, so you can use it to store encryption keys securely with granular access control and simply inject the encryption key at runtime as an environment variable via the CLI.

First, you need to setup the Onboardbase configuration file:

onboardbase setup

This command will create a onboardbase.yaml file containing your project name and the corresponding development environment. You can use the web app or the command line to create a new secret variable for your encryption key:

onboardbase secrets:upload -p [PROJECT NAME] -e [ENVIRONMENT NAME] '{"TERRAFORM_KEY":"value"}'

Developers will never need to know the encryption key. They can simply use the onboardbase run command. If we take the example of decrypting a state file via URL, you can create a bash script that will be executed via the onboardbase run command:


curl -s <TERRAFORM_STATE_FILE_URL> | onboardbase tf --enc-key "$ENC_KEY" --file "-" -- "terraform init"

And then:

onboardbase run --command="./terraform_init.sh"

Onboardbase will not only secure the entire workflow but also provide you with a detailed audit log of all the secrets used by your developers to prevent malicious intents from Onboardbase’s web interface.

How Onboardbase Solves the Problems

Onboardbase provides a single platform for handling encryption, decryption, and sharing, simplifying the process for development teams. The risk of accidental data leaks and state file corruption is significantly reduced to ensure a reliable infrastructure management experience:

  • Your devops teammates can access to up-to-date state files to make changes from the Git repository. The Onboardbase CLI can automatically run to encrypt state files on each commit.
  • The Git repository acts as a single source of truth to prevent Terraform state file conflicts. Just git pull or use the downloadable URL to get the latest state file. Each change needs to be approved via pull request.
  • State files are always encrypted at rest (in the remote storage or in the local environment) and in transit (via HTTPS).
  • Only devops team members or people with write access to the Git repository can change the state file, but other developers can have read access to run code. Encryption keys are stored in Onboardbase, and their granular usage is monitored. This way, you know exactly who can access your state files.


Securing Terraform state files is an important part of scaling your infrastructure, and Onboardbase provides a powerful, developer-friendly solution to common issues involved in this process. Not only does it prevent security threats, but it’ll also save hours of development time dealing with collaborative features.

But that’s not all. Onboardbase not only works well with Terraform, but also with other platforms, tools, and services involved in your daily CI/CD pipeline: Github, npm, AWS… you name it! Don’t hesitate to reach out to me Dante to get you started. We can help design a custom-fit solution for all devsecops needs.

Subscribe to our newsletter

The latest news, articles, features and resources of Onboardbase, sent to your inbox weekly