Introducing envwarden – manage your server secrets with Bitwarden


envwarden is a simple, open-source script that lets you easily manage your server secrets with the Bitwarden password manager.

Background story

I’ve been using a few password managers over the years, but was usually left with a sense of something missing. I used Keepass for a fairly long while, but switching between my laptop, desktop and phone was always a bit tricky with a standalone program. I also used clipperz in the past. I think it was the first online password manager I discovered (back in 2007 or so?). But it had no real sharing options, and over time became harder to install, felt abandoned for a while, and with disclaimers such as this, I wasn’t exactly filled with confidence:

The open source version of Clipperz is suitable for testing and educational purposes only.

As an example, the current PHP backend lacks several critical capabilities such as bot protection and concurrent sessions management, moreover it could be vulnerable to serious threats (SQL injections, remote code execution, …).

I was then thrilled to discover Mitro. It had everything I wanted, and a very intuitive UI. Sharing was a breeze. Sadly it was abandoned after the team acquihired by Twitter… :(

I also tried Lastpass ages ago, and hated its UI. I think it didn’t have Linux support at the time either, so it was a no-go.

Recently I discovered Bitwarden, and immediately knew it’s a good choice. Open-Source, but with paid plans that would hopefully ensure long-term viability and support. Mobile apps. Browser extensions for all browsers. Even a CLI !

And then I realized, if it has a CLI, we can actually use Bitwarden for storing our server secrets as well. I contacted Kyle from Bitwarden, and asked him if he knows of anyone doing this. He said this was definitely possible, but he wasn’t aware of anyone doing this.

And so envwarden was born.

Basic operation

envwarden is a very simple bash script (also available as a Docker image) that uses the bw CLI and jq to fetch secrets from your Bitwarden vault, and then export them as environment variables (or an .env file).

You define all your secrets as custom fields on one (or more) Bitwarden items.

You can let envwarden (using the bw CLI) to prompt you for the password, or (more typically for an unattended server environment), you can store your Bitwarden credentials inside a .envwarden file. This means that this .envwarden file is your master secret or trust root, and that’s all you need to fetch all other server secrets.

The envwarden script itself can be run in two modes:

  1. eval $(envwarden) – would get all secrets as environment variables. eval is considered dangerous, but effort was made to make it safe and avoid any command injection
  2. envwarden --dotenv > .env – would export the secrets into a .env file.

To make your secrets available to your server apps, you can use something as simple as eval $(envwarden) && launch-your-server-app.

If you prefer using a .env file, there are plenty of libraries that support this format. (for example, python-dotenv, the dotenv rubygem, go dotenv, dotenv npm and probably plenty more…). I would personally recommend using .env over using eval, both from a security perspective, and also convenience. For example, the dotenv format allows you to use variable substitution and some other convenience methods to better organize your secrets.

Security considerations

As I mentioned before, the master secret is all you need, but obviously this is also your most important secret. With it, anyone can fetch all your server secrets. Depending on your setup, you don’t need to store it, but can let an operator enter it on boot, but of course, if the server is then restarted, you’d need an operator ready to enter the credentials again.

The Bitwarden credentials can also use a multi-factor authentication, if you really need a higher level of security. This would make envwarden unsuitable for completely unattended operation however.

Secret management

envwarden would essentially run a search for all items matching a specific search query (defaults to ‘envwarden’). You can use a single account with different search queries for each environment, e.g. –search ‘envwarden-development’ for your development secrets. However, ideally you’d like to split your accounts to ensure the principle of least privilege. So your development bitwarden account won’t have any access to your production environment secrets (or even other non-production environment, like staging).

Bitwarden’s flexible authorization means you can also control who has access to your production secrets, and who has access to development etc. This is a very good model to work with. You probably also only give read-only access to your secrets from your servers. This is all possible with Bitwarden.

Protect your secret files

If you use one, the .envwarden file is your most important secret, because it gives access to all other secrets. Make sure you protect this file and make it only readable to specific user accounts, e.g. chmod 400 .envwraden.

If you also use a .env file for your server app, please use similar precautions as well.

Alternative secret management options?

I’m not super-familiar with all options, but it’s probably worth mentioning a few. Most options are much more “heavy-weight” than envwarden/Bitwarden, but this is exactly the reason I created it: simplicity, and integration with your normal passwords (which can be considered a pro or a con, depending on your perspective)

  • Vault – is a very robust tool. I’m not aware of a hosted option, and setup isn’t trivial. If you have a big operation, it’s probably worth it
  • SSM Parameter Store
  • Chamber – a CLI on top of AWS SSM Parameter Store
  • EnvKey – is probably the most similar to what envwarden attempts to do, but separates server secrets from password management
  • Amazon KMS – is a much lower-level service

Take it for a spin?

envwarden is still experimental at this stage, but I hope you find it useful. If you have any suggestions or ideas for improvements, please get in touch on Github.

Special thanks to Kyle from Bitwarden for being so responsive and positive about envwarden. Even if you’re not looking for a tool to manage your server secrets, I recommend using the Bitwarden password manager. It’s really great.

Leave a Reply

Your email address will not be published. Required fields are marked *