🔱 البروكسي الوحيد المستقل للاعتمادات لوكلاء الذكاء الاصطناعي: عزل بخزاناتك الخاصة وسياسات طلب بأقل الامتيازات. تبقى مفاتيحك حيث تخزنها بالفعل، ولا تصل أبدًا إلى ذاكرة الوكيل. متوافق مع 1Password و keychain و keepassxc والعديد غيرها.
# 🔱 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)
🔱 الوكيل الوحيد المستقل لبيانات الاعتماد لوكلاء الذكاء الاصطناعي: عزل الخزنة الخاصة بك وسياسات الطلبات بأقل صلاحيات. مفاتيحك تبقى حيث تحتفظ بها بالفعل، ولا تدخل أبدًا في ذاكرة الوكيل. متوافق مع 1Password وkeychain وkeepassxc وغيرها الكثير.
تقوم بإعداد Claude Code أو Codex أو OpenClaw أو Hermes أو Docker Sandboxes، والآن تجد نفسك تحدّق في ملفات `.env` التي تحتوي على مفاتيح API الثمينة مكشوفة كنص صريح. لقد قرأت المقالات. تعرف ما يحدث عندما يتعرض الوكيل لهجوم حقن الأوامر. نحن نتفهم ذلك.
يعالج Aquaman هذه المشكلة بثلاث طبقات من الحماية:
1. **عزل العمليات**: مفاتيح API تعيش في عملية وكيل منفصلة تحقنها عند الخروج. يحمل الوكيل علامة مرجعية، وليس مفتاحًا أبدًا، لذا حتى تنفيذ التعليمات عن بُعد (RCE) في الوكيل لا يمكنه قراءة أي مفتاح. وكلاء البرمجة يحصلون فقط على المراجع التي تعلنها، أمرًا واحدًا في كل مرة.
2. **سياسات الطلبات**: قواعد لكل خدمة تتحكم في *أي نقاط نهاية* يمكن للوكيل استدعاؤها. احجب واجهات الإدارة، وامنع الحذف، واسمح بالمسودات لكن ارفض الإرسال. الطلبات المرفوضة لا تحصل أبدًا على بيانات اعتماد حقيقية.
3. **تدقيق مقاوم للتلاعب**: كل استخدام لبيانات الاعتماد يُسجَّل بسلاسل تجزئة SHA-256. يمكنك إثبات ما تم الوصول إليه واكتشاف أي تلاعب بعد وقوعه.
## اختر مسارك
يُوزَّع Aquaman كأربع حزم متناسقة، تشترك في خزنة واحدة + خادم خفي واحد. ثبّت فقط ما تحتاجه:
| الحزمة | ما تفعله | متى تُثبَّت |
|---|---|---|
| **[`aquaman-proxy`](https://github.com/tech4242/aquaman/blob/main/packages/proxy)** | النواة: الخزنة، الخادم الخفي، التدقيق، السياسة، واجهة الأوامر. الجزء الذي يحتاجه الجميع. | دائمًا. |
| **[`aquaman-plugin`](https://github.com/tech4242/aquaman/blob/main/packages/plugin)** | محوّل OpenClaw Gateway. يشغّل الوكيل عند بدء Gateway؛ ويوجّه حركة النموذج وTelegram عبره؛ و25 خدمة مدمجة عبر 5 أنماط مصادقة. | إذا كنت تشغّل OpenClaw Gateway. متاح أيضًا على https://clawhub.ai/plugins/aquaman-plugin |
| **[`aquaman-coder`](https://github.com/tech4242/aquaman/blob/main/packages/coder)** | محوّل وكيل البرمجة بالذكاء الاصطناعي. مراجع `aquaman://service/key` المرتبطة بالمشروع تُحلّ لكل استدعاء لأداة Bash. | إذا كنت تستخدم Claude Code أو Codex. |
| **[`aquaman-hermes`](https://github.com/tech4242/aquaman/blob/main/packages/hermes)** | إضافة مضيف وكيل Hermes (Python، على PyPI). توجّه Hermes إلى مستمع loopback اختياري محمي برمز عبر `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` الأصليين؛ وتضيف أمر `/aquaman-status` داخل الجلسة، وأداة، وفحص صحة. العزل من جهة الوكيل؛ الإضافة لا تحمل أي بيانات اعتماد. | إذا كنت تشغّل مضيف وكيل Hermes. `pip install aquaman-hermes` |
| **Docker Sandboxes** | ليست حزمة: مسار منفصل يحتاج فقط إلى `aquaman-proxy`. وكيل Docker الخاص يحقن الأسرار؛ ويوفّرها `aquaman get` من خزنتك، مع قائمة السماح وسجل التدقيق. | إذا كنت تشغّل الوكلاء في Docker Sandboxes. راجع [البدء السريع 5](#5-docker-sandboxes). |
واجهة `aquaman` CLI واحدة تُظهر الأربعة جميعًا: أوامر عليا للخزنة والتدقيق، و`aquaman openclaw ...` لتكامل OpenClaw، و`aquaman coder ...` لتكامل وكيل البرمجة (تفوّض إلى `aquaman-coder` في الخلفية) وكذلك `aquaman hermes ...` لحزمة Hermes بلغة Python.
## البدء السريع
`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` يفعل الشيء نفسه - يثبّت واجهة سطر أوامر الوكيل (proxy CLI)، ويخزّن مفاتيحك، ويثبّت الإضافة (plugin) في `~/.openclaw/extensions/aquaman-plugin/`، ويربط بيانات الاعتماد (مراجع SecretRef على OpenClaw ≥ 2026.6.5، وعنصر نائب auth-profiles.json على الإصدارات الأقدم).
يوجّه `aquaman openclaw setup` كلاً من `models.providers.<svc>.baseUrl` و`channels.telegram.apiRoot` إلى مستمع الاسترجاع (loopback listener) الخاص بالوكيل، لأن ناقل النماذج في OpenClaw وقنواته يبني كل منهما عميل HTTP خاصاً به ويتجاوز معترض fetch. القنوات غير Telegram لا تكشف عن أي تجاوز لنقطة النهاية، لذا تُخزَّن رموزها وتُهاجَر ولكن لا تُحقَن عند الخروج (انظر [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/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، 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
```
**جرّبه بنفسك (لحظة الإدراك في 30 ثانية):** أعد تشغيل Claude Code (أو Codex)، وافتح جلسة جديدة داخل `~/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، سكربتات الاستيراد - أي شيء يحتاجه فعلاً يعمل). أما *الوكيل* - الشيء الذي يقرر أي كود يُشغَّل على جهازك - فلا يرى القيمة أبداً، وبالتالي لا يراها سجل المحادثة، ولا سجلات مزوّد النموذج، ولا أي شخص يلتقط لاحقاً لقطة شاشة لطرفيتك.
**استخدمه من طرفيتك الخاصة أيضاً.** نفس الغلاف يعمل بدون الوكيل. ما عليك سوى `cd` إلى مشروع مغطّى وسبق أمرك:
```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py
```
نفس حقن env، ونفس التنقيح على stdout/stderr. أدرجه في أهداف Makefile، أو أسماء shell المستعارة، أو مشغّلات CI - في أي مكان كنت ستلجأ فيه إلى ملف `.env` بدلاً من ذلك.
عندما يشغّل Claude Code أو Codex أمر shell في `~/code/my-app`، يعيد hook الخاص بـ aquaman كتابة الأمر عبر `updatedInput.command` لتغليفه تحت `aquaman-coder exec`. ذلك الغلاف:
- يحلّ كل مرجع `aquaman://service/key` عبر الوسيط (`POST /broker/resolve` فوق UDS). تُجسَّد بيانات الاعتماد لأمر واحد، لا لعمر الوكيل.
- يمرّر stdout/stderr عبر مُنقّح يضيف نمطًا قائمًا على القيمة لكل قيمة محلولة: **أي سلسلة تم حقنها تُنقَّح، بغض النظر عن شكلها** (رموز Atlassian، أسرار Notion، مفاتيح API الداخلية - لا يحتاج أي منها لمطابقة تنسيق مزوّد معروف). لا تزال الأنماط العامة القائمة على الشكل (sk-ant-، ghp_، sk_live_، AKIA…، JWTs، كتل PEM، ATATT3xF…) تعمل بعد ذلك كدفاع في العمق للأسرار التي يُظهرها الابن والتي لم نحقنها.
- ينظّف عند خروج الأمر.
**صندوق رمل Claude Code:** يحجب Unix sockets افتراضيًا، لذا يضع `aquaman coder setup claude-code` socket الوسيط في القائمة المسموحة على macOS (`sandbox.network.allowUnixSockets`). يتجاهل Linux وWSL2 تلك القائمة، حيث الخيار الوحيد هو `sandbox.network.allowAllUnixSockets: true`، الذي يفتح كل Unix socket للأوامر داخل صندوق الرمل.
**Codex:** وافق على hooks الخاصة بـ aquaman في مراجعة hooks عند بدء تشغيل Codex بعد الإعداد (يتخطى Codex الـ hooks الجديدة حتى تثق بها). يحجب صندوق الرمل الخاص به أيضًا socket الوسيط افتراضيًا؛ يطبع `aquaman coder setup codex` ملف تعريف أذونات `config.toml` الذي يسمح به. لا تستطيع hooks الخاصة بـ Codex إعادة كتابة مخرجات shell، لذا يحدث التنقيح داخل `aquaman-coder exec`. التفاصيل في [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md#codex).
### 4. Hermes (مضيف الوكيل)
Hermes مضيف أجنبي (Python) بلا hook نقل للحقن، لذا تُنجز العزلة من جهة الوسيط: يكشف الوسيط عن مستمع loopback اختياري محمي برمز، ويُوجَّه Hermes إليه عبر متغيرات env الخاصة به.
```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` بالإضافة إلى api_key مؤقت يساوي الرمز المميز. يرسل Hermes الرمز المميز كمفتاح المزوّد الخاص به؛ فيقوم الوكيل بإزالته، وحقن بيانات الاعتماد الحقيقية من الخزنة، ثم التمرير إلى المنبع. مزوّدو 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`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/README.md).
### 5. بيئات Docker Sandboxes المعزولة
تُبقي Docker Sandboxes بيانات الاعتماد خارج البيئة المعزولة بالفعل: إذ يحقنها وكيل (proxy) على جهازك في الطلبات، ويرى الوكيل داخل الآلة الافتراضية قيمة بديلة (placeholder). افتراضياً تأتي القيم من سلسلة مفاتيح نظام التشغيل لديك. وجّهها إلى aquaman بدلاً من ذلك للحصول على كل خزنة يدعمها aquaman، وقائمة المراجع المسموح بها، وسجل تدقيق مقاوم للتلاعب في كل مرة يقرأ فيها sbx سراً.
```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 بتشغيل هذا الأمر من خدمته الخلفية الخاصة، والتي لا تحتوي على `PATH` الخاص بالصدفة (shell) لديك، لذا تقوم الخطوة 5 بتخزين مسارات مطلقة. كرّر الخطوتين 4 و5 لكل خدمة يستخدمها صندوقك الرملي (sandbox).
يعمل الأمر نفسه `aquaman get` في أي مكان تطلب فيه أداة أمرًا يطبع سرًا: Codex (`model_providers.<id>.auth.command`)، وClaude Code (`apiKeyHelper`)، ومزوّدي أسرار exec في OpenClaw، ومصادر أسرار الأوامر في Hermes.
## كيف يعمل
```
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، Keeper، KeePassXC، systemd-creds، ملف مشفّر).
2. **السياسة**: يتحقق الوكيل من قواعد الطريقة + المسار *قبل* لمس بيانات الاعتماد. الطلبات المرفوضة تحصل على `403`، ولا تحصل أبداً على ترويسات مصادقة حقيقية.
3. **الحقن**: يبحث الوكيل عن بيانات الاعتماد ويضيف ترويسة المصادقة قبل التمرير. 25 خدمة مدمجة، 4 أنماط حقن للمصادقة (header، URL-path، HTTP Basic، OAuth)؛ والنمط الخامس، `none`، مخصص للتخزين الساكن فقط (يرفض الوكيل حركة المرور).
4. **الوسيط (coder، مصدر أسرار Hermes، `aquaman get`)**: يقوم `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 لكن ليس إلى واجهة API الإدارية الخاصة بها؛ يمكنه صياغة رسائل بريد إلكتروني لكن ليس إرسالها |
| **سجل التدقيق** | سجلات مسلسلة بتجزئة SHA-256 لكل استخدام لبيانات الاعتماد | تحقيق جنائي بعد الحوادث، كشف التلاعب، أدلة الامتثال |
| **وسيط لكل استدعاء أداة (coder)** | يجسّد `aquaman-coder exec` بيانات الاعتماد لأمر واحد في كل مرة | لا تنتشر بيانات الاعتماد عبر بيئة shell الخاصة بالوكيل |
| **حجب المخرجات (coder)** | يمرّر `aquaman-coder exec` المخرجات القياسية/الخطأ عبر حاجب يمحو كل قيمة حقنها للتو حرفياً - بالإضافة إلى أنماط المزوّدين العامة كخيار احتياطي | حتى بيانات الاعتماد العشوائية بلا شكل محدد لا تصل أبداً إلى سجل الوكيل |
### وسائل النقل والتحكم في الوصول
| المسار | وسيلة النقل | التحكم في الوصول |
|---|---|---|
| وكلاء البرمجة، أي عميل يمكنه الاتصال بمقبس | مقبس Unix `~/.aquaman/proxy.sock` | أذونات الملف (`0600`): فقط العمليات التي تعمل باسمك |
| Hermes (v0.13.0+)، حركة نموذج OpenClaw وTelegram (v0.15.0+) | Loopback TCP `127.0.0.1:<port>` | رمز لكل تثبيت، فحص بزمن ثابت، ربط loopback |
يبني Hermes وOpenClaw كل منهما عميل HTTP خاصاً به ولا يمكنه الاتصال بمقبس، لذا يستخدمان المستمع. كل شيء آخر يستخدم المقبس.
الرمز هو قدرة على الوصول إلى الوكيل المحلي، وليس بيانات اعتماد. يُولَّد لكل تثبيت، ويُخزَّن في `~/.aquaman/config.yaml` (`0600`)، ويرسله المضيف كمفتاح api الخاص بمزوّده. يتحقق منه الوكيل، ويزيله، ويحقن مفتاحك الحقيقي. لا يملك 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
```
- **المسارات هي المسار الكامل لواجهة API الخاصة بالخدمة الأصلية** بعد بادئة الخدمة: واجهة Slack Web API هي `/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 مخزنًا داخليًا. اختر الخلفية التي تشغلها بالفعل؛ تبقى الأسرار هناك، ويقرأها الوكيل في مكانها.
| الخلفية | الأفضل لـ | الإعداد |
|---|---|---|
| `keychain` | التطوير المحلي على macOS (افتراضي) | يعمل مباشرة دون إعداد |
| `encrypted-file` | Linux، WSL2، CI/CD | AES-256-GCM، محمي بكلمة مرور |
| `keepassxc` | مستخدمو KeePass الحاليون | `npm i -g kdbxweb argon2` (نظائر اختيارية منذ v0.14.1)، ثم عيّن `AQUAMAN_KEEPASS_PASSWORD` أو ملف مفتاح |
| `1password` | مشاركة بيانات الاعتماد بين الفريق | `brew install 1password-cli && op signin`. للوكلاء غير المراقبين استخدم [حساب خدمة](https://developer.1password.com/docs/service-accounts/) (`OP_SERVICE_ACCOUNT_TOKEN`) |
| `vault` | إدارة أسرار المؤسسات | عيّن `VAULT_ADDR` + `VAULT_TOKEN` |
| `systemd-creds` | Linux مع systemd ≥ 256 | مدعوم بـ TPM2، لا يتطلب صلاحيات root |
| `bitwarden` | مستخدمو Bitwarden | `bw login && export BW_SESSION=$(bw unlock --raw)` |
| `keeper` | مستخدمو مدير كلمات المرور Keeper (v0.16.0+) | `pip install keepercommander`، سجّل الدخول مرة واحدة باستخدام `keeper shell` وفعّل `this-device persistent-login on`، أنشئ مجلدًا لـ aquaman، ثم `export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>`. تُعنون السجلات بـ `aquaman::<service>::<key>` |
يقوم `aquaman setup` بالكشف التلقائي عن إعداد افتراضي مناسب (macOS → `keychain`؛ Linux → `keychain` إذا كان libsecret متاحًا، وإلا `systemd-creds` إذا كان systemd ≥ 256، وإلا `encrypted-file`).
`encrypted-file` هو الملاذ الأخير لبيئات Linux/CI بدون واجهة رسومية ودون حلقة مفاتيح أصلية. لأمان أفضل على Linux، ثبّت `libsecret-1-dev` (GNOME Keyring)، أو استخدم `systemd-creds` (ربط TPM2)، أو استخدم 1Password/Vault.
### تخزين بيانات الاعتماد مؤقتًا (v0.13.1+)
الخلفيات التي تتحمل تكلفة لكل وصول، مثل `1password` (مطالبة بيومترية لكل قراءة في وضع تطبيق سطح المكتب)، و `bitwarden` (~1-2 ثانية لتشغيل CLI)، و `keeper` (تشغيل Commander الذي يسجل الدخول ويزامن)، و `vault` (رحلة ذهاب وإياب عبر HTTP)، يتم تخزينها مؤقتًا **في ذاكرة الخادم الخفي** لمدة 15 دقيقة افتراضيًا، بحيث تفتح جلسة وكيل مزدحمة الخزنة مرة واحدة لكل نافذة بدلاً من مرة لكل طلب. الخلفيات الأخرى سريعة بالفعل أو تخزن مؤقتًا داخليًا، لذا يكون التخزين المؤقت معطلاً لها افتراضيًا. اضبطه عبر `credentials.cacheTtlSeconds` في `~/.aquaman/config.yaml` (أو `AQUAMAN_CACHE_TTL`)؛ القيمة `0` تعطله.
المقايضة الصريحة: المطالبة البيومترية لكل وصول هي فحص لحضور المستخدم، والتخزين المؤقت يزيل الحضور لكل وصول خلال نافذة TTL. بالنسبة للوكلاء غير المراقبين، لا تتم الإجابة على هذه المطالبة أبدًا، لذا يتم التخلي عن الخزنة لصالح ملف `.env` نصي صريح، وهو أسوأ بشكل قاطع. التخزين المؤقت **لا** ينقل حدود العزل: القيم تعيش فقط في عملية الوكيل (حيث تمر بالفعل في كل طلب)، ولا تُكتب أبدًا على القرص، ويتم إبطالها فورًا عند التدوير عبر `aquaman credentials add`. الكتابات تذهب دائمًا إلى خزنتك. تم اختبارها للتوافق في [`test/compliance/cache-residency.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/cache-residency.test.ts). للحصول على صفر مطالبات مع 1Password، استخدم حساب خدمة مقيّدًا بخزنة `aquaman`؛ سيرشدك `aquaman doctor` إلى هناك.
## الترخيص
MIT - انظر [LICENSE](https://github.com/tech4242/aquaman/blob/main/LICENSE).