Safer Dependencies for Claude Code

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

safer-dependencies هي طبقة أمان لـ Claude Code: تقع بين Claude وملفات البيان الخاصة بك وتشغّل فحوصاتها الأمنية تلقائيًا: يتم رفض عمليات التثبيت المعرّضة للثغرات قبل تشغيلها، ويتم تصحيح أي إصدار محفوف بالمخاطر يُكتب في ملف بيان على القرص فورًا بعد الكتابة. تكتشف وتصلح التبعيات الخطرة — CVEs، والانتحال عبر الأخطاء الإملائية (typosquats)، والحزم المهجورة، ومشاكل عمر الإصدار، بالإضافة إلى فترة تهدئة للإصدارات الجديدة كليًا — عبر npm وPyPI وRubyGems وMaven وGo وRust وPHP (Composer). راجع CAPABILITIES.md لمعرفة ما هو مغطى وما هو غير مغطى بالضبط.

جديد هنا؟ يأخذك GETTING-STARTED.md من الصفر إلى تثبيت يعمل في حوالي خمس دقائق.

الأمان والخصوصية: راجع SECURITY.md (الإفصاح عن الثغرات)، وPRIVACY.md (خروج البيانات، دون تتبع عن بُعد)، وCAPABILITIES.md (ما يدافع عنه الأداة وما لا يدافع عنه).

الترخيص (متاح المصدر — وليس "مفتوح المصدر" وفق OSI): حر في الاستخدام والتعديل لأغراضك الخاصة، بما في ذلك الاستخدام الداخلي للشركات/الأرباح وبناء المنتجات التي تبيعها. يلزم ترخيص مدفوع منفصل فقط لتحقيق الدخل من البرنامج نفسه — أي بيعه، أو تضمينه ضمن منتج أو خدمة تُباع، أو تقديم وظائفه لأطراف ثالثة مقابل رسوم (بما في ذلك الاستضافة/الخدمات السحابية/الواجهات البرمجية). يجب أن يحتفظ إعادة التوزيع والمشتقات بالترخيص وينسب الفضل إلى هذا المشروع. انظر LICENSE (القسم 4 للقيود التجارية)؛ طلبات الترخيص التجاري عبر github.com/robert-auger.

المحتويات

• بدء الاستخدام — من الصفر إلى التثبيت في حوالي خمس دقائق
• ما الذي يفعله
• كيف يعمل
  • الوضع العادي (يدوي)
  • وضع الاعتراض (تلقائي)
  • وضع ما قبل التثبيت (خطاف Bash)
  • وضع ما بعد التثبيت (خطاف Bash)
  • وضع ما بعد الوكيل (زوج خطافات الوكيل)
• ما الذي يطلقها
• ماذا يوجد في هذا المستودع
• الأنظمة البيئية المدعومة
• التثبيت
  • الإعدادات
• مستويات التحذير
• سجل التدقيق
• المتطلبات
• الأسئلة الشائعة

بدء الاستخدام

GETTING-STARTED.md يأخذك من الصفر إلى تثبيت يعمل في حوالي خمس دقائق — المتطلبات الأساسية، والتثبيت التفاعلي، والتحقق. للمرجع الكامل للتثبيت (التثبيت العام/على مستوى المشروع/اليدوي، وخصوصيات Windows، وقائمة السماح بالأذونات، والتحديث، وإلغاء التثبيت)، انظر INSTALLATION.md.

الاستخدام اليومي: بمجرد تثبيت الخطافات، لا يوجد شيء لتشغيله — يعمل safer-dependencies تلقائيًا في الخلفية. عندما يضيف Claude الحزم أو يثبّتها، فإنه يضع علامات على التبعيات الخطرة ويُرقّي الإصدارات المعرّضة للثغرات إلى إصدار آمن في مكانها — ويمنع تثبيت إصدار معروف بثغراته قبل أن يعمل — لذلك يتم اكتشاف الحزم غير الآمنة وتصحيحها دون أن تطلب ذلك. يمكنك أيضًا استدعاؤه مباشرة في أي وقت: "هل [email protected] آمن؟"، "تحقق من إعداد safer-dependencies"، أو "اعرض إحصائيات safer-dependencies".

ما الذي يفعله

عندما يكون Claude على وشك إضافة حزمة إلى مشروعك، يعترض safer-dependencies الأمر ويجري 5 فحوصات:

1. المصدر (Provenance) -- السجل الرسمي، وكشف الانتحال عبر الأخطاء الإملائية (npm/PyPI/RubyGems/Maven/crates.io)، وعمر الحزمة
2. عمر الإصدار -- يختار أحدث إصدار مستقر تم نشره قبل 7+ أيام (نافذة التهدئة)
3. فحص الثغرات -- واجهة OSV API، مع الأدوات الأصلية للنظام البيئي (npm audit وpip-audit وbundle audit) عند توفرها
4. سلامة تثبيت بصمة التجزئة -- بالنسبة لسطور PyPI في requirements.txt التي تحتوي على تثبيتات --hash=sha256:...، يتم التحقق من بصمة التجزئة المُعلنة مقابل بصمات التجزئة المنشورة على PyPI؛ ويؤدي عدم التطابق إلى إصدار WARNING
5. الحزم المهجورة والراكدة -- الحزم المعروفة بأنها مهجورة (مثل paperclip وrequest وpycrypto وgithub.com/dgrijalva/jwt-go) يتم حظرها فورًا مع اقتراح بديل؛ الحزم التي لم تصدر إصدارًا مستقرًا منذ 2+ سنة تحصل على تحذير استشاري STALE:. تتم إزالة الحزم المحظورة من ملف البيان وسيسألك Claude عن كيفية المتابعة؛ الحزم التي تحمل تحذير stale فقط تبقى في مكانها.

إذا تم العثور على مشكلات، يصدر Claude تحذيرات وقد يتراجع إلى إصدار أكثر أمانًا. تُسجَّل جميع الفحوصات في ~/.claude/safer-dependencies-audit-YYYY-MM.log (ملف واحد لكل شهر تقويمي).

كيف يعمل

تعمل المهارة في خمسة أوضاع (ملخصة أدناه؛ الأساس المنطقي الأعمق للتصميم موجود في skills/safer-dependencies.md):

الوضع العادي (يدوي)

عندما يكون Claude على وشك كتابة import، أو إضافة حزمة إلى ملف بيان، أو تحديث ملف قفل، تعمل المهارة داخل جلستك مباشرة:

1. الاستعلام عن سجل الحزم للحصول على الإصدارات المستقرة
2. الاختيار التلقائي لأحدث إصدار تم نشره قبل 7+ أيام (حتمي -- دون حكم LLM)
3. التحقق من الثغرات المعروفة عبر أدوات النظام البيئي وواجهة OSV API
4. التحقق من توقيعات الحزم حيثما كانت متاحة
5. إصدار تحذيرات إذا تم العثور على مشكلات، وتثبيت الإصدار الدقيق
6. تسجيل النتيجة في سجل التدقيق

يتم التعامل مع اختيار الإصدار بواسطة نصوص بايثون المستقلة المرفقة مع المهارة، وليس عبر LLM في تفسير القواعد. يُخرج الأمر SELECTED: <version> ويستخدم Claude هذا الإصدار بالضبط.

وضع الاعتراض (تلقائي)

قم بإعداد .claude/settings.json مع خطاف PostToolUse لتفعيل التحقق التلقائي والشفاف من الحزم:

1. يكتب Claude ملف بيان (مثل package.json) بالإصدار المطلوب أصلاً — ويُحفظ الملف على القرص
2. يتم تشغيل خطاف PostToolUse فور اكتمال الكتابة ويستدعي safer-dependencies-shim.sh
3. يقرأ الشيم الملف، ويحلل الحزم المُعلنة، ويجري جميع الفحوصات الأمنية (الانتحال الإملائي، المهجور، CVE، القِدَم، تثبيت بصمة التجزئة)
4. إذا كانت هناك حاجة إلى تصحيحات، يعيد الشيم كتابة ملف البيان في مكانه بإصدارات آمنة (أو يزيل الإدخالات التي لا تملك إصدارًا آمنًا)
5. يُصدر الشيم إشارات (UPDATED:, BLOCKED:, WARNING:, STALE:, MAJOR-UPDATE-CONFIRM:, REFACTOR-REQUIRED:, REGRESSION:, TYPOSQUAT-CONFIRM:, VERIFY:, CLEAN:) عبر على stdout. تسبق إشارة عندما يُظهر سجل التدقيق أن نفس (الملف، الحزمة) قد تم تصحيحه مسبقًا إلى نفس الهدف الآمن — أي أن وكيلًا فرعيًا أو خطة قديمة أعادت إدخال إصدار معروف بثغراته، وينبغي للمنسق استعادة الإصدار المعتمد سابقًا بدلاً من إعادة اتخاذ قرار الترقية الكبرى.

ملاحظة تصميم — الشكل C (تصحيحي بعد الكتابة): لا يقوم الخطاف بحظر عمليات الكتابة. يصل كل إصدار معرّض للثغرات إلى القرص أولاً ثم يتم تصحيحه تلقائيًا في نفس دورة استخدام الأداة. هذا خيار متعمد بدلاً من تصميم الحظر عبر PreToolUse — راجع FAQ.md للمقايضات.

مثال على إشارة:``` UPDATED: aiohttp 3.8.5 → 3.9.0 (HIGH: 33 CVEs fixed)

يستخدم الوكيل الأب هذه الإشارات لتحديد الكود المتأثر وإعادة هيكلته حسب الحاجة.

### وضع ما قبل التثبيت (خطاف Bash)

قم بتكوين `.claude/settings.json` مع خطاف `PreToolUse:Bash` لتفعيل
التدقيق المسبق لأوامر تثبيت مدير الحزم. يُكمل هذا
(ولا يستبدل) وضع الاعتراض — معًا يشكلان دفاعًا متعدد الطبقات.

1. يحاول Claude استدعاء أداة Bash (مثل `npm install [email protected]`)
2. يُطلق خطاف `PreToolUse` قبل تنفيذ الاستدعاء ويستدعي
   `safer-dependencies-pretooluse-bash.sh`
3. يقوم مُرشِّح مبكر مكتوب بلغة bash نقية بتجاوز الأوامر غير التابعة لمدير الحزم خلال ~115 مللي ثانية
   (دون استدعاء Python)، لذا فإن `git status` / `ls` / `npm test` تتحمل
   تكلفة ضئيلة على المسار الحرج
4. بالنسبة لعمليات تثبيت مدير الحزم المعتمدة (`npm`/`pnpm`/`yarn`
   `install`/`i`/`add`), يقوم المساعد بتقسيم المدخلات عبر `shlex`، ويستخرج كل
   وسيط `pkg@version`، ثم يرسلها عبر POST إلى OSV
5. أي تثبيت محدد (concrete pin) معرّض للخطر ← يُرجع الخطاف
   `permissionDecision: "deny"` مع معرف GHSA-id + CVSS +
   ملخص لكل نتيجة، بالإضافة إلى تلميح لاستدعاء مهارة safer-dependencies
6. لا يتم تشغيل التثبيت أبدًا — لا جلب من الشبكة، ولا نصوص ما بعد التثبيت

**لماذا يوجد هذا بالإضافة إلى وضع الاعتراض:** طبقة ما بعد الكتابة (post-write shim)
لا ترى Bash. `npm install [email protected]` يكتمل تنفيذه (وتُنفَّذ
نصوص ما بعد التثبيت) قبل أن يعمل أي تدقيق؛ بينما `npm install -g
typosquat-pkg` لا يكتب أي ملف بيان للمشروع على الإطلاق. وضع ما قبل التثبيت
يسد هذه الفجوات بنيويًا.

وضع ما قبل التثبيت يرى فقط ما **كتبه** المستخدم (وسائط `pkg@version` على
سطر الأوامر). ولا يمكنه رؤية الشجرة الانتقالية للتبعيات التي سيثبّتها
محلّل التبعيات فعليًا. **وضع ما بعد التثبيت** (أدناه) يدقق في ملف القفل (lockfile) بمجرد
اكتمال التثبيت — الوضعان متكاملان، وليسا مكررين.

**النطاق:** واجهات سطر أوامر مدير الحزم المشمولة هنا تغطي خمسة أنظمة بيئية
(npm/pnpm/yarn/bun/npx/deno، وpip/pip3/pipx/pipenv/uv/uvx/poetry، وgem/bundle،
وgo، وcargo)، بالإضافة إلى Maven عبر وضع الاعتراض (عادةً ما تُعلن تبعيات Maven
في `pom.xml`/`build.gradle`، ولا تُضاف عبر فعل أوامر CLI).

> **فجوة معروفة:** تدعم واجهة Maven CLI التنزيلات المباشرة عبر
> `mvn dependency:get -Dartifact=group:art:version` و`mvn dependency:copy`.
> لا يتعرف هذا الخطاف بعد على تلك الاستدعاءات. إذا كنت تستخدمها
> بانتظام، فإن طبقة ما بعد الكتابة الحالية لا تزال تلتقط أي شيء يصل إلى
> ملف البيان الخاص بك، لكن حماية ما قبل الجلب تنطبق فقط على
> الأنظمة البيئية المذكورة أعلاه. يُتتبع كخطوة لاحقة.

الصيغة المعتمدة لكل نظام بيئي:

| PM | الأفعال | صيغة التثبيت المحدد |
|---|---|---|
| `npm`, `pnpm`, `yarn`, `bun` | `install`, `i`, `add` (بالإضافة إلى `yarn`/`pnpm dlx`، و`bun x`، و`yarn create`) | `[email protected]`, `@scope/[email protected]` |
| `npx` | (بدون فعل — الحزمة هي الوسيط الموضعي الأول) | `[email protected]` |
| `deno` | `add`, `install` | `npm:[email protected]` (مواصفات مسبوقة بـ npm) |
| `pip`, `pip3`, `pipx`, `pipenv`, `uv`, `uvx`, `poetry` | `install` (لـ pip/pip3/pipx/pipenv) / `add` (لـ uv/poetry) / بدون فعل (uvx) | `pkg==1.2.3` (الملحقات `pkg[extra]==X` معالجة أيضًا) |
| `gem`, `bundle` | `install` (لـ gem) / `add` | `-v 1.2.3`, `--version 1.2.3`, `--version=1.2.3` (علامة منفصلة) |
| `go` | `get`, `install` | `[email protected]` (يجب تضمين بادئة `v` وفق وحدات Go) |
| `cargo` | `add`, `install` | `[email protected]` |

تثبيتات النطاق (npm `^4.17`، وpip `>=`، وpoetry `^`/`~`، وGo `@latest`) والإصدارات
غير المحددة تمر إلى وضع الاعتراض بعد التثبيت — حيث تدقق طبقة ما بعد الكتابة في
ما يختاره محلّل التبعيات. إعادة الكتابة التلقائية إلى إصدار آمن مدرجة كخطوة لاحقة.

**وضع الفشل:** fail-open. أي خطأ (غياب Python، أو وميض شبكة،
أو إدخال غير صالح) يخرج بالرمز 0 دون أي مخرجات، مما يسمح لـ bash بالمتابعة.
وضع الاعتراض لا يزال يعمل بعد التثبيت، لذا فإن فشل الفحص المسبق يتراجع
بسلاسة إلى الحماية القائمة.

**مثال على الرفض:**```
safer-dependencies pre-flight audit blocked this install.
Vulnerable pinned version(s) detected:
  - [email protected] → GHSA-35jh-r3h4-6jhm (CVSS:7.4): Command Injection in lodash
Re-run with a patched version, or invoke the safer-dependencies skill
for a recommended pin.

وضع Post-Install (خطاف Bash)

قم بتكوين خطاف PostToolUse:Bash في .claude/settings.json لتمكين تدقيق ما بعد التنفيذ بعد أوامر Bash. يشغّل ثلاث عمليات فحص مستقلة على cwd الخاص بالأمر، كل منها يسد فجوة لا تستطيع الخطافات الأخرى معالجتها:

• الفحص A — ملفات القفل (lockfiles). بعد تنفيذ أمر تثبيت ناجح (npm install, bundle install, poetry install, uv sync, go mod tidy, إلخ)، يدقّق ملفات القفل المعدّلة حديثًا (package-lock.json, Gemfile.lock, poetry.lock, uv.lock, go.sum, yarn.lock, pnpm-lock.yaml, Pipfile.lock). يسد هذا فجوة الثغرات غير المباشرة (transitive-CVE) التي لا يستطيع Pre-Install رؤيتها: كتب المستخدم pkg@version، لكن الحلّال (resolver) ربما يكون قد سحب العشرات من الحزم غير المباشرة التي لم يسمِّها أحد.

كيفية عمل الفحص:

1. يشغّل Claude استدعاء أداة Bash
2. يتم تشغيل خطاف PostToolUse بعد اكتمال الأمر ويستدعي safer-dependencies-posttooluse-bash.sh
3. مرشّح مبكر مكتوب بلغة Bash خالصة يوقف الأوامر التي لا تطابق أي بوابة فحص في ~115 مللي ثانية (نفس اتفاقية المسار السريع كما في Pre-Install)، لذا تتحمّل ls / git / cat تكلفة لا تذكر
4. يجتاز كل فحص cwd باستخدام find -maxdepth 5 (يغطي تخطيطات monorepo؛ ويستثني node_modules و.git و.venv وvenv) بحثًا عن الملفات المعدّلة خلال آخر 60 ثانية — يمكن تجاوز هذه المدة عبر SAFE_DEP_POSTINSTALL_MTIME_WINDOW
5. لكل ملف معدّل حديثًا (الفحصان A/B)، يصنع الخطاف حمولة اصطناعية من نوع PostToolUse:Write ويمررها إلى الـ shim الموجود — فتعمل أدوات تدقيق ملفات القفل وملفات البيان الخاصة بالـ shim دون أي تغيير، دون منطق مكرر

ما يلتقطه ولا يستطيع Pre-Install التقاطه: الثغرات غير المباشرة (transitive vulnerabilities). يمكن لتثبيت bundle install ذي المظهر النظيف أن يسحب [email protected] (CVE-2025-27610) كحزمة غير مباشرة من sinatra — لم يكتب المستخدم rack أبدًا، لذا لا يستطيع Pre-Install رؤيته، لكن Post-Install يقرأ Gemfile.lock المُحلَّل ويُبلّغ عن CVE.

النطاق: لا يعيد الفحص A كتابة الإصدارات المُحلَّلة — فاتفاقية التصحيح التلقائي تنطبق فقط على ملفات البيان التي كتبها Claude مباشرة. بالنسبة للثغرات غير المباشرة (transitive CVEs)، يكون الإصلاح عادةً «تحديث الاعتماد المباشر الذي يملك الاعتماد غير المباشر»، وهو ما يتطلب حكمًا بشريًا. الفحص B يقوم بالتصحيح التلقائي، لأنه يدقّق ملفات البيان عبر نفس مسار الـ shim الذي يستخدمه وضع Intercept Mode. يتخطى الفحص A عندما يكون مستوى فحص transitive مضبوطًا على off (config set checks.transitive off).

وضع الفشل: فشل مفتوح (fail-open)، كما هو الحال مع الخطافات الأخرى. أي خطأ (فقدان الـ shim، حمولة غير صالحة، عدم توفر Python) يخرج برمز 0 بصمت.

مثال على تحذير (WARNING):``` WARNING: [email protected] in lock file has GHSA-29mw-wpgm-hmr9, GHSA-35jh-r3h4-6jhm

### وضع ما بعد الوكيل (زوج خطافات الوكيل)

الأنماط الأربعة أعلاه تعمل فقط لاستدعاءات الأدوات في **جلسة الجذر**. عندما ترسل
جلسة الجذر وكيلًا فرعيًا (عبر أداة `Agent` — تقوم العديد من المهارات وأوامر
الشرطة المائلة بهذا داخليًا)، تتجاوز استدعاءات Write/Edit/Bash الخاصة بالوكيل
الفرعي جميع هذه الأنماط. وضع ما بعد الوكيل هو شبكة الأمان التفاعلية لهذه الفجوة.

1. يعمل خطاف `PreToolUse:Agent` (`safer-dependencies-pretooluse-agent.sh`)
   مباشرة قبل كل إرسال لوكيل، ويلمس ملفًا حارسًا في
   `/tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel` (مع التراجع إلى
   اسم يعتمد على PPID فقط عندما لا يتوفر معرّف جلسة)
2. يعمل الوكيل الفرعي وقد يكتب ملفات بيان أو ملفات قفل
3. يعمل خطاف `PostToolUse:Agent` (`safer-dependencies-posttooluse-agent.sh`)
   بعد عودة استدعاء الوكيل، ويستخدم `find` للعثور على كل ملف بيان وملف قفل أحدث
   من الملف الحارس، ويدقق كلًا منها عبر مسار الواجهة نفسه
4. تظهر النتائج كـ `additionalContext` في الدورة التالية لجلسة الجذر؛ ويتم
   إزالة الملف الحارس

تتم تغطية الوكلاء الفرعيين المتداخلين تلقائيًا — لا يتم تشغيل خطاف
`PostToolUse:Agent` الخاص بجلسة الجذر إلا بعد أن تكون جميع أعمال الوكيل الخارجي
(بما في ذلك أي شيء *أرسله* هو) قد كُتبت على القرص. الفجوة الوحيدة هي تثبيت عام
لا يكتب أي ملف بيان أو ملف قفل (`npm install -g …`): لا يوجد ما يمكن فحصه.
مثل الخطافات الأخرى، يتبع نمط الفشل المفتوح — أي خطأ (فقدان الملف الحارس،
فقدان الواجهة، حمولة غير قابلة للقراءة) يخرج بالكود 0 بصمت. الأساس المنطقي
الكامل للتصميم موجود في `skills/safer-dependencies.md`.

## ما الذي يفعّله

تعمل المهارة تلقائيًا عندما يقوم Claude بما يلي:

**عمليات البيان / التثبيت**
- يضيف أو يحدّث حزمة في `package.json` أو `requirements.txt` أو `Gemfile` أو `pom.xml` أو `build.gradle` أو `Cargo.toml` أو `go.mod` أو أي ملف بيان مدعوم آخر
- يكتب `import` أو `require` أو `use` لحزمة غير معلنة مسبقًا في ملف البيان
- ينشئ أو يحدّث ملف قفل (يفحص الإدخالات الجديدة/المتغيرة فقط)
- يشغّل تثبيت مدير حزم عبر Bash (`npm install`، `bundle install`، `poetry install`، `uv sync`، `go mod tidy`، إلخ) — يدقق وضع ما قبل التثبيت وسائط الأمر، ويدقق وضع ما بعد التثبيت ملف القفل الناتج
- يكتب `Dockerfile` أو سير عمل CI (`.github/workflows/*.yml`، إلخ) يضمّ خطوات تثبيت مثبّتة لمدير الحزم

**أسئلة الاختيار والتوصية**
- مقارنات المكتبات/الأطر: «هل يجب أن أستخدم axios أم node-fetch؟»، «moment أم dayjs؟»، «أيهما أفضل X أم Y؟»
- طلبات التوصية: «ما هو عميل HTTP جيد لـ Python؟»، «أوصِ بمكتبة تسجيل لـ Go»، «ما الحزمة التي تتعامل مع CSV في Node؟»
- اختيار الإصدار: «ما إصدار Django الذي يجب أن أستخدمه؟»، «أحدث إصدار مستقر من Flask؟»

**عبارات النية للاستخدام (قبل الإضافة)**
- «أريد استخدام FastAPI لهذا»، «أفكر في إضافة Celery»، «ننظر إلى Prisma كـ ORM»، «لنستخدم Tailwind»

**أسئلة صحة الحزم والثقة بها**
- «هل ما يزال moment.js مُصانًا؟»، «هل ما تزال هذه الجوهرة نشطة؟»، «هل X مهجور؟»، «هل X وصل لنهاية الدعم؟»، «هل يمكنني الوثوق بهذه الحزمة؟»، «متى تم آخر تحديث لـ faker؟»

**أوامر التهيئة**
- `npx create-react-app`، `npm create vite@latest`، `django-admin startproject`، `rails new`، `cargo new` + `cargo add`، «أطلق مشروع FastAPI جديدًا»

**إضافات الحزم الضمنية (طلبات ميزات تستلزم اعتمادًا جديدًا)**
- «أضف التخزين المؤقت Redis إلى التطبيق»، «اتصل بـ Postgres»، «أضف مصادقة JWT»، «اكتب كودًا لإرسال رسائل البريد الإلكتروني» — تُفعَّل عندما لا توجد حزمة لتلك الإمكانية في ملف البيان بالفعل

**الترحيل والنقل**
- «رحّل من requests إلى httpx»، «انتقل من CRA إلى Vite»، «انقل من moment إلى date-fns» — تدقيق الحزمة الواردة

لا تعمل في الحالات التالية:

- استيرادات المكتبة القياسية (`os`, `fs`, `java.util.*`، إلخ)
- الاعتماديات المعلنة مسبقًا التي لا يجري تغييرها
- النقاش الأكاديمي حول كيفية عمل حزمة داخليًا («اشرح مُنسّق React»، «كيف يعمل حل الوحدات في webpack؟») — مع بقاء أسئلة المقارنة والاختيار قادرة على التفعيل
- تثبيت تطبيقات على مستوى نظام التشغيل، أو بيئات التشغيل، أو إضافات بيئة التطوير (Python نفسه، Docker، Homebrew، إضافات VS Code)

## ماذا يوجد في هذا المستودع

هذه **حزمة مهارة + خطافات**، وليست ملف مهارة واحدًا. يوزّع التثبيت الكامل هذه الأجزاء:

| الملف | الدور |
|---|---|
| `skills/safer-dependencies.md` | **المهارة** (`SKILL.md` بعد التثبيت). تصف إجراءات التدقيق وتتضمن وضع إدارة للتثبيت/الإحصائيات. |
| `skills/safer-dependencies-shim.sh` | خطاف `PostToolUse:Write`/`Edit` — يدقق كتابة ملفات البيان وملفات القفل ويصحح تلقائيًا الإصدارات المعرضة للثغرات في مكانها (وضع الاعتراض). |
| `skills/safer-dependencies-pretooluse-bash.sh` | خطاف `PreToolUse:Bash` — تدقيق OSV أولي لأوامر تثبيت مدير الحزم؛ يرفض التثبيتات المحددة المعرضة للثغرات قبل تشغيل التثبيت (وضع ما قبل التثبيت). |
| `skills/safer-dependencies-posttooluse-bash.sh` | خطاف `PostToolUse:Bash` — تدقيق لاحق بعد أوامر Bash؛ يلتقط ثغرات CVE غير المباشرة في ملفات القفل المكتوبة حديثًا، وملفات البيان المعدّلة عبر `sed`/`jq`/النصوص البرمجية، والبيئة المُحلَّلة لـ `pip install` البسيط (وضع ما بعد التثبيت). |
| `skills/safer-dependencies-pretooluse-agent.sh` + `skills/safer-dependencies-posttooluse-agent.sh` | زوج خطافات `PreToolUse:Agent` + `PostToolUse:Agent` — يسد فجوة تغطية الوكيل الفرعي. تعمل الأنماط 2–4 فقط لاستدعاءات أدوات جلسة الجذر، لذا فإن أي ملف بيان يكتبه وكيل فرعي يتجاوزها. يدقق وضع ما بعد الوكيل كل ما كتبه الوكيل الفرعي بعد عودة كل استدعاء لأداة Agent (وضع ما بعد الوكيل). |
| `skills/scripts/` | مكتبة Python مشتركة (`safedep/`) ونصوص حل مستقلة تستخدمها جميع الخطافات. |
| `skills/scripts/safer_dependencies_manager.py` | وحدة إدارة للتثبيت التفاعلي وإحصائيات الاستخدام والتحقق من الإعداد. |

ملف المهارة وحده ليس كافيًا — بدون الخطافات، يعتمد الاستدعاء التلقائي على قرار Claude بالوصول إلى المهارة. ثبّت القطع الخمس جميعها لتغطية كاملة؛ العديد من المهارات وأوامر الشرطة المائلة ترسل وكلاء فرعيين داخليًا، لذا فإن زوج وضع ما بعد الوكيل مهم حتى لو لم تستدعِ واحدًا صراحةً. (انظر [FAQ.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md#why-a-skill-alone-is-not-sufficient) لمعرفة سبب عدم قدرة المهارة وحدها على ضمان التغطية).

## الأنظمة البيئية المدعومة

| النظام البيئي | ملف البيان | ملف القفل |
|-----------|----------|-----------|
| npm | `package.json` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
| PyPI | `requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py`, `setup.cfg` | `Pipfile.lock`, `poetry.lock`, `uv.lock` |
| RubyGems | `Gemfile`, `*.gemspec` | `Gemfile.lock` |
| Maven | `pom.xml`, `build.gradle`, `libs.versions.toml` | -- |
| Go | `go.mod` | `go.sum` |
| Rust | `Cargo.toml` | `Cargo.lock` |
| PHP (Composer) | `composer.json` | `composer.lock` |

## التثبيت

جديد على المشروع؟ ابدأ بـ **[GETTING-STARTED.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/GETTING-STARTED.md)**. النسخة المختصرة:```bash
git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies
python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

يطلب المثبّت تحديد النطاق (عام global مقابل مشروع project) والخطافات hooks التي تريد تفعيلها، ثم يكتب لك ملف settings.json — بما يشمل إدخالات الخطافات وقائمة السماح (permissions allowlist) التي تتيح لأوامر الفحص الخاصة بالمهارة العمل دون طلب موافقة في كل تدقيق.

كل ما يتعلق بالتثبيت موجود في INSTALLATION.md، وهو المرجع الوحيد لآليات التثبيت: التثبيت اليدوي ملفًا بملف (على المستوى العام ومستوى المشروع)، خصوصيات Windows، خطافات ما بعد الوكيل Post-Agent، قائمة السماح، التحقق من الإعداد، التحديث، التثبيت عند علامة إصدار معينة، وإلغاء التثبيت.

بعد التثبيت، تتم الإدارة اليومية عبر اللغة الطبيعية مع Claude — install safer-dependencies (إعادة التشغيل / تغيير الخطافات)، show safer-dependencies stats، check safer-dependencies setup — أو عبر قائمة /safer-dependencies. التحديث يتم أيضًا داخل الجلسة: /safer-dependencies update يطبّق أحدث إصدار (update --check لتجربة جافة، update --rollback للتراجع)؛ انظر INSTALLATION.md لنموذج الثقة.

ملاحظة حول المنصات: يدعم macOS وLinux وWindows. يتطلب Windows تثبيت Git for Windows (يوفر bash) وPython 3 في PATH — دون الحاجة إلى WSL. الاختبار العملي حتى الآن تركز على macOS وWindows؛ دعم Linux يتم اختباره عبر مصفوفة CI الآلية.

الإعداد

هناك أمران قابلان للإعداد بعد التثبيت:

• قائمة السماح (Permissions allowlist) — تمنح موافقة مسبقة على أوامر الفحص للقراءة فقط الخاصة بالمهارة (قواعد npm audit / bundle audit بالصيغة الدقيقة ونصوص الحل الخاصة بالمهارة) بحيث يتم تنفيذ التدقيق دون طلب موافقة في كل مرة؛ curl لا يحصل أبدًا على موافقة مسبقة، وnpm view / pip-audit اختياريان عبر ملف الراحة (Convenience profile). المثبّت التفاعلي يكتب الإدخالات الأساسية لك؛ التثبيت اليدوي يضيف الكتلة كاملة يدويًا. الكتلة الكاملة والأساس المنطقي: INSTALLATION.md → قائمة السماح.
• سياسة الأمان — نافذة/وضع تبريد عمر الإصدار (release-age cooldown) ومستوى لكل فحص off/warn/block لكل نوع فحص، تُعدَّل باستخدام /safer-dependencies config وتُخزَّن في ~/.config/safer-dependencies/config.toml. المخطط ودلالات المستويات: skills/references/configuration.md.

مستويات التحذير

سجل التدقيق

يتم تسجيل كل فحص في ~/.claude/safer-dependencies-audit-YYYY-MM.log (ملف واحد لكل شهر ميلادي، حيث YYYY-MM هو السنة والشهر بتوقيت UTC) كسطر JSON واحد. يمكن تجاوز المسار الكامل عبر متغير البيئة SAFE_DEP_AUDIT_LOG (عند تعيينه، لا تتم إضافة لاحقة التاريخ). كما يتم تدوير الملفات حسب الحجم عندما تتجاوز SAFE_DEP_LOG_MAX_BYTES (الافتراضي 10 MiB؛ اضبطه على 0 لتعطيل ذلك). اضبط SAFE_DEP_MODEL لتجاوز قيمة النموذج المكتوبة في source.model في كل إدخال — مفيد لمقارنات A/B بين إصدارات النماذج.

جميع الأوضاع الخمسة تضيف إلى نفس الملف. يحمل كل إدخال كتلة source (المخطط schema 2.2) تحدد المكوّن الذي كتبه:

source.model يسجّل نموذج Claude Code النشط في الجلسة (مثل "claude-sonnet-4-6"). وهو موجود في المخطط 2.1+؛ الإدخالات المكتوبة بواسطة تثبيتات أقدم تحذف الحقل. عند غيابه، يتحول أمر الإحصائيات بأمان إلى "unknown".

تصفية حسب source.component باستخدام jq:```bash jq -r '.source.component' audit.log | sort | uniq -c | sort -rn jq -c 'select(.source.component == "bash.pretooluse")' audit.log

Surface every silent fail-open across all hooks:

jq -c 'select(.source.mode == "fail_open") | {component: .source.component, reason: .fail_open.reason, ts}' audit.log

لتسهيل التحليل، اطلب من Claude إحصائيات الاستخدام بدلاً من معالجة السجلات يدويًا:```
"Show safer-dependencies stats for the last month"

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

أشكال الإدخالات (schema 2.2). تتشارك ثلاثة أشكال مميزة في الترويسة نفسها ts / schema / source:

إدخالات التدقيق: يعمل Intercept Mode على تشغيل خط الأنابيب الكامل (الأصل، عمر الإصدار، OSV، المهجورة/المتقادمة، typosquat، التوقيعات)، وبذلك يمكن لجميع المصفوفات أن تمتلئ. وضع Pre-Install Mode يشغّل OSV فقط حاليًا، لذا تكون abandoned / stale / typosquat / signatures فارغة دائمًا. إرسال ما بعد التثبيت (تدقيق lockfile) يكتب تحت shim.posttooluse مع findings المملوءة بسلاسل WARNING: الصادرة عن مدققي lockfile. تحمل مصفوفة notes إشارات معلوماتية NOTE: (مثل manifest-skipped-because-unpinned).

أضاف Schema 2.2 — بشكل إضافي — أربعة حقول إلى إدخالات تدقيق lockfile: lockfile, manifest_ref, relation_summary (تصنيف direct/transitive/unknown لكل حزمة مُعلَّمة مقارنةً بـ manifest الشقيق)، وكتلة policy تسجّل طبقة transitive السارية. هذا التحديث متوافق مع الإصدارات السابقة: قرّاء إدخالات 2.1 يتحملون الحقول الجديدة، ويبقى حقل source.model موجودًا منذ 2.1 فصاعدًا.```json { "ts": "2026-04-19T12:34:56Z", "schema": "2.2", "source": { "component": "shim.posttooluse", "script": "shim.sh", "hook": "PostToolUse:Write", "tool": "Write", "mode": "intercept", "model": "claude-sonnet-4-6" }, "file": "/path/to/project/package.json", "ecosystem": "npm", "checked": ["[email protected]", "[email protected]"], "findings": ["UPDATED: express 4.18.2 → 4.22.1 (HIGH: 1 CVE fixed)"], "abandoned": [], "stale": [], "typosquat": [], "unknown": [], "signatures": [], "notes": [], "clean": ["[email protected]"] }

مثال على وضع ما قبل التثبيت (Bash hook، تم رفض الرقم السري الضعيف):```json
{
  "ts": "2026-04-23T06:56:21Z",
  "schema": "2.2",
  "source": {
    "component": "bash.pretooluse",
    "script": "pretooluse-bash.sh",
    "hook": "PreToolUse:Bash",
    "tool": "Bash",
    "mode": "intercept",
    "model": "claude-sonnet-4-6"
  },
  "file": "bash:npm install [email protected] [email protected]",
  "ecosystem": "npm",
  "checked": ["[email protected]", "[email protected]"],
  "findings": [
    "BLOCKED: [email protected] GHSA-35jh-r3h4-6jhm (CVSS:3.1/...): Command Injection in lodash"
  ],
  "abandoned": [],
  "stale": [],
  "typosquat": [],
  "unknown": [],
  "signatures": [],
  "notes": [],
  "clean": ["[email protected]"]
}

مثال لوضع الفتح عند الفشل (خطاف Bash بعد التثبيت يُستدعى بدون وجود shim مجاور — تثبيت معطوب):```json { "ts": "2026-05-03T07:14:11Z", "schema": "2.2", "source": { "component": "bash.posttooluse", "script": "safer-dependencies-posttooluse-bash.sh", "hook": "PostToolUse", "tool": "Bash", "mode": "fail_open", "model": "claude-sonnet-4-6" }, "fail_open": { "reason": "shim_missing", "detail": "/home/alice/.claude/skills/safer-dependencies" } }

يقول إدخال fail-open: "تم تشغيل هذا الخطاف (hook) لكنه خرج مبكرًا دون إجراء تدقيق لأن شرطًا مسبقًا كان مفقودًا." استخدم مرشّح jq أعلاه (`select(.source.mode == "fail_open")`) لإظهار كل حدث صامت لفقدان الحماية في سجلّك.

عندما يعمل الـ shim في وضع dry-run (`SAFE_DEP_DRY_RUN=1`)، تتضمن الإدخالات أيضًا `"mode": "dry_run"` حتى يمكن للتحليل اللاحق تصفية الاستدعاءات المخصّصة للتدقيق فقط.

## المتطلبات

- Python 3.9+ (تتحقق الخطافات من هذا وتدخل في وضع fail-open على المفسّرات الأقدم)
- `curl` (لاستدعاءات واجهة برمجة تطبيقات السجل registry API وفحوصات الثغرات الأمنية OSV)
- أدوات الأنظمة البيئية (اختيارية، تلجأ المهارة إلى OSV API إذا كانت مفقودة):
  - `npm` لحزم npm
  - `pip-audit` لحزم Python
  - `bundle` لحزم Ruby
  - `dependency-check` لحزم Java

## الأسئلة الشائعة

الأساس المنطقي لقرارات التصميم (لماذا `PostToolUse` بدلًا من `PreToolUse`، ولماذا لا تُتحقَّق التوقيعات، ولماذا تُكرَّر السكربتات والـ shim، ومزالق تحميل المهارة، وما إلى ذلك) موثّق في [`FAQ.md`](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md).