🔱 Aquaman

🔱 L'unico proxy indipendente per le credenziali dedicato agli agenti AI: isolamento bring-your-own-vault e policy di richiesta a privilegio minimo. Le tue chiavi restano dove le conservi già, mai nella memoria dell'agente. Compatibile con 1Password, keychain, keepassxc e molti altri.

Hai configurato Claude Code, OpenClaw o Hermes, e ora stai fissando i file .env con le tue preziose chiavi API in chiaro. Hai letto gli articoli. Sai cosa succede quando un agente subisce un prompt injection. Ci siamo passati anche noi.

Aquaman risolve il problema con tre livelli di difesa:

1. Isolamento dei processi: le chiavi API risiedono in un processo proxy separato che le inietta in uscita. L'agente detiene un marker, mai una chiave, quindi nemmeno un RCE nell'agente può leggerla. Gli agenti di coding ricevono solo i riferimenti che dichiari, un comando alla volta.
2. Policy di richiesta: regole per singolo servizio controllano quali endpoint un agente può chiamare. Blocca le API di amministrazione, impedisci le eliminazioni, consenti le bozze ma nega gli invii. Le richieste negate non ricevono mai credenziali reali.
3. Audit a prova di manomissione: ogni utilizzo di credenziali viene registrato con catene di hash SHA-256. Puoi dimostrare cosa è stato consultato e rilevare manomissioni a posteriori.

Scegli il tuo percorso

Aquaman viene distribuito come quattro pacchetti coordinati, che condividono un unico vault + un unico daemon. Installa solo ciò che ti serve:

Un'unica CLI aquaman espone tutti e quattro: comandi di primo livello per vault e audit, aquaman openclaw ... per l'integrazione OpenClaw, aquaman coder ... per l'integrazione con gli agenti di coding (che delega ad aquaman-coder dietro le quinte) e aquaman hermes ... per il pacchetto Python Hermes.

Avvio rapido

aquaman help, aquaman doctor sono tuoi amici.

1. Solo vault (solo il proxy + i tuoi segreti)```bash

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

Il proxy ascolta su `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`). Punta qualsiasi strumento su `http://aquaman.local/<service>/<path>` e il proxy inietta gli header di autenticazione per quel servizio dal backend vault scelto.

### 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

Risoluzione dei problemi: openclaw aquaman doctor.

Usare npm direttamente? npm install -g aquaman-proxy && aquaman openclaw setup fa la stessa cosa - installa la CLI del proxy, memorizza le tue chiavi, installa il plugin in ~/.openclaw/extensions/aquaman-plugin/ e collega le credenziali (riferimenti SecretRef su OpenClaw ≥ 2026.6.5, il segnaposto auth-profiles.json sulle versioni precedenti).

aquaman openclaw setup punta models.providers.<svc>.baseUrl e channels.telegram.apiRoot verso il listener di loopback del proxy, perché il trasporto dei modelli di OpenClaw e i suoi canali costruiscono ciascuno il proprio client HTTP e bypassano l'intercettore fetch. I canali diversi da Telegram non espongono alcun override dell'endpoint, quindi i loro token vengono memorizzati e migrati ma non iniettati in uscita (vedi packages/plugin/README.md). Aggiungi i canali sotto la configurazione del plugin in openclaw.json; tra quelli supportati ci sono 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 altri (25 in totale).

3. Agenti di coding AI (Claude Code oggi)```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

**Provalo tu stesso (l'effetto "aha" in 30 secondi):** riavvia Claude Code, apri una nuova sessione dentro `~/code/my-app` e chiedi all'agente di eseguire:```
printenv | grep ANTHROPIC_API_KEY

Lo vedrai nella trascrizione:``` ANTHROPIC_API_KEY=[REDACTED:injected-value]

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

Il processo *figlio* vedeva la chiave reale (i tuoi test, le build, i server MCP, gli script di importazione - qualsiasi cosa che ne abbia effettivamente bisogno funziona). L'*agente* - la cosa che decide quale codice eseguire sulla tua macchina - non vede mai il valore, e quindi non lo vedono nemmeno la cronologia della conversazione, né i log del provider del modello, né chiunque in seguito faccia uno screenshot del tuo terminale.

**Usalo anche dal tuo terminale.** Lo stesso wrapper funziona senza l'agente. Basta fare `cd` in un progetto coperto e anteporre il comando:```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

Stessa iniezione di env, stessa redazione su stdout/stderr. Inseriscilo nei target dei Makefile, negli alias della shell o nei runner CI - ovunque altrimenti ricorreresti a un file .env.

Quando Claude Code esegue uno strumento Bash in ~/code/my-app, l'hook di aquaman riscrive il comando tramite updatedInput.command per avvolgerlo sotto aquaman-coder exec. Quel wrapper:

• Risolve ogni riferimento aquaman://service/key tramite il broker (POST /broker/resolve su UDS). Le credenziali vengono materializzate per un singolo comando, non per l'intera durata dell'agente.
• Canalizza stdout/stderr attraverso un redattore che antepone un pattern basato sul valore per ogni valore risolto: qualunque stringa sia stata iniettata viene redatta, indipendentemente dalla forma (token Atlassian, segreti Notion, chiavi di API interne - nessuno di essi deve corrispondere a un formato di provider noto). I pattern generici basati sulla forma (sk-ant-, ghp_, sk_live_, AKIA…, JWT, blocchi PEM, ATATT3xF…) vengono comunque eseguiti in seguito come difesa in profondità per i segreti che il processo figlio espone e che NON abbiamo iniettato.
• Esegue la pulizia all'uscita del comando.

Sandbox di Claude Code: blocca i socket Unix per impostazione predefinita, quindi aquaman coder setup claude-code inserisce nella allowlist il socket del proxy su macOS (sandbox.network.allowUnixSockets). Linux e WSL2 ignorano quella lista, dove l'unica opzione è sandbox.network.allowAllUnixSockets: true, che apre ogni socket Unix ai comandi in sandbox.

4. Hermes (host dell'agente)

Hermes è un host esterno (Python) senza hook di trasporto per l'iniezione, quindi l'isolamento viene effettuato lato proxy: il proxy espone un listener loopback opt-in, protetto da token, e Hermes viene indirizzato verso di esso tramite le proprie variabili d'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` abilita il listener di loopback, genera un token per installazione e scrive un blocco gestito da aquaman in `~/.hermes/.env` (rispettando `HERMES_HOME`): il nativo `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` più un api_key segnaposto uguale al token. Hermes invia il token come chiave del suo provider; il proxy lo rimuove, inietta la tua credenziale reale dal vault e inoltra a monte. Solo provider LLM (Anthropic, OpenAI) al momento.

**Zuccherino opzionale in-session** - il plugin Python aggiunge un comando `/aquaman-status`, uno strumento `aquaman_status` e una sonda di salute all'avvio della sessione dentro Hermes (non detiene credenziali):```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

Il plugin registra anche una sorgente di segreti aquaman (Hermes ≥ 0.18.1) per i segreti di progetto come GITHUB_TOKEN. Associali sotto secrets.aquaman.env nel config.yaml di Hermes, poi dichiara ogni riferimento con aquaman broker allow aquaman://github/token (richiesto dalla v0.15.0; aquaman hermes doctor elenca quelli che hai dimenticato). A differenza delle chiavi LLM sopra, questi valori entrano nell'env di Hermes. Vedi packages/hermes/README.md.

Come funziona```

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**: Le credenziali risiedono nel backend del vault che già utilizzi - nessun vault proprietario (Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, encrypted-file).
2. **Policy**: Il proxy verifica il metodo + le regole di percorso *prima* di toccare le credenziali. Le richieste negate ricevono un `403`, mai header di autenticazione reali.
3. **Inject**: Il proxy cerca la credenziale e aggiunge l'header di autenticazione prima dell'inoltro. 25 servizi integrati, 4 modalità di iniezione dell'autenticazione (header, URL-path, HTTP Basic, OAuth); una quinta, `none`, è solo at-rest (il proxy rifiuta il traffico).
4. **Broker (coder + sorgente segreta Hermes)**: `POST /broker/resolve` materializza una credenziale per ogni chiamata di tool, limitata all'env di un singolo comando. Solo `aquaman daemon` lo serve, e solo per i ref che hai dichiarato (`projects.yaml` o `aquaman broker allow`). Il proxy del plugin OpenClaw non lo serve mai (v0.15.0+).
5. **Audit**: Ogni utilizzo di credenziali viene registrato con catene di hash SHA-256.

Sui percorsi del proxy l'agente vede un endpoint locale più un marker: il placeholder `aquaman-proxy-managed`, o il token loopback, che funziona solo contro il tuo proxy locale. Mai una chiave reale. Sul percorso coder il comando *figlio* riceve i valori dichiarati e l'agente vede l'output redatto.

## Modello di sicurezza

| Livello | Cosa fa | Cosa blocca |
|---|---|---|
| **Isolamento dei processi** | Credenziali in un processo separato, raggiunto tramite un socket Unix (`chmod 0o600`) o un listener loopback protetto da token | Un agente compromesso non può leggere le chiavi proxate: spazio di indirizzamento diverso |
| **Ambito del broker** | Solo `aquaman daemon` distribuisce valori, e solo per i ref che hai dichiarato; i proxy ospitati da OpenClaw non lo fanno mai (v0.15.0+) | Un agente non può estrarre voci arbitrarie del vault attraverso il socket |
| **Allowlisting dei servizi** | `proxiedServices` controlla quali API l'agente può raggiungere | L'agente non può comunicare con servizi che non hai autorizzato |
| **Policy delle richieste** | Regole di metodo + percorso per servizio, applicate prima dell'iniezione delle credenziali | L'agente può raggiungere Anthropic ma non la sua API di amministrazione; può redigere email ma non inviarle |
| **Traccia di audit** | Log con catene di hash SHA-256 di ogni utilizzo di credenziali | Analisi forense post-incidente, rilevamento di manomissioni, prove di conformità |
| **Broker per chiamata di tool (coder)** | `aquaman-coder exec` materializza le credenziali per un comando alla volta | Le credenziali non si diffondono nell'ambiente shell dell'agente |
| **Redazione dell'output (coder)** | `aquaman-coder exec` canalizza stdout/stderr attraverso un redattore che elimina ogni valore appena iniettato alla lettera - più pattern generici dei provider come fallback | Anche credenziali arbitrarie e senza forma non raggiungono mai il transcript dell'agente |

### Trasporti e controllo degli accessi

| Percorso | Trasporto | Controllo degli accessi |
|---|---|---|
| Agenti di coding, qualsiasi client che può contattare un socket | Socket Unix `~/.aquaman/proxy.sock` | Permessi file (`0600`): solo i processi eseguiti come te |
| Hermes (v0.13.0+), traffico modello e Telegram di OpenClaw (v0.15.0+) | Loopback TCP `127.0.0.1:<port>` | Token per installazione, controllo a tempo costante, bind su loopback |

Hermes e OpenClaw costruiscono ciascuno il proprio client HTTP e non possono contattare un socket, quindi usano il listener. Tutto il resto usa il socket.

Il token è una capability per raggiungere il proxy locale, non una credenziale. Generato per installazione, memorizzato in `~/.aquaman/config.yaml` (`0600`), inviato dall'host come sua api key del provider. Il proxy lo verifica, lo rimuove, inietta la tua chiave reale. Telegram non ha header di autenticazione, quindi lì il token viaggia nel segmento di percorso `/bot<TOKEN>`.

Compromesso: qualsiasi processo locale può raggiungere una porta loopback, inclusi altri utenti, dove il `0600` del socket li esclude. Il token è il cancello lì, quindi il listener resta spento finché `aquaman hermes setup` o `aquaman openclaw setup` non lo attiva.

### Credenziali dei canali su OpenClaw 2026.7.33+

| Canale | Egress attraverso il proxy |
|---|---|
| Telegram | Sì, dalla v0.15.0 |
| Tutto il resto | No. Solo archiviazione nel vault e migrazione |

Ogni canale costruisce il proprio client HTTP per richiesta, quindi l'intercettore `fetch` del plugin non vede più il traffico dei canali su queste versioni. Instradare un canale richiede un override dell'endpoint da parte dell'host, e Telegram è l'unico che lo ha: `aquaman openclaw setup` punta `channels.telegram.apiRoot` al proxy e sostituisce il token del bot con il token loopback.

Per il resto, il tuo token resta nel vault ma OpenClaw lo usa direttamente, quindi il proxy non è nel percorso e quelle chiamate non vengono sottoposte ad audit. `aquaman openclaw doctor` elenca quali dei tuoi canali configurati sono in quale gruppo. I provider dei modelli non sono interessati.

**Cosa non può fare l'isolamento tra utenti dello stesso sistema.** Il `0o600` del socket tiene fuori gli altri utenti, non gli altri processi eseguiti come te. Un tale processo può inviare richieste attraverso il proxy mentre è in esecuzione (limitato dalla policy delle richieste, registrato nel log di audit) e può recuperare i ref che hai dichiarato, che è ciò che significa dichiarare. Non può leggere le chiavi che il proxy inietta. Per un confine più solido, esegui l'agente come un utente OS diverso o in una sandbox.

Il modello dettagliato - specifiche per integrazione (ambito dell'intercettore HTTP, profili di autenticazione, risultati dello scanner, nota dell'editore ClawScan) - si trova in [`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).

### Postura di conformità

Aquaman include test di conformità eseguibili sotto `test/compliance/` mappati su:

- **MITRE ATLAS** v5.4.0: tecniche 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/`)

Più narrazioni di allineamento per CISA/Five-Eyes "Careful Adoption of Agentic AI Services" (aprile 2026), CSA MAESTRO e OWASP Top 10 for Agentic Applications. I test vengono eseguiti come parte di `npm test`. Vedi [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) per le mappature.


## Policy delle richieste

Gli scope OAuth non riescono a distinguere tra "redigere un'email" e "inviare un'email". Sono entrambi `gmail.send`. Le policy delle richieste colmano questa 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

• I percorsi sono il percorso completo dell'API upstream dopo il prefisso del servizio: la Web API di Slack è /api/<method>, quella di Gmail è /gmail/v1/.... I preset precedenti alla v0.15.0 usavano /admin.* e /v1/users/*/messages/send, che non corrispondevano mai al traffico reale. aquaman doctor li segnala se sono ancora nella tua configurazione.
• Nessuna policy = consenti tutto (retrocompatibile)
• Vince la prima corrispondenza: le regole vengono valutate dall'alto verso il basso, le richieste non corrispondenti ricadono su defaultAction
• Negato prima dell'autenticazione: le richieste bloccate non ricevono mai credenziali reali
• Glob dei percorsi: * corrisponde all'interno di un segmento, ** corrisponde a zero o più segmenti
• aquaman setup applica impostazioni predefinite sicure per i servizi memorizzati (anthropic, openai, slack, gmail).
• aquaman policy list / aquaman policy test <svc> <method> <path> per l'ispezione / dry-run.

Backend delle credenziali

Porta il tuo vault - aquaman non ha un archivio interno. Scegli il backend che già utilizzi; i segreti restano lì e il proxy li legge sul posto.

aquaman setup rileva automaticamente un valore predefinito sensato (macOS → keychain; Linux → keychain se libsecret, altrimenti systemd-creds se systemd ≥ 256, altrimenti encrypted-file).

encrypted-file è l'ultima risorsa per ambienti Linux/CI headless senza un keyring nativo. Per una maggiore sicurezza su Linux, installa libsecret-1-dev (GNOME Keyring), usa systemd-creds (binding TPM2) oppure usa 1Password/Vault.

Caching delle credenziali (v0.13.1+)

I backend con un costo per accesso, come 1password (un prompt biometrico per lettura in modalità app desktop), bitwarden (~1-2 s per l'avvio della CLI) e vault (un round-trip HTTP), vengono memorizzati nella cache in memoria del daemon per 15 minuti per impostazione predefinita, così una sessione intensa dell'agente sblocca il vault una volta per finestra invece di una volta per richiesta. Gli altri backend sono già veloci o memorizzano internamente, quindi per loro la cache è disattivata per impostazione predefinita. Regola con credentials.cacheTtlSeconds in ~/.aquaman/config.yaml (o AQUAMAN_CACHE_TTL); 0 disabilita.

Il compromesso onesto: un prompt biometrico per accesso è un controllo di presenza dell'utente, e la cache rimuove la presenza per accesso per la finestra del TTL. Per gli agenti non presidiati quel prompt non riceve mai risposta, quindi il vault viene abbandonato in favore di un .env in chiaro, che è decisamente peggio. La cache non sposta il confine di isolamento: i valori vivono solo nel processo del proxy (dove già transitano a ogni richiesta), non vengono mai scritti su disco e vengono invalidati immediatamente quando ruoti tramite aquaman credentials add. Le scritture vanno sempre nel tuo vault. Testato per conformità in test/compliance/cache-residency.test.ts. Per zero prompt con 1Password, usa un service account con ambito limitato al vault aquaman; aquaman doctor ti indirizzerà lì.

Licenza

MIT - vedi LICENSE.