🔱 Aquaman

🔱 El único proxy de credenciales independiente para agentes de IA: aislamiento con tu propia bóveda y políticas de solicitud de mínimo privilegio. Tus llaves se quedan donde ya las guardas, nunca en la memoria del agente. Compatible con 1Password, llavero, keepassxc y muchos más.

Configuras Claude Code, OpenClaw o Hermes, y ahora miras archivos .env con tus valiosas claves API en texto plano. Lees los artículos. Sabes lo que pasa cuando un agente sufre una inyección de prompt. Lo entendemos.

Aquaman lo soluciona con tres capas de defensa:

1. Aislamiento de procesos: Las claves API viven en un proceso proxy separado. El agente nunca las ve. Incluso un RCE en el agente no puede alcanzar las credenciales. Están en un espacio de direcciones diferente.
2. Políticas de solicitud: Reglas por servicio controlan qué endpoints puede llamar un agente. Bloquea APIs de administración, previene eliminaciones, permite borradores pero deniega envíos. Las solicitudes denegadas nunca obtienen credenciales reales.
3. Auditoría resistente a manipulaciones: Cada uso de credenciales se registra con cadenas hash SHA-256. Puedes probar qué se accedió y detectar manipulaciones a posteriori.

Elige tu camino

Aquaman se distribuye como cuatro paquetes coordinados, que comparten una bóveda y un daemon. Instala solo lo que necesites:

Una única CLI aquaman abarca los cuatro: comandos de alto nivel para bóveda y auditoría, aquaman openclaw ... para la integración con OpenClaw, aquaman coder ... para la integración con agentes de codificación (delega en aquaman-coder internamente), así como aquaman hermes ... para el paquete Python de Hermes.

Inicio rápido

aquaman help, aquaman doctor son tus amigos.

1. Solo bóveda (solo el proxy + tus secretos)

npm install -g aquaman-proxy
aquaman setup                                # asistente de backend + almacenar claves
aquaman daemon &                             # iniciar el proxy
aquaman credentials list                     # verificar

El proxy escucha en ~/.aquaman/proxy.sock (UDS, chmod 0o600). Apunta cualquier herramienta a http://aquaman.local/<servicio>/<ruta> y el proxy inyecta los encabezados de autenticación para ese servicio desde el backend de bóveda que elijas.

2. OpenClaw Gateway

openclaw plugins install aquaman-plugin           # 1. instalar plugin + proxy
openclaw aquaman setup                            # 2. backend + claves + conexión del plugin
openclaw                                          # 3. listo - el proxy se inicia automáticamente

Solución de problemas: openclaw aquaman doctor.

¿Usas npm directamente? npm install -g aquaman-proxy && aquaman openclaw setup hace lo mismo: instala el CLI del proxy, guarda tus claves, instala el plugin en ~/.openclaw/extensions/aquaman-plugin/ y conecta las credenciales (referencias SecretRef en OpenClaw ≥ 2026.6.5, el placeholder auth-profiles.json en versiones anteriores).

El interceptor HTTP del plugin solo redirige tráfico para los servicios en su configuración services (Anthropic + OpenAI por defecto). Añade más bajo la configuración del plugin en openclaw.json - los canales soportados incluyen Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face y más (25 en total).

3. Agentes de codificación de IA (Claude Code hoy)

npm install -g aquaman-proxy aquaman-coder        # 1. instalar daemon + adaptador
aquaman setup                                      # 2. asistente de bóveda
aquaman daemon &                                   # 3. iniciar el proxy

aquaman coder project add my-app --path ~/code/my-app \
  --env ANTHROPIC_API_KEY=aquaman://anthropic/api_key \
  --env GITHUB_TOKEN=aquaman://github/token         # 4. declarar un proyecto
aquaman coder setup claude-code                    # 5. conectar hooks de Claude Code
aquaman doctor                                     # 6. verificar - debería mostrar tanto bóveda como coder en verde

Compruébalo tú mismo (el momento «ajá» en 30 segundos): reinicia Claude Code, abre una nueva sesión dentro de ~/code/my-app y pídele al agente que ejecute:

printenv | grep ANTHROPIC_API_KEY

Verás esto en la transcripción:

ANTHROPIC_API_KEY=[REDACTED:valor-inyectado]

⏺ ANTHROPIC_API_KEY está establecida y disponible (inyectada a través de la bóveda de aquaman).

El proceso hijo vio la clave real (tus tests, builds, servidores MCP, scripts de importación, todo lo que realmente la necesita funciona). El agente - lo que decide qué código ejecutar en tu máquina - nunca ve el valor, y por lo tanto tampoco lo ve el historial de la conversación, ni los registros del proveedor del modelo, ni nadie que luego haga una captura de pantalla de tu terminal.

Úsalo desde tu propio terminal también. El mismo envoltorio funciona sin el agente. Solo cd a un proyecto cubierto y prefija tu comando:

cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

La misma inyección de entorno, la misma redacción en stdout/stderr. Incorpóralo en objetivos de Makefile, alias de shell o ejecutores de CI, en cualquier lugar donde de otro modo recurrirías a un archivo .env.

Cuando Claude Code ejecuta la herramienta Bash en ~/code/my-app, el hook de aquaman reescribe el comando mediante updatedInput.command para envolverlo bajo aquaman-coder exec. Ese envoltorio:

• Resuelve cada referencia aquaman://servicio/clave a través del broker (POST /broker/resolve sobre UDS). Las credenciales se materializan para un solo comando, no para toda la vida del agente.
• Canaliza stdout/stderr a través de un redactor que antepone un patrón basado en el valor para cada valor resuelto: cualquier cadena inyectada se redacta, independientemente de su forma (tokens de Atlassian, secretos de Notion, claves de API internas - ninguna necesita coincidir con un formato de proveedor conocido). Los patrones genéricos basados en forma (sk-ant-, ghp_, sk_live_, AKIA…, JWT, bloques PEM, ATATT3xF…) aún se ejecutan después como defensa en profundidad para secretos que el hijo muestre y que NO hayamos inyectado.
• Limpia cuando el comando termina.

4. Hermes (host de agente)

Hermes es un host externo (Python) sin un hook de transporte para inyectar, por lo que el aislamiento se realiza del lado del proxy: el proxy expone un listener de loopback opt-in y protegido por token, y Hermes se apunta a él a través de sus propias variables de entorno.

npm install -g aquaman-proxy                       # 1. instalar daemon
aquaman setup                                      # 2. asistente de bóveda
aquaman credentials add anthropic api_key sk-ant-... # 3. almacenar una clave de proveedor

aquaman hermes setup                               # 4. habilitar loopback + escribir ~/.hermes/.env
aquaman daemon &                                   # 5. iniciar el proxy (UDS + loopback)
aquaman hermes doctor                              # 6. verificar - listener + env + bóveda + Hermes

aquaman hermes setup habilita el listener de loopback, genera un token por instalación y escribe un bloque gestionado por aquaman en ~/.hermes/.env (respetando HERMES_HOME): las variables nativas ANTHROPIC_BASE_URL/OPENAI_BASE_URL más un placeholder api_key igual al token. Hermes envía el token como su clave de proveedor; el proxy lo elimina, inyecta tu credencial real de la bóveda y lo reenvía. Solo proveedores de LLM (Anthropic, OpenAI) por ahora.

Azúcar opcional en sesión - el plugin de Python añade un comando /aquaman-status, una herramienta aquaman_status y un sondeo de salud al inicio de la sesión dentro de Hermes (no tiene credenciales):

pip install aquaman-hermes            # o: uv tool install aquaman-hermes
aquaman-hermes install                # coloca el plugin en ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman

Cómo funciona

Agent / OpenClaw / Coding Agent             Aquaman Proxy
┌──────────────────────┐                    ┌──────────────────────┐
│                      │                    │                      │
│  ANTHROPIC_BASE_URL  │═══ UDS / HTTP ════>│  Keychain / 1Pass /  │
│  = aquaman.local     │                    │  Vault / Encrypted   │
│                      │<══════════════════ │                      │
│  fetch() interceptor │═══ broker:resolve  │  + Policy enforced   │
│   (channel APIs)     │                    │  + Auth injected:    │
│                      │                    │    header / url-path │
│  No credentials.     │  ~/.aquaman/       │    basic / oauth     │
│  No open ports.      │  proxy.sock        │                      │
│  Nothing to steal.   │  (chmod 0o600)     │                      │
└──────────────────────┘                    └──┬─────────┬─────────┘
                                               │         │
                                               │         ▼
                                               │  ~/.aquaman/audit/
                                               │  (hash-chained)
                                               ▼
                                     api.anthropic.com
                                     api.telegram.org
                                     slack.com/api …

1. Almacena: Las credenciales viven en el backend de bóveda que ya ejecutas - sin bóveda interna (Llavero, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, archivo cifrado).
2. Política: El proxy verifica reglas de método + ruta antes de tocar las credenciales. Las solicitudes denegadas reciben un 403, nunca encabezados de autenticación reales.
3. Inyecta: El proxy busca la credencial y añade el encabezado de autenticación antes de reenviar. 25 servicios incorporados, 4 modos de autenticación inyectada (encabezado, ruta URL, HTTP Basic, OAuth); un quinto, none, es solo en reposo (el proxy rechaza tráfico).
4. Broker (ruta coder): POST /broker/resolve materializa una credencial por llamada a herramienta, con ámbito en el entorno de un solo comando, luego expira.
5. Auditoría: Cada uso de credenciales se registra con cadenas hash SHA-256.

El agente solo ve un nombre de host centinela (aquaman.local) o un marcador placeholder (aquaman-proxy-managed). Nunca ve una clave real, y ningún puerto TCP está abierto para que otros procesos lo sondeen.

Modelo de seguridad

El modelo detallado - especificidades por integración (alcance del interceptor HTTP, perfiles de autenticación, hallazgos del escáner, nota del editor de ClawScan) - se encuentra en packages/plugin/README.md y packages/coder/README.md.

Postura de cumplimiento

Aquaman incluye pruebas de conformidad ejecutables bajo test/compliance/ mapeadas a:

• MITRE ATLAS v5.4.0: técnicas AML.T0055, T0012, T0062, T0090, T0098 (test/compliance/atlas/)
• NIST SP 800-53 Rev 5: IA-5, AC-3, AC-6, AU-2/9/10, SC-12/28, SI-10 (test/compliance/nist/)

Además, narrativas de alineación para la guía CISA/Cinco Ojos "Adopción Cuidadosa de Servicios de IA Agéntica" (abril de 2026), CSA MAESTRO y OWASP Top 10 para Aplicaciones Agénticas. Las pruebas se ejecutan como parte de npm test. Consulta docs/compliance/ para los mapeos.

Políticas de solicitud

Los alcances de OAuth no pueden distinguir entre «redactar un correo» y «enviar un correo». Ambos son gmail.send. Las políticas de solicitud llenan ese vacío.

# ~/.aquaman/config.yaml
policy:
  anthropic:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organizations/**"
        action: deny          # bloquear API de administración/facturación
  openai:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organization/**"
        action: deny
      - method: DELETE
        path: "/v1/**"
        action: deny          # sin eliminaciones
  slack:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/admin.*"
        action: deny
  gmail:
    defaultAction: allow
    rules:
      - method: POST
        path: "/v1/users/*/messages/send"
        action: deny          # borradores ok, envío bloqueado

• Sin política = permitir todo (compatible con versiones anteriores)
• Primera coincidencia gana: las reglas se evalúan de arriba a abajo; las solicitudes no coincidentes pasan a defaultAction
• Denegado antes de la autenticación: las solicitudes bloqueadas nunca obtienen credenciales reales
• Globs de ruta: * coincide dentro de un segmento, ** coincide con cero o más segmentos
• aquaman setup aplica valores predeterminados seguros para los servicios almacenados (anthropic, openai, slack, gmail).
• aquaman policy list / aquaman policy test <svc> <method> <path> para inspección/pruebas en seco.

Backends de credenciales

Trae tu propia bóveda - aquaman no tiene almacenamiento interno. Elige el backend que ya ejecutas; los secretos se quedan allí y el proxy los lee en su lugar.

aquaman setup detecta automáticamente un valor predeterminado razonable (macOS → keychain; Linux → keychain si libsecret, sino systemd-creds si systemd ≥ 256, sino encrypted-file).

encrypted-file es un último recurso para entornos Linux/CI sin un llavero nativo. Para mejor seguridad en Linux, instala libsecret-1-dev (GNOME Keyring), usa systemd-creds (enlace TPM2) o usa 1Password/Vault.

Caché de credenciales (v0.13.1+)

Los backends con un costo por acceso — 1password (una solicitud biométrica por lectura en modo app de escritorio), bitwarden (~1-2 s de creación del CLI), vault (un viaje redondo HTTP) — se almacenan en caché en la memoria del daemon durante 15 minutos por defecto, de modo que una sesión de agente ocupada desbloquea la bóveda una vez por ventana en lugar de una vez por solicitud. Los otros backends ya son rápidos o almacenan en caché internamente, por lo que la caché está desactivada para ellos por defecto. Ajusta con credentials.cacheTtlSeconds en ~/.aquaman/config.yaml (o AQUAMAN_CACHE_TTL); 0 desactiva.

La compensación honesta: una solicitud biométrica por acceso es una verificación de presencia del usuario, y la caché elimina la verificación de presencia por acceso durante la ventana TTL. Para agentes desatendidos, esa solicitud nunca se responde — se abandona la bóveda por un .env en texto plano, que es estrictamente peor. La caché no mueve el límite de aislamiento: los valores viven solo en el proceso proxy (donde ya transitan en cada solicitud), nunca se escriben en disco y se invalidan inmediatamente cuando rotas mediante aquaman credentials add. Las escrituras siempre van a tu bóveda. Probado en conformidad en test/compliance/cache-residency.test.ts. Para cero solicitudes con 1Password, usa una cuenta de servicio con ámbito en la bóveda aquaman — aquaman doctor te indicará cómo.

Licencia

MIT - ver LICENSE.