وثائق

أمان الموصل

ما الذي يقوم به موصل CoRoid على جهازك وما الذي لا يقوم به، والطلبات التي يصدرها، وما الذي صُمم لتحمله، وكيفية التحقق من أن الإصدار مطابق لما بناه المصدر العام.

موصل CoRoid هو البرنامج الذي يسمح لوكلاء الكود على جهازك بأداء العمل لصالح CoRoid (انظر وكلاء الكود على جهازك الخاص). وهو برنامج مفتوح المصدر بموجب رخصة Apache-2.0، ومصدره الكامل متاح على github.com/COROID-AI/coroid-connector. هذه الصفحة موجهة لمن يقرر ما إذا كان يمكن تشغيله على أجهزة مؤسستك.

كيفية تدفق البيانات

آلتك

موصل CoRoid

مفتوح المصدر. يبدأ تشغيل الوكيل لجولة واحدة في مجلد فارغ جديد ويتوقف بعدها.

وكيل البرمجة الخاص بك

الوكيل الذي تستخدمه، مسجل الدخول باسمك، مع إيقاف أدواته الخاصة.

  1. 1يطلب القيام بالعمل. كل طلب يستغرق حتى 25 ثانية؛ ويبلغ الموصل عما يقوله الوكيل كل 3 ثوانٍ.
  2. 2يستدعي أدوات الدور. برمز مميز لهذه الجولة فقط، ويتوقف عن العمل عند انتهاء الجولة.
  3. 3يستفسر من نموذجه. كما لو كان بدون CoRoid. لا يرى CoRoid ذلك تسجيل الدخول أبدًا.

CoRoid

منسق

يوزع عمل الدور على آلة الشخص الذي بدأ المهمة (1).

أدوات الدور

يعمل داخل بيئة العزل الخاصة بالمهمة، حيث يظل كودك محفوظًا (2).

مزود الوكيل

يستجيب لطلبات نموذج الوكيل تحت تسجيل دخولك الخاص، ضمن خطتك (3).

لا شيء يصل إلى الآلة: لا يفتح الموصل أي منفذ، ولا يرسل أيًا من ملفاته، ولا ينفذ أي أمر خاص به.

على الآلة تبقى بيانات تسجيل دخولك للوكيل وما يحتفظ به الوكيل نفسه من معلومات عن الجولة.

تبدأ كل عملية اتصال من الآلة وتخرج عبر بروتوكول HTTPS. يظل المستودع داخل بيئة العزل الخاصة بالمهمة في CoRoid؛ ولا يعمل الوكيل عليه إلا عبر أدوات الدور المخصص.
  • تصدير فقط. لا يفتح الموصل أي منفذ، باستثناء لحظة واحدة أثناء 127.0.0.1 تسجيل الدخول. يطلب العمل من CoRoid عبر بروتوكول HTTPS. كل طلب يظل معلقًا لمدة تصل إلى 25 ثانية ثم يُطلب مرة أخرى، وهذه هي الطريقة التي تعرف بها CoRoid أن الجهاز متصل.
  • يظل الكود الخاص بك داخل CoRoid. لا يتم نسخ المستودع أبدًا إلى الجهاز. أدوات الدور (قراءة ملف، تشغيل الاختبارات، تعديل الكود) تعمل ضمن بيئة العزل المخصصة للمهمة في CoRoid. ما يصل إلى الجهاز هو تعليمات الدور وما تُرجعه تلك الأدوات، مثل محتوى ملف قرأه الوكيل أو نتيجة تشغيل اختبار.
  • طلبات نموذج الوكيل تذهب إلى مزوده، تحت حسابك الشخصي وخطة اشتراكك، كما لو لم يكن CoRoid موجودًا. ما يرسله الوكيل إلى النموذج يشمل ما أرجعته أدوات الدور، لذا فإن اتفاقيتك مع ذلك المزود تغطيه.
  • العمل يذهب فقط إلى الشخص الذي بدأه. لا يعمل دور ما على جهاز إلا إذا حدّدت تكليفته وكيلًا، وكان الشخص الذي بدأ المهمة لديه جهاز متصل في تلك المؤسسة، وسمحت سياسة المؤسسة باستخدام ذلك الوكيل. العمل الذي لم يبدأه أحد، مثل العمليات الآلية، يعمل على نموذجه الخاص.

ما يفعله الموصل

  • تسجيل الدخول باستخدام بروتوكول OAuth 2.1 وPKCE في متصفحك، لنطاق واحدconnector.turns). تظل رمزية الوصول سارية لمدة 15 دقيقة؛ ورمزية التجديد لمدة 30 يومًا، ويتم استبدالها عند كل استخدام. قطع الاتصال في أجهزتك يُلغى كليهما.
  • يحتفظ بتلك الرموز في سلسلة مفاتيح macOS أو خدمة الأسرار في بيئات سطح المكتب لينكس، ويسلمها إلى تلك الأدوات عبر المدخل القياسي، وليس في سطر الأوامر. وفي الحالات التي لا تتوفر فيها هذه الوسائل، تُخزن في ملف يمكنك قراءته فقط. coroid-connector status يوضح مكان وجودها.
  • يخبر CoRoid، مع طلبه الأول، باسم الجهاز ونظام التشغيل الخاص به ونسخته، بالإضافة إلى نسخة كل وكيل وحالته والنماذج التي يقدمها.
  • تنفيذ دورة عمل واحدة: يبدأ تشغيل الوكيل في مجلد فارغ جديد مع إيقاف أدوات الوكيل الخاصة به، ويمنحه مجموعة واحدة من الأدوات (أدوات الدور المخصصة لتلك الدورة)، وينقل ما يقوله، ويرفض أي طلب إذن غير متعلق بتلك الأدوات، ثم يوقفه. بعد ذلك يزيل المجلد.

ما لا يفعله

  • قراءة ملفاتك أو إرسالها، أو تشغيل أمر باسمه. الملف الوحيد الذي يقرأه وليس من صنعه هو إعدادات Cursor، للقيمتين اللتين تحددان ما إذا كان مسموحًا له باستخدام Cursor (انظر القيود)؛ ولا يغادر أي جزء منه الجهاز.
  • السماح للوكيل باستخدام شله أو تحرير الملفات أو البحث على الويب أو خوادم MCP ووصلاته الخاصة. يتم تشغيل كل وكيل باستخدام إعداداته الخاصة لهذا الغرض، وفقًا لنسخ الوكيل التي تم اختبارها؛ أي وكيل من نسخة أخرى يُدرج في القائمة ولا يُستخدم.
  • فتح منفذ يمكن للآخرين الوصول إليه، أو تلقي تعليمات من أي شخص غير CoRoid عبر الاتصال الذي فتحه.
  • تنزيل أي شيء أثناء تشغيله. coroid-connector add يقوم بتثبيت محول الوكيل مرة واحدة، من الحزم التي تحددها ملفات القفل الخاصة بإصداره (كل منها مقيد بنسخة وSHA-512)، مع تعطيل برامج التثبيت.

الطلبات التي يصدرها

إلىعندلأجل ما
CoRoid's API (https://api.coroid.ai)تسجيل الدخول والخروجتسجيل الموصل، تبادل رموزه وتجديدها وإلغاؤها (/oauth/…)
CoRoid's APIأثناء تشغيلهطلب العمل (/connector/v1/poll) وإبلاغ عن دورة عمل (/connector/v1/turns/…/events)
سجل npmفقط أثناء coroid-connector addحزم المحول تتبع أسماء ملفات القفل الخاصة بالإصدار

الوكيل، وليس الموصل، يستدعي أدوات الدور (عنوان تحت /connector/v1/turns/، مع رمزية تلك الدورة) ومزوده الخاص.

ما صُمم لتحمله

إذاثم
طلب شخص آخر توصيل جهاز باسمكيتم الموافقة على ذلك في متصفحك، بعد تسجيل دخولك، ولا يكتمل تسجيل الدخول إلا على الجهاز الذي بدأ العملية (في 127.0.0.1، مع بروتوكول PKCE). اعتمد فقط الموصل الذي بدأته للتو.
تُسرق رموز الوصول الخاصة بالموصل.إنها تصل إلى نطاق واحد فقط: طلب عمل هذا الشخص والإبلاغ عنه. تنتهي صلاحية رمز الوصول خلال 15 دقيقة، ويمنع 'Disconnect' استخدامهما كليهما.
يتم إعادة استخدام رمز الوصول الخاص بكل جولة.يعمل هذا الرمز لجولة واحدة فقط، ويتوقف عن العمل عند انتهاء الجولة.
تطلب الجولة من الوكيل شيئًا آخر.أدوات الوكيل نفسه معطلة، ويرفض الموصل طلبات الأذونات الأخرى. أدوات الدور نفسها الموجودة في نموذج سحابي، مع نفس عمليات ضمان الجودة والمراجعة والقيود والحدود.
الإصدار لا يتطابق مع ما يذكره مصدره.يتم بناء كل إصدار بواسطة إجراءات GitHub من التزام مُوسوم في المستودع العام، ثم يتم التصديق عليه ونشره على npm مع ذكر المنشأ. لا يقبل برنامج Homebrew إصدارًا جديدًا إلا بعد التحقق من تصديقه. يمكنك التحقق من ذلك بنفسك (أدناه).

الحدود

  • يعمل الوكيل نيابةً عنك، بامتيازات مستخدمك على الجهاز. يعتمد تقييده على أدوات CoRoid على مفتاح تفعيل خاص بكل وكيل، ولهذا السبب يستخدم الموصل وكيلًا فقط في الإصدارات التي تم اختباره عليها.
  • ما يحتفظ به الوكيل من بيانات جولة في تخزينه الخاص يعتمد على نوع الوكيل (انظر ما يبقى على جهازك). تحدد سياسة مؤسستك أي الوكلاء يمكن لموظفيها استخدامه (انظر ما تسمح به مؤسستك).
  • يطلب برنامج Cursor إذنًا قبل إجراء عمليات الاسترجاع عبر الويب والبحث والتصفح في إعداداته الافتراضية. يقرأ الموصل اثنين من هذه الإعدادات على الجهاز (وضع الموافقة، وما إذا كان البحث عبر الويب مقبولًا تلقائيًا) ولا يستخدم برنامج Cursor عندما يسمح له بتشغيل هذه الأدوات دون طلب إذن.
  • لم يتم اختبار الموصل على نظام Windows.

التحقق من إصدار

يحتوي كل إصدار على GitHub على الحزمة المنشورة، وملف الموصل، وقائمة مكونات CycloneDX و SHA256SUMS. استبدل <version> بالإصدار الذي تريد التحقق منه.

توقيع سجل حزمة npm وذكر المنشأ:

mkdir check && cd check && npm init -y
npm install @coroid/connector@<version>
npm audit signatures

التصديق، الذي يذكر التزام البناء وسير العمل الذي أنتج الملف:

gh release download v<version> --repo COROID-AI/coroid-connector
gh attestation verify coroid-connector-<version>.tgz --repo COROID-AI/coroid-connector \
  --signer-workflow COROID-AI/coroid-connector/.github/workflows/release.yml

الملف، الذي تم بناؤه بنفسك من المصدر المُوسوم:

git clone https://github.com/COROID-AI/coroid-connector && cd coroid-connector
git checkout v<version> && npm ci && npm run build
shasum -a 256 dist/coroid-connector.mjs   # the same as its line in SHA256SUMS

للإبلاغ عن ثغرة أمنية، استخدم سياسة الأمان الخاصة بالمستودع (نظام الإبلاغ عن الثغرات الخاص بـ GitHub).