trustlock

وحدة تحكم لقبول التبعيات أصيلة مع Git. تقوم بتقييم إشارات الثقة عند كل تغيير تابع.

كيف يعمل

يعمل trustlock كـ خطاف ما قبل الالتزام في Git (وضع استشاري) وفحص CI (وضع إجباري):

• استشاري (قبل الالتزام): يحذر من المخالفات، يخرج برمز 0، ويحدث خط الأساس الموثوق عند قبول جميع الحزم.
• إجباري (--enforce): يمنع المخالفات، يخرج برمز 1، ولا يحدث خط الأساس أبدًا.

إشارات الثقة التي يتم تقييمها لكل حزمة:

• فترة التهدئة — المدة منذ نشر الإصدار إلى السجل
• الأصل — ما إذا كانت الحزمة تحتوي على شهادات SLSA
• التثبيت — ما إذا كان ملف القفل يستخدم إصدارات دقيقة
• نصوص التثبيت — ما إذا كانت الحزمة تشغّل نصوصًا أثناء التثبيت
• المصادر — ما إذا كانت الحزمة تأتي من السجل، رابط Git، مسار محلي، أو رابط URL
• التبعيات الجديدة — الإضافات الأولى للمشروع
• المفاجأة المتعدية — قفزة غير متوقعة في عدد التبعيات المتعدية
• تغير الناشر — ما إذا كانت هوية ناشر الحزمة تغيرت بين الإصدارات

التثبيت

npm install -g trustlock

يتطلب Node.js >= 18.3.

ملفات القفل المدعومة

بداية سريعة

سير العمل 1 — إعداد مشروع

# 1. تهيئة trustlock في مشروعك
trustlock init

# 2. تثبيت خطاف ما قبل الالتزام في Git
trustlock install-hook

# 3. اختياري: مراجعة وضع التبعيات الحالي
trustlock audit

بعد init، يقوم trustlock بإنشاء:

• .trustlockrc.json — إعدادات السياسة
• .trustlock/baseline.json — لقطة للتبعيات الموثوقة
• .trustlock/approvals.json — سجلات الموافقات
• .trustlock/.cache/ — ذاكرة تخزين مؤقت للسجل (مهملة في gitignore)

قم بتضمين .trustlockrc.json و .trustlock/baseline.json إلى المستودع الخاص بك.

سير العمل 2 — فحص وقبول تحديث تبعية

# تشغيل تثبيت التبعيات كالمعتاد
npm install [email protected]

# يقوم trustlock check بالتشغيل تلقائيًا عبر خطاف ما قبل الالتزام.
# للتشغيل يدويًا:
trustlock check

# الإخراج عند قبول جميع الحزم:
# ✔ [email protected] — مقبولة

عندما تنجح جميع الحزم، يقوم trustlock check بتحديث خط الأساس تلقائيًا (وضع استشاري فقط) ويخرج برمز 0.

سير العمل 3 — التعامل مع تبعية محظورة

# حزمة جديدة تفشل في قاعدة فترة التهدئة:
trustlock check
# ✖ [email protected] — محظورة
#   exposure:cooldown  نُشرت منذ ساعتين (السياسة تتطلب 72 ساعة)
#   قم بالتشغيل للموافقة: trustlock approve [email protected] --override cooldown --reason "..." --expires 7d

# الموافقة على التجاوز، ثم إعادة الفحص:
trustlock approve [email protected] \
  --override cooldown \
  --reason "مطلوب للميزة X؛ تم التحقق من الأمان بواسطة مراجعة الفريق" \
  --expires 7d

trustlock check
# ✔ [email protected] — مقبولة مع موافقة

سير العمل 4 — مقارنة وضع التبعيات عبر المشاريع

# كشف انحراف الإصدارات وتناقضات الأصل عبر حزم المستودع الأحادي
trustlock audit --compare packages/frontend packages/backend packages/shared

الأوامر

ملفات تعريف السياسة

يحتوي trustlock على ملفين تعريفيين مدمجين يمكن اختيارهما باستخدام --profile:

# استخدام الملف التعريفي الصارم في CI
trustlock check --enforce --profile strict

وراثة سياسة المنظمة

يمكن للفرق مركزية السياسة في رابط URL مشترك وتوسيعها لكل مستودع:

{
  "extends": "https://policy.example.com/trustlockrc.json",
  "cooldown_hours": 96
}

يمكن لتكوينات المستودع فقط تشديد سياسة المنظمة — حيث يمنع الحد الأدنى التنفيذي المستودعات من تقليل العتبات التي تفرضها المنظمة.

التوثيق

• USAGE.md — مرجع كامل للأوامر، جميع العلامات، رموز الخروج، رسائل الخطأ
• POLICY-REFERENCE.md — كل خيار في .trustlockrc.json
• ARCHITECTURE.md — قرارات التصميم وخريطة الوحدات
• examples/ — أمثلة على التكوين وسير عمل CI

التكامل مع CI

أضف trustlock إلى خط أنابيب CI الخاص بك:

# GitHub Actions — انظر examples/ci/github-actions.yml
- run: npx trustlock check --enforce

انظر examples/ لتكوينات GitHub Actions وLefthook وHusky.

أين يقع trustlock في الجدول الزمني

يقوم trustlock بتقييم تغييرات ملف القفل في وقت الالتزام. لا يعترض أو يعزل تثبيت npm. إذا قامت حزمة ضارة بتشغيل نص ما بعد التثبيت، فإن ذلك يتم قبل أن يراه trustlock. يمنع trustlock إلتزام ملف القفل المخترق ودمجه، مما يحصر نصف قطر الانفجار على جهاز مطور واحد بدلاً من الفريق بأكمله والإنتاج. لحظر النصوص أثناء التثبيت، استخدم --ignore-scripts أو عناصر التحكم الافتراضية في دورة حياة pnpm.

ما لا يفعله trustlock

• ليس ماسح ضوئي للبرامج الضارة — لا يفحص trustlock كود المصدر للحزم أو يكتشف تواقيع معروفة ضارة. استخدم ماسحًا مخصصًا لذلك.
• ليس عازلًا أثناء التثبيت — لا يعترض trustlock تثبيت npm. استخدم --ignore-scripts لذلك.
• ليس متتبعًا لثغرات CVE — استخدم npm audit أو Snyk لقواعد بيانات الثغرات.
• ليس فاحص تراخيص — استخدم license-checker أو ما شابه.
• ليس بديلاً عن trustPolicy في pnpm أو min-release-age في npm — تلك أدوات تحكم من جانب الخادم تفرضها السجلات. trustlock هو بوابة قبول من جانب العميل عند حدود المستودع.

حول

تم بناء trustlock من الإحباط من سلبية سلسلة أدوات Node.js القياسية تجاه ما يتم سحبه فعليًا إلى مشروع. يقوم npm install بجلب أي شيء — حزمة نُشرت قبل دقيقتين، واحدة تشغل نصوصًا عشوائية أثناء التثبيت، واحدة تحولت من كرة مضغوطة في السجل إلى رابط Git بين ليلة وضحاها — والتغذية الراجعة الوحيدة التي تحصل عليها هي فرق ملف القفل.

نموذج التهديد الذي يعالجه trustlock ضيق لكنه حقيقي: الفترة الزمنية بين نشر إصدار ضار وسحبه أو وضع علامة عليه. تعمل ماسحات الثغرات بعد وقوع الحدث. يعمل trustlock عند نقطة القبول، قبل أن يصل أي شيء إلى مستودعك أو CI الخاص بك.

التصميم بسيط عمدًا. لا يحتوي trustlock على أي تبعيات وقت تشغيل — هو بحد ذاته أداة خالية من مخاطر سلسلة التوريد. لا يحل محل ماسح الثغرات أو تدقيق التبعيات؛ إنه يفرض استمرارية الثقة. بمجرد أن يكون الإصدار في خط الأساس الخاص بك، يتم الوثوق به. أي شيء جديد يجب أن يكسب القبول وفقًا للسياسة التي تعلنها.

سير عمل الموافقة موجود للفرق التي تحتاج إلى مخرج طوارئ دون فقدان قابلية التدقيق. كل تجاوز موقّع زمنيًا، ومقيّد بقواعد محددة، وينتهي. clean-approvals هو أمر من الدرجة الأولى، وليس فكرة لاحقة.