deptrust

     __           __                  __
 ___/ /___  ___  / /________  _______/ /_
/ _  / __ \/ _ \/ __/ ___/ / / / ___/ __/
/  __/ /_/ /  __/ /_/ /  / /_/ (__  ) /_
\__,_/\____/ .___/\__/_/   \__,_/____/\__/
           /_/
`

deptrust هي واجهة سطر أوامر تتحقق من إصدارات الحزم بحثاً عن الثغرات الأمنية المعروفة عبر npm و PyPI و crates.io و Go modules و RubyGems و NuGet و Maven و Packagist و pub.dev و CocoaPods و Hex.pm و Hackage و GitHub Actions والمزيد.

تعمل محلياً كواجهة CLI وكخادم MCP. تستخدم واجهات برمجة التطبيقات العامة للسجلات و OSV مباشرة؛ لا توجد خدمة deptrust مُستضافة لتثق بها أو تهيئها.

وُلدت هذه الأداة من الإحباط المتمثل في وكلاء الذكاء الاصطناعي الذين يستخدمون الإصدارات القديمة باستمرار.

## المحتويات

- [النطاق](#scope)
- [استخدام CLI](#cli-usage)
- [التثبيت](#install)
- [إعداد الوكيل](#agent-setup)
- [إعداد MCP يدوي](#manual-mcp-setup)
- [أدوات MCP](#mcp-tools)
- [الاستخدام بالمهارة فقط](#skill-only-use)
- [استكشاف الأخطاء وإصلاحها](#troubleshooting)

## النطاق

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

- npm، بما في ذلك الحزم المُنَطَّقَة مثل `@clidey/ux`
- PyPI
- Cargo / crates.io
- Go modules
- RubyGems
- NuGet
- Maven، باستخدام أسماء الحزم بتنسيق `groupId:artifactId`
- Packagist / Composer، باستخدام أسماء الحزم بتنسيق `vendor/package`
- pub.dev
- CocoaPods
- Hex.pm
- Hackage
- GitHub Actions، باستخدام أسماء الحزم بتنسيق `owner/repo` والوسوم (tags) ومراجع الفروع (branch refs) أو SHA للالتزامات (commit SHAs) كإصدارات

يبلغ deptrust حالياً عن الثغرات الأمنية المعروفة ويقدم توصية بسيطة:

| أعلى شدة معروفة | التوصية |
| --- | --- |
| حرجة (critical) | منع (block) |
| عالية (high) | منع (block) |
| متوسطة / غير معروفة (medium / unknown) | مراجعة (review) |
| منخفضة (low) | السماح (allow) |
| لم يتم العثور على أي منها | السماح (allow) |

`allow` تعني عدم العثور على ثغرة أمنية معروفة تعيق الاستخدام في مصادر البيانات العامة. لا يثبت ذلك أن الحزمة آمنة.

كما يُصدر deptrust إشارات خطر ليست CVEs. على سبيل المثال، يتم تمييز الإصدار المنشور خلال الـ 72 ساعة الماضية للمراجعة حتى لا يقوم الوكيل بتثبيت إصدار جديد تماماً دون تمحيص.

يتم استعلام مزودي النصائح (Advisory providers) بالتوازي:

- OSV
- قاعدة بيانات نصائح GitHub (GitHub Advisory Database)، بما في ذلك النصائح المُرتجَعَة (reviewed advisories) والنصائح المتعلقة بالبرامج الضارة (malware advisories)

تتفاوت تغطية المزود حسب النظام البيئي. إذا تمكن deptrust من حل بيانات السجل ولكن لا يوجد مزود ثغرات مهيأ يدعم هذا النظام البيئي، فإنه يُرجع `unknown` بدلاً من اعتبار الحزمة آمنة.

تغطية المزود:

| النظام البيئي | بيانات السجل | OSV | قاعدة بيانات نصائح GitHub |
| --- | --- | --- | --- |
| npm | نعم | نعم | نعم |
| PyPI | نعم | نعم | نعم |
| Cargo / crates.io | نعم | نعم | نعم |
| Go modules | نعم | نعم | نعم |
| RubyGems | نعم | نعم | نعم |
| NuGet | نعم | نعم | نعم |
| Maven | نعم | نعم | نعم |
| Packagist / Composer | نعم | نعم | نعم |
| pub.dev | نعم | نعم | نعم |
| CocoaPods | نعم | لا | نعم |
| Hex.pm | نعم | نعم | نعم |
| Hackage | نعم | نعم | لا |
| GitHub Actions | نعم | نعم | نعم |

يتضمن مخرجات JSON حقول تغطية النصائح:

- `checked_providers`: مزودو الثغرات الذين استعلمهم deptrust فعلياً
- `skipped_providers`: المزودون المُهيئون الذين تم تخطيهم لأن النظام البيئي غير مدعوم
- `advisory_coverage`: `full` أو `partial` أو `none` أو `error`
- `advisory_coverage_reason`: شرح مختصر لقيمة التغطية
- `registry_verification`: `verified` عندما أكدت بيانات السجل الإصدار، أو `unverified` عندما استمر الفحص الدقيق للإصدار بعد فشل مؤقت في السجل
- `registry_verification_reason`: خطأ السجل عندما تكون التقييم غير متاح

لا يزال الفحص الدقيق للإصدار يستعلم مزودي النصائح عندما يكون تقييم السجل غير متاح مؤقتاً. تكون تلك النتيجة دائماً غير قابلة للتثبيت ولا تحصل أبداً على توصية `allow`. لا تزال عمليات الفحص لأحدث إصدار (`latest`)، والحزم غير المعروفة، والإصدارات المُعدومة بشكل قاطع تتطلب حل السجل بنجاح.

تستخدم طلبات HTTP إعادة المحاولة للردود `429` و `502` و `503` و `504` حتى ثلاث محاولات إجمالية. تستخدم إعادة المحاولة تأخيرات أسية قصيرة وتحترم قيم `Retry-After` حتى ثانيتين؛ أما الطلبات التي يطلبها الخادم لمدة أطول فتفشل بسرعة حتى لا تعلق CLI. يؤدي استنفاذ إعادة محاولات النصائح إلى جعل النتيجة غير مكتملة ويمنع توصية `allow`.

### مصادقة GitHub API

يمكن لطلبات قاعدة بيانات نصائح GitHub و GitHub Actions API استخدام رمز (token) لتطبيق GitHub قصير العمر وأقل امتياز. في CI، قم بتمريره عبر `DEPTRUST_GITHUB_TOKEN`:

```bash
DEPTRUST_GITHUB_TOKEN="$GITHUB_APP_TOKEN" deptrust check npm lodash 4.17.20

أولوية بيانات الاعتماد هي DEPTRUST_GITHUB_TOKEN، ثم GITHUB_TOKEN، ثم GH_TOKEN. للاستخدام المحلي، يتم تمكين الاحتياطي الاختياري لـ GitHub CLI صراحةً باستخدام DEPTRUST_GITHUB_AUTH=gh deptrust check ...؛ يقوم بتشغيل gh auth token دون طلب موجه. إذا لم تكن هناك بيانات اعتماد متاحة، يستمر DepTrust دون مصادقة. يؤدي حد معدل API أو فشل الإذن من GitHub إلى إرجاع unknown مع تشخيص، ولا يُعتبر أبداً نجاحاً يعتمد فقط على OSV.

لا يقوم DepTrust أبداً بتخزين أو تجميع أو تخبئة أو تسجيل أو قياس أو إصدار رموز GitHub. يتم إرسال رؤوس المصادقة فقط إلى https://api.github.com.

استخدام CLI

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

deptrust check npm lodash 4.17.20

مثال لرد عادي:

npm [email protected]: 2 known vulnerabilities found
recommendation: block
risk_score: 80

التحقق من أحدث إصدار:

deptrust check pypi requests latest

إرجاع JSON:

deptrust check --json cargo serde latest

التحقق من وحدة Go:

deptrust check go golang.org/x/crypto latest

التحقق من RubyGems أو NuGet أو Maven:

deptrust check rubygems rails latest
deptrust check nuget Newtonsoft.Json latest
deptrust check maven org.apache.logging.log4j:log4j-core latest

التحقق من Packagist أو pub.dev أو CocoaPods أو Hex.pm أو Hackage أو GitHub Actions:

deptrust check packagist monolog/monolog latest
deptrust check pub http latest
deptrust check cocoapods AFNetworking latest
deptrust check hex plug latest
deptrust check hackage aeson latest
deptrust check github-actions actions/checkout v7.0.0
deptrust check github-actions actions/checkout main

بالنسبة لـ GitHub Actions، تُعامل SHA الكاملة للالتزامات على أنها مثبتة. تُقبل وسوم semver الكاملة مثل v4.2.2 بدون إشارة تثبيت إضافية. الوسوم الرئيسية فقط مثل v4 ومراجع الفروع مثل main هي مراجع صالحة، لكن deptrust يضيف إشارة مراجعة لأنها قد تتغير.

مثال لرد JSON:

{
  "ecosystem": "npm",
  "package": "lodash",
  "version": "4.17.20",
  "latest_version": "4.17.21",
  "known_vulnerabilities_found": true,
  "safe_to_use": false,
  "should_install": false,
  "risk_score": 80,
  "recommendation": "block",
  "classification": "vulnerable",
  "reason": "Found 2 known vulnerability records.",
  "next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
  "summary": "lodash 4.17.20 has 2 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
  "signals": [],
  "checked_providers": [
    "OSV",
    "GitHub Advisory DB"
  ],
  "skipped_providers": [],
  "advisory_coverage": "full",
  "advisory_coverage_reason": "all configured vulnerability providers were checked",
  "registry_verification": "verified",
  "vulnerabilities": [
    {
      "id": "GHSA-35jh-r3h4-6jhm",
      "aliases": [
        "CVE-2021-23337"
      ],
      "cve_ids": [
        "CVE-2021-23337"
      ],
      "ghsa_ids": [
        "GHSA-35jh-r3h4-6jhm"
      ],
      "summary": "Command Injection in lodash",
      "severity": "high",
      "source": "OSV",
      "advisory_url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm",
      "affected_ranges": [
        "SEMVER: introduced 0, fixed 4.17.21"
      ],
      "fixed_versions": [
        "4.17.21"
      ],
      "references": [
        {
          "type": "ADVISORY",
          "url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm"
        }
      ]
    }
  ],
  "provider_errors": []
}

اقتراح أحدث إصدار فقط عندما لا يتم العثور على ثغرات أمنية معروفة:

deptrust suggest npm lodash