DEV Community

Cover image for Acceso Seguro a Agentes Bitwarden: Comparte Credenciales con IA de Codificación
Roobia
Roobia

Posted on • Originally published at apidog.com

Acceso Seguro a Agentes Bitwarden: Comparte Credenciales con IA de Codificación

#agents #ai #security #spanish

Si usa Claude Code, Codex o Cursor con cualquier flujo que toca una API real, el agente necesita credenciales. Ahí aparece el problema: su gestor de contraseñas intenta mantenerlas bloqueadas, pero el agente necesita ejecutarlas. Pegar una API key en el chat la deja dentro del contexto del modelo. Guardarla en un .env permite que cualquier comando ejecutado por el agente la lea, la imprima o la envíe fuera. La solución práctica es dar acceso temporal, con alcance mínimo y sin exponer el secreto al modelo.

Prueba Apidog hoy

El proyecto open source de Bitwarden, Agent Access, propone una forma más segura de resolverlo. Incluye un protocolo para compartir credenciales, una CLI (aac) y SDKs de Rust y Python. Su objetivo es crear un túnel cifrado entre un proveedor de credenciales —por ejemplo, Bitwarden— y un consumidor remoto: un agente, un script, un runner de CI o una herramienta interna.

En esta guía verá cómo instalar Agent Access, cómo usar aac connect y aac run, y cómo aplicarlo en flujos con Claude Code, Codex, Cursor y pruebas de API. También complementa las prácticas de higiene descritas en Cómo asegurar las credenciales de API de agentes de IA.

Qué es Agent Access

Agent Access es un protocolo abierto y una implementación de referencia creada por Bitwarden. La CLI aac establece un túnel cifrado de extremo a extremo usando el protocolo Noise.

El modelo tiene dos partes:

  • Proveedor: proceso que tiene acceso a la bóveda o fuente de credenciales.
  • Consumidor: agente, script, runner de CI o proceso remoto que solicita una credencial.

El consumidor no obtiene acceso a la bóveda completa. Solo puede pedir una credencial por:

  • dominio, por ejemplo github.com
  • ID de elemento de bóveda

El proveedor decide qué entregar. El consumidor recibe únicamente la credencial permitida.

Agent Access está en vista previa temprana. El README advierte que las APIs y protocolos pueden cambiar y que no se recomienda introducir credenciales sensibles directamente en LLMs o agentes de IA.

El patrón recomendado es usar aac run: inyectar secretos como variables de entorno en un subproceso, sin mostrarlos al modelo ni escribirlos en disco.

Por qué importa para agentes de IA

Los agentes de codificación ya no solo sugieren código. Ahora pueden:

  • leer repositorios
  • ejecutar tests
  • llamar APIs
  • abrir pull requests
  • desplegar servicios
  • interactuar con CI/CD

Cada una de esas acciones suele requerir credenciales. El incidente de claves de API expuestas de Postman mostró lo difícil que es mantener buena higiene de secretos incluso cuando solo intervienen humanos. Con agentes, el riesgo aumenta.

La solución no es confiar más en el agente. Es darle menos acceso.

Agent Access aplica este principio:

  • credenciales con alcance limitado
  • cifrado en tránsito
  • obtención en tiempo de ejecución
  • sin persistencia en disco por defecto
  • credenciales disponibles solo mientras vive el proceso

Frente a otras herramientas de gestión de claves API, Agent Access se enfoca en el caso específico de agentes y procesos automatizados.

Instalación

Elija el binario correspondiente a su 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

Descargue aac-windows-x86_64.zip desde la página de releases y extraiga el ejecutable en un directorio incluido en su PATH.

Verifique la instalación:

aac --help
Enter fullscreen mode Exit fullscreen mode

Si la CLI de Bitwarden (bw) está en su PATH, aac la usará como proveedor de credenciales predeterminado.

Para pruebas locales sin Bitwarden, use el proveedor de demostración:

aac --provider example
Enter fullscreen mode Exit fullscreen mode

Inicio rápido: emparejar y obtener una credencial

Ejecute el listener en la máquina que tiene acceso a la bóveda, normalmente su portátil:

aac listen
Enter fullscreen mode Exit fullscreen mode

El comando imprimirá un token de emparejamiento.

Desde el consumidor —otra terminal, un host remoto o un runner— use ese token para solicitar una credencial por dominio:

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

La respuesta tendrá esta forma:

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

Su script puede parsear ese JSON y usar los campos necesarios.

También puede solicitar una credencial por ID de elemento de bóveda:

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

--id y --domain son mutuamente excluyentes. Use uno u otro.

Si el elemento de bóveda tiene TOTP configurado, el código se devuelve en el mismo payload.

Patrón recomendado: aac run

aac connect es útil cuando su script puede procesar JSON. Para agentes de IA, el patrón más seguro suele ser aac run.

aac run obtiene la credencial y ejecuta un proceso hijo con los secretos inyectados como variables de entorno.

No imprime el secreto en stdout, no lo escribe en disco y no lo expone directamente al prompt del agente.

Inyectar campos específicos 

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

En este ejemplo:

  • DB_PASSWORD recibe el campo password
  • DB_USER recibe el campo username
  • psql se ejecuta como proceso hijo

Inyectar todos los campos 

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

Con --env-all, los campos se exponen con prefijo AAC_.

Combinar --env-all con variables personalizadas 

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

Campos disponibles:

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

Ejemplo: envolver un despliegue

Suponga que tiene este script:

# run-deploy.sh
#!/usr/bin/env bash

curl -H "Authorization: Bearer $AAC_PASSWORD" \
  https://api.example.com/deploy
Enter fullscreen mode Exit fullscreen mode

No ejecute ese script directamente desde el agente. Envuélvalo:

# deploy.sh
#!/usr/bin/env bash

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

Luego indique al agente que ejecute:

./deploy.sh
Enter fullscreen mode Exit fullscreen mode

El modelo ve el comando, pero no ve el valor de $AAC_PASSWORD.

Si el agente intenta imprimir la variable desde fuera del subproceso, no tendrá acceso a ella. El secreto solo existe en el entorno del proceso hijo ejecutado por aac run.

Este es el mismo principio de aislamiento explicado en Cómo asegurar las credenciales de API de agentes de IA, aplicado con una herramienta concreta.

SDKs de Python y Rust

Si una llamada CLI no es suficiente, Agent Access también ofrece SDKs.

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

El módulo de Python está respaldado por PyO3, por lo que la implementación de bajo nivel permanece en Rust.

Úselo cuando quiera integrar Agent Access dentro de una aplicación o herramienta propia en Python.

Rust

El SDK de Rust expone la interfaz RemoteClient como biblioteca de primera clase. Las implementaciones de referencia están en:

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

Tiene sentido usarlo para:

  • CLIs internas
  • runners de build
  • herramientas de despliegue
  • servicios que distribuyen binarios compilados

Para equipos que ya trabajan con gestores empresariales, Agent Access puede convivir con integraciones como HashiCorp Vault o Azure Key Vault. No los reemplaza en todos los escenarios, pero cubre bien el caso de portátiles de desarrollador, scripts locales y runners de CI.

Integración con agentes de codificación

Claude Code

Para Claude Code, cree scripts que encapsulen aac run.

Ejemplo:

# deploy.sh
#!/usr/bin/env bash

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

Luego configure el flujo de trabajo para que Claude Code ejecute:

./deploy.sh
Enter fullscreen mode Exit fullscreen mode

El agente invoca el script, pero no recibe la credencial en el prompt.

El mismo patrón puede extenderse a CI. En un flujo como Claude Code GitHub Actions, el runner instala aac, se empareja con un proveedor de bóveda y obtiene credenciales con alcance durante el job.

OpenAI Codex

Para Codex, use el mismo enfoque: el modelo llama scripts, no secretos.

# test-api.sh
#!/usr/bin/env bash

aac run --domain staging.example.com \
  --env API_TOKEN=password \
  -- npm test
Enter fullscreen mode Exit fullscreen mode

La capa de herramientas muestra el comando al modelo, pero el valor de API_TOKEN queda fuera de su contexto.

La publicación Codex desde su teléfono cubre la superficie general de Codex; este patrón se enfoca en la gestión de credenciales.

Cursor

En Cursor, aplique el mismo diseño a comandos de terminal y flujos de Composer.

Por ejemplo:

# local-contract-test.sh
#!/usr/bin/env bash

aac run --domain api.local.example.com \
  --env-all \
  -- npm run test:contract
Enter fullscreen mode Exit fullscreen mode

Como Cursor suele ejecutarse en la máquina local, el listener y el consumidor pueden estar en el mismo host.

OpenClaw

Agent Access incluye una habilidad oficial de OpenClaw lista para usar. El repositorio contiene un SKILL.md.

Para equipos que usan habilidades de estilo OpenClaw, esta integración permite que la habilidad conozca el protocolo, solicite credenciales y las entregue a herramientas descendentes sin exponer la bóveda completa.

La guía de claves API de OpenClaw cubre el contexto más amplio de credenciales en ese ecosistema.

Modelo de seguridad

Agent Access se apoya en tres ideas principales.

1. Cifrado de extremo a extremo

El tráfico entre consumidor y proveedor usa el marco del protocolo Noise, la misma familia de handshakes utilizada por sistemas como WireGuard y Signal.

2. Credenciales con alcance

El consumidor solicita una credencial por dominio o por ID de elemento. No puede enumerar la bóveda completa.

Ejemplo:

aac connect --domain github.com --output json
Enter fullscreen mode Exit fullscreen mode

Esa llamada no debería dar acceso a credenciales de otros dominios.

3. Sin secretos en disco por defecto

Con aac run, los secretos se pasan como variables de entorno al proceso hijo.

No se escriben automáticamente en:

  • archivos .env
  • logs
  • historial de shell
  • salida estándar

Lo que Agent Access no resuelve

Agent Access reduce exposición, pero no elimina todos los riesgos.

No protege contra:

  • Un consumidor comprometido: si el proceso que recibe la credencial es malicioso, puede filtrarla.
  • Un proveedor comprometido: si su bóveda está comprometida, Agent Access no puede corregirlo.
  • Secretos pegados manualmente en prompts: si copia una API key en una ventana de chat, el protocolo ya no interviene.

La defensa principal es el alcance. Entregue al agente solo la credencial mínima, durante el menor tiempo posible.

Patrón común: agente + CI + Apidog

Un flujo práctico para equipos que usan agentes de IA y APIs puede verse así:

  1. El agente modifica el código

    • Claude Code, Codex o Cursor editan un endpoint.
    • El agente abre un PR.

  2. CI ejecuta pruebas

    • El runner llama aac run.
    • La clave de API se inyecta solo en el proceso de test.

  3. Apidog valida el contrato

    • Apidog ejecuta pruebas de contrato OpenAPI como paso separado.
    • También puede ejecutarse detrás de aac run.

Ejemplo:

aac run --domain staging-api.example.com \
  --env API_TOKEN=password \
  -- npm run test:contract
Enter fullscreen mode Exit fullscreen mode

Resultado:

  • el agente genera código
  • CI valida el cambio
  • Apidog verifica el contrato
  • la credencial no entra en el contexto del modelo

Para profundizar en pruebas de cambios generados por agentes, vea Cómo probar agentes de IA que llaman a sus API.

Limitaciones actuales

Tenga en cuenta estas advertencias antes de usarlo en producción.

  • Vista previa temprana: las APIs y protocolos pueden cambiar.
  • Proveedor Bitwarden por defecto: si usa la integración real, instale primero la CLI de Bitwarden.
  • Proveedor de demo solo para pruebas: --provider example sirve para experimentar, no para producción.
  • Sin archivo de configuración estable: actualmente se trabaja principalmente con flags, por lo que conviene envolver comandos repetidos en scripts.
  • No evita errores manuales: si pega secretos en prompts, Agent Access no puede protegerlos.

Checklist de implementación

Use esta lista para empezar de forma segura:

  1. Instale aac.
  2. Verifique que funciona: 
   aac --help
Enter fullscreen mode Exit fullscreen mode
  1. Pruebe el proveedor de ejemplo: 
   aac listen
Enter fullscreen mode Exit fullscreen mode
  1. Desde otra terminal, conecte: 
   aac connect --provider example --domain test.com --output json
Enter fullscreen mode Exit fullscreen mode
  1. Reemplace el proveedor de ejemplo por Bitwarden (bw).
  2. Cree scripts pequeños que encapsulen aac run.
  3. Configure su agente para ejecutar esos scripts, no comandos con secretos.
  4. Evite imprimir variables sensibles en logs.
  5. Use dominios o IDs de bóveda con alcance mínimo.
  6. Revise periódicamente los accesos y credenciales usadas por sus agentes.

Preguntas frecuentes

¿Agent Access es gratuito?

Sí. La CLI, los SDKs y el protocolo son open source bajo la organización de Bitwarden en GitHub. Si usa Bitwarden como bóveda, sigue aplicando el modelo de uso o pago correspondiente a Bitwarden.

¿Funciona con otros gestores de contraseñas?

El protocolo está diseñado para ser independiente del proveedor. La implementación de referencia incluye soporte para Bitwarden y un proveedor de ejemplo. Otros proveedores podrían implementar el protocolo en el futuro.

¿Puedo usarlo sin gestor de contraseñas?

Para pruebas, sí:

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

Para producción, necesita un proveedor real.

¿El consumidor necesita acceso a red?

Sí. El consumidor debe poder comunicarse con el listener del proveedor. También puede usarlo localmente si listener y consumidor corren en el mismo host.

¿En qué se diferencia de un archivo .env?

Un .env vive en disco, puede terminar en Git y puede ser leído por cualquier comando que el agente ejecute.

aac run mantiene el secreto en el entorno del proceso hijo y desaparece cuando ese proceso termina.

¿Reemplaza a HashiCorp Vault o AWS Secrets Manager?

No. Las bóvedas empresariales siguen siendo adecuadas para secretos de servicio a servicio a gran escala.

Agent Access cubre mejor el espacio de:

  • portátiles de desarrollador
  • agentes de codificación
  • scripts locales
  • runners de CI
  • herramientas temporales

¿Anthropic, OpenAI u otros proveedores lo integran directamente?

No hay integración directa anunciada. El modelo actual es envolver scripts con aac run.

¿Dónde puedo reportar errores o contribuir?

En el repositorio de GitHub. Allí se gestionan issues, pull requests y discusiones del protocolo.

Prueba mínima

Para validar el flujo completo:

aac listen
Enter fullscreen mode Exit fullscreen mode

Luego, en otra terminal:

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

Si recibe JSON, el ciclo básico funciona.

Después:

  1. Configure bw como proveedor real.
  2. Cree un wrapper con aac run.
  3. Use ese wrapper desde Claude Code, Codex, Cursor o CI.
  4. Deje de pegar API keys en prompts.

Combine Agent Access con Apidog para separar responsabilidades: la bóveda guarda el secreto, Apidog prueba el contrato, el agente modifica el código y las credenciales no salen en texto plano.

Top comments (0)