DEV Community

Cover image for Bitwarden Agent Access: كيفية مشاركة بيانات اعتماد الخزنة بشكل آمن مع وكلاء ترميز الذكاء الاصطناعي
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

Bitwarden Agent Access: كيفية مشاركة بيانات اعتماد الخزنة بشكل آمن مع وكلاء ترميز الذكاء الاصطناعي

إذا كنت تستخدم Claude Code أو Codex أو Cursor مع أي شيء يتصل بواجهة برمجة تطبيقات حقيقية، فالمشكلة العملية هي بيانات الاعتماد: الوكيل يحتاجها، ومدير كلمات المرور لا يريد تسريبها. لصق مفتاح API داخل المحادثة يضعه في سياق النموذج. وضعه في ملف .env يجعله قابلًا للقراءة من أي أمر يشغله الوكيل. الحل الأفضل هو إعطاء الوكيل أقل قدر ممكن من الأسرار، وفي وقت التشغيل فقط.

جرّب Apidog اليوم

مشروع Bitwarden مفتوح المصدر، Agent Access، يحاول حل هذه الفجوة عمليًا. يوفر بروتوكولًا لمشاركة بيانات الاعتماد، وواجهة سطر أوامر باسم aac، وحزم SDK بلغة Rust وPython لبناء نفق مشفر بين مدير كلمات المرور وعملية بعيدة مثل وكيل AI، أو مهمة CI، أو سكريبت محلي.

في هذا الدليل ستتعلم كيف تثبت Agent Access، تستخدم aac connect لجلب بيانات اعتماد محددة النطاق، وتستخدم aac run لحقن الأسرار في بيئة عملية فرعية بدون كشفها للوكيل. هذا يكمل أنماط النظافة الأمنية الموضحة في كيفية تأمين بيانات اعتماد واجهة برمجة تطبيقات وكيل الذكاء الاصطناعي.

ما هو Agent Access؟

Agent Access هو بروتوكول مفتوح وتطبيق مرجعي من Bitwarden، لكنه مصمم بحيث يمكن لأي مدير كلمات مرور تبنيه. يعمل عبر طرفين:

  • Provider: الجهاز أو الخدمة التي تمتلك الوصول إلى القبو.
  • Consumer: الوكيل، السكريبت، أو مهمة CI التي تحتاج إلى بيانات اعتماد محددة.

تستخدم أداة aac نفقًا مشفرًا من طرف إلى طرف عبر Noise Protocol. يطلب المستهلك بيانات اعتماد حسب النطاق أو معرف عنصر القبو، ويقرر المزود ما الذي يُرجع. المستهلك لا يرى القبو بالكامل، والمزود لا يحتاج لمعرفة ما الذي ستفعله العملية بالسر بعد استلامه.

Agent Access architecture

المشروع في معاينة مبكرة. يوضح README أن واجهات API والبروتوكول قابلة للتغيير، وأنه لا يُنصح بإدخال بيانات الاعتماد الحساسة مباشرة في LLMs أو وكلاء الذكاء الاصطناعي.

النمط العملي الموصى به هو استخدام aac run: اجلب السر وقت التشغيل، احقنه كمتغير بيئة في عملية فرعية، ولا تعرضه في stdout أو في سياق النموذج.

لماذا هذا مهم؟

وكلاء البرمجة لم يعودوا يكتبون كودًا فقط. Claude Code وCodex وCursor يمكنهم قراءة المستودع، تشغيل الاختبارات، استدعاء APIs، وبدء عمليات نشر. كل خطوة قد تحتاج إلى بيانات اعتماد.

حادثة مفاتيح API المكشوفة في Postman أوضحت أن إدارة الأسرار صعبة حتى بدون وكلاء. مع الوكلاء، يصبح الخطر أكبر لأن الأداة تستطيع تشغيل أوامر وقراءة ملفات وإرسال مخرجات.

القاعدة العملية:

لا تثق بالوكيل أكثر. أعطه أقل.

Agent Access يطبق ذلك عبر:

  • بيانات اعتماد محددة النطاق.
  • تشفير أثناء النقل.
  • جلب في وقت التشغيل.
  • عدم حفظ الأسرار على القرص افتراضيًا.
  • عزل السر داخل عملية فرعية عند استخدام aac run.

للمقارنة مع أدوات إدارة المفاتيح الأخرى، راجع أدوات إدارة مفاتيح API.

التثبيت

اختر الحزمة المناسبة لنظامك.

macOS Apple Silicon 

curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-aarch64.tar.gz | tar xz
sudo mv aac /usr/local/bin/
Enter fullscreen mode Exit fullscreen mode

macOS Intel 

curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/
Enter fullscreen mode Exit fullscreen mode

Linux x86_64 

curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-linux-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/
Enter fullscreen mode Exit fullscreen mode

Windows x86_64

نزّل aac-windows-x86_64.zip من صفحة الإصدارات، ثم استخرجه إلى مجلد موجود في متغير PATH.

تحقق من التثبيت:

aac --help
Enter fullscreen mode Exit fullscreen mode

إذا كان Bitwarden CLI (bw) موجودًا في PATH، فسيستخدمه aac كمزود افتراضي. للتجربة بدون Bitwarden، استخدم المزود التجريبي:

aac --provider example --help
Enter fullscreen mode Exit fullscreen mode

بدء سريع: الإقران وجلب بيانات الاعتماد

شغّل المستمع على الجهاز الذي لديه الوصول إلى القبو، غالبًا جهازك المحلي:

aac listen
Enter fullscreen mode Exit fullscreen mode

سيطبع الأمر رمز إقران. من جهة المستهلك، نفّذ:

aac connect --token <pairing-token> --domain github.com --output json
Enter fullscreen mode Exit fullscreen mode

الناتج سيكون مشابهًا:

{
  "credential": {
    "notes": null,
    "password": "alligator5",
    "totp": null,
    "uri": "https://github.com",
    "username": "example"
  },
  "domain": "github.com",
  "success": true
}
Enter fullscreen mode Exit fullscreen mode

يمكنك أيضًا الجلب حسب معرف عنصر القبو بدل النطاق:

aac connect --id <vault-item-id> --output json
Enter fullscreen mode Exit fullscreen mode

ملاحظات مهمة:

  • --id و--domain لا يُستخدمان معًا.
  • إذا كان عنصر القبو يحتوي على TOTP، فسيظهر ضمن الحمولة.
  • --output json مناسب للسكريبتات التي تريد تحليل الناتج مباشرة.

مثال بسيط باستخدام jq:

PASSWORD=$(aac connect --domain github.com --output json | jq -r '.credential.password')
Enter fullscreen mode Exit fullscreen mode

لكن انتبه: هذا النمط قد يضع السر في متغير داخل shell. في معظم حالات الوكلاء، استخدم aac run بدلًا من ذلك.

استخدام aac run لحقن الأسرار في البيئة

aac run هو النمط الأكثر أمانًا مع وكلاء AI. بدل طباعة السر، يشغل عملية فرعية ويحقن القيم المطلوبة كمتغيرات بيئة.

حقن حقول محددة 

aac run --domain example.com \
  --env DB_PASSWORD=password \
  --env DB_USER=username \
  -- psql
Enter fullscreen mode Exit fullscreen mode

في هذا المثال:

  • قيمة حقل password تصبح DB_PASSWORD.
  • قيمة حقل username تصبح DB_USER.
  • العملية الفرعية psql فقط هي التي تستقبل المتغيرات.

حقن كل الحقول 

aac run --domain example.com --env-all -- ./deploy.sh
Enter fullscreen mode Exit fullscreen mode

سيتم حقن الحقول المتاحة ببادئة افتراضية مثل AAC_.

دمج --env-all مع أسماء مخصصة 

aac run --domain example.com \
  --env-all \
  --env CUSTOM_PW=password \
  -- ./deploy.sh
Enter fullscreen mode Exit fullscreen mode

الحقول المتاحة:

  • username
  • password
  • totp
  • uri
  • notes
  • domain
  • credential_id

نمط عملي مع سكريبت نشر

بدل أن تجعل Claude Code أو Codex يعرف المفتاح، اجعل الوكيل يستدعي سكريبتًا مغلفًا بـ aac run.

# deploy.sh
#!/usr/bin/env bash
set -euo pipefail

aac run --domain api.example.com \
  --env API_TOKEN=password \
  -- ./run-deploy.sh
Enter fullscreen mode Exit fullscreen mode

ثم داخل run-deploy.sh:

#!/usr/bin/env bash
set -euo pipefail

curl -H "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/deploy
Enter fullscreen mode Exit fullscreen mode

بهذا الشكل:

  • الوكيل يرى الأمر ./deploy.sh.
  • السر لا يظهر في المحادثة.
  • السر لا يُكتب إلى ملف.
  • السر موجود فقط داخل بيئة العملية الفرعية.

هذا يطبق نفس مبدأ العزل الموضح في كيفية تأمين بيانات اعتماد واجهة برمجة تطبيقات وكيل الذكاء الاصطناعي، لكن بأداة قابلة للتنفيذ.

استخدام SDKs بلغة Python وRust

إذا كنت تريد تضمين Agent Access داخل تطبيقك بدل استدعاء CLI، يمكنك استخدام SDK.

Python 

from agent_access import RemoteClient

client = RemoteClient("python-remote")
client.connect(token="ABC-DEF-GHI")

cred = client.request_credential("example.com")
print(cred.username, cred.password)

client.close()
Enter fullscreen mode Exit fullscreen mode

وحدة Python مبنية فوق PyO3، لذلك يبقى تنفيذ البروتوكول الأساسي في Rust مع توفير واجهة Python.

Rust

توفر حزمة Rust واجهة RemoteClient كمكتبة مباشرة. التطبيقات المرجعية موجودة في المستودع تحت:

examples/rust-remote/
Enter fullscreen mode Exit fullscreen mode

استخدم Rust SDK عندما تبني:

  • CLI مخصصًا.
  • build runner.
  • خدمة داخلية توزعها كثنائي compiled.
  • أداة تحتاج إلى دمج Agent Access بدون shell wrapper.

إذا كان فريقك يستخدم أدوات مثل HashiCorp Vault أو Azure Key Vault، فاعتبر Agent Access طبقة مناسبة أكثر لحالات أجهزة المطورين ومشغلات CI، وليس بديلًا كاملًا لخزائن الأسرار المؤسسية.

التكامل مع وكلاء برمجة الذكاء الاصطناعي

Claude Code

اجعل Claude Code يستدعي سكريبتًا بدل التعامل مع السر مباشرة:

# deploy.sh
#!/usr/bin/env bash
set -euo pipefail

aac run --domain prod.example.com --env-all -- ./run-deploy.sh
Enter fullscreen mode Exit fullscreen mode

أضف السكريبت إلى مشروعك، ثم وجّه سير العمل إليه. الوكيل ينفذ:

./deploy.sh
Enter fullscreen mode Exit fullscreen mode

ولا يرى بيانات الاعتماد.

يمتد نفس النمط إلى CI مع Claude Code GitHub Actions: ثبّت aac في runner، اربطه بمزود القبو، واجعل خطوات النشر أو الاختبار تعمل عبر aac run.

OpenAI Codex

في Codex CLI، يرى النموذج الأوامر التي سيستدعيها. لذلك لا تمرر المفتاح داخل الأمر. استخدم wrapper:

# test-api.sh
#!/usr/bin/env bash
set -euo pipefail

aac run --domain staging.example.com \
  --env API_KEY=password \
  -- npm run test:api
Enter fullscreen mode Exit fullscreen mode

بهذا يبقى المفتاح خارج سياق النموذج. للمزيد حول استخدام Codex في سيناريوهات أوسع، راجع Codex من هاتفك.

Cursor

مع أوامر الطرفية وComposer في Cursor، استخدم نفس السكريبتات المغلفة بـ aac run. غالبًا سيكون المستمع والمستهلك على نفس الجهاز لأن Cursor يركز على التحرير المحلي.

مثال:

aac run --domain dev.example.com \
  --env DATABASE_URL=uri \
  -- npm run dev
Enter fullscreen mode Exit fullscreen mode

OpenClaw

يوفر Agent Access مهارة OpenClaw رسمية جاهزة للاستخدام، وملف SKILL.md موجود في المستودع. إذا كنت تستخدم مهارات على نمط OpenClaw، فهذا هو التكامل الأكثر مباشرة: المهارة تعرف البروتوكول، تجلب بيانات الاعتماد، ثم تمررها للأداة التابعة.

راجع أيضًا دليل مفاتيح API لـ OpenClaw.

نموذج الأمان

ثلاث نقاط يجب فهمها قبل الاعتماد على Agent Access:

  1. تشفير من طرف إلى طرف عبر Noise

    الاتصال بين المستهلك والمزود مشفر باستخدام Noise Protocol Framework، وهي نفس عائلة المصافحة التي تستخدمها أنظمة مثل WireGuard وSignal.

  2. بيانات اعتماد محددة النطاق

    المستهلك يطلب نطاقًا واحدًا أو عنصر قبو واحدًا. لا يحصل على إمكانية تعداد القبو بالكامل.

  3. لا أسرار على قرص المستهلك افتراضيًا

    مع aac run، تُمرر الأسرار كمتغيرات بيئة إلى عملية فرعية. لا تُكتب إلى ملف، ولا تظهر في stdout، ولا تُسجل في shell history إذا لم تطبعها أنت.

ما لا يحميك منه Agent Access:

  • عملية مستهلك مخترقة. إذا كانت العملية التي استلمت السر ضارة، يمكنها تسريبه.
  • مزود مخترق. إذا كان القبو نفسه مخترقًا، هذه الطبقة لا تكفي.
  • لصق الأسرار يدويًا في نافذة LLM. البروتوكول لا يستطيع حمايتك إذا نسخت المفتاح إلى المحادثة.

نمط CI عملي: الوكيل يكتب، Apidog يختبر

نمط العمل المفيد لمعظم الفرق:

  1. الوكيل يكتب الكود

    Claude Code أو Codex أو Cursor يفتح PR يضيف استدعاء API أو يغير عقدًا.

  2. CI يشغل الاختبارات

    runner يستخدم aac run لجلب مفتاح API محدد النطاق وتشغيل اختبارات التكامل.

  3. Apidog يتحقق من العقد

    Apidog يشغل اختبارات OpenAPI أو اختبارات العقد كخطوة منفصلة في CI، أيضًا عبر aac run.

مثال مبسط:

aac run --domain staging-api.example.com \
  --env API_TOKEN=password \
  -- npm run test:contract
Enter fullscreen mode Exit fullscreen mode

النتيجة:

  • الوكيل يشحن الكود.
  • اختبارات API تتحقق من العقد.
  • السر لا يظهر في سياق النموذج.
  • المفتاح لا يُحفظ في المستودع.

للتوسع في هذا النمط، راجع كيفية اختبار وكلاء الذكاء الاصطناعي الذين يستدعون واجهات برمجة التطبيقات الخاصة بك.

القيود والتحذيرات

  • المشروع في معاينة مبكرة

    واجهات API والبروتوكول قابلة للتغيير. لا تبنِ سير عمل إنتاجيًا حساسًا بدون توقع تغييرات لاحقة.

  • يعتمد افتراضيًا على Bitwarden CLI

    ثبّت Bitwarden CLI إذا أردت استخدام قبو Bitwarden. للتجارب، استخدم --provider example.

  • لا يوجد ملف إعداد ثابت حتى الآن

    يتم التحكم في السلوك عبر flags، لذلك يفضل تغليف الاستدعاءات المتكررة داخل سكريبتات.

  • لا تطبع الأسرار

    حتى مع aac run، يمكن لسكريبتك أن يطبع المتغيرات بالخطأ. تجنب set -x في سكريبتات تحتوي على أسرار.

  • لا تلصق الأسرار في Prompts

    إذا وضعت المفتاح يدويًا في محادثة LLM، فلن ينقذك أي بروتوكول.

أسئلة شائعة

هل Agent Access مجاني؟

نعم. CLI وSDKs والبروتوكول مفتوحة المصدر ضمن منظمة Bitwarden على GitHub. إذا استخدمت Bitwarden كقبو، فتنطبق عليك شروط وتسعير Bitwarden نفسه.

هل يعمل مع مديري كلمات مرور غير Bitwarden؟

البروتوكول مصمم ليكون محايدًا للموردين. التطبيق المرجعي يدعم Bitwarden ومزودًا تجريبيًا. يمكن لموردين آخرين إضافة مزوداتهم لاحقًا.

هل يمكن استخدامه بدون مدير كلمات مرور؟

للاختبار نعم:

aac connect --provider example --domain test.com --output json
Enter fullscreen mode Exit fullscreen mode

للإنتاج، تحتاج إلى مزود حقيقي مثل Bitwarden.

هل يحتاج المستهلك إلى الشبكة؟

نعم. المستهلك يحتاج إلى الوصول إلى مستمع المزود. إذا كان الاثنان على نفس الجهاز، يمكن استخدام إعداد محلي.

كيف يختلف عن ملف .env؟

ملف .env موجود على القرص، ويمكن إيداعه بالخطأ في المستودع، ويمكن لأي أمر يشغله الوكيل قراءته. أما aac run فيحقن السر في ذاكرة عملية فرعية فقط، ويختفي عند خروج العملية.

هل يحل محل HashiCorp Vault أو AWS Secrets Manager؟

لا. الخزائن المؤسسية ما زالت مناسبة للأسرار بين الخدمات وعلى نطاق واسع. Agent Access يعالج فجوة مختلفة: أجهزة المطورين، وكلاء AI، ومشغلات CI التي تحتاج إلى سر محدد في وقت التشغيل.

هل ستدمجه Anthropic أو OpenAI مباشرة؟

لم يُعلن عن دعم مباشر. نموذج التكامل الحالي هو تغليف أوامرك وسكريبتاتك باستخدام aac run.

أين أبلغ عن الأخطاء أو أساهم؟

استخدم مستودع GitHub. المشكلات، طلبات السحب، ومناقشات البروتوكول تتم هناك.

جرّبه الآن

ابدأ بأصغر حلقة ممكنة:

aac listen
Enter fullscreen mode Exit fullscreen mode

ثم من طرفية أخرى:

aac connect --provider example --domain test.com --output json
Enter fullscreen mode Exit fullscreen mode

بعد التأكد من عودة JSON، انتقل إلى Bitwarden CLI، ثم غلّف سكريبتًا حقيقيًا:

aac run --domain api.example.com \
  --env API_KEY=password \
  -- ./run-tests.sh
Enter fullscreen mode Exit fullscreen mode

استخدم Agent Access لحماية الأسرار، وApidog لاختبار واجهات API والعقود. بهذه البنية: القبو يحتفظ بالسر، Apidog يتحقق من API، والوكيل يكتب الكود بدون أن يرى بيانات الاعتماد.

Top comments (0)