vsh

vsh

vsh es una herramienta cli y shell interactiva de HashiCorp Vault. Viene con múltiples operaciones comunes y trata las rutas como directorios y archivos. Las características principales son:

• operaciones recursivas en rutas para muchas operaciones, por ejemplo, cp , rm , mv
• buscar con grep (subcadena o expresión regular)
• sustituir patrones en claves y/o valores (subcadena o expresión regular) con replace
• transparencia hacia las diferencias entre KV1 y KV2, es decir, puede mover/copiar secretos libremente entre ambos
• modo no interactivo para automatización ( vsh -c "<cmd>" )
• fusionar claves con diferentes estrategias mediante append

Instalación

cerveza casera

brew install vsh

Nada

nix-env -i vsh

Binarios estáticos para Linux/MacOS

Descargue los binarios estáticos más recientes desde la página de lanzamiento.

Comandos admitidos

• add agrega una única clave y valor a una ruta
• append fusiona secretos con diferentes estrategias (permite operaciones recursivas en rutas)
• cat muestra los pares clave/valor de una ruta
• El cd permite la navegación interactiva por los caminos.
• cp copia secretos de una ubicación a otra (permite operaciones recursivas en rutas)
• grep busca subcadenas o expresiones regulares (permite operaciones recursivas en rutas)
• ls muestra las subrutas de una ruta determinada
• mv mueve secretos de una ubicación a otra (permite operaciones recursivas en rutas)
• reemplazar subcadenas o expresiones regulares (permite operaciones recursivas en rutas)
• rm elimina secretos (permite operaciones recursivas en rutas)

Configurar el token de la bóveda

Para obtener un token válido, vsh utiliza el mecanismo TokenHelper de Vault. Eso significa que vsh admite la configuración de tokens de bóveda a través de ~/.vault-token , VAULT_TOKEN y un asistente de token externo.

TLS

Agregue el certificado tls para el servidor configurando la variable de entorno VAULT_CACERT en la ruta del certificado pem .

Requisitos de permiso de token

vsh requiere permiso List en las rutas operadas. Esto es necesario para determinar si una ruta apunta a un nodo o a una hoja en el árbol de rutas. Además, es necesario recopilar datos de autocompletar.

Los comandos que modifican los datos como cp o mv también requieren permisos Read y Write en las rutas operadas.

Para descubrir de manera confiable todos los backends disponibles, lo ideal es que el token de bóveda utilizado por vsh tenga permiso List en sys/mount . Sin embargo, este no es un requisito estricto. Si el token no tiene permiso List en sys/mount , entonces vsh no conoce los backends disponibles de antemano. Eso significa que inicialmente no habrá autocompletado de ruta en el nivel superior (backend). De todos modos, vsh intentará con la mejor estrategia posible determinar de manera confiable la versión kv de cada ruta ingresada.

Modo interactivo

 export VAULT_ADDR=http://localhost:8080
export VAULT_TOKEN=root
export VAULT_PATH=secret/  # VAULT_PATH is optional
./vsh
http://localhost:8080 /secret/>

Nota: el token proporcionado se utiliza para la autocompletación, es decir, las consultas List() se realizan con ese token, incluso si no rm o mv nada. vsh almacena en caché los resultados List() para reducir la cantidad de consultas. Sin embargo, después de la ejecución de cada comando, el caché se borra para poder completar la tabulación con precisión. Si su token tiene un número limitado de usos, considere usar el modo no interactivo o desactivar el autocompletado para evitar consultas List() .

Alternar autocompletado

Para reducir la cantidad de consultas en Vault, puede deshabilitar la finalización automática de rutas de dos maneras:

1. Desactivar a la hora de inicio:

 ./vsh --disable-auto-completion

2. Alternar dentro del modo interactivo:

 ./vsh
http://localhost:8080 /secret/> toggle-auto-completion
Use path auto-completion: false
http://localhost:8080 /secret/> toggle-auto-completion
Use path auto-completion: true

Modo no interactivo

 export VAULT_ADDR=<addr>
export VAULT_TOKEN=<token>
./vsh -c "rm secret/dir/to/remove/"

Algunas palabras sobre la calidad.

Trabajar en los secretos de la bóveda puede ser fundamental, lo que hace que la calidad y el comportamiento correcto sean elementos de primera clase para vsh . Dicho esto, vsh sigue siendo un pequeño proyecto de código abierto, lo que significa que no podemos ofrecer ninguna garantía. Sin embargo, ponemos gran énfasis en el desarrollo basado en pruebas. Cada PR se prueba con un amplio conjunto de pruebas de integración. La gran mayoría de las pruebas se ejecutan en KV1 y KV2 y cada prueba se ejecuta en Vault 1.13.4 y 1.16.2 , es decir, es probable que las versiones intermedias de Vault también sean compatibles.

️ En general, utilizar vsh es bajo su propia responsabilidad. No asumimos ninguna responsabilidad y no damos ninguna garantía.

Contribuciones

¡Las contribuciones en cualquier forma siempre son bienvenidas! Sin las contribuciones de la comunidad, vsh no sería la herramienta que es hoy.

Desarrollo Local

Requisitos:

• golang ( >= v1.21 )
• docker para pruebas de integración
• make comandos simplificados

 make compile
make get-bats
make integration-tests

Depuración

-v DEBUG establece el nivel de registro de depuración, que también crea un archivo vsh_trace.log para registrar cualquier objeto de error de la API del almacén.