المحتويات

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

البدء

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

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

ما الذي يفعله

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

1. المصدر — السجل الرسمي، كشف انتحال الأسماء (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) يتم حظرها بشدة فورًا مع اقتراح بديل؛ الحزم التي لا تحتوي على إصدار مستقر منذ أكثر من عامين تحصل على تحذير استشاري STALE:. تتم إزالة الحزم المحظورة بشدة من ملف البيان وسيسأل Claude عن كيفية المتابعة؛ الحزم القديمة فقط تُترك في مكانها.

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

ما الذي يطلق تشغيله

تُطلق المهارة تلقائيًا عندما يقوم 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؟") — أسئلة المقارنة والاختيار لا تزال تُطلق
• تثبيت تطبيقات مستوى نظام التشغيل أو بيئات التشغيل أو إضافات IDE (Python نفسه، Docker، Homebrew، إضافات VS Code)

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

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

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

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

التثبيت

جديد في المشروع؟ ابدأ بـ 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

نفس الأفعال تعمل خارج جلسة Claude:```bash python3 skills/scripts/safer_dependencies_manager.py config set cooloff.days 14

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

وضع ما قبل التثبيت (خطاف 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. أي إصدار محدد ثابت معرض للخطر ← يعيد الخطاف permissionDecision: "deny" مع معرّف GHSA-id الخاص بكل اكتشاف + CVSS + ملخص، بالإضافة إلى تلميح لاستدعاء مهارة safer-dependencies
6. لا يتم تنفيذ التثبيت أبدًا — لا جلب من الشبكة، ولا نصوص postinstall

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

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

النطاق: واجهات سطر أوامر مدير الحزم المغطاة هنا تمتد عبر خمسة أنظمة بيئية (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 تدعم التنزيل المباشر عبر mvn dependency:get -Dartifact=group:art:version وmvn dependency:copy. هذا الخطاف لا يتعرف بعد على هذه الاستدعاءات. إذا كنت تستخدمها بانتظام، فإن شيم ما بعد الكتابة الحالي لا يزال يلتقط ما يصل إلى ملف manifest الخاص بك، لكن حماية ما قبل الجلب تنطبق فقط على الأنظمة البيئية المذكورة أعلاه. يُتتبع كمتابعة لاحقة.

الصيغة المعترف بها لكل نظام بيئي:

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

نمط الفشل: فتح عند الفشل. أي خطأ (غياب 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.

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

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

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

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

سجل التدقيق

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

جميع الأنماط الخمسة تلحق بنفس الملف. يحمل كل إدخال كتلة source (المخطط 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

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

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

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

أضاف المخطط 2.2 — بشكل إضافي — أربعة حقول إلى إدخالات تدقيق ملف القفل: lockfile, manifest_ref, relation_summary (تصنيف مباشر/غير مباشر/غير معروف لكل حزمة مُعلَّمة مقابل المانيفست الشقيق)، وكتلة 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]"] }

وضع الفشل المفتوح (Fail-open Mode) مثال (خطاف 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" } }