🔱 Aquaman

🔱 Der einzige unabhängige Credential-Proxy für KI-Agenten: Bring-your-own-Vault-Isolation & Least-Privilege-Request-Richtlinien. Deine Schlüssel bleiben dort, wo du sie bereits aufbewahrst, niemals im Speicher des Agenten. Kompatibel mit 1Password, Keychain, keepassxc und vielen weiteren.

Du hast Claude Code, OpenClaw oder Hermes eingerichtet, und jetzt starrst du auf .env-Dateien, in denen deine wertvollen API-Schlüssel im Klartext herumliegen. Du hast die Artikel gelesen. Du weißt, was passiert, wenn ein Agent per Prompt-Injection kompromittiert wird. Wir verstehen das.

Aquaman löst dies mit drei Verteidigungsebenen:

1. Prozessisolation: API-Schlüssel leben in einem separaten Proxy-Prozess, der sie beim Egress injiziert. Der Agent hält nur einen Marker, niemals einen Schlüssel, sodass selbst RCE im Agenten keinen auslesen kann. Coding-Agenten erhalten nur die Referenzen, die du deklarierst, einen Befehl nach dem anderen.
2. Request-Richtlinien: Regeln pro Dienst steuern, welche Endpunkte ein Agent aufrufen kann. Admin-APIs blockieren, Löschungen verhindern, Entwürfe erlauben, aber Versand verweigern. Abgelehnte Anfragen erhalten niemals echte Credentials.
3. Manipulationssicheres Audit: Jede Credential-Nutzung wird mit SHA-256-Hashketten protokolliert. Du kannst beweisen, worauf zugegriffen wurde, und Manipulationen im Nachhinein erkennen.

Wähle deinen Weg

Aquaman wird als vier koordinierte Pakete ausgeliefert, die sich einen Vault + einen Daemon teilen. Installiere nur, was du brauchst:

Eine einzige aquaman-CLI macht alle vier verfügbar: Top-Level-Befehle für Vault und Audit, aquaman openclaw ... für die OpenClaw-Integration, aquaman coder ... für die Coding-Agent-Integration (delegiert unter der Haube an aquaman-coder) sowie aquaman hermes ... für das Hermes-Python-Paket.

Schnellstart

aquaman help, aquaman doctor sind deine Freunde.

1. Nur Vault (nur der Proxy + deine Secrets)```bash

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

Der Proxy lauscht auf `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`). Richte ein beliebiges Tool auf `http://aquaman.local/<service>/<path>` aus, und der Proxy injiziert Auth-Header für diesen Dienst aus deinem gewählten Vault-Backend.

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

Fehlerbehebung: openclaw aquaman doctor.

npm direkt verwenden? npm install -g aquaman-proxy && aquaman openclaw setup macht dasselbe – installiert die Proxy-CLI, speichert deine Schlüssel, installiert das Plugin in ~/.openclaw/extensions/aquaman-plugin/ und verdrahtet die Anmeldedaten (SecretRef-Referenzen auf OpenClaw ≥ 2026.6.5, den auth-profiles.json-Platzhalter auf älteren Versionen).

aquaman openclaw setup richtet models.providers.<svc>.baseUrl und channels.telegram.apiRoot auf den Loopback-Listener des Proxys aus, weil OpenClaws Modelltransport und seine Kanäle jeweils ihren eigenen HTTP-Client aufbauen und den Fetch-Interceptor umgehen. Kanäle außer Telegram bieten keine Endpoint-Überschreibung, daher werden ihre Tokens gespeichert und migriert, aber nicht beim Egress injiziert (siehe packages/plugin/README.md). Füge Kanäle unter der Plugin-Konfiguration in openclaw.json hinzu; unterstützte umfassen Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face und mehr (insgesamt 25).

3. KI-Coding-Agenten (heute Claude Code)```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

**Überzeugen Sie sich selbst (das 30-Sekunden-Aha-Erlebnis):** Starten Sie Claude Code neu, öffnen Sie eine neue Sitzung in `~/code/my-app` und bitten Sie den Agenten, Folgendes auszuführen:```
printenv | grep ANTHROPIC_API_KEY

Das sehen Sie im Transkript:``` ANTHROPIC_API_KEY=[REDACTED:injected-value]

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

Der *Kind*-Prozess sah den echten Schlüssel (deine Tests, Builds, MCP-Server, Import-Skripte – alles, was ihn tatsächlich benötigt, funktioniert). Der *Agent* – das Ding, das entscheidet, welcher Code auf deiner Maschine ausgeführt wird – sieht den Wert nie, und damit auch nicht die Konversationshistorie, nicht die Logs des Modellanbieters, nicht jeder, der später dein Terminal screenshottet.

**Nutze es auch von deinem eigenen Terminal aus.** Derselbe Wrapper funktioniert ohne den Agenten. Wechsle einfach mit `cd` in ein abgedecktes Projekt und stelle deinem Befehl Folgendes voran:```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

Gleiche Env-Injektion, gleiche Redaktion auf stdout/stderr. Einfach in Makefile-Targets, Shell-Aliase oder CI-Runner einfügen – überall dort, wo du sonst zu einer .env-Datei greifen würdest.

Wenn Claude Code ein Bash-Tool in ~/code/my-app ausführt, schreibt aquamans Hook den Befehl über updatedInput.command um, um ihn unter aquaman-coder exec zu wrappen. Dieser Wrapper:

• Löst jede aquaman://service/key-Referenz über den Broker auf (POST /broker/resolve über UDS). Credentials werden für einen Befehl materialisiert, nicht für die Lebensdauer des Agenten.
• Leitet stdout/stderr durch einen Redactor, der für jeden aufgelösten Wert ein wertbasiertes Muster voranstellt: welcher String auch immer injiziert wurde, wird redigiert, unabhängig von seiner Form (Atlassian-Tokens, Notion-Secrets, interne API-Keys – keiner davon muss einem bekannten Provider-Format entsprechen). Generische formbasierte Muster (sk-ant-, ghp_, sk_live_, AKIA…, JWTs, PEM-Blöcke, ATATT3xF…) laufen danach weiterhin als Defense-in-Depth für Secrets, die das Kindprozess an die Oberfläche bringt und die wir NICHT injiziert haben.
• Räumt auf, wenn der Befehl beendet wird.

Claude Code Sandbox: Sie blockiert Unix-Sockets standardmäßig, daher allowlistet aquaman coder setup claude-code den Proxy-Socket unter macOS (sandbox.network.allowUnixSockets). Linux und WSL2 ignorieren diese Liste, wo die einzige Option sandbox.network.allowAllUnixSockets: true ist, was jeden Unix-Socket für sandboxed Befehle öffnet.

4. Hermes (Agent-Host)

Hermes ist ein fremder (Python-)Host ohne Transport-Hook zum Injizieren, daher erfolgt die Isolation proxy-seitig: Der Proxy stellt einen opt-in, token-gated Loopback-Listener bereit, und Hermes wird über seine eigenen Env-Variablen darauf ausgerichtet.```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` aktiviert den Loopback-Listener, generiert ein Token pro Installation und schreibt einen von aquaman verwalteten Block in `~/.hermes/.env` (unter Beachtung von `HERMES_HOME`): die nativen `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` plus einen Platzhalter-api_key, der dem Token entspricht. Hermes sendet das Token als seinen Provider-Schlüssel; der Proxy entfernt es, fügt Ihre echte Vault-Anmeldeinformation ein und leitet es upstream weiter. Derzeit nur LLM-Anbieter (Anthropic, OpenAI).

**Optionales In-Session-Sugar** – das Python-Plugin fügt einen `/aquaman-status`-Befehl, ein `aquaman_status`-Tool und eine Health-Probe beim Sitzungsstart innerhalb von Hermes hinzu (enthält keine Anmeldeinformationen):```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

Das Plugin registriert außerdem eine aquaman Secret Source (Hermes ≥ 0.18.1) für Projekt-Secrets wie GITHUB_TOKEN. Binde sie unter secrets.aquaman.env in Hermes' config.yaml ein und deklariere dann jede Referenz mit aquaman broker allow aquaman://github/token (erforderlich seit v0.15.0; aquaman hermes doctor listet alle auf, die du vergessen hast). Anders als die oben genannten LLM-Keys gelangen diese Werte in Hermes' Env. Siehe packages/hermes/README.md.

Funktionsweise```

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. **Speicher**: Anmeldedaten liegen im Vault-Backend, das Sie bereits betreiben - kein eigenes Vault (Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, verschlüsselte Datei).
2. **Richtlinie**: Der Proxy prüft Methode + Pfadregeln, *bevor* er Anmeldedaten anfasst. Abgelehnte Anfragen erhalten ein `403`, niemals echte Auth-Header.
3. **Injizieren**: Der Proxy schlägt die Anmeldedaten nach und fügt den Auth-Header vor der Weiterleitung hinzu. 25 integrierte Dienste, 4 injizierende Auth-Modi (Header, URL-Pfad, HTTP Basic, OAuth); ein 5., `none`, ist nur at-rest (Proxy lehnt Traffic ab).
4. **Broker (coder + Hermes Secret Source)**: `POST /broker/resolve` materialisiert eine Anmeldedaten pro Tool-Aufruf, beschränkt auf die Umgebung eines einzelnen Befehls. Nur `aquaman daemon` stellt ihn bereit, und nur für Refs, die Sie deklariert haben (`projects.yaml` oder `aquaman broker allow`). Der Proxy des OpenClaw-Plugins stellt ihn niemals bereit (v0.15.0+).
5. **Audit**: Jede Verwendung von Anmeldedaten wird mit SHA-256-Hash-Ketten protokolliert.

Auf den Proxy-Pfaden sieht der Agent einen lokalen Endpunkt plus einen Marker: den Platzhalter `aquaman-proxy-managed` oder das Loopback-Token, das nur gegen Ihren lokalen Proxy funktioniert. Niemals einen echten Schlüssel. Auf dem Coder-Pfad erhält der *Kind*-Befehl die deklarierten Werte und der Agent sieht redigierte Ausgabe.

## Sicherheitsmodell

| Ebene | Was sie tut | Was sie verhindert |
|---|---|---|
| **Prozessisolierung** | Anmeldedaten in einem separaten Prozess, erreichbar über einen Unix-Socket (`chmod 0o600`) oder einen token-geschützten Loopback-Listener | Ein kompromittierter Agent kann proxied Keys nicht lesen: anderer Adressraum |
| **Broker-Scope** | Nur `aquaman daemon` gibt Werte heraus, und nur für Refs, die Sie deklariert haben; von OpenClaw gehostete Proxies tun dies niemals (v0.15.0+) | Ein Agent kann keine beliebigen Vault-Einträge über den Socket abrufen |
| **Service-Allowlisting** | `proxiedServices` steuert, welche APIs der Agent erreichen kann | Der Agent kann nicht mit Diensten kommunizieren, die Sie nicht autorisiert haben |
| **Anfrage-Richtlinien** | Methode + Pfadregeln pro Dienst, durchgesetzt vor der Injektion von Anmeldedaten | Der Agent kann Anthropic erreichen, aber nicht dessen Admin-API; kann E-Mails entwerfen, aber nicht senden |
| **Audit-Trail** | SHA-256-hash-verkettete Logs jeder Verwendung von Anmeldedaten | Forensik nach Vorfällen, Manipulationserkennung, Compliance-Nachweise |
| **Per-Tool-Call-Broker (coder)** | `aquaman-coder exec` materialisiert Anmeldedaten für jeweils einen Befehl | Anmeldedaten breiten sich nicht über die Shell-Umgebung des Agenten aus |
| **Ausgabe-Redaktion (coder)** | `aquaman-coder exec` leitet stdout/stderr durch einen Redaktor, der jeden gerade injizierten Wert wörtlich entfernt - plus generische Provider-Muster als Fallback | Selbst beliebige, formlose Anmeldedaten erreichen niemals das Transkript des Agenten |

### Transporte und Zugriffskontrolle

| Pfad | Transport | Zugriffskontrolle |
|---|---|---|
| Coding-Agents, jeder Client, der einen Socket anwählen kann | Unix-Socket `~/.aquaman/proxy.sock` | Dateiberechtigungen (`0600`): nur Prozesse, die als Sie laufen |
| Hermes (v0.13.0+), OpenClaw-Modell- und Telegram-Traffic (v0.15.0+) | Loopback-TCP `127.0.0.1:<port>` | Token pro Installation, Constant-Time-Prüfung, Loopback-Bind |

Hermes und OpenClaw bauen jeweils ihren eigenen HTTP-Client und können keinen Socket anwählen, daher verwenden sie den Listener. Alles andere verwendet den Socket.

Das Token ist eine Berechtigung, den lokalen Proxy zu erreichen, keine Anmeldedaten. Pro Installation generiert, gespeichert in `~/.aquaman/config.yaml` (`0600`), vom Host als dessen Provider-API-Key gesendet. Der Proxy prüft es, entfernt es, injiziert Ihren echten Schlüssel. Telegram hat keinen Auth-Header, daher reist das Token dort stattdessen im Pfadsegment `/bot<TOKEN>`.

Kompromiss: Jeder lokale Prozess kann einen Loopback-Port erreichen, auch andere Benutzer, wo der `0600`-Modus des Sockets sie aussperrt. Das Token ist dort das Tor, daher bleibt der Listener aus, bis `aquaman hermes setup` oder `aquaman openclaw setup` ihn einschaltet.

### Kanal-Anmeldedaten auf OpenClaw 2026.7.33+

| Kanal | Egress durch den Proxy |
|---|---|
| Telegram | Ja, seit v0.15.0 |
| Alles andere | Nein. Nur Vault-Speicherung und -Migration |

Jeder Kanal baut seinen eigenen HTTP-Client pro Anfrage, daher sieht der `fetch`-Interceptor des Plugins auf diesen Versionen keinen Kanal-Traffic mehr. Das Routing eines Kanals erfordert eine Endpunkt-Überschreibung vom Host, und Telegram ist der einzige, der sie hat: `aquaman openclaw setup` richtet `channels.telegram.apiRoot` auf den Proxy und ersetzt das Bot-Token durch das Loopback-Token.

Für die übrigen bleibt Ihr Token im Vault, aber OpenClaw verwendet es direkt, sodass der Proxy nicht im Pfad liegt und diese Aufrufe nicht auditiert werden. `aquaman openclaw doctor` listet auf, welche Ihrer konfigurierten Kanäle in welcher Gruppe sind. Modell-Provider sind nicht betroffen.

**Was Same-User-Isolierung nicht leisten kann.** Der `0o600`-Modus des Sockets hält andere Benutzer fern, nicht andere Prozesse, die als Sie laufen. Ein solcher Prozess kann während seiner Laufzeit Anfragen durch den Proxy senden (begrenzt durch die Anfrage-Richtlinie, im Audit-Log aufgezeichnet) und kann Refs abrufen, die Sie deklariert haben - was Deklarieren bedeutet. Er kann die Schlüssel, die der Proxy injiziert, nicht lesen. Für eine härtere Grenze führen Sie den Agenten als anderen OS-Benutzer oder in einer Sandbox aus.

Detailliertes Modell - integrationsspezifische Besonderheiten (HTTP-Interceptor-Scope, Auth-Profile, Scanner-Befunde, ClawScan-Publisher-Hinweis) - finden Sie in [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) und [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md).

### Compliance-Position

Aquaman liefert ausführbare Konformitätstests unter `test/compliance/`, zugeordnet zu:

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

Dazu Ausrichtungsnarrative für CISA/Five-Eyes "Careful Adoption of Agentic AI Services" (April 2026), CSA MAESTRO und OWASP Top 10 for Agentic Applications. Die Tests laufen als Teil von `npm test`. Siehe [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) für die Zuordnungen.


## Anfrage-Richtlinien

OAuth-Scopes können nicht zwischen "eine E-Mail entwerfen" und "eine E-Mail senden" unterscheiden. Beides ist `gmail.send`. Anfrage-Richtlinien schließen diese Lücke.```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

• Pfade sind die vollständigen Pfade der Upstream-API nach dem Service-Präfix: Slacks Web-API ist /api/<method>, Gmails ist /gmail/v1/.... Presets vor v0.15.0 verwendeten /admin.* und /v1/users/*/messages/send, die nie echten Traffic abgefangen haben. aquaman doctor markiert diese, falls sie noch in deiner Konfiguration sind.
• Keine Policy = alles erlauben (abwärtskompatibel)
• Erste Übereinstimmung gewinnt: Regeln werden von oben nach unten ausgewertet, nicht übereinstimmende Anfragen fallen auf defaultAction durch
• Verweigert vor Authentifizierung: blockierte Anfragen erhalten nie echte Anmeldedaten
• Pfad-Globs: * stimmt innerhalb eines Segments überein, ** stimmt mit null oder mehr Segmenten überein
• aquaman setup wendet sichere Standardwerte für gespeicherte Dienste an (anthropic, openai, slack, gmail).
• aquaman policy list / aquaman policy test <svc> <method> <path> zur Inspektion / für Dry-Runs.

Credential Backends

Bring deinen eigenen Vault mit - aquaman hat keinen eigenen Speicher. Wähle das Backend, das du bereits betreibst; Secrets bleiben dort, und der Proxy liest sie direkt vor Ort.

aquaman setup erkennt automatisch einen sinnvollen Standard (macOS → keychain; Linux → keychain falls libsecret, sonst systemd-creds falls systemd ≥ 256, sonst encrypted-file).

encrypted-file ist die letzte Option für headless Linux-/CI-Umgebungen ohne nativen Keyring. Für bessere Sicherheit unter Linux installiere libsecret-1-dev (GNOME Keyring), verwende systemd-creds (TPM2-Bindung) oder nutze 1Password/Vault.

Credential-Caching (v0.13.1+)

Backends mit Kosten pro Zugriff, wie 1password (ein biometrischer Prompt pro Lesevorgang im Desktop-App-Modus), bitwarden (~1-2 s CLI-Spawn) und vault (ein HTTP-Round-Trip), werden im Speicher des Daemons standardmäßig 15 Minuten lang zwischengespeichert, sodass eine stark beanspruchte Agent-Session den Vault einmal pro Zeitfenster entsperrt statt einmal pro Anfrage. Die anderen Backends sind bereits schnell oder cachen intern, daher ist Caching für sie standardmäßig deaktiviert. Anpassen mit credentials.cacheTtlSeconds in ~/.aquaman/config.yaml (oder AQUAMAN_CACHE_TTL); 0 deaktiviert es.

Der ehrliche Kompromiss: Ein biometrischer Prompt pro Zugriff ist eine Prüfung der Anwesenheit des Nutzers, und der Cache entfernt die Anwesenheitsprüfung pro Zugriff für das TTL-Zeitfenster. Bei unbeaufsichtigten Agents wird dieser Prompt nie beantwortet, sodass der Vault zugunsten einer Klartext-.env aufgegeben wird, was strikt schlechter ist. Der Cache verschiebt nicht die Isolationsgrenze: Werte leben nur im Proxy-Prozess (wo sie ohnehin bei jeder Anfrage durchlaufen), werden nie auf die Festplatte geschrieben und werden sofort ungültig, wenn du über aquaman credentials add rotierst. Schreibvorgänge gehen immer in deinen Vault. Konformitätsgetestet in test/compliance/cache-residency.test.ts. Für null Prompts mit 1Password verwende ein Service-Konto, das auf den aquaman-Vault beschränkt ist; aquaman doctor wird dich dorthin verweisen.

Lizenz

MIT - siehe LICENSE.