🔱 Aquaman

🔱 Единственный независимый прокси для учётных данных AI-агентов: изоляция с собственным хранилищем секретов и политики запросов с минимальными привилегиями. Ваши ключи остаются там, где вы их уже храните, и никогда не попадают в память агента. Совместим с 1Password, keychain, keepassxc и многими другими.

Вы настроили Claude Code, OpenClaw или Hermes, и теперь смотрите на файлы .env, где ваши драгоценные API-ключи лежат в открытом виде. Вы читали статьи. Вы знаете, что происходит, когда агент подвергается prompt injection. Мы понимаем.

Aquaman решает эту проблему с помощью трёх уровней защиты:

1. Изоляция процессов: API-ключи находятся в отдельном процессе прокси, который подставляет их на выходе. Агент хранит только маркер, а не ключ, поэтому даже RCE в агенте не сможет прочитать ключ. Агенты для написания кода получают только те ссылки, которые вы объявили, по одной команде за раз.
2. Политики запросов: Правила для каждого сервиса контролируют, к каким эндпоинтам агент может обращаться. Блокируйте административные API, запрещайте удаления, разрешайте черновики, но запрещайте отправку. Отклонённые запросы никогда не получают реальных учётных данных.
3. Аудит с защитой от подделки: Каждое использование учётных данных регистрируется с цепочками хешей SHA-256. Вы можете доказать, к чему был получен доступ, и обнаружить подделку постфактум.

Выберите свой путь

Aquaman поставляется в виде четырёх согласованных пакетов, использующих одно хранилище секретов и один демон. Устанавливайте только то, что вам нужно:

Единый CLI aquaman объединяет все четыре: команды верхнего уровня для хранилища секретов и аудита, aquaman openclaw ... для интеграции с OpenClaw, aquaman coder ... для интеграции с агентом написания кода (под капотом делегирует в aquaman-coder), а также aquaman hermes ... для Python-пакета Hermes.

Быстрый старт

aquaman help, aquaman doctor — ваши друзья.

1. Только хранилище секретов (просто прокси + ваши секреты)```bash

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

Прокси прослушивает `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`). Направьте любой инструмент на `http://aquaman.local/<service>/<path>`, и прокси внедрит заголовки аутентификации для этого сервиса из выбранного вами бэкенда хранилища.

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

Устранение неполадок: openclaw aquaman doctor.

Используете npm напрямую? npm install -g aquaman-proxy && aquaman openclaw setup делает то же самое — устанавливает прокси-CLI, сохраняет ваши ключи, устанавливает плагин в ~/.openclaw/extensions/aquaman-plugin/ и прописывает учётные данные (ссылки SecretRef в OpenClaw ≥ 2026.6.5, заполнитель auth-profiles.json в более старых версиях).

aquaman openclaw setup направляет models.providers.<svc>.baseUrl и channels.telegram.apiRoot на loopback-слушатель прокси, потому что транспорт моделей OpenClaw и его каналы каждый создают собственный HTTP-клиент и обходят перехватчик fetch. Каналы, отличные от Telegram, не предоставляют переопределения эндпоинта, поэтому их токены сохраняются и мигрируются, но не внедряются на исходящем трафике (см. packages/plugin/README.md). Добавляйте каналы в конфигурацию плагина в openclaw.json; среди поддерживаемых — Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face и другие (всего 25).

3. Агенты для программирования с ИИ (сегодня — 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

**Убедитесь сами (озарение за 30 секунд):** перезапустите Claude Code, откройте новую сессию внутри `~/code/my-app` и попросите агента выполнить:```
printenv | grep ANTHROPIC_API_KEY

Вы увидите это в расшифровке:``` ANTHROPIC_API_KEY=[REDACTED:injected-value]

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

*Дочерний* процесс видел настоящий ключ (ваши тесты, сборки, MCP-серверы, скрипты импорта — всё, что действительно в нём нуждается, работает). *Агент* — то, что решает, какой код запускать на вашей машине, — никогда не видит значение, а значит, его не видит ни история диалога, ни логи провайдера модели, ни кто-либо, кто позже сделает скриншот вашего терминала.

**Используйте его и из собственного терминала.** Тот же wrapper работает и без агента. Просто выполните `cd` в покрытый проект и добавьте префикс к вашей команде:```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

Тот же env injection, та же редакция stdout/stderr. Вставьте это в цели Makefile, shell-алиасы или CI-раннеры — везде, где иначе вы бы обратились к файлу .env.

Когда Claude Code запускает Bash-инструмент в ~/code/my-app, хук aquaman перезаписывает команду через updatedInput.command, оборачивая её в aquaman-coder exec. Эта обёртка:

• Разрешает каждую ссылку aquaman://service/key через брокер (POST /broker/resolve по UDS). Учётные данные материализуются для одной команды, а не на всё время жизни агента.
• Пропускает stdout/stderr через редактор, который добавляет шаблон на основе значения для каждого разрешённого значения: любая строка, которая была внедрена, редактируется, независимо от формы (токены Atlassian, секреты Notion, ключи внутренних API — ни один из них не обязан соответствовать известному формату провайдера). Общие шаблоны на основе формы (sk-ant-, ghp_, sk_live_, AKIA…, JWT, PEM-блоки, ATATT3xF…) всё ещё применяются после как эшелонированная защита для секретов, которые дочерний процесс раскрывает, но которые мы НЕ внедряли.
• Выполняет очистку при завершении команды.

Песочница Claude Code: по умолчанию она блокирует Unix-сокеты, поэтому aquaman coder setup claude-code добавляет прокси-сокет в белый список на macOS (sandbox.network.allowUnixSockets). Linux и WSL2 игнорируют этот список, где единственный вариант — sandbox.network.allowAllUnixSockets: true, что открывает все Unix-сокеты для команд в песочнице.

4. Hermes (хост агента)

Hermes — это сторонний (Python) хост без транспортного хука для внедрения, поэтому изоляция выполняется на стороне прокси: прокси предоставляет опциональный, защищённый токеном loopback-слушатель, и Hermes направляется на него через свои собственные переменные окружения.```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` включает loopback-слушатель, генерирует токен для каждой установки и записывает управляемый aquaman блок в `~/.hermes/.env` (с учётом `HERMES_HOME`): нативные `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` плюс placeholder api_key, равный токену. Hermes отправляет токен как ключ провайдера; прокси удаляет его, подставляет ваш реальный учётный данные из vault и перенаправляет запрос вверх по цепочке. Только LLM-провайдеры (Anthropic, OpenAI) на данный момент.

**Опциональные удобства в сессии** — Python-плагин добавляет команду `/aquaman-status`, инструмент `aquaman_status` и проверку работоспособности при старте сессии внутри Hermes (не хранит учётные данные):```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

Плагин также регистрирует источник секретов aquaman (Hermes ≥ 0.18.1) для секретов проекта, таких как GITHUB_TOKEN. Привяжите их в разделе secrets.aquaman.env в config.yaml Hermes, затем объявите каждую ссылку с помощью aquaman broker allow aquaman://github/token (требуется начиная с v0.15.0; aquaman hermes doctor перечисляет все пропущенные). В отличие от ключей LLM выше, эти значения попадают в окружение Hermes. См. packages/hermes/README.md.

Как это работает```

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. **Хранение**: Учётные данные находятся в том хранилище, которое вы уже используете, — без собственного хранилища (Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, зашифрованный файл).
2. **Политика**: Прокси проверяет правила метода + пути *до* обращения к учётным данным. Отклонённые запросы получают `403`, а не реальные заголовки аутентификации.
3. **Инъекция**: Прокси находит учётные данные и добавляет заголовок аутентификации перед пересылкой. 25 встроенных сервисов, 4 режима инъекции аутентификации (header, URL-path, HTTP Basic, OAuth); пятый, `none`, только для хранения (прокси отклоняет трафик).
4. **Брокер (coder + источник секретов Hermes)**: `POST /broker/resolve` материализует учётные данные для каждого вызова инструмента, ограничивая их окружением одной команды. Обслуживает его только `aquaman daemon`, и только для объявленных вами ссылок (`projects.yaml` или `aquaman broker allow`). Прокси плагина OpenClaw его никогда не обслуживает (v0.15.0+).
5. **Аудит**: Каждое использование учётных данных регистрируется в цепочках хешей SHA-256.

На путях через прокси агент видит локальную конечную точку плюс маркер: плейсхолдер `aquaman-proxy-managed` или loopback-токен, который работает только с вашим локальным прокси. Никогда — реальный ключ. На пути coder *дочерняя* команда получает объявленные значения, а агент видит отредактированный вывод.

## Модель безопасности

| Уровень | Что делает | Что останавливает |
|---|---|---|
| **Изоляция процессов** | Учётные данные в отдельном процессе, доступном через Unix-сокет (`chmod 0o600`) или loopback-слушатель с токеном | Скомпрометированный агент не может прочитать проксируемые ключи: другое адресное пространство |
| **Область брокера** | Только `aquaman daemon` выдаёт значения, и только для объявленных вами ссылок; прокси, размещённые в OpenClaw, этого никогда не делают (v0.15.0+) | Агент не может вытащить произвольные записи хранилища через сокет |
| **Белый список сервисов** | `proxiedServices` управляет тем, к каким API может обращаться агент | Агент не может обращаться к сервисам, которые вы не авторизовали |
| **Политики запросов** | Правила метода + пути для каждого сервиса, применяемые до инъекции учётных данных | Агент может обращаться к Anthropic, но не к его admin API; может создавать черновики писем, но не отправлять их |
| **Журнал аудита** | Журналы каждого использования учётных данных с цепочками хешей SHA-256 | Пост-инцидентная криминалистика, обнаружение подделки, доказательства соответствия |
| **Брокер на каждый вызов инструмента (coder)** | `aquaman-coder exec` материализует учётные данные для одной команды за раз | Учётные данные не расползаются по окружению оболочки агента |
| **Редактирование вывода (coder)** | `aquaman-coder exec` пропускает stdout/stderr через редактор, который дословно вычищает каждое только что внедрённое значение — плюс обобщённые шаблоны провайдеров как запасной вариант | Даже произвольные учётные данные без узнаваемой формы никогда не попадают в транскрипт агента |

### Транспорты и контроль доступа

| Путь | Транспорт | Контроль доступа |
|---|---|---|
| Агенты для кодинга, любой клиент, способный подключиться к сокету | Unix-сокет `~/.aquaman/proxy.sock` | Права доступа к файлу (`0600`): только процессы, запущенные от вашего имени |
| Hermes (v0.13.0+), трафик моделей и Telegram в OpenClaw (v0.15.0+) | Loopback TCP `127.0.0.1:<port>` | Токен для каждой установки, проверка с постоянным временем, привязка к loopback |

Hermes и OpenClaw каждый создают собственный HTTP-клиент и не могут подключиться к сокету, поэтому используют слушатель. Всё остальное использует сокет.

Токен — это возможность доступа к локальному прокси, а не учётные данные. Генерируется при каждой установке, хранится в `~/.aquaman/config.yaml` (`0600`), отправляется хостом как его api key провайдера. Прокси проверяет его, удаляет и внедряет ваш реальный ключ. У Telegram нет заголовка аутентификации, поэтому там токен передаётся в сегменте пути `/bot<TOKEN>`.

Компромисс: любой локальный процесс может достичь loopback-порта, включая других пользователей, тогда как `0600` сокета их отсекает. Токен здесь служит воротами, поэтому слушатель остаётся выключенным, пока `aquaman hermes setup` или `aquaman openclaw setup` его не включит.

### Учётные данные каналов в OpenClaw 2026.7.33+

| Канал | Исходящий трафик через прокси |
|---|---|
| Telegram | Да, начиная с v0.15.0 |
| Всё остальное | Нет. Только хранение в хранилище и миграция |

Каждый канал создаёт собственный HTTP-клиент для каждого запроса, поэтому перехватчик `fetch` плагина больше не видит трафик каналов в этих версиях. Для маршрутизации канала требуется переопределение конечной точки со стороны хоста, и только у Telegram оно есть: `aquaman openclaw setup` направляет `channels.telegram.apiRoot` на прокси и заменяет токен бота на loopback-токен.

Для остальных ваш токен остаётся в хранилище, но OpenClaw использует его напрямую, поэтому прокси не находится на пути и эти вызовы не аудируются. `aquaman openclaw doctor` показывает, какие из настроенных вами каналов в какой группе. Провайдеры моделей не затронуты.

**Чего не может изоляция в пределах одного пользователя.** `0o600` сокета не пускает других пользователей, но не другие процессы, запущенные от вашего имени. Такой процесс может отправлять запросы через прокси, пока он работает (ограничено политикой запросов, зафиксировано в журнале аудита), и может получать объявленные вами ссылки — это и означает «объявить». Он не может прочитать ключи, которые внедряет прокси. Для более жёсткой границы запускайте агента от имени другого пользователя ОС или в песочнице.

Подробная модель — особенности каждой интеграции (область действия HTTP-перехватчика, профили аутентификации, находки сканера, примечание издателя ClawScan) — описана в [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) и [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md).

### Соответствие требованиям

Aquaman поставляет исполняемые тесты соответствия в `test/compliance/`, сопоставленные с:

- **MITRE ATLAS** v5.4.0: техники 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/`)

Плюс описания соответствия для CISA/Five-Eyes «Careful Adoption of Agentic AI Services» (апрель 2026), CSA MAESTRO и OWASP Top 10 for Agentic Applications. Тесты запускаются в рамках `npm test`. См. [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) для сопоставлений.


## Политики запросов

Области OAuth не могут отличить «создать черновик письма» от «отправить письмо». И то, и другое — `gmail.send`. Политики запросов восполняют этот пробел.```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

• Пути — это полный путь upstream API после префикса сервиса: Web API Slack — /api/<method>, Gmail — /gmail/v1/.... Пресеты до v0.15.0 использовали /admin.* и /v1/users/*/messages/send, которые никогда не совпадали с реальным трафиком. aquaman doctor помечает их, если они всё ещё в вашей конфигурации.
• Нет политики = разрешить всё (обратная совместимость)
• Первое совпадение побеждает: правила оцениваются сверху вниз, несовпавшие запросы переходят к defaultAction
• Отказ до аутентификации: заблокированные запросы никогда не получают реальные учётные данные
• Глобы путей: * совпадает в пределах сегмента, ** совпадает с нулём или более сегментов
• aquaman setup применяет безопасные значения по умолчанию для хранимых сервисов (anthropic, openai, slack, gmail).
• aquaman policy list / aquaman policy test <svc> <method> <path> для инспекции / пробных запусков.

Бэкенды учётных данных

Принесите своё хранилище — у aquaman нет собственного. Выберите бэкенд, который вы уже используете; секреты остаются там, и прокси читает их на месте.

aquaman setup автоматически определяет разумное значение по умолчанию (macOS → keychain; Linux → keychain, если есть libsecret, иначе systemd-creds, если systemd ≥ 256, иначе encrypted-file).

encrypted-file — крайняя мера для headless Linux/CI-сред без нативного keyring. Для лучшей безопасности на Linux установите libsecret-1-dev (GNOME Keyring), используйте systemd-creds (привязка к TPM2) или используйте 1Password/Vault.

Кэширование учётных данных (v0.13.1+)

Бэкенды с затратами на каждое обращение, такие как 1password (биометрический запрос на каждое чтение в режиме десктопного приложения), bitwarden (~1-2 с на запуск CLI) и vault (HTTP-обмен), кэшируются в памяти демона на 15 минут по умолчанию, так что занятая сессия агента разблокирует хранилище один раз за окно, а не один раз за запрос. Остальные бэкенды уже быстрые или кэшируют внутри себя, поэтому для них кэширование по умолчанию отключено. Настройте с помощью credentials.cacheTtlSeconds в ~/.aquaman/config.yaml (или AQUAMAN_CACHE_TTL); 0 отключает.

Честный компромисс: биометрический запрос на каждое обращение — это проверка присутствия пользователя, а кэш убирает присутствие на каждое обращение в течение окна TTL. Для автономных агентов этот запрос никогда не получает ответа, поэтому хранилище забрасывается ради plaintext .env, что строго хуже. Кэш не сдвигает границу изоляции: значения живут только в процессе прокси (где они и так проходят при каждом запросе), никогда не записываются на диск и немедленно аннулируются при ротации через aquaman credentials add. Записи всегда идут в ваше хранилище. Проверено на соответствие в test/compliance/cache-residency.test.ts. Для нуля запросов с 1Password используйте сервисный аккаунт с областью доступа к хранилищу aquaman; aquaman doctor укажет вам туда.

Лицензия

MIT — см. LICENSE.