🗝️ vault-conductor

وكيل SSH (SSH Agent) يوفّر مفاتيح SSH المخزّنة كأسرار (secrets) في Bitwarden Secrets Manager.

يدعم مصادقة SSH وتوقيع الـ commits في Git.

عرض توضيحي

الميزات

ينفّذ بروتوكول SSH Agent كخادم Unix domain socket، ليعمل كجسر آمن بين عملاء SSH لديك وBitwarden Secrets Manager.

يتميز بـ:

• دورة حياة الوكيل (Agent lifecycle): يعمل كعملية خلفية (daemon) أو عملية أمامية (foreground)، ويستمع على مقبس Unix في /tmp/vc-$(whoami)-ssh-agent.sock
• التحميل الكسول للمفاتيح (Lazy loading): تُجلب مفاتيح SSH من Bitwarden عبر Rust SDK الرسمي فقط عند الطلب، ثم تُخزَّن مؤقتًا في الذاكرة
• عمليات SSH آمنة: عندما يستعلم عملاء SSH عن الهويات أو يطلبون توقيعات، يعالج الوكيل الطلبات باستخدام crate باسم ssh-agent-lib دون كشف المفاتيح الخاصة على القرص مطلقًا
• إدارة العمليات: الوضع الخلفي ينشئ عملية فرعية منفصلة (detached child process)، ويتتبّع PID، ويدعم الإيقاف الآمن (graceful shutdown) عبر SIGTERM/SIGINT
• الأمان: صلاحيات المقبس مثبّتة على 0600 (المالك فقط)، والمفاتيح تعيش في ذاكرة العملية فقط، ويتم استدعاء واجهات Bitwarden API باستخدام machine token مقيّد النطاق يمكنك إعداده بصلاحيات وصول دقيقة للأسرار.

في جوهره، هو مبني بـ Tokio للإدخال/الإخراج غير المتزامن، ويستخدم crate باسم ssh-key للعمليات التشفيرية، ويدعم مفاتيح Ed25519 وRSA بصيغة OpenSSH.

لماذا

وُلد من حاجة شخصية لديّ. ميزة Bitwarden SSH Agent في عميل Bitwarden الرسومي مريحة، لكن ماذا تستخدم إذا كنت تعمل بواجهة CLI فقط على جهاز التطوير لديك؟ كيف تنقل مفتاح SSH بأمان في خط أنابيب CI/CD لتوقيع الـ commits في Git؟ ماذا لو احتجت إلى فتح اتصال SSH من حاوية مؤقتة أو جهاز افتراضي دون نسخ أي مفتاح خاص؟ كيف تتجنب التعامل مع عبارات المرور (passphrases) المخزّنة في سلسلة المفاتيح (keychain) والمرتبطة بجلسات تسجيل الدخول؟

لذا كتبت أداة CLI صغيرة لاسترجاع مفاتيح SSH وإتاحتها دون كشف نظيرتها الخاصة.

ولتجنب جلب خزنة Bitwarden كاملة إلى البيئة، تستخدم Bitwarden Secrets Manager حتى تتمكن من اختيار أي جهاز يمكنه الوصول إلى أي سر، وتعيين صلاحيات token دقيقة.

المتطلبات

• حساب Bitwarden مع تفعيل Bitwarden Secret Manager (يمكنك إنشاؤه وإعداده مجانًا) (الدعم لـ Bitwarden المستضاف ذاتيًا (self-hosted) مخطط له)
• مفتاح SSH بنوعي Ed25519 أو RSA وبصيغة OpenSSH الجديدة، محفوظ كقيمة سر في BWS
  • يجب حفظه متضمنًا -----BEGIN OPENSSH PRIVATE KEY----- و-----END OPENSSH PRIVATE KEY----- strings.
  • ملاحظة: تم تقديم صيغة OpenSSH الجديدة لمفاتيح SSH الخاصة مع OpenSSH 7.8 في 2018.
• macOS أو Linux صدر خلال آخر 5 سنوات

التثبيت

إما باستخدام إحدى الطرق أدناه.

poof

باستخدام poof:

poof install pirafrank/vault-conductor

سكربت بسطر واحد

curl -fsSL https://raw.githubusercontent.com/pirafrank/vault-conductor/main/install.sh | sh

Homebrew

brew tap pirafrank/tap
brew install vault-conductor

يدويًا

أو عن طريق تنزيل أحدث إصدار مستقر يدويًا ووضعه في $PATH.

من المصدر

cargo install --locked --git https://github.com/pirafrank/poof --tag VERSION

الإعداد

يجب عليك توفير:

• BWS_ACCESS_TOKEN، وهو machine token الذي قمت بإعداده أعلاه. اسم متغير البيئة هو نفسه اسم أداة CLI bws من Bitwarden
• BW_SECRET_IDS، قائمة مفصولة بفواصل من UUIDs للأسرار حيث يتم تخزين كل مفتاح خاص. يمكنك قراءة UUID لكل سر في تطبيق BWS على الويب (تحقق تحت اسم السر).
• BW_SERVER_ENDPOINT (اختياري)، نقطة نهاية خادم Bitwarden مخصصة (المضيف فقط، دون البروتوكول). إذا لم يتم توفيرها، فالقيمة الافتراضية هي bitwarden.com. أمثلة صالحة: bitwarden.eu (سحابي) وmyvault.example.com و192.168.1.100 وvault.internal (مستضاف ذاتيًا).

يمكنك تمريرها إما كمتغيرات البيئة أعلاه (مناسبة لإعدادات CI وDevOps) أو عبر ملف إعداد:

# download the example config file at the default path, then customize to your needs
mkdir ~/.config/vault-conductor
curl -sSL https://github.com/pirafrank/vault-conductor/raw/refs/heads/main/config.yaml.example > ~/.config/vault-conductor/config.yaml
chmod 0600 ~/.config/vault-conductor/config.yaml

الاستخدام

# set SSH Agent env var to vault-conductor socket
export SSH_AUTH_SOCK="/tmp/vc-$(whoami)-ssh-agent.sock"

# Start in foreground
# (recommended for first time users to verify config is ok)
vault-conductor start --fg

# Start the agent in background
vault-conductor start

# Stop the background agent
vault-conductor stop

أمر start يدعم أيضًا خيار --config لتوفير مسار إعداد مخصص. متغيرات البيئة دائمًا لها الأولوية على ملف الإعداد.

التصحيح

قد تحتاج أحيانًا إلى تصحيح موقف غريب وتحتاج إلى أكبر قدر ممكن من السجلات (logs). نفّذ ما يلي للتشغيل في المقدمة والحصول على سجلات verbose على sysout:

vault-conductor start --fg -vv

التثبيت كخدمة

يمكنك تثبيتها كخدمة Systemd في مساحة المستخدم (userspace). اقرأ المزيد هنا.

الوثائق

راجع مجلد docs للعثور على مخططات حول كيفية عمل الكود وتنظيمه. اطّلع على سياسة الأمان قبل استخدام مفاتيح RSA أو إعادة توجيه الوكيل (agent forwarding).

ما التالي

• دعم مفاتيح SSH متعددة
• دعم إعدادات Bitwarden المستضافة ذاتيًا
• اختبارات أفضل
• توفير طرق تثبيت أكثر (Homebrew وAUR وnix و.deb و.rpm)
• دعم موفّرين آخرين غير Bitwarden؟

عن الاسم

vault، /voːlt/ - غرفة تحت الأرض، خاصةً لتخزين الأشياء الثمينة

conductor، /kənˈdʌk·tər/ - قائد، شيء ينقل الحرارة أو الكهرباء

وبالامتداد، شيء ينقل مفتاح SSH القيّم خاصتك من خزنة Bitwarden إلى بيئة التطوير لديك.

الترخيص

هذا المشروع مرخّص بموجب رخصة MIT.

راجع ملف LICENSE للتفاصيل.