tg-bw-helper 1.1.0

Thorgate helper for ansible vault password

CLI command that connects two awesome tools together - Ansible Vault & Bitwarden Password Manager

---

---

Table of Contents

• Why?

• Getting Started

  • Prerequisites

  • Installation

  • Setting Up With Ansible

• Usage

• CLI Options

• Environment

• Contributing

  • Developing

  • Opening MR

• License

Why?

At Thorgate, we deploy project using Ansible. Ansible comes with awesome encrypted storage, and every storage needs it’s own password to access it contents.

We also using Bitwarden to store company-wide passwords and sensitive information. And if we already are storing passwords to Ansible Vault’s in Bitwarden, we thought why not use Bitwarden CLI tool to pass these passwords directly to Ansible Vault?

And that’s how this project was born 😎

Getting Started

Prerequisites

We need these tools to be installed:

• Python 3.9+ & Pip

• Ansible

• Ansible project that uses Ansible Vault

• Bitwarden Account

• Bitwarden CLI

We strongly recommend installing Python packages in dedicated and isolated virtual environments. There are several tools that helps manage virtual environments:

• Virtualenv

• Pipenv

• Poetry (We will be using this one)

Installation

We assume several things:

• That you have existing or starting new Ansible project

• That your Ansible installation lives in virtual environment

Based on these assumptions, for installation you need to add this package into your virtual environment. For example you might run $ poetry add tg-bw-helper

Setting Up With Ansible

1. Create if not yet existing shell script with this example content (it can be named ask-vault-pass.sh) - note that you do not need to add poetry run before invoking bw_helper here, or activate virtualenv etc., since your ansible will be already running in correct environment

   #!/bin/sh
   bw_helper --vault-item "Ansible Vault" --vault-item-field "Password"

2. Make sure that this script is executable! If not, run $ sudo chmod +x ask-vault-pass.sh

3. Edit ansible.cfg to specify script that Ansible will be using to get Vault password

   [defaults]
   vault_password_file=./ask-vault-pass.sh

Usage

Now when all these steps completed:

• tg-bw-helper is installed into virtual environment where Ansible is installed

• Ansible project is configured to use special script

We are ready to use the tool:

1. Run $ bw login (Needs to be run once per user session)

2. Run your usual Ansible playbook that previously asked for Vault password

3. Enter Bitwarden master password

CLI Options

--bw-executable

Optional, should point to bw executable, defaults to /usr/bin/bw, can also be set with TG_BW_AP_EXECUTABLE_PATH env variable

--fallback-prompt

optional, prompt to display if bw fails, defaults to “Vault password: “, can also be set with TG_BW_AP_FALLBACK_PROMPT env variable

--vault-item

vault item ID or name, should be specific since tool will fail if multiple items are found

• Item name is what you see as it’s name in bitwarden UI

• Item ID is useful if you have two items with same name, you can learn it by using bitwarden CLI (use bw login to login, follow the instructions for how to pass the session information over to the next command, and then use bw list items --search <item name>. You will get json array of matching objects, each object will have ID that you can use.)

--vault-item-field

optional, field to use on the item. If not specified, password is used. Examples:

• You have an item “Awesome project ansible vault” with password “123”, and you want to use “123”. You do not specify --valut-item-field in this case.

• You have an item “Ansible secrets” with password set to “abc”, that has additional fields “Test server ansible” set to “123” and “Live server ansible” set to “456”, and you want to use “123”. You specify --valut-item-field="Test server ansible" in this case.

Environment

If BW_SESSION is set in environment, it will be used instead of asking bitwarden master password to unlock bitwarden.

If using linux, you can opt to save the bitwarden session in linux kernel secret storage by setting TG_BW_SESSION_SECRET_NAME environment variable to to some string (preferably random) that will be used to store the secret on user’s session keyring.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Developing

For local development project repository contains pyproject.toml and poetry.lock. When using them with Poetry you will be able to recreate ready to use environment.

We also added Makefile that contains lots of useful commands to help setup the project, run tests and lint code. Do check it out by running make

Opening MR

1. Clone the Project

2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

3. Commit your Changes (git commit -m 'Add some AmazingFeature')

4. Push to the Branch (git push origin feature/AmazingFeature)

5. Open a Merge Request

License

Distributed under the MIT License. See LICENSE for more information.