Bitwarden CLI: gestión de contraseñas desde la terminal y automatización de CI/CD

Bitwarden CLI — la utilidad oficial de línea de comandos bw para trabajar con el almacén de Bitwarden: buscar una contraseña en el terminal, obtener un secreto en un script, pasarla a un pipeline CI/CD. El código es abierto, la utilidad es gratuita y funciona tanto con la nube de Bitwarden como con un servidor propio, incluido Vaultwarden.

A continuación — instalación, inicio de sesión, comandos principales y una plantilla lista para CI. Si aún no tiene un servidor propio, empiece por el artículo Vaultwarden en 30 minutos; sobre la elección de un gestor de contraseñas para la empresa — en la serie «Gestores de contraseñas».

1. Instalación

Según la documentación de Bitwarden existen varias formas:

# npm (cualquier SO; Bitwarden llama a este método el más sencillo para actualizaciones)
npm install -g @bitwarden/cli

# Snap (Linux)
sudo snap install bw

# Chocolatey (Windows)
choco install bitwarden-cli

# Homebrew (macOS y Linux)
brew install bitwarden-cli

Además, en bitwarden.com se publican ejecutables listos para Windows, macOS y Linux (x64). El archivo debe colocarse en un directorio que esté en PATH, de lo contrario habrá que ejecutar las órdenes desde el directorio donde está el archivo. Al instalar vía npm en Linux puede ser necesario el paquete build-essential.

Verificación:

bw --version

2. Conexión a su propio servidor

Por defecto el CLI trabaja con la nube de Bitwarden. Para un servidor propio — Vaultwarden o Bitwarden self-hosted — la dirección se especifica antes de iniciar sesión:

bw config server https://vault.example.ru

Para la nube europea de Bitwarden la dirección es https://vault.bitwarden.eu. Si los servicios del servidor están en direcciones distintas, el comando tiene parámetros separados: --web-vault, --api, --identity y otros.

Vaultwarden implementa la API cliente de Bitwarden, incluyendo la clave API personal, por lo que todo lo descrito abajo funciona también con él.

3. Inicio de sesión

Inicio de sesión interactivo

bw login

La utilidad pedirá la dirección de correo, la contraseña maestra y, si está activada, la autenticación de dos factores. Para organizaciones con inicio único hay bw login --sso.

Inicio de sesión con clave API

Para scripts y CI el inicio interactivo no sirve. La clave API personal se obtiene en la interfaz web: Settings → Security → Keys. Consiste en un client_id del tipo user.xxxx y un client_secret.

export BW_CLIENTID="user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export BW_CLIENTSECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

bw login --apikey

Importante: la clave API no sustituye a la contraseña maestra. Solo autoriza en el servidor, y para descifrar el almacén sigue siendo necesario bw unlock. Si la clave se compromete, puede regenerarse: la clave antigua y todas las sesiones abiertas con ella dejarán de funcionar.

4. Desbloqueo y BW_SESSION

Tras el inicio de sesión los datos del almacén siguen cifrados. Se descifran con el comando:

bw unlock

Este imprime la llave de sesión en forma del comando export BW_SESSION="...". Mientras la variable BW_SESSION esté definida, bw descifra los datos sin volver a pedir la contraseña maestra. La llave también puede pasarse a un comando individual con el flag --session.

En scripts la contraseña maestra se toma de una variable de entorno o de un archivo, y la llave de sesión se obtiene en una sola línea:

# contraseña en la variable de entorno
export BW_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw)

# o en un archivo (se lee la primera línea)
export BW_SESSION=$(bw unlock --passwordfile /run/secrets/bw_master --raw)

El archivo con la contraseña debe ser accesible solo para el usuario que ejecuta bw unlock. La llave de sesión es válida hasta bw lock o bw logout y no se transfiere a una nueva ventana de terminal.

Comprobar el estado actual — si ha iniciado sesión y si el almacén está desbloqueado:

bw status

5. Comandos principales

Algunas observaciones prácticas:

• bw sync solo descarga datos del servidor. Las modificaciones hechas vía CLI se envían al servidor inmediatamente. Si cambió la contraseña en el navegador y el script ve la antigua — ejecute bw sync.
• bw get acepta ID o una cadena de búsqueda. En trabajo interactivo la búsqueda es práctica, pero en scripts es más fiable usar el ID: la cadena puede encontrar el elemento equivocado o varios.
• La salida es JSON, que es conveniente procesar con la utilidad jq:

bw list items --search "github" | jq -r '.[] | "\(.id)  \(.name)"'

Copiar la contraseña al portapapeles en Linux:

bw get password github | xclip -selection clipboard

6. Plantilla de script para CI/CD

Para CI conviene crear una cuenta separada con acceso solo a los elementos necesarios, por ejemplo a una colección de la organización. BW_CLIENTID, BW_CLIENTSECRET y BW_PASSWORD se guardan en variables protegidas del CI, no en el repositorio.

#!/usr/bin/env bash
set -euo pipefail

# 1. Dirección del servidor (antes de iniciar sesión)
bw config server https://vault.example.ru

# 2. Inicio de sesión con clave API: BW_CLIENTID y BW_CLIENTSECRET — desde variables del CI
bw login --apikey

# 3. Desbloqueo: la contraseña maestra — desde la variable BW_PASSWORD
export BW_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw)

# 4. Secreto por ID del elemento (ID por adelantado: bw list items --search "my-db")
DB_PASS=$(bw get item "8a562df1-443b-4892-baee-b123456789ab" | jq -r '.login.password')

# 5. Usamos el secreto sin imprimirlo en los logs
./deploy.sh

# 6. Finalizamos la sesión
bw logout

En GitHub Actions, el valor obtenido en el paso conviene enmascararlo inmediatamente con el comando echo "::add-mask::$DB_PASS" — así no aparecerá en el registro de la compilación, incluso si se imprime en la salida.

7. Bitwarden Secrets Manager y la utilidad bws

Bitwarden tiene un producto separado para secretos de infraestructura — Secrets Manager — con su propia utilidad bws y su propia política de precios. En él los secretos se agrupan en proyectos, y el acceso se da a cuentas de máquina mediante un token de acceso, sin contraseña maestra:

export BWS_ACCESS_TOKEN="..."
bws secret list
bws secret get <SECRET_ID>
bws run -- ./deploy.sh   # ejecutar un comando con los secretos en variables de entorno

En la lista de capacidades Vaultwarden no figura Secrets Manager, por lo que para un servidor propio con Vaultwarden queda usar bw según el esquema anterior.

Reglas de seguridad

1. No almacene BW_SESSION en disco y no lo imprima en logs — solo en la memoria del proceso.
2. Finalice la sesión con bw lock o bw logout al terminar el script.
3. Oculte los secretos en CI y no los pase como argumentos de línea de comandos: los argumentos son visibles en la lista de procesos.
4. Separe los accesos. La cuenta para CI debe tener acceso solo a los secretos que necesita la pipeline.

Cómo evitar la filtración de claves desde el repositorio y qué hacer si la filtración ya ocurrió — en el artículo de la serie «Desarrollo seguro» «Secrets en el código».