DEV Community

Cover image for Acesso Seguro do Agente Bitwarden: Compartilhando Credenciais do Vault com Agentes de IA de Codificação
Lucas
Lucas

Posted on • Originally published at apidog.com

Acesso Seguro do Agente Bitwarden: Compartilhando Credenciais do Vault com Agentes de IA de Codificação

#agents #ai #opensource #security

Se você usa Claude Code, Codex ou Cursor com qualquer fluxo que toque uma API real, precisa resolver um problema prático: o agente precisa de credenciais, mas seu gerenciador de senhas foi feito para mantê-las bloqueadas. Colar uma chave de API no chat coloca o segredo na janela de contexto do modelo. Salvar segredos em .env permite que a ferramenta bash do agente leia e exfiltre esses valores. A saída correta é dar ao agente acesso mínimo, temporário e com escopo.

Experimente o Apidog hoje

O novo projeto open source do Bitwarden, Agent Access, tenta resolver isso com um protocolo de compartilhamento de credenciais, um CLI (aac) e SDKs em Rust + Python. Ele cria um túnel criptografado entre seu gerenciador de senhas e um processo consumidor: agente, runner de CI ou script local. O consumidor recebe apenas os segredos necessários, com escopo por domínio ou item do cofre, sem acessar o cofre inteiro.

Este guia mostra como instalar o Agent Access, usar aac connect e aac run, integrar com Claude Code, Codex e Cursor, e aplicar os padrões de higiene de credenciais descritos em Como Proteger Credenciais de API de Agentes de IA.

O que é o Agent Access

Agent Access é um protocolo aberto e uma implementação de referência criada pelo Bitwarden, mas desenhada para que outros gerenciadores de senhas possam adotá-la.

O fluxo básico é:

  1. Um provedor escuta solicitações de conexão.
  2. Um consumidor se conecta ao provedor.
  3. O consumidor solicita uma credencial por domínio ou ID de item do cofre.
  4. O provedor decide o que retornar.
  5. O consumidor recebe somente a credencial solicitada.

O CLI aac cria um túnel criptografado de ponta a ponta usando o Noise protocol. O consumidor não vê o cofre completo. O provedor não vê como o consumidor usa a credencial. Ambos os lados podem manter trilhas de auditoria.

Agent Access

O projeto ainda está em pré-visualização inicial. O README avisa que “APIs e protocolos estão sujeitos a alterações” e que “não recomendamos inserir credenciais sensíveis diretamente em LLMs ou agentes de IA”.

Por isso, o padrão mais útil hoje é usar aac run: ele injeta segredos como variáveis de ambiente em um subprocesso, sem expor os valores ao prompt, ao stdout ou ao disco.

Por que isso importa

Agentes de codificação de IA já não ficam restritos a sugestões de código. Claude Code, Codex, Cursor e ferramentas similares leem repositórios, executam testes, chamam APIs e acionam deploys. Cada etapa pode exigir credenciais.

O incidente de chaves de API expostas do Postman mostrou como a higiene de credenciais falha quando apenas humanos estão envolvidos. Com agentes executando comandos automaticamente, o risco aumenta.

A resposta não é confiar mais no agente. É dar menos ao agente.

O Agent Access aplica esse princípio no nível do protocolo:

  • credenciais com escopo;
  • criptografia em trânsito;
  • busca em tempo de execução;
  • remoção do segredo quando o processo termina.

Para um panorama mais amplo de opções, veja também Ferramentas de Gerenciamento de Chaves de API.

Instalar

Escolha o binário da sua plataforma.

macOS Apple Silicon 

curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-aarch64.tar.gz | tar xz
sudo mv aac /usr/local/bin/
Enter fullscreen mode Exit fullscreen mode

macOS Intel 

curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/
Enter fullscreen mode Exit fullscreen mode

Linux x86_64 

curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-linux-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/
Enter fullscreen mode Exit fullscreen mode

Windows x86_64

Baixe aac-windows-x86_64.zip na página da última versão e extraia o binário para um diretório incluído no seu PATH.

Depois, valide a instalação:

aac --help
Enter fullscreen mode Exit fullscreen mode

Se o CLI do Bitwarden (bw) também estiver no PATH, o aac o usará como provedor de credenciais padrão.

Para testar sem Bitwarden, use o provedor de demonstração:

aac --provider example --help
Enter fullscreen mode Exit fullscreen mode

Início rápido: parear e buscar uma credencial

Execute o listener na máquina que contém seu cofre, normalmente seu laptop:

aac listen
Enter fullscreen mode Exit fullscreen mode

O comando imprime um token de emparelhamento.

Em outro terminal, máquina remota ou runner de CI, conecte usando o token e solicite uma credencial por domínio:

aac connect --token <token-de-emparelhamento> --domain github.com --output json
Enter fullscreen mode Exit fullscreen mode

Exemplo de resposta:

{
  "credential": {
    "notes": null,
    "password": "alligator5",
    "totp": null,
    "uri": "https://github.com",
    "username": "example"
  },
  "domain": "github.com",
  "success": true
}
Enter fullscreen mode Exit fullscreen mode

Se preferir buscar pelo ID do item no cofre:

aac connect --id <id-do-item-do-cofre> --output json
Enter fullscreen mode Exit fullscreen mode

Use apenas um dos dois modos:

  • --domain;
  • --id.

Eles são mutuamente exclusivos.

Quando o item do cofre tiver TOTP configurado, o código também é retornado na carga útil JSON.

Use aac run para injetar segredos no ambiente

aac connect é útil quando seu script sabe processar JSON. Para agentes de IA, o padrão mais seguro é aac run.

Ele busca a credencial e executa um processo filho com os segredos injetados como variáveis de ambiente. Os valores não são impressos no terminal, não são gravados no disco e não aparecem na transcrição do agente.

Injetar campos específicos 

aac run --domain example.com --env DB_PASSWORD=password --env DB_USER=username -- psql
Enter fullscreen mode Exit fullscreen mode

Nesse exemplo:

  • DB_PASSWORD recebe o campo password;
  • DB_USER recebe o campo username;
  • psql é executado como subprocesso.

Injetar todos os campos 

aac run --domain example.com --env-all -- deploy.sh
Enter fullscreen mode Exit fullscreen mode

Com --env-all, os campos são injetados com prefixo AAC_.

Combinar --env-all com variáveis customizadas 

aac run --domain example.com --env-all --env CUSTOM_PW=password -- deploy.sh
Enter fullscreen mode Exit fullscreen mode

Campos disponíveis:

  • username;
  • password;
  • totp;
  • uri;
  • notes;
  • domain;
  • credential_id.

Esse é o padrão recomendado para uso com agentes. O modelo pode ver o comando:

aac run --domain api.stripe.com --env-all -- ./deploy.sh
Enter fullscreen mode Exit fullscreen mode

Mas não vê a chave real.

Se o agente perguntar pelo valor de uma variável como $STRIPE_API_KEY, ele não consegue acessá-lo diretamente, porque o segredo foi limitado ao subprocesso chamado por aac run.

Esse é o princípio de isolamento descrito em Como Proteger Credenciais de API de Agentes de IA, aplicado com uma ferramenta concreta.

SDKs para Python e Rust

Se o CLI não for suficiente, você pode incorporar o Agent Access diretamente na sua aplicação.

Python 

from agent_access import RemoteClient

client = RemoteClient("python-remote")
client.connect(token="ABC-DEF-GHI")

cred = client.request_credential("example.com")
print(cred.username, cred.password)

client.close()
Enter fullscreen mode Exit fullscreen mode

O módulo Python usa PyO3, mantendo a implementação principal em Rust e reaproveitando a mesma base do protocolo Noise.

Rust

O SDK Rust expõe a interface RemoteClient como biblioteca de primeira classe.

Consulte as implementações de referência em:

examples/rust-remote/
Enter fullscreen mode Exit fullscreen mode

Use essa opção quando estiver escrevendo:

  • CLIs;
  • runners de build;
  • serviços que precisam de binários compilados;
  • consumidores de credenciais embutidos em ferramentas internas.

Para equipes que já usam ferramentas de gestão de segredos, o Agent Access pode coexistir com integrações como HashiCorp Vault ou Azure Key Vault. Ele não substitui esses cofres no nível empresarial, mas é útil para laptops de desenvolvedores, scripts locais e runners de CI.

Integrando com agentes de codificação de IA

Claude Code

Crie um script que encapsula a chamada a aac run.

Exemplo para deploy:

# deploy.sh
#!/usr/bin/env bash
aac run --domain prod.example.com --env-all -- ./run-deploy.sh
Enter fullscreen mode Exit fullscreen mode

Depois:

  1. adicione deploy.sh ao projeto;
  2. garanta que ele seja executável;
  3. configure o Claude Code para chamar ./deploy.sh;
  4. mantenha os segredos fora do prompt. 
chmod +x deploy.sh
Enter fullscreen mode Exit fullscreen mode

A integração de Claude Code GitHub Actions pode usar o mesmo padrão no CI: instale aac no runner, emparelhe com um provedor de cofre Bitwarden e injete as credenciais no momento do job.

OpenAI Codex

O mesmo padrão funciona com a CLI do Codex.

Em vez de permitir que o modelo veja uma chave, faça o Codex chamar um script:

# test-api.sh
#!/usr/bin/env bash
aac run --domain staging.example.com --env API_TOKEN=password -- ./run-api-tests.sh
Enter fullscreen mode Exit fullscreen mode

O Codex vê apenas a chamada ao script. O segredo fica restrito ao processo filho.

A postagem Codex do seu telefone cobre a superfície mais ampla do Codex; aqui, o foco é proteger credenciais durante execução de comandos.

Cursor

Nos comandos de terminal e fluxos do Composer do Cursor, use os mesmos scripts encapsulados em aac run.

Como o Cursor normalmente roda localmente, um fluxo comum é:

  1. executar aac listen no laptop;
  2. criar scripts como deploy.sh, test-api.sh ou seed-db.sh;
  3. fazer o Cursor chamar esses scripts;
  4. manter os segredos fora do contexto do modelo.

OpenClaw

O Agent Access inclui uma habilidade OpenClaw oficial pronta para uso. O repositório contém um SKILL.md.

Para equipes que usam habilidades no ecossistema OpenClaw, essa é uma integração mais direta: a habilidade conhece o formato do protocolo, busca credenciais e as entrega às ferramentas downstream expostas pela própria habilidade.

Veja também o guia de chaves de API do OpenClaw.

Modelo de segurança em termos práticos

Verifique estas três propriedades antes de adotar o fluxo:

  1. Criptografia de ponta a ponta via Noise

    O tráfego entre consumidor e provedor é criptografado com o Noise protocol framework, a mesma família de handshakes usada por WireGuard e Signal.

  2. Credenciais com escopo

    O consumidor solicita um domínio ou um ID de item do cofre. Ele não enumera o cofre inteiro.

  3. Sem segredo no disco por padrão

    Com aac run, os segredos passam como variáveis de ambiente para um processo filho. Nada é gravado em .env, nada é impresso no stdout e nada vai para o histórico do shell.

O Agent Access não protege contra:

  • processo consumidor malicioso ou comprometido;
  • cofre/provedor comprometido;
  • usuário colando segredos diretamente em prompts de LLM.

A defesa principal é reduzir escopo e tempo de vida da credencial exposta.

Padrão de CI: agente escreve, Apidog testa

Um fluxo prático para times que usam agentes e APIs:

  1. O agente altera o código

    Claude Code, Codex ou Cursor abre um PR modificando um endpoint.

  2. O CI executa a suíte

    O runner usa aac run para buscar a chave de API com escopo e executa testes contra staging.

  3. O Apidog valida o contrato

    O Apidog executa testes de contrato OpenAPI em uma etapa separada do CI, também via aac run.

Exemplo de script:

#!/usr/bin/env bash
aac run \
  --domain staging.example.com \
  --env API_TOKEN=password \
  -- ./run-contract-tests.sh
Enter fullscreen mode Exit fullscreen mode

Resultado:

  • o agente envia código;
  • o contrato da API é validado;
  • a chave não aparece no prompt;
  • a credencial não fica em .env.

Para o playbook de testes com agentes, veja Como testar agentes de IA que chamam suas APIs.

Limitações

Antes de usar em produção, considere:

  • Pré-visualização inicial

    APIs e protocolos podem mudar. Evite depender do protocolo v0 sem prever manutenção futura.

  • CLI do Bitwarden exigido por padrão

    O provedor padrão é bw. Instale o CLI do Bitwarden ou use --provider example para testes.

  • Ainda sem arquivo de configuração

    O uso atual é baseado em flags. Para fluxos repetidos, encapsule comandos em scripts.

  • Não resolve mau uso do LLM

    Se você copiar uma credencial para o chat, nenhum protocolo consegue impedir a exposição.

Perguntas comuns

O Agent Access é gratuito?

Sim. O CLI, os SDKs e o protocolo são open source na organização GitHub do Bitwarden. Você ainda paga pelo Bitwarden se usá-lo como cofre.

Funciona com gerenciadores de senhas além do Bitwarden?

O protocolo foi desenhado para ser neutro em relação ao fornecedor. A implementação de referência inclui suporte ao Bitwarden e um provedor de exemplo. Outros fornecedores podem criar seus próprios provedores.

Posso usar sem um gerenciador de senhas?

Para testes, sim:

aac connect --provider example --domain test.com --output json
Enter fullscreen mode Exit fullscreen mode

Para produção, use um provedor real.

O consumidor precisa de rede?

Sim. O consumidor precisa alcançar o listener do provedor. Fluxos locais funcionam quando listener e consumidor rodam no mesmo host.

Qual a diferença para um arquivo .env?

Um .env fica no disco, pode ser commitado por acidente e pode ser lido por qualquer comando executado pelo agente.

Com aac run, o segredo fica na memória do processo filho e desaparece quando o processo termina.

Ele substitui HashiCorp Vault ou AWS Secrets Manager?

Não. Cofres empresariais continuam sendo mais adequados para segredos serviço-a-serviço em escala.

O Agent Access cobre melhor o caso de:

  • laptop de desenvolvedor;
  • scripts locais;
  • runners de CI;
  • agentes de IA que precisam executar comandos com credenciais temporárias.

Anthropic, OpenAI ou outros fornecedores integrarão isso diretamente?

Não há anúncio. O modelo atual é encapsular scripts com aac run. Suporte nativo por fornecedores de agentes seria um próximo passo natural, mas ainda não foi lançado.

Onde reportar bugs ou contribuir?

No repositório do GitHub. Issues, PRs e discussões de protocolo acontecem lá.

Experimente agora

Teste o menor fluxo de ponta a ponta:

  1. Instale aac.
  2. Em um terminal, execute: 
aac listen
Enter fullscreen mode Exit fullscreen mode
  1. Em outro terminal, use o provedor de exemplo: 
aac connect --provider example --domain test.com --output json
Enter fullscreen mode Exit fullscreen mode
  1. Confirme que o JSON foi retornado.
  2. Troque o provedor de exemplo por bw.
  3. Encapsule um script real com aac run.

Exemplo final:

aac run --domain staging.example.com --env API_TOKEN=password -- ./run-api-tests.sh
Enter fullscreen mode Exit fullscreen mode

Combine o Agent Access com o Apidog para a etapa de teste de API: o cofre guarda o segredo, o Apidog valida o contrato, o agente envia o código e nenhuma credencial precisa ser colada em texto puro.

Top comments (0)