🔱 Aquaman

🔱 O único proxy de credenciais independente para agentes de IA: isolamento bring-your-own-vault e políticas de requisição de privilégio mínimo. Suas chaves permanecem onde você já as guarda, nunca na memória do agente. Compatível com 1Password, keychain, keepassxc e muitos outros.

Você configurou o Claude Code, OpenClaw ou Hermes, e agora está encarando arquivos .env com suas preciosas chaves de API expostas em texto puro. Você leu os artigos. Você sabe o que acontece quando um agente sofre prompt injection. Nós entendemos.

O Aquaman resolve isso com três camadas de defesa:

1. Isolamento de processo: as chaves de API vivem em um processo proxy separado que as injeta na saída. O agente carrega um marcador, nunca uma chave, então mesmo um RCE no agente não consegue lê-la. Agentes de codificação recebem apenas as referências que você declara, um comando por vez.
2. Políticas de requisição: regras por serviço controlam quais endpoints um agente pode chamar. Bloqueie APIs administrativas, impeça exclusões, permita rascunhos mas negue envios. Requisições negadas nunca recebem credenciais reais.
3. Auditoria à prova de adulteração: cada uso de credencial é registrado com cadeias de hash SHA-256. Você pode provar o que foi acessado e detectar adulterações posteriormente.

Escolha seu caminho

O Aquaman é distribuído como quatro pacotes coordenados, compartilhando um vault + um daemon. Instale apenas o que você precisa:

Uma única CLI aquaman expõe todos os quatro: comandos de nível superior para vault e auditoria, aquaman openclaw ... para a integração com OpenClaw, aquaman coder ... para a integração com agente de codificação (delegando ao aquaman-coder nos bastidores) bem como aquaman hermes ... para o pacote Python do Hermes.

Início Rápido

aquaman help, aquaman doctor são seus amigos.

1. Apenas o vault (somente o proxy + seus segredos)```bash

npm install -g aquaman-proxy aquaman setup # backend wizard + store keys aquaman daemon & # start the proxy aquaman credentials list # verify

O proxy escuta em `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`). Aponte qualquer ferramenta para `http://aquaman.local/<service>/<path>` e o proxy injeta os cabeçalhos de autenticação para esse serviço a partir do backend de cofre escolhido.

### 2. OpenClaw Gateway```bash
openclaw plugins install aquaman-plugin           # 1. install plugin + proxy
openclaw aquaman setup                            # 2. backend + keys + plugin wire-up
openclaw                                          # 3. done - proxy starts automatically

Solução de problemas: openclaw aquaman doctor.

Usando npm diretamente? npm install -g aquaman-proxy && aquaman openclaw setup faz o mesmo - instala a CLI do proxy, armazena suas chaves, instala o plugin em ~/.openclaw/extensions/aquaman-plugin/ e configura as credenciais (refs SecretRef no OpenClaw ≥ 2026.6.5, o placeholder auth-profiles.json em versões mais antigas).

aquaman openclaw setup aponta models.providers.<svc>.baseUrl e channels.telegram.apiRoot para o listener de loopback do proxy, porque o transporte de modelo do OpenClaw e seus canais constroem cada um seu próprio cliente HTTP e ignoram o interceptor de fetch. Canais diferentes do Telegram não expõem substituição de endpoint, então seus tokens são armazenados e migrados mas não injetados na saída (veja packages/plugin/README.md). Adicione canais sob a configuração do plugin em openclaw.json; os suportados incluem Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face, e mais (25 no total).

3. Agentes de codificação com IA (Claude Code atualmente)```bash

npm install -g aquaman-proxy aquaman-coder # 1. install daemon + adapter aquaman setup # 2. vault wizard aquaman daemon & # 3. start the 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. declare a project aquaman coder setup claude-code # 5. wire Claude Code hooks aquaman doctor # 6. verify - should show both vault + coder green

**Veja você mesmo (o momento "aha" de 30 segundos):** reinicie o Claude Code, abra uma nova sessão dentro de `~/code/my-app` e peça ao agente para executar:```
printenv | grep ANTHROPIC_API_KEY

Você verá isto na transcrição:``` ANTHROPIC_API_KEY=[REDACTED:injected-value]

⏺ ANTHROPIC_API_KEY is set and available (injected via aquaman vault).

O processo *filho* viu a chave real (seus testes, builds, servidores MCP, scripts de importação - qualquer coisa que realmente precise dela funciona). O *agente* - a coisa que decide qual código executar na sua máquina - nunca vê o valor, e portanto nem o histórico da conversa, nem os logs do provedor do modelo, nem qualquer pessoa que depois tire um screenshot do seu terminal.

**Use-o também no seu próprio terminal.** O mesmo wrapper funciona sem o agente. Basta fazer `cd` para um projeto coberto e prefixar o seu comando:```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

Mesma injeção de env, mesma redação em stdout/stderr. Coloque-o em alvos de Makefile, aliases de shell ou runners de CI - em qualquer lugar onde você, de outra forma, recorreria a um arquivo .env.

Quando o Claude Code executa uma ferramenta Bash em ~/code/my-app, o hook do aquaman reescreve o comando via updatedInput.command para envolvê-lo sob aquaman-coder exec. Esse wrapper:

• Resolve cada referência aquaman://service/key através do broker (POST /broker/resolve sobre UDS). As credenciais são materializadas para um comando, não para o tempo de vida do agente.
• Canaliza stdout/stderr através de um redator que prefixa um padrão baseado em valor para cada valor resolvido: qualquer string que foi injetada é redigida, independentemente da forma (tokens Atlassian, segredos Notion, chaves de API internas - nenhum deles precisa corresponder a um formato de provedor conhecido). Padrões genéricos baseados em forma (sk-ant-, ghp_, sk_live_, AKIA…, JWTs, blocos PEM, ATATT3xF…) ainda são executados depois como defesa em profundidade para segredos que o processo filho expõe e que NÃO injetamos.
• Limpa quando o comando termina.

Sandbox do Claude Code: ele bloqueia sockets Unix por padrão, então aquaman coder setup claude-code adiciona o socket do proxy à allowlist no macOS (sandbox.network.allowUnixSockets). Linux e WSL2 ignoram essa lista, onde a única opção é sandbox.network.allowAllUnixSockets: true, que abre todos os sockets Unix para comandos em sandbox.

4. Hermes (host de agente)

Hermes é um host estrangeiro (Python) sem hook de transporte para injetar, então o isolamento é feito no lado do proxy: o proxy expõe um listener de loopback opcional, protegido por token, e o Hermes é apontado para ele através de suas próprias variáveis de ambiente.```bash npm install -g aquaman-proxy # 1. install daemon aquaman setup # 2. vault wizard aquaman credentials add anthropic api_key sk-ant-... # 3. store a provider key

aquaman hermes setup # 4. enable loopback + write ~/.hermes/.env aquaman daemon & # 5. start the proxy (UDS + loopback) aquaman hermes doctor # 6. verify - listener + env + vault + Hermes

`aquaman hermes setup` ativa o listener de loopback, gera um token por instalação e escreve um bloco gerenciado pelo aquaman em `~/.hermes/.env` (respeitando `HERMES_HOME`): o `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` nativo mais uma api_key placeholder igual ao token. O Hermes envia o token como sua chave de provedor; o proxy o remove, injeta sua credencial real do vault e encaminha para upstream. Apenas provedores de LLM (Anthropic, OpenAI) atualmente.

**Açúcar opcional em sessão** - o plugin Python adiciona um comando `/aquaman-status`, uma ferramenta `aquaman_status` e uma sondagem de saúde no início da sessão dentro do Hermes (não mantém credenciais):```bash
pip install aquaman-hermes            # or: uv tool install aquaman-hermes
aquaman-hermes install                # drops the plugin into ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman

O plugin também registra uma secret source aquaman (Hermes ≥ 0.18.1) para segredos de projeto como GITHUB_TOKEN. Vincule-os em secrets.aquaman.env no config.yaml do Hermes, depois declare cada ref com aquaman broker allow aquaman://github/token (obrigatório desde a v0.15.0; aquaman hermes doctor lista os que você esqueceu). Diferente das chaves de LLM acima, esses valores entram no env do Hermes. Veja packages/hermes/README.md.

Como 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 │ │ │ No keys to read. │ (chmod 0o600) │ │ └──────────────────────┘ └──┬─────────┬─────────┘ │ │ │ ▼ │ ~/.aquaman/audit/ │ (hash-chained) ▼ api.anthropic.com api.telegram.org slack.com/api …

1. **Store**: As credenciais ficam no backend de cofre que você já executa - sem cofre próprio (Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, arquivo criptografado).
2. **Policy**: O proxy verifica as regras de método + caminho *antes* de tocar nas credenciais. Requisições negadas recebem um `403`, nunca cabeçalhos de autenticação reais.
3. **Inject**: O proxy busca a credencial e adiciona o cabeçalho de autenticação antes de encaminhar. 25 serviços integrados, 4 modos de injeção de autenticação (header, URL-path, HTTP Basic, OAuth); um 5º, `none`, é apenas em repouso (o proxy rejeita o tráfego).
4. **Broker (coder + fonte de segredos do Hermes)**: `POST /broker/resolve` materializa uma credencial por chamada de ferramenta, com escopo no env de um único comando. Apenas `aquaman daemon` o serve, e apenas para refs que você declarou (`projects.yaml` ou `aquaman broker allow`). O proxy do plugin OpenClaw nunca o serve (v0.15.0+).
5. **Audit**: Todo uso de credencial é registrado com cadeias de hash SHA-256.

Nos caminhos do proxy, o agente vê um endpoint local mais um marcador: o placeholder `aquaman-proxy-managed`, ou o token de loopback, que só funciona contra o seu proxy local. Nunca uma chave real. No caminho do coder, o comando *filho* recebe os valores declarados e o agente vê a saída redigida.

## Security Model

| Layer | What it does | What it stops |
|---|---|---|
| **Process isolation** | Credentials in a separate process, reached over a Unix socket (`chmod 0o600`) or a token-gated loopback listener | Compromised agent can't read proxied keys: different address space |
| **Broker scope** | Only `aquaman daemon` hands out values, and only for refs you declared; OpenClaw-hosted proxies never do (v0.15.0+) | An agent can't pull arbitrary vault entries through the socket |
| **Service allowlisting** | `proxiedServices` controls which APIs the agent can reach | Agent can't talk to services you didn't authorize |
| **Request policies** | Method + path rules per service, enforced before credential injection | Agent can reach Anthropic but not its admin API; can draft emails but not send them |
| **Audit trail** | SHA-256 hash-chained logs of every credential use | Post-incident forensics, tamper detection, compliance evidence |
| **Per-tool-call broker (coder)** | `aquaman-coder exec` materializes creds for one command at a time | Credentials don't sprawl across the agent's shell environment |
| **Output redaction (coder)** | `aquaman-coder exec` pipes stdout/stderr through a redactor that scrubs each value it just injected verbatim - plus generic provider patterns as a fallback | Even arbitrary, shape-less credentials never reach the agent transcript |

### Transports and access control

| Path | Transport | Access control |
|---|---|---|
| Coding agents, any client that can dial a socket | Unix socket `~/.aquaman/proxy.sock` | File permissions (`0600`): only processes running as you |
| Hermes (v0.13.0+), OpenClaw model and Telegram traffic (v0.15.0+) | Loopback TCP `127.0.0.1:<port>` | Per-install token, constant-time check, loopback bind |

Hermes e OpenClaw constroem cada um seu próprio cliente HTTP e não conseguem discar um socket, então usam o listener. Todo o resto usa o socket.

O token é uma capacidade de alcançar o proxy local, não uma credencial. Gerado por instalação, armazenado em `~/.aquaman/config.yaml` (`0600`), enviado pelo host como sua chave de API do provedor. O proxy o verifica, o remove, injeta sua chave real. O Telegram não tem cabeçalho de autenticação, então lá o token viaja no segmento de caminho `/bot<TOKEN>`.

Trade-off: qualquer processo local pode alcançar uma porta de loopback, incluindo outros usuários, onde o `0600` do socket os exclui. O token é o portão ali, então o listener permanece desligado até que `aquaman hermes setup` ou `aquaman openclaw setup` o ative.

### Channel credentials on OpenClaw 2026.7.33+

| Channel | Egress through the proxy |
|---|---|
| Telegram | Yes, since v0.15.0 |
| Everything else | No. Vault storage and migration only |

Cada canal constrói seu próprio cliente HTTP por requisição, então o interceptor `fetch` do plugin não vê mais o tráfego de canais nessas versões. Rotear um canal exige uma substituição de endpoint pelo host, e o Telegram é o único que a possui: `aquaman openclaw setup` aponta `channels.telegram.apiRoot` para o proxy e substitui o token do bot pelo token de loopback.

Para o resto, seu token permanece no cofre, mas o OpenClaw o usa diretamente, então o proxy não está no caminho e essas chamadas não são auditadas. `aquaman openclaw doctor` lista quais dos seus canais configurados estão em qual grupo. Provedores de modelo não são afetados.

**O que o isolamento de mesmo usuário não consegue fazer.** O `0o600` do socket mantém outros usuários fora, não outros processos executando como você. Tal processo pode enviar requisições através do proxy enquanto ele executa (limitado pela política de requisições, registrado no log de auditoria) e pode buscar refs que você declarou, que é o que declarar significa. Ele não consegue ler as chaves que o proxy injeta. Para uma fronteira mais rígida, execute o agente como um usuário de SO diferente ou em um sandbox.

Modelo detalhado - especificidades por integração (escopo do interceptor HTTP, perfis de autenticação, descobertas do scanner, nota do publicador do ClawScan) - está em [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) e [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md).

### Compliance posture

O Aquaman fornece testes de conformidade executáveis em `test/compliance/` mapeados para:

- **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/`)

Além de narrativas de alinhamento para CISA/Five-Eyes "Careful Adoption of Agentic AI Services" (abril de 2026), CSA MAESTRO e OWASP Top 10 for Agentic Applications. Os testes rodam como parte de `npm test`. Veja [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) para os mapeamentos.


## Request Policies

Escopos OAuth não conseguem distinguir entre "rascunhar um e-mail" e "enviar um e-mail". Ambos são `gmail.send`. As políticas de requisição preenchem essa lacuna.```yaml
# ~/.aquaman/config.yaml
policy:
  anthropic:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organizations/**"
        action: deny          # block admin/billing API
  openai:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organization/**"
        action: deny
      - method: DELETE
        path: "/v1/**"
        action: deny          # no deletions
  slack:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/api/admin.*"
        action: deny          # Slack Web API admin methods
  gmail:
    defaultAction: allow
    rules:
      - method: POST
        path: "/gmail/v1/users/*/messages/send"
        action: deny          # drafts ok, sending blocked

• Os caminhos são o caminho completo da API upstream após o prefixo do serviço: a Web API do Slack é /api/<method>, a do Gmail é /gmail/v1/.... Presets anteriores à v0.15.0 usavam /admin.* e /v1/users/*/messages/send, que nunca correspondiam ao tráfego real. O aquaman doctor sinaliza esses casos se ainda estiverem na sua configuração.
• Sem política = permitir tudo (compatível com versões anteriores)
• A primeira correspondência vence: as regras são avaliadas de cima para baixo, e as requisições sem correspondência caem em defaultAction
• Negado antes da autenticação: requisições bloqueadas nunca recebem credenciais reais
• Globs de caminho: * corresponde dentro de um segmento, ** corresponde a zero ou mais segmentos
• aquaman setup aplica padrões seguros para serviços armazenados (anthropic, openai, slack, gmail).
• aquaman policy list / aquaman policy test <svc> <method> <path> para inspeção / simulações.

Backends de Credenciais

Traga o seu próprio cofre - o aquaman não tem armazenamento próprio. Escolha o backend que você já usa; os segredos permanecem lá, e o proxy os lê no local.

O aquaman setup detecta automaticamente um padrão sensato (macOS → keychain; Linux → keychain se libsecret, senão systemd-creds se systemd ≥ 256, senão encrypted-file).

O encrypted-file é um último recurso para ambientes Linux/CI sem interface gráfica e sem keyring nativo. Para maior segurança no Linux, instale libsecret-1-dev (GNOME Keyring), use systemd-creds (vinculação TPM2) ou use 1Password/Vault.

Cache de credenciais (v0.13.1+)

Backends com um custo por acesso, como 1password (um prompt biométrico por leitura no modo aplicativo desktop), bitwarden (~1-2 s para iniciar a CLI) e vault (uma ida e volta HTTP), são armazenados em cache na memória do daemon por 15 minutos por padrão, de modo que uma sessão movimentada de agente desbloqueia o cofre uma vez por janela em vez de uma vez por requisição. Os outros backends já são rápidos ou fazem cache internamente, então o cache fica desativado para eles por padrão. Ajuste com credentials.cacheTtlSeconds em ~/.aquaman/config.yaml (ou AQUAMAN_CACHE_TTL); 0 desativa.

O trade-off honesto: um prompt biométrico por acesso é uma verificação de presença do usuário, e o cache remove a presença por acesso durante a janela de TTL. Para agentes não assistidos, esse prompt nunca é respondido, então o cofre acaba sendo abandonado em favor de um .env em texto simples, o que é estritamente pior. O cache não move a fronteira de isolamento: os valores vivem apenas no processo do proxy (onde já transitam em cada requisição), nunca são gravados em disco e são invalidados imediatamente quando você rotaciona via aquaman credentials add. As gravações sempre vão para o seu cofre. Testado quanto à conformidade em test/compliance/cache-residency.test.ts. Para zero prompts com o 1Password, use uma conta de serviço com escopo no cofre aquaman; o aquaman doctor vai indicar o caminho.

Licença

MIT - consulte LICENSE.