🔱 Der einzige unabhängige Credential-Proxy für KI-Agenten: Bring-Your-Own-Vault-Isolation & Least-Privilege-Anfragenrichtlinien. Ihre Schlüssel bleiben dort, wo Sie sie bereits aufbewahren, niemals im Speicher des Agenten. Kompatibel mit 1Password, keychain, keepassxc und vielen anderen.
# 🔱 Aquaman
[](https://github.com/tech4242/aquaman/actions/workflows/ci.yml)
[](https://codecov.io/gh/tech4242/aquaman)
[](https://www.npmjs.com/package/aquaman-proxy)
[](https://www.npmjs.com/package/aquaman-proxy)
[](https://github.com/tech4242/aquaman#security-model)
[](https://www.typescriptlang.org/)
[](LICENSE)
🔱 Der einzige unabhängige Credential-Proxy für KI-Agenten: Bring-your-own-Vault-Isolation und 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, Codex, OpenClaw, Hermes oder Docker Sandboxes 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 darf. 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 nachweisen, worauf zugegriffen wurde, und Manipulationen im Nachhinein erkennen.
## Wähle deinen Weg
Aquaman wird als vier koordinierte Pakete ausgeliefert, die sich einen Vault und einen Daemon teilen. Installiere nur, was du brauchst:
| Paket | Was es tut | Wann installieren |
|---|---|---|
| **[`aquaman-proxy`](https://github.com/tech4242/aquaman/blob/main/packages/proxy)** | Kern: Vault, Daemon, Audit, Policy, CLI. Das Stück, das jeder braucht. | Immer. |
| **[`aquaman-plugin`](https://github.com/tech4242/aquaman/blob/main/packages/plugin)** | OpenClaw-Gateway-Adapter. Startet den Proxy beim Gateway-Start; leitet Modell- und Telegram-Traffic darüber; 25 integrierte Dienste über 5 Auth-Modi. | Wenn du ein OpenClaw Gateway betreibst. Auch verfügbar unter https://clawhub.ai/plugins/aquaman-plugin |
| **[`aquaman-coder`](https://github.com/tech4242/aquaman/blob/main/packages/coder)** | Adapter für KI-Coding-Agenten. Projektbezogene `aquaman://service/key`-Referenzen, aufgelöst pro Bash-Tool-Aufruf. | Wenn du Claude Code oder Codex verwendest. |
| **[`aquaman-hermes`](https://github.com/tech4242/aquaman/blob/main/packages/hermes)** | Hermes-Agent-Host-Plugin (Python, auf PyPI). Richtet Hermes auf einen opt-in, token-geschützten Loopback-Listener über dessen natives `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL`; fügt einen In-Session-Befehl `/aquaman-status`, ein Tool und eine Health-Probe hinzu. Die Isolation liegt proxy-seitig; das Plugin hält keine Credentials. | Wenn du den Hermes-Agent-Host betreibst. `pip install aquaman-hermes` |
| **Docker Sandboxes** | Kein Paket: ein separater Weg, der nur `aquaman-proxy` benötigt. Dockers eigener Proxy injiziert die Secrets; `aquaman get` liefert sie aus deinem Vault, mit Allow-List und Audit-Log. | Wenn du Agenten in Docker Sandboxes betreibst. Siehe [Quick Start 5](#5-docker-sandboxes). |
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.
## Quick Start
`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 Endpunkt-Überschreibung, daher werden ihre Tokens gespeichert und migriert, aber nicht beim Egress injiziert (siehe [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/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 weitere (25 insgesamt).
### 3. KI-Coding-Agenten (Claude Code, Codex)
```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
# (or: aquaman coder setup codex)
aquaman doctor # 6. verify - should show both vault + coder green
```
**Überzeugen Sie sich selbst (das 30-Sekunden-Aha-Erlebnis):** Starten Sie Claude Code (oder Codex) 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 der Konversationsverlauf, nicht die Logs des Modellanbieters, nicht jeder, der später dein Terminal screenshottet.
**Verwende es auch von deinem eigenen Terminal aus.** Derselbe Wrapper funktioniert auch 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. Setze es in Makefile-Targets, Shell-Aliase oder CI-Runner ein – überall dort, wo du sonst zu einer `.env`-Datei greifen würdest.
Wenn Claude Code oder Codex einen Shell-Befehl 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). Anmeldedaten werden für einen Befehl materialisiert, nicht für die Lebensdauer des Agenten.
- Leitet stdout/stderr durch einen Redaktor, 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.
**Codex:** Genehmige die aquaman-Hooks in Codex' Startup-Hook-Review nach dem Setup (Codex überspringt neue Hooks, bis du ihnen vertraust). Seine Sandbox blockiert den Proxy-Socket ebenfalls standardmäßig; `aquaman coder setup codex` gibt das `config.toml`-Berechtigungsprofil aus, das ihn erlaubt. Codex-Hooks können Shell-Output nicht umschreiben, daher findet die Redaktion innerhalb von `aquaman-coder exec` statt. Details in [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md#codex).
### 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-gesteuerten 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 stromaufwärts 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 (hä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`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/README.md).
### 5. Docker Sandboxes
Docker Sandboxes hält Anmeldedaten bereits aus der Sandbox heraus: Ein Proxy auf deinem Rechner injiziert sie in Anfragen, und der Agent innerhalb der VM sieht nur einen Platzhalter. Standardmäßig stammen die Werte aus deinem OS-Schlüsselbund. Richte sie stattdessen auf aquaman aus, um jeden von aquaman unterstützten Vault, die Ref-Allow-List und einen manipulationssicheren Audit-Eintrag bei jedem Secret-Lesezugriff von sbx zu erhalten.
```bash
npm install -g aquaman-proxy
aquaman setup # 1. vault wizard
aquaman daemon & # 2. start the proxy
aquaman credentials add github token # 3. store the secret (if not already there)
aquaman broker allow aquaman://github/token # 4. allow it to be handed out
sbx secret set github \
--command "$(command -v node) $(command -v aquaman) get aquaman://github/token" \
--refresh on-demand # 5. sbx reads it from aquaman
```
sbx führt diesen Befehl aus seinem eigenen Hintergrunddienst aus, der nicht über den `PATH` deiner Shell verfügt, daher speichert Schritt 5 absolute Pfade. Wiederhole die Schritte 4 und 5 für jeden Dienst, den deine Sandbox verwendet.
Derselbe `aquaman get`-Befehl funktioniert überall dort, wo ein Tool einen Befehl benötigt, der ein Secret ausgibt: Codex (`model_providers.<id>.auth.command`), Claude Code (`apiKeyHelper`), OpenClaw exec secret providers und Hermes command secret sources.
## 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. **Speichern**: Anmeldedaten liegen im Vault-Backend, das du bereits betreibst - kein eigenes Vault (Keychain, 1Password, HashiCorp Vault, Bitwarden, Keeper, KeePassXC, systemd-creds, verschlüsselte Datei).
2. **Richtlinie**: Der Proxy prüft Methoden- und Pfadregeln, *bevor* er Anmeldedaten anfasst. Abgelehnte Anfragen erhalten einen `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-Quelle, `aquaman get`)**: `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 du deklariert hast (`projects.yaml` oder `aquaman broker allow`). Der Proxy des OpenClaw-Plugins stellt ihn nie bereit (v0.15.0+).
5. **Audit**: Jede Verwendung von Anmeldedaten wird mit SHA-256-Hashketten 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 deinen 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 du deklariert hast; von OpenClaw gehostete Proxies tun das nie (v0.15.0+) | Ein Agent kann keine beliebigen Vault-Einträge über den Socket abziehen |
| **Service-Allowlisting** | `proxiedServices` steuert, welche APIs der Agent erreichen kann | Der Agent kann nicht mit Diensten sprechen, die du nicht autorisiert hast |
| **Anfrage-Richtlinien** | Methoden- und 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-hashverkettete Logs jeder Verwendung von Anmeldedaten | Forensik nach Vorfällen, Manipulationserkennung, Compliance-Nachweise |
| **Broker pro Tool-Aufruf (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 nie 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 du 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, also nutzen sie den Listener. Alles andere nutzt 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 deinen echten Schlüssel. Telegram hat keinen Auth-Header, also reist das Token dort stattdessen im Pfadsegment `/bot<TOKEN>`.
Abwägung: 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, also 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, also 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 den Rest bleibt dein Token im Vault, aber OpenClaw verwendet es direkt, also ist der Proxy nicht im Pfad und diese Aufrufe werden nicht auditiert. `aquaman openclaw doctor` listet auf, welche deiner konfigurierten Kanäle in welcher Gruppe sind. Modell-Provider sind nicht betroffen.
**Was Same-User-Isolierung nicht kann.** Der `0o600`-Modus des Sockets hält andere Benutzer draußen, nicht andere Prozesse, die als du 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 du deklariert hast, was Deklarieren bedeutet. Er kann die Keys, die der Proxy injiziert, nicht lesen. Für eine härtere Grenze führe 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) - steht 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-Positionierung
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 stehen.
- **Keine Policy = alles erlauben** (abwärtskompatibel)
- **Erste Übereinstimmung gewinnt**: Regeln werden von oben nach unten ausgewertet, nicht übereinstimmende Anfragen fallen auf `defaultAction` durch
- **Ablehnung 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; die Secrets bleiben dort, und der Proxy liest sie direkt vor Ort.
| Backend | Am besten für | Einrichtung |
|---|---|---|
| `keychain` | Lokale Entwicklung auf macOS (Standard) | Funktioniert sofort |
| `encrypted-file` | Linux, WSL2, CI/CD | AES-256-GCM, passwortgeschützt |
| `keepassxc` | Bestehende KeePass-Nutzer | `npm i -g kdbxweb argon2` (optionale Peers seit v0.14.1), dann `AQUAMAN_KEEPASS_PASSWORD` oder eine Schlüsseldatei setzen |
| `1password` | Team-Credential-Sharing | `brew install 1password-cli && op signin`. Für unbeaufsichtigte Agenten ein [Service-Konto](https://developer.1password.com/docs/service-accounts/) verwenden (`OP_SERVICE_ACCOUNT_TOKEN`) |
| `vault` | Enterprise-Secrets-Management | `VAULT_ADDR` + `VAULT_TOKEN` setzen |
| `systemd-creds` | Linux mit systemd ≥ 256 | TPM2-gestützt, kein Root erforderlich |
| `bitwarden` | Bitwarden-Nutzer | `bw login && export BW_SESSION=$(bw unlock --raw)` |
| `keeper` | Nutzer des Keeper-Passwortmanagers (v0.16.0+) | `pip install keepercommander`, einmal mit `keeper shell` anmelden und `this-device persistent-login on` aktivieren, einen Ordner für aquaman erstellen, dann `export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>`. Einträge werden mit `aquaman::<service>::<key>` betitelt |
`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 ein letzter Ausweg 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` (eine biometrische Aufforderung pro Lesevorgang im Desktop-App-Modus), `bitwarden` (~1-2 s CLI-Spawn), `keeper` (ein Commander-Spawn, der sich anmeldet und synchronisiert) und `vault` (ein HTTP-Round-Trip), werden standardmäßig **im Speicher des Daemons** für 15 Minuten zwischengespeichert, sodass eine geschäftige Agenten-Sitzung den Vault einmal pro Fenster 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: Eine biometrische Aufforderung pro Zugriff ist eine Anwesenheitsprüfung des Nutzers, und der Cache entfernt die Anwesenheit pro Zugriff für das TTL-Fenster. Bei unbeaufsichtigten Agenten wird diese Aufforderung 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`](https://github.com/tech4242/aquaman/blob/main/test/compliance/cache-residency.test.ts). Für null Aufforderungen mit 1Password verwende ein Service-Konto, das auf den `aquaman`-Vault beschränkt ist; `aquaman doctor` wird dich dorthin verweisen.
## Lizenz
MIT - siehe [LICENSE](https://github.com/tech4242/aquaman/blob/main/LICENSE).