vsh

vsh

vsh é um shell interativo do HashiCorp Vault e uma ferramenta CLI. Ele vem com várias operações comuns e trata caminhos como diretórios e arquivos. Os principais recursos são:

• operações recursivas em caminhos para muitas operações, por exemplo, cp , rm , mv
• pesquise com grep (substring ou expressão regular)
• substitua padrões em chaves e/ou valores (substring ou expressão regular) por replace
• transparência em relação às diferenças entre KV1 e KV2, ou seja, você pode mover/copiar livremente segredos entre ambos
• modo não interativo para automação ( vsh -c "<cmd>" )
• mesclando chaves com estratégias diferentes por meio de append

Instalação

Cerveja caseira

brew install vsh

Nix

nix-env -i vsh

Binários estáticos para Linux/MacOS

Baixe os binários estáticos mais recentes da página de lançamento.

Comandos suportados

• add adiciona uma única chave e valor a um caminho
• anexar mescla segredos com estratégias diferentes (permite operação recursiva em caminhos)
• cat mostra os pares chave/valor de um caminho
• cd permite navegação interativa pelos caminhos
• cp copia segredos de um local para outro (permite operação recursiva em caminhos)
• grep procura substrings ou expressões regulares (permite operação recursiva em caminhos)
• ls mostra os subcaminhos de um determinado caminho
• mv move segredos de um local para outro (permite operação recursiva em caminhos)
• substitua substrings ou expressões regulares (permite operação recursiva em caminhos)
• rm remove segredo(s) (permite operação recursiva em caminhos)

Configurando o token do cofre

Para obter um token válido, vsh usa o mecanismo TokenHelper do vault. Isso significa que vsh suporta a configuração de tokens de cofre via ~/.vault-token , VAULT_TOKEN e token-helper externo.

TLS

Adicione o certificado tls para o servidor definindo a variável de ambiente VAULT_CACERT para o caminho do certificado pem .

Requisitos de permissão de token

vsh requer permissão List nos caminhos operados. Isto é necessário para determinar se um caminho aponta para um nó ou folha na árvore de caminhos. Além disso, é necessário coletar dados de preenchimento automático.

Comandos que alteram os dados como cp ou mv também requerem permissões Read e Write nos caminhos operados.

Para descobrir com segurança todos os back-ends disponíveis, o ideal é que o token do vault usado pelo vsh tenha permissão List em sys/mount . No entanto, este não é um requisito difícil. Se o token não tiver permissão List em sys/mount , então vsh não conhece os back-ends disponíveis de antemão. Isso significa que inicialmente não haverá preenchimento automático de caminho no nível superior (backend). Independentemente disso, vsh tentará, com a estratégia de melhor esforço, determinar com segurança a versão kv de cada caminho inserido.

Modo interativo

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

Nota: o token fornecido é usado para preenchimento automático, ou seja, as consultas List() são feitas com esse token, mesmo se você não fizer rm ou mv nada. vsh armazena em cache os resultados List() para reduzir a quantidade de consultas. No entanto, após a execução de cada comando, o cache é limpo para fazer um preenchimento preciso da guia. Se o seu token tiver um número limitado de usos, considere usar o modo não interativo ou desative o preenchimento automático para evitar consultas List() .

Alternar preenchimento automático

Para reduzir o número de consultas no vault, você pode desabilitar o preenchimento automático do caminho de duas maneiras:

1. Desativar na hora de início:

 ./vsh --disable-auto-completion

2. Alternar dentro do modo interativo:

 ./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 não interativo

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

Algumas palavras sobre a qualidade

Trabalhar nos segredos do cofre pode ser crítico, tornando a qualidade e o comportamento correto um cidadão de primeira classe para vsh . Dito isto, vsh ainda é um pequeno projeto de código aberto, o que significa que não podemos dar nenhuma garantia. No entanto, colocamos forte ênfase no desenvolvimento orientado a testes. Cada PR é testado com um extenso conjunto de testes de integração. A grande maioria dos testes é executada em KV1 e KV2 e todos os testes são executados no vault 1.13.4 e 1.16.2 , ou seja, as versões intermediárias do vault provavelmente também serão compatíveis.

️ Em geral, usar vsh é por sua conta e risco. Não assumimos qualquer responsabilidade e não damos quaisquer garantias.

Contribuições

Contribuições em qualquer formato são sempre bem-vindas! Sem as contribuições da comunidade, vsh não seria a ferramenta que é hoje.

Desenvolvimento Local

Requisitos:

• golang ( >= v1.21 )
• docker para testes de integração
• make para comandos simplificados

 make compile
make get-bats
make integration-tests

Depuração

-v DEBUG define o nível de log de depuração, que também cria um arquivo vsh_trace.log para registrar qualquer objeto de erro da API do vault.