🔱 Aquaman

🔱 L'unico proxy indipendente per le credenziali degli agenti AI: porta il tuo archivio personale con isolamento e politiche di richiesta con privilegi minimi. Le tue chiavi rimangono dove già le tieni, mai nella memoria dell'agente. Compatibile con 1Password, keychain, keepassxc e molti altri.

Hai configurato Claude Code, OpenClaw o Hermes, e ora stai fissando file .env con le tue preziose chiavi API in chiaro. Hai letto gli articoli. Sai cosa succede quando un agente subisce un'iniezione di prompt. Ti capiamo.

Aquaman risolve questo problema con tre livelli di difesa:

1. Isolamento dei processi: Le chiavi API vivono in un processo proxy separato. L'agente non le vede mai. Nemmeno una RCE nell'agente può raggiungere le credenziali. Sono in uno spazio di indirizzi diverso.
2. Politiche di richiesta: Regole per servizio controllano quali endpoint un agente può chiamare. Blocca le API di amministrazione, impedisci le eliminazioni, permetti bozze ma nega gli invii. Le richieste negate non ottengono 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 accesso e rilevare manomissioni a posteriori.

Scegli il tuo percorso

Aquaman è distribuito come quattro pacchetti coordinati, che condividono un unico archivio + un unico demone. Installa solo ciò che ti serve:

Un singolo comando aquaman CLI copre tutti e quattro: comandi di alto livello per archivio e audit, aquaman openclaw ... per l'integrazione OpenClaw, aquaman coder ... per l'integrazione con agenti di codifica (delega a aquaman-coder internamente) e aquaman hermes ... per il pacchetto Python Hermes.

Avvio Rapido

aquaman help, aquaman doctor sono tuoi amici.

1. Solo archivio (solo proxy + i tuoi segreti)

npm install -g aquaman-proxy
aquaman setup                                # procedura guidata backend + memorizza chiavi
aquaman daemon &                             # avvia il proxy
aquaman credentials list                     # verifica

Il proxy ascolta su ~/.aquaman/proxy.sock (UDS, chmod 0o600). Punta qualsiasi strumento a http://aquaman.local/<servizio>/<percorso> e il proxy inietta le intestazioni di autenticazione per quel servizio dal tuo backend di archivio scelto.

2. OpenClaw Gateway

openclaw plugins install aquaman-plugin           # 1. installa plugin + proxy
openclaw aquaman setup                            # 2. backend + chiavi + collegamento plugin
openclaw                                          # 3. fatto - il proxy si avvia automaticamente

Risoluzione problemi: openclaw aquaman doctor.

Usi direttamente npm? npm install -g aquaman-proxy && aquaman openclaw setup fa lo stesso - installa la CLI del proxy, memorizza le tue chiavi, installa il plugin in ~/.openclaw/extensions/aquaman-plugin/ e collega le credenziali (ref SecretRef su OpenClaw ≥ 2026.6.5, file auth-profiles.json nei precedenti).

L'intercettatore HTTP del plugin reindirizza solo il traffico per i servizi nella sua configurazione services (Anthropic + OpenAI di default). Aggiungine altri nella configurazione del plugin in openclaw.json - i canali supportati includono 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 codifica AI (Claude Code oggi)

npm install -g aquaman-proxy aquaman-coder        # 1. installa demone + adattatore
aquaman setup                                      # 2. procedura guidata archivio
aquaman daemon &                                   # 3. avvia il 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. dichiara un progetto
aquaman coder setup claude-code                    # 5. collega gli hook di Claude Code
aquaman doctor                                     # 6. verifica - dovrebbe mostrare sia archivio che coder verdi

Vedilo con i tuoi occhi (illuminazione da 30 secondi): riavvia Claude Code, apri una nuova sessione dentro ~/code/my-app, e chiedi all'agente di eseguire:

printenv | grep ANTHROPIC_API_KEY

Vedrai questo nel trascritto:

ANTHROPIC_API_KEY=[REDACTED:injected-value]

⏺ ANTHROPIC_API_KEY è impostato e disponibile (iniettato tramite archivio aquaman).

Il processo figlio ha visto la chiave reale (i tuoi test, build, server MCP, script di import - tutto ciò che ne ha realmente bisogno funziona). L'agente - la cosa che decide quale codice eseguire sulla tua macchina - non vede mai il valore, e quindi non lo vede neanche la cronologia della conversazione, né i log del fornitore del modello, né chiunque faccia uno screenshot del tuo terminale.

Usalo anche dal tuo terminale. Lo stesso wrapper funziona senza agente. Basta cd in un progetto coperto e anteporre il comando:

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

Stessa iniezione di env, stessa oscuramento su stdout/stderr. Inseriscilo in target Makefile, alias di shell o runner CI - ovunque altrimenti raggiungeresti 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://servizio/chiave tramite il broker (POST /broker/resolve su UDS). Le credenziali vengono materializzate per un singolo comando, non per la vita dell'agente.
• Pipe stdout/stderr attraverso un oscuratore che prepara un pattern basato sul valore per ogni valore risolto: qualsiasi stringa iniettata viene oscurata, indipendentemente dalla forma (token Atlassian, segreti Notion, chiavi API interne - nessuno deve corrispondere a un formato di provider noto). I pattern generici basati su forma (sk-ant-, ghp_, sk_live_, AKIA…, JWT, blocchi PEM, ATATT3xF…) vengono ancora eseguiti come difesa in profondità per i segreti che il figlio espone e che NON abbiamo iniettato.
• Pulisce quando il comando termina.

4. Hermes (host agente)

Hermes è un host Python esterno senza alcun hook di trasporto in cui iniettare, quindi l'isolamento è lato proxy: il proxy espone un ascoltatore loopback facoltativo con token gate e Hermes viene puntato ad esso tramite le proprie variabili d'ambiente.

npm install -g aquaman-proxy                       # 1. installa demone
aquaman setup                                      # 2. procedura guidata archivio
aquaman credentials add anthropic api_key sk-ant-... # 3. memorizza una chiave provider

aquaman hermes setup                               # 4. abilita loopback + scrive ~/.hermes/.env
aquaman daemon &                                   # 5. avvia il proxy (UDS + loopback)
aquaman hermes doctor                              # 6. verifica - listener + env + archivio + Hermes

aquaman hermes setup abilita l'ascoltatore 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 placeholder uguale al token. Hermes invia il token come sua chiave provider; il proxy lo rimuove, inietta la tua vera credenziale di archivio e inoltra a monte. Solo provider LLM (Anthropic, OpenAI) oggi.

Zucchero facoltativo in sessione - il plugin Python aggiunge un comando /aquaman-status, uno strumento aquaman_status e un probe di integrità all'avvio della sessione dentro Hermes (non contiene credenziali):

pip install aquaman-hermes            # oppure: uv tool install aquaman-hermes
aquaman-hermes install                # inserisce il plugin in ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman

Come Funziona

Agente / OpenClaw / Agente di Codifica        Proxy Aquaman
┌──────────────────────┐                    ┌──────────────────────┐
│                      │                    │                      │
│  ANTHROPIC_BASE_URL  │═══ UDS / HTTP ════>│  Keychain / 1Pass /  │
│  = aquaman.local     │                    │  Vault / Encrypted   │
│                      │<══════════════════ │                      │
│  intercettatore      │═══ broker:resolve  │  + Politiche         │
│   fetch() (API canali)│                    │  + Auth iniettata:   │
│                      │                    │    header / url-path │
│  Nessuna credenziale.│  ~/.aquaman/       │    basic / oauth     │
│  Nessuna porta       │  proxy.sock        │                      │
│  aperta.             │  (chmod 0o600)     │                      │
│  Niente da rubare.   │                    │                      │
└──────────────────────┘                    └──┬─────────┬─────────┘
                                               │         │
                                               │         ▼
                                               │  ~/.aquaman/audit/
                                               │  (catena di hash)
                                               ▼
                                     api.anthropic.com
                                     api.telegram.org
                                     slack.com/api …

1. Memorizza: Le credenziali vivono nel backend di archivio che già esegui - nessun archivio interno (Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, file crittografato).
2. Politica: Il proxy controlla le regole di metodo + percorso prima di toccare le credenziali. Le richieste negate ottengono un 403, mai intestazioni di autenticazione reali.
3. Inietta: Il proxy cerca la credenziale e aggiunge l'intestazione di autenticazione prima di inoltrare. 25 servizi integrati, 4 modalità di autenticazione iniezione (header, URL-path, HTTP Basic, OAuth); una quinta, none, è solo a riposo (il proxy rifiuta il traffico).
4. Broker (percorso coder): POST /broker/resolve materializza una credenziale per chiamata dello strumento, limitata all'env di un singolo comando, poi scade.
5. Audit: Ogni utilizzo di credenziali viene registrato con catene di hash SHA-256.

L'agente vede solo un hostname sentinella (aquaman.local) o un marcatore placeholder (aquaman-proxy-managed). Non vede mai una chiave reale e nessuna porta TCP è aperta per essere sondata da altri processi.

Modello di Sicurezza

Modello dettagliato - specifiche per integrazione (ambito dell'intercettatore HTTP, profili di autenticazione, risultati dello scanner, nota dell'editore ClawScan) - vive in packages/plugin/README.md e packages/coder/README.md.

Postura di conformità

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

• 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ù narrative di allineamento per CISA/Five-Eyes "Careful Adoption of Agentic AI Services" (Aprile 2026), CSA MAESTRO e OWASP Top 10 per Applicazioni Agenti. I test vengono eseguiti come parte di npm test. Vedi docs/compliance/ per le mappature.

Politiche di Richiesta

Gli ambiti OAuth non possono distinguere tra "scrivi una bozza di email" e "invia un'email". Sono entrambi gmail.send. Le politiche di richiesta colmano questa lacuna.

# ~/.aquaman/config.yaml
policy:
  anthropic:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organizations/**"
        action: deny          # blocca API amministrazione/fatturazione
  openai:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organization/**"
        action: deny
      - method: DELETE
        path: "/v1/**"
        action: deny          # niente eliminazioni
  slack:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/admin.*"
        action: deny
  gmail:
    defaultAction: allow
    rules:
      - method: POST
        path: "/v1/users/*/messages/send"
        action: deny          # bozze ok, invio bloccato

• Nessuna politica = permetti tutto (retrocompatibile)
• Prima corrispondenza vince: le regole vengono valutate dall'alto verso il basso, le richieste non corrispondenti cadono in defaultAction
• Negato prima dell'autenticazione: le richieste bloccate non ottengono mai credenziali reali
• Glob sui percorsi: * corrisponde all'interno di un segmento, ** corrisponde a zero o più segmenti
• aquaman setup applica impostazioni di sicurezza predefinite per i servizi memorizzati (anthropic, openai, slack, gmail).
• aquaman policy list / aquaman policy test <svc> <method> <path> per ispezione / prove a secco.

Backend di Credenziali

Porta il tuo archivio: aquaman non ha un archivio interno. Scegli il backend che già esegui; i segreti rimangono 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 è un'ultima risorsa per ambienti Linux/CI senza un portachiavi nativo. Per una migliore sicurezza su Linux, installa libsecret-1-dev (GNOME Keyring), usa systemd-creds (TPM2 binding), o usa 1Password/Vault.

Cache delle credenziali (v0.13.1+)

I backend con un costo per accesso — 1password (un prompt biometrico per lettura in modalità app desktop), bitwarden (~1-2 s di spawn CLI), vault (un round trip HTTP) — vengono memorizzati nella cache in memoria del demone per 15 minuti per impostazione predefinita, così una sessione di agente occupata sblocca l'archivio una volta per finestra invece che una volta per richiesta. Gli altri backend sono già veloci o tengono cache internamente, quindi la cache è disattivata per loro. 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 utente, e la cache rimuove il controllo di presenza per accesso per la finestra TTL. Per agenti non presidiati quel prompt non riceverà mai risposta — e si finisce con l'abbandonare l'archivio per un .env in chiaro, che è decisamente peggio. La cache non sposta il confine di isolamento: i valori vivono solo nel processo proxy (dove già transitano ad ogni richiesta), non vengono mai scritti su disco e vengono invalidati immediatamente quando ruoti tramite aquaman credentials add. Le scritture vanno sempre al tuo archivio. Testato per conformità in test/compliance/cache-residency.test.ts. Per zero prompt con 1Password, usa un service account con ambito limitato all'archivio aquaman — aquaman doctor ti indirizzerà lì.

Licenza

MIT - vedi LICENSE.