🔱 Aquaman

🔱 Le seul proxy d'identifiants indépendant pour les agents IA : isolation avec votre propre coffre et politiques de requêtes au 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 configurez Claude Code, OpenClaw ou Hermes, et vous vous retrouvez face à des fichiers .env avec vos précieuses clés API en texte brut. Vous lisez les articles. Vous savez ce qui se passe quand un agent subit une injection par prompt. Nous comprenons.

Aquaman résout cela avec trois couches de défense :

1. Isolation des processus : Les clés API vivent dans un processus proxy séparé. L'agent ne les voit jamais. Même une exécution de code à distance (RCE) dans l'agent ne peut pas atteindre les identifiants. Ils sont dans un espace d'adressage différent.
2. Politiques de requêtes : Des règles par service contrôlent quels points de terminaison 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 n'obtiennent jamais de véritables identifiants.
3. Audit inviolable : Chaque utilisation d'identifiant est enregistré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 chemin

Aquaman est livré sous forme de quatre packages coordonnés, partageant un seul coffre + un seul démon. Installez seulement ce dont vous avez besoin :

Un seul CLI aquaman expose les quatre : commandes de haut niveau pour le coffre et l'audit, aquaman openclaw ... pour l'intégration OpenClaw, aquaman coder ... pour l'intégration avec les agents de codage (délègue à aquaman-coder en interne) ainsi que aquaman hermes ... pour le package Python Hermes.

Démarrage rapide

aquaman help, aquaman doctor sont vos amis.

1. Coffre uniquement (juste le proxy + vos secrets)

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 que vous avez choisi.

2. OpenClaw Gateway

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.

Utilisation directe via npm ? 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 câble les identifiants (références SecretRef sur OpenClaw ≥ 2026.6.5, placeholder auth-profiles.json sur les versions plus anciennes).

L'intercepteur HTTP du plugin ne redirige que le trafic pour les services de sa configuration services (Anthropic + OpenAI par défaut). Ajoutez-en d'autres 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 (25 au total).

3. Agents de codage IA (Claude Code aujourd'hui)

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 par vous-même (le « aha » 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 le transcript :

ANTHROPIC_API_KEY=[REDACTED:injected-value]

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

Le processus enfant a vu la vraie clé (vos tests, builds, serveurs MCP, scripts d'importation – tout ce qui en a réellement besoin fonctionne). L'agent – ce qui décide quel code exécuter sur votre machine – ne voit jamais la valeur, et donc ni l'historique de la conversation, ni les journaux du fournisseur de modèle, ni quiconque qui ferait une capture d'écran de votre terminal par la suite.

Utilisez-le depuis votre propre terminal aussi. Le même wrapper fonctionne sans l'agent. Il suffit de cd dans un projet couvert et de préfixer votre commande :

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 exécuteurs 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'envelopper 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 la durée de vie de l'agent.
• Redirige stdout/stderr à travers un masqueur qui ajoute un motif basé sur la valeur pour chaque valeur résolue : toute chaîne injectée est masquée, quelle que soit sa forme (jetons Atlassian, secrets Notion, clés d'API internes – aucune 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 après comme défense en profondeur pour les secrets que l'enfant a révélés et que nous n'avons PAS injectés.
• Nettoie quand la commande se termine.

4. Hermes (hôte d'agent)

Hermes est un hôte étranger (Python) sans crochet de transport pour injecter, donc l'isolation est faite côté proxy : le proxy expose un écouteur de boucle locale optionnel avec jeton et Hermes y est pointé via ses propres variables d'environnement.

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 de boucle locale, génère un jeton par installation et écrit un bloc géré par aquaman dans ~/.hermes/.env (en respectant HERMES_HOME) : le ANTHROPIC_BASE_URL/OPENAI_BASE_URL natif plus un api_key placeholder égal au jeton. Hermes envoie le jeton comme sa clé fournisseur ; le proxy le retire, injecte votre véritable identifiant de coffre 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) :

pip install aquaman-hermes            # or: uv tool install aquaman-hermes
aquaman-hermes install                # drops the plugin into ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman

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

1. Stockage : Les identifiants résident dans le backend de coffre que vous exécutez déjà – pas de coffre maison (Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, encrypted-file).
2. Politique : Le proxy vérifie les règles de méthode + chemin avant de toucher aux identifiants. Les requêtes refusées obtiennent un 403, jamais de véritables en-têtes d'authentification.
3. Injection : Le proxy recherche l'identifiant et ajoute l'en-tête d'authentification avant de transmettre. 25 services intégrés, 4 modes d'authentification par injection (en-tête, chemin URL, HTTP Basic, OAuth) ; un 5ème, none, est uniquement au repos (le proxy rejette le trafic).
4. Broker (chemin codeur) : POST /broker/resolve matérialise un identifiant par appel d'outil, limité à l'environnement d'une seule commande, puis expire.
5. Audit : Chaque utilisation d'identifiant est enregistrée avec des chaînes de hachage SHA-256.

L'agent ne voit jamais qu'un nom d'hôte sentinelle (aquaman.local) ou un marqueur placeholder (aquaman-proxy-managed). Il ne voit jamais une vraie clé, et aucun port TCP n'est ouvert pour que d'autres processus puissent sonder.

Modèle de sécurité

Modèle détaillé – spécificités par intégration (portée de l'intercepteur HTTP, profils d'authentification, résultats du scanner, note de l'éditeur ClawScan) – se trouve dans packages/plugin/README.md et 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 récits d'alignement pour le document « Careful Adoption of Agentic AI Services » du CISA/Cinq-Yeux (avril 2026), CSA MAESTRO, et l'OWASP Top 10 pour les applications agentiques. Les tests sont exécutés dans le cadre de npm test. Voir docs/compliance/ pour les correspondances.

Politiques de requêtes

Les portées OAuth ne peuvent pas faire la distinction entre « rédiger un email » et « envoyer un email ». Les deux sont gmail.send. Les politiques de requêtes comblent cette lacune.

# ~/.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: "/admin.*"
        action: deny
  gmail:
    defaultAction: allow
    rules:
      - method: POST
        path: "/v1/users/*/messages/send"
        action: deny          # drafts ok, sending blocked

• Pas de politique = tout autoriser (rétrocompatible)
• Première correspondance gagne : les règles sont évaluées de haut en bas, les requêtes non correspondantes tombent sur defaultAction
• Refusé avant authentification : les requêtes bloquées n'obtiennent jamais de véritables identifiants
• Globes de chemin : * correspond à 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 inspection / exécutions à blanc.

Backends d'identifiants

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

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

encrypted-file est un dernier recours pour les environnements Linux/CI sans tête sans trousseau natif. Pour une meilleure sécurité sur 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 avec un coût par accès – 1password (une invite biométrique par lecture en mode application de bureau), bitwarden (~1-2 s de lancement CLI), 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 occupée déverrouille le coffre 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 pour eux par défaut. 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 utilisateur, et le cache supprime la présence par accès pendant la fenêtre TTL. Pour les agents non supervisés, cette invite n'est jamais répondue – ils abandonnent le coffre pour un .env en texte brut, ce qui est strictement pire. Le cache ne déplace pas la frontière d'isolation : les valeurs ne vivent que dans le processus proxy (où elles transitent déjà à chaque requête), ne sont jamais écrites sur le disque et sont invalidées immédiatement lorsque vous faites 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 dirigera.

Licence

MIT - voir LICENSE.