🔱 Aquaman

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

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

Aquaman resolve isso com três camadas de defesa:

1. Isolamento de processo: As chaves de API vivem em um processo proxy separado. O agente nunca as vê. Até RCE no agente não consegue alcançar as credenciais. Elas estão em um espaço de endereço diferente.
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ção após o fato.

Escolha seu caminho

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

Um único CLI aquaman superfície todos os quatro: comandos de nível superior para cofre e auditoria, aquaman openclaw ... para integração OpenClaw, aquaman coder ... para integração com agente de codificação (delega para aquaman-coder internamente), bem como aquaman hermes ... para o pacote Python Hermes.

Início Rápido

aquaman help, aquaman doctor são seus amigos.

1. Apenas cofre (apenas o proxy + seus segredos)

npm install -g aquaman-proxy
aquaman setup                                # assistente de backend + armazenar chaves
aquaman daemon &                             # iniciar o proxy
aquaman credentials list                     # verificar

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

2. OpenClaw Gateway

openclaw plugins install aquaman-plugin           # 1. instalar plugin + proxy
openclaw aquaman setup                            # 2. backend + chaves + configuração do plugin
openclaw                                          # 3. pronto - proxy inicia automaticamente

Solução de problemas: openclaw aquaman doctor.

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

O interceptor HTTP do plugin redireciona apenas o tráfego para serviços listados em sua configuração services (Anthropic + OpenAI por padrão). Adicione mais sob a configuração do plugin em openclaw.json - canais 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 de IA (Claude Code hoje)

npm install -g aquaman-proxy aquaman-coder        # 1. instalar daemon + adaptador
aquaman setup                                      # 2. assistente de cofre
aquaman daemon &                                   # 3. iniciar o 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 um projeto
aquaman coder setup claude-code                    # 5. configurar hooks do Claude Code
aquaman doctor                                     # 6. verificar - deve mostrar tanto cofre quanto coder verde

Veja por si 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á isso no transcript:

ANTHROPIC_API_KEY=[REDACTED:injected-value]

⏺ ANTHROPIC_API_KEY está definida e disponível (injetada via cofre aquaman). 

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 em sua máquina - nunca vê o valor, e portanto nem o histórico da conversa, nem os logs do provedor de modelo, nem qualquer um que depois tire um print do seu terminal.

Use a partir do seu próprio terminal também. O mesmo wrapper funciona sem o agente. Basta cd para um projeto coberto e prefixar seu comando:

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

Mesma injeção de env, mesma redação em stdout/stderr. Coloque em targets de Makefile, aliases de shell ou runners de CI - em qualquer lugar onde você 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 via UDS). As credenciais são materializadas para um comando, não para a vida inteira do agente.
• Canaliza stdout/stderr por um redator que prepara um padrão baseado em valor para cada valor resolvido: qualquer string injetada é redigida, independentemente da forma (tokens do Atlassian, segredos do Notion, chaves de API internas - nenhum 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 filho revela e que NÃO injetamos.
• Limpa quando o comando termina.

4. Hermes (host de agente)

Hermes é um host estrangeiro (Python) sem hook de transporte para injetar, então o isolamento é feito do lado do proxy: o proxy expõe um listener loopback opt-in com token, e Hermes é apontado para ele através de suas próprias variáveis de ambiente.

npm install -g aquaman-proxy                       # 1. instalar daemon
aquaman setup                                      # 2. assistente de cofre
aquaman credentials add anthropic api_key sk-ant-... # 3. armazenar uma chave de provedor

aquaman hermes setup                               # 4. habilitar loopback + escrever ~/.hermes/.env
aquaman daemon &                                   # 5. iniciar o proxy (UDS + loopback)
aquaman hermes doctor                              # 6. verificar - listener + env + cofre + Hermes

aquaman hermes setup habilita o listener 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 um placeholder api_key igual ao token. Hermes envia o token como chave do provedor; o proxy o remove, injeta sua credencial real do cofre e encaminha para upstream. Apenas provedores LLM (Anthropic, OpenAI) hoje.

Açúcar opcional na sessão - o plugin Python adiciona um comando /aquaman-status, uma ferramenta aquaman_status e uma sonda de saúde no início da sessão dentro do Hermes (não possui credenciais):

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

Como Funciona

Agente / OpenClaw / Agente de Codificação             Proxy Aquaman
┌──────────────────────┐                    ┌──────────────────────┐
│                      │                    │                      │
│  ANTHROPIC_BASE_URL  │═══ UDS / HTTP ════>│  Keychain / 1Pass /  │
│  = aquaman.local     │                    │  Cofre / Criptografado│
│                      │<══════════════════ │                      │
│  interceptor fetch() │═══ broker:resolve  │  + Política aplicada │
│   (APIs de canal)    │                    │  + Autenticação injetada:│
│                      │                    │    header / url-path  │
│  Sem credenciais.    │  ~/.aquaman/       │    basic / oauth     │
│  Sem portas abertas. │  proxy.sock        │                      │
│  Nada para roubar.   │  (chmod 0o600)     │                      │
└──────────────────────┘                    └──┬─────────┬─────────┘
                                               │         │
                                               │         ▼
                                               │  ~/.aquaman/audit/
                                               │  (cadeias de hash)
                                               ▼
                                     api.anthropic.com
                                     api.telegram.org
                                     slack.com/api …

1. Armazenar: As credenciais vivem no backend de cofre que você já executa - sem cofre próprio (Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, arquivo criptografado).
2. Política: O proxy verifica regras de método + caminho antes de tocar nas credenciais. Requisições negadas recebem um 403, nunca cabeçalhos de autenticação reais.
3. Injetar: O proxy busca a credencial e adiciona o cabeçalho de autenticação antes de encaminhar. 25 serviços integrados, 4 modos de autenticação de injeção (header, URL-path, HTTP Basic, OAuth); um quinto, none, é apenas em repouso (proxy rejeita tráfego).
4. Broker (caminho coder): POST /broker/resolve materializa uma credencial por chamada de ferramenta, com escopo para o env de um único comando, depois expira.
5. Auditoria: Cada uso de credencial é registrado com cadeias de hash SHA-256.

O agente vê apenas um hostname sentinela (aquaman.local) ou um marcador placeholder (aquaman-proxy-managed). Nunca vê uma chave real, e nenhuma porta TCP está aberta para outros processos sondarem.

Modelo de Segurança

Modelo detalhado - especificidades por integração (escopo do interceptor HTTP, perfis de autenticação, descobertas do scanner, nota do editor ClawScan) - vive em packages/plugin/README.md e packages/coder/README.md.

Postura de conformidade

Aquaman inclui testes de conformidade executáveis sob 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 a "Adoção Cuidadosa de Serviços de IA Agentic" do CISA/Cinco-Olhos (Abril 2026), CSA MAESTRO e OWASP Top 10 para Aplicações Agentic. Os testes são executados como parte do npm test. Veja docs/compliance/ para os mapeamentos.

Políticas de Requisição

Escopos OAuth não conseguem distinguir entre "criar rascunho de e-mail" e "enviar e-mail". Ambos são gmail.send. Políticas de requisição preenchem essa lacuna.

# ~/.aquaman/config.yaml
policy:
  anthropic:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organizations/**"
        action: deny          # bloquear API administrativa/faturamento
  openai:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organization/**"
        action: deny
      - method: DELETE
        path: "/v1/**"
        action: deny          # sem exclusões
  slack:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/admin.*"
        action: deny
  gmail:
    defaultAction: allow
    rules:
      - method: POST
        path: "/v1/users/*/messages/send"
        action: deny          # rascunhos ok, envio bloqueado

• Sem política = permitir tudo (compatível com versões anteriores)
• Primeira correspondência vence: regras avaliadas de cima para baixo, requisições não correspondidas caem para 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 seu próprio cofre - o aquaman não tem armazenamento próprio. Escolha o backend que você já executa; os segredos permanecem lá, e o proxy os lê no local.

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).

encrypted-file é um último recurso para ambientes Linux/CI headless sem um keyring nativo. Para melhor 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 custo por acesso — 1password (um prompt biométrico por leitura no modo app desktop), bitwarden (~1-2 s de spawn do CLI), vault (uma viagem de 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 ocupada 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 está desligado para eles por padrão. Ajuste com credentials.cacheTtlSeconds em ~/.aquaman/config.yaml (ou AQUAMAN_CACHE_TTL); 0 desativa.

A troca honesta: um prompt biométrico por acesso é uma verificação de presença do usuário, e o cache remove a verificação de presença por acesso durante a janela TTL. Para agentes não supervisionados esse prompt nunca é respondido — leva ao abandono do cofre por um .env em texto puro, que é estritamente pior. O cache não move a fronteira de isolamento: valores vivem apenas no processo proxy (onde já transitam em toda requisição), nunca são escritos em disco e são invalidados imediatamente quando você rotaciona através de aquaman credentials add. Escritas sempre vão para seu cofre. Testado em conformidade em test/compliance/cache-residency.test.ts. Para zero prompts com 1Password, use uma conta de serviço com escopo para o cofre aquaman — aquaman doctor apontará você para lá.

Licença

MIT - veja LICENSE.