🔱 Aquaman

🔱 Le seul proxy d'identifiants indépendant pour agents IA : isolation bring-your-own-vault et politiques de requêtes à moindre privilège. Vos clés restent là où vous les conservez déjà, jamais dans la mémoire de l'agent. Compatible avec 1Password, keychain, keepassxc et bien d'autres.

Vous avez configuré Claude Code, OpenClaw ou Hermes, et vous fixez maintenant vos fichiers .env avec vos précieuses clés API qui traînent en clair. Vous avez lu les articles. Vous savez ce qui se passe quand un agent subit une injection de prompt. On comprend.

Aquaman résout ce problème avec trois couches de défense :

1. Isolation des processus : les clés API vivent dans un processus proxy séparé qui les injecte à la sortie. L'agent détient un marqueur, jamais une clé, donc même une RCE dans l'agent ne peut pas en lire une. Les agents de codage ne reçoivent que les références que vous déclarez, une commande à la fois.
2. Politiques de requêtes : des règles par service contrôlent quels endpoints un agent peut appeler. Bloquez les API d'administration, empêchez les suppressions, autorisez les brouillons mais refusez les envois. Les requêtes refusées ne reçoivent jamais de vrais identifiants.
3. Audit à l'épreuve de la falsification : chaque utilisation d'identifiant est journalisée avec des chaînes de hachage SHA-256. Vous pouvez prouver ce qui a été accédé et détecter toute falsification après coup.

Choisissez votre parcours

Aquaman est livré sous forme de quatre paquets coordonnés, partageant un seul vault + un seul daemon. Installez uniquement ce dont vous avez besoin :

Une seule CLI aquaman expose les quatre : commandes de premier niveau pour le vault et l'audit, aquaman openclaw ... pour l'intégration OpenClaw, aquaman coder ... pour l'intégration d'agent de codage (délègue à aquaman-coder en interne) ainsi que aquaman hermes ... pour le paquet Python Hermes.

Démarrage rapide

aquaman help, aquaman doctor sont vos amis.

1. Vault uniquement (juste le proxy + vos secrets)```bash

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

Le proxy écoute sur `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`). Pointez n'importe quel outil vers `http://aquaman.local/<service>/<path>` et le proxy injecte les en-têtes d'authentification pour ce service depuis le backend de coffre-fort que vous avez choisi.

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

Dépannage : openclaw aquaman doctor.

Utiliser npm directement ? npm install -g aquaman-proxy && aquaman openclaw setup fait la même chose - installe le CLI proxy, stocke vos clés, installe le plugin dans ~/.openclaw/extensions/aquaman-plugin/, et configure les identifiants (références SecretRef sur OpenClaw ≥ 2026.6.5, l'espace réservé auth-profiles.json sur les versions plus anciennes).

aquaman openclaw setup pointe models.providers.<svc>.baseUrl et channels.telegram.apiRoot vers l'écouteur loopback du proxy, car le transport de modèle d'OpenClaw et ses canaux construisent chacun leur propre client HTTP et contournent l'intercepteur fetch. Les canaux autres que Telegram n'exposent aucune substitution de point de terminaison, donc leurs jetons sont stockés et migrés mais non injectés à la sortie (voir packages/plugin/README.md). Ajoutez des canaux sous la configuration du plugin dans openclaw.json ; les canaux pris en charge incluent Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face, et plus encore (25 au total).

3. Agents de codage IA (Claude Code aujourd'hui)```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

**Voyez-le par vous-même (le déclic en 30 secondes) :** redémarrez Claude Code, ouvrez une nouvelle session dans `~/code/my-app`, et demandez à l'agent d'exécuter :```
printenv | grep ANTHROPIC_API_KEY

Vous verrez ceci dans la transcription :``` ANTHROPIC_API_KEY=[REDACTED:injected-value]

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

Le processus *enfant* voyait la vraie clé (vos tests, builds, serveurs MCP, scripts d'import - tout ce qui en a réellement besoin fonctionne). L'*agent* - la chose qui décide quel code exécuter sur votre machine - ne voit jamais la valeur, et donc l'historique de conversation ne la voit pas non plus, les logs du fournisseur du modèle non plus, et personne qui prendra plus tard une capture d'écran de votre terminal non plus.

**Utilisez-le aussi depuis votre propre terminal.** Le même wrapper fonctionne sans l'agent. Faites simplement `cd` dans un projet couvert et préfixez votre commande :```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

Même injection d'environnement, même masquage sur stdout/stderr. Intégrez-le dans des cibles Makefile, des alias shell ou des runners CI - partout où vous utiliseriez autrement un fichier .env.

Lorsque Claude Code exécute un outil Bash dans ~/code/my-app, le hook d'aquaman réécrit la commande via updatedInput.command pour l'encapsuler sous aquaman-coder exec. Ce wrapper :

• Résout chaque référence aquaman://service/key via le broker (POST /broker/resolve sur UDS). Les identifiants sont matérialisés pour une seule commande, pas pour toute la durée de vie de l'agent.
• Fait passer stdout/stderr par un masqueur qui préfixe un motif basé sur la valeur pour chaque valeur résolue : quelle que soit la chaîne injectée, elle sera masquée, indépendamment de sa forme (jetons Atlassian, secrets Notion, clés d'API internes - aucun d'entre eux n'a besoin de correspondre à un format de fournisseur connu). Les motifs génériques basés sur la forme (sk-ant-, ghp_, sk_live_, AKIA…, JWT, blocs PEM, ATATT3xF…) s'exécutent toujours ensuite en défense en profondeur pour les secrets que le processus enfant expose et que nous n'avons PAS injectés.
• Nettoie à la sortie de la commande.

Bac à sable de Claude Code : il bloque les sockets Unix par défaut, donc aquaman coder setup claude-code ajoute le socket du proxy à la liste d'autorisation sur macOS (sandbox.network.allowUnixSockets). Linux et WSL2 ignorent cette liste, où la seule option est sandbox.network.allowAllUnixSockets: true, ce qui ouvre tous les sockets Unix aux commandes sandboxées.

4. Hermes (hôte d'agent)

Hermes est un hôte étranger (Python) sans hook de transport pour l'injection, donc l'isolation est effectuée côté proxy : le proxy expose un listener loopback opt-in protégé par jeton, et Hermes y est pointé via ses propres variables d'environnement.```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` active l'écouteur loopback, génère un jeton par installation et écrit un bloc géré par aquaman dans `~/.hermes/.env` (en respectant `HERMES_HOME`) : les variables natives `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` plus une api_key fictive égale au jeton. Hermes envoie le jeton comme clé de son fournisseur ; le proxy le retire, injecte votre véritable identifiant du coffre-fort et transmet en amont. Fournisseurs LLM uniquement (Anthropic, OpenAI) pour l'instant.

**Sucre optionnel en session** - le plugin Python ajoute une commande `/aquaman-status`, un outil `aquaman_status` et une sonde de santé au démarrage de session dans Hermes (ne détient aucun identifiant) :```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

Le plugin enregistre également une source de secrets aquaman (Hermes ≥ 0.18.1) pour les secrets de projet comme GITHUB_TOKEN. Liez-les sous secrets.aquaman.env dans le config.yaml de Hermes, puis déclarez chaque référence avec aquaman broker allow aquaman://github/token (requis depuis la v0.15.0 ; aquaman hermes doctor liste celles que vous avez manquées). Contrairement aux clés LLM ci-dessus, ces valeurs entrent dans l'environnement de Hermes. Voir packages/hermes/README.md.

Comment ça fonctionne```

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** : Les identifiants résident dans le backend de coffre-fort que vous exécutez déjà - pas de coffre-fort maison (Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, fichier chiffré).
2. **Policy** : Le proxy vérifie la méthode + les règles de chemin *avant* de toucher aux identifiants. Les requêtes refusées reçoivent un `403`, jamais de vrais en-têtes d'authentification.
3. **Inject** : Le proxy recherche l'identifiant et ajoute l'en-tête d'authentification avant de transmettre. 25 services intégrés, 4 modes d'injection d'authentification (header, URL-path, HTTP Basic, OAuth) ; un 5ème, `none`, est uniquement au repos (le proxy rejette le trafic).
4. **Broker (coder + source de secrets Hermes)** : `POST /broker/resolve` matérialise un identifiant par appel d'outil, limité à l'environnement d'une seule commande. Seul `aquaman daemon` le sert, et uniquement pour les refs que vous avez déclarées (`projects.yaml` ou `aquaman broker allow`). Le proxy du plugin OpenClaw ne le sert jamais (v0.15.0+).
5. **Audit** : Chaque utilisation d'identifiant est journalisée avec des chaînes de hachage SHA-256.

Sur les chemins proxy, l'agent voit un endpoint local plus un marqueur : le placeholder `aquaman-proxy-managed`, ou le token loopback, qui ne fonctionne que contre votre proxy local. Jamais une vraie clé. Sur le chemin coder, la commande *enfant* reçoit les valeurs déclarées et l'agent voit une sortie expurgée.

## Modèle de sécurité

| Couche | Ce qu'elle fait | Ce qu'elle bloque |
|---|---|---|
| **Isolation de processus** | Identifiants dans un processus séparé, atteint via un socket Unix (`chmod 0o600`) ou un listener loopback protégé par token | Un agent compromis ne peut pas lire les clés proxifiées : espace d'adressage différent |
| **Portée du broker** | Seul `aquaman daemon` distribue des valeurs, et uniquement pour les refs que vous avez déclarées ; les proxys hébergés par OpenClaw ne le font jamais (v0.15.0+) | Un agent ne peut pas extraire des entrées de coffre-fort arbitraires via le socket |
| **Liste blanche de services** | `proxiedServices` contrôle les API que l'agent peut atteindre | L'agent ne peut pas parler à des services que vous n'avez pas autorisés |
| **Politiques de requête** | Règles méthode + chemin par service, appliquées avant l'injection d'identifiants | L'agent peut atteindre Anthropic mais pas son API d'administration ; peut rédiger des emails mais pas les envoyer |
| **Piste d'audit** | Journaux chaînés par hachage SHA-256 de chaque utilisation d'identifiant | Forensique post-incident, détection d'altération, preuves de conformité |
| **Broker par appel d'outil (coder)** | `aquaman-coder exec` matérialise les identifiants pour une commande à la fois | Les identifiants ne se dispersent pas dans l'environnement shell de l'agent |
| **Expurgation de sortie (coder)** | `aquaman-coder exec` fait passer stdout/stderr par un expurgateur qui efface chaque valeur qu'il vient d'injecter verbatim - plus des motifs génériques de fournisseurs en secours | Même des identifiants arbitraires et sans forme n'atteignent jamais la transcription de l'agent |

### Transports et contrôle d'accès

| Chemin | Transport | Contrôle d'accès |
|---|---|---|
| Agents de codage, tout client pouvant se connecter à un socket | Socket Unix `~/.aquaman/proxy.sock` | Permissions de fichier (`0600`) : uniquement les processus s'exécutant sous votre identité |
| Hermes (v0.13.0+), trafic modèle et Telegram d'OpenClaw (v0.15.0+) | TCP loopback `127.0.0.1:<port>` | Token par installation, vérification à temps constant, bind loopback |

Hermes et OpenClaw construisent chacun leur propre client HTTP et ne peuvent pas se connecter à un socket, ils utilisent donc le listener. Tout le reste utilise le socket.

Le token est une capacité à atteindre le proxy local, pas un identifiant. Généré par installation, stocké dans `~/.aquaman/config.yaml` (`0600`), envoyé par l'hôte comme sa clé API de fournisseur. Le proxy le vérifie, le retire, injecte votre vraie clé. Telegram n'a pas d'en-tête d'authentification, donc là le token voyage dans le segment de chemin `/bot<TOKEN>` à la place.

Compromis : tout processus local peut atteindre un port loopback, y compris d'autres utilisateurs, là où le `0600` du socket les exclut. Le token est la barrière ici, donc le listener reste désactivé jusqu'à ce que `aquaman hermes setup` ou `aquaman openclaw setup` l'active.

### Identifiants de canaux sur OpenClaw 2026.7.33+

| Canal | Sortie via le proxy |
|---|---|
| Telegram | Oui, depuis la v0.15.0 |
| Tout le reste | Non. Stockage en coffre-fort et migration uniquement |

Chaque canal construit son propre client HTTP par requête, donc l'intercepteur `fetch` du plugin ne voit plus le trafic des canaux sur ces versions. Router un canal nécessite une substitution d'endpoint de la part de l'hôte, et Telegram est le seul à l'avoir : `aquaman openclaw setup` pointe `channels.telegram.apiRoot` vers le proxy et remplace le token du bot par le token loopback.

Pour le reste, votre token reste dans le coffre-fort mais OpenClaw l'utilise directement, donc le proxy n'est pas dans le chemin et ces appels ne sont pas audités. `aquaman openclaw doctor` liste lesquels de vos canaux configurés sont dans quel groupe. Les fournisseurs de modèles ne sont pas affectés.

**Ce que l'isolation même-utilisateur ne peut pas faire.** Le `0o600` du socket exclut les autres utilisateurs, pas les autres processus s'exécutant sous votre identité. Un tel processus peut envoyer des requêtes via le proxy pendant son exécution (limité par la politique de requête, enregistré dans le journal d'audit) et peut récupérer les refs que vous avez déclarées, ce qui est le sens de « déclarer ». Il ne peut pas lire les clés que le proxy injecte. Pour une frontière plus stricte, exécutez l'agent sous un autre utilisateur OS ou dans un bac à sable.

Le modèle détaillé - spécificités par intégration (portée de l'intercepteur HTTP, profils d'authentification, résultats de scanner, note de l'éditeur ClawScan) - se trouve dans [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) et [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md).

### Posture de conformité

Aquaman fournit des tests de conformité exécutables sous `test/compliance/` mappés à :

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

Plus des narratifs d'alignement pour CISA/Five-Eyes « Careful Adoption of Agentic AI Services » (avril 2026), CSA MAESTRO, et OWASP Top 10 for Agentic Applications. Les tests s'exécutent dans le cadre de `npm test`. Voir [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) pour les mappings.


## Politiques de requête

Les scopes OAuth ne peuvent pas distinguer entre « rédiger un email » et « envoyer un email ». Les deux sont `gmail.send`. Les politiques de requête comblent ce vide.```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

• Les chemins correspondent au chemin complet de l'API en amont après le préfixe de service : l'API Web de Slack est /api/<method>, celle de Gmail est /gmail/v1/.... Les presets antérieurs à la v0.15.0 utilisaient /admin.* et /v1/users/*/messages/send, qui ne correspondaient jamais au trafic réel. aquaman doctor les signale s'ils sont encore dans votre configuration.
• Pas de politique = tout autoriser (rétrocompatible)
• La première correspondance l'emporte : les règles sont évaluées de haut en bas, les requêtes sans correspondance retombent sur defaultAction
• Refus avant authentification : les requêtes bloquées ne reçoivent jamais de vrais identifiants
• Globs de chemin : * correspond à l'intérieur d'un segment, ** correspond à zéro ou plusieurs segments
• aquaman setup applique des valeurs par défaut sûres pour les services stockés (anthropic, openai, slack, gmail).
• aquaman policy list / aquaman policy test <svc> <method> <path> pour l'inspection / les simulations.

Backends d'identifiants

Apportez votre propre coffre-fort - aquaman n'a pas de stockage interne. Choisissez le backend que vous utilisez déjà ; les secrets y restent, et le proxy les lit sur place.

aquaman setup détecte automatiquement une valeur par défaut pertinente (macOS → keychain ; Linux → keychain si libsecret, sinon systemd-creds si systemd ≥ 256, sinon encrypted-file).

encrypted-file est une solution de dernier recours pour les environnements Linux/CI sans interface graphique et sans trousseau natif. Pour une meilleure sécurité sous Linux, installez libsecret-1-dev (GNOME Keyring), utilisez systemd-creds (liaison TPM2), ou utilisez 1Password/Vault.

Mise en cache des identifiants (v0.13.1+)

Les backends ayant un coût par accès, comme 1password (une invite biométrique par lecture en mode application de bureau), bitwarden (~1-2 s de lancement du CLI) et vault (un aller-retour HTTP), sont mis en cache dans la mémoire du démon pendant 15 minutes par défaut, de sorte qu'une session d'agent chargée ne déverrouille le coffre qu'une fois par fenêtre au lieu d'une fois par requête. Les autres backends sont déjà rapides ou mettent en cache en interne, donc la mise en cache est désactivée par défaut pour eux. Ajustez avec credentials.cacheTtlSeconds dans ~/.aquaman/config.yaml (ou AQUAMAN_CACHE_TTL) ; 0 désactive.

Le compromis honnête : une invite biométrique par accès est une vérification de présence de l'utilisateur, et le cache supprime la présence par accès pendant la fenêtre du TTL. Pour les agents non surveillés, cette invite n'obtient jamais de réponse, donc le coffre est abandonné au profit d'un .env en clair, ce qui est strictement pire. Le cache ne déplace pas la frontière d'isolation : les valeurs ne vivent que dans le processus du proxy (où elles transitent déjà à chaque requête), ne sont jamais écrites sur disque, et sont invalidées immédiatement lorsque vous effectuez une rotation via aquaman credentials add. Les écritures vont toujours dans votre coffre. Testé de conformité dans test/compliance/cache-residency.test.ts. Pour zéro invite avec 1Password, utilisez un compte de service limité au coffre aquaman ; aquaman doctor vous y orientera.

Licence

MIT - voir LICENSE.