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

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 check npm lodash 4.17.20

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

deptrust check pypi requests latest

deptrust check --json cargo serde latest

deptrust check go golang.org/x/crypto latest

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

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

{
  "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

deptrust compare npm lodash 4.17.20 4.17.21

lodash 4.17.20 -> 4.17.21 improves risk: score 80 to 0.
recommendation: allow
next_action: upgrade_to_target

deptrust version

npx @clidey/deptrust install
pnpx @clidey/deptrust@latest install

npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall

brew install clidey/tap/deptrust

brew tap clidey/tap
brew install deptrust
brew upgrade deptrust

deptrust setup

go install github.com/clidey/deptrust/cmd/deptrust@latest

# Run without installing
nix run github:clidey/deptrust

# Install into your profile
nix profile install github:clidey/deptrust

# قم بتثبيت Devbox أولاً (إذا لم يكن مثبتاً بالفعل)
curl -fsSL https://get.jetify.dev/devbox | bash

# قم بتهيئة البيئة
devbox shell

# بناء المشروع
devbox run build

brew install jetify-com/devbox/devbox

npx @clidey/deptrust install --all
pnpx @clidey/deptrust@latest install --all

npx @clidey/deptrust install --codex-mcp
npx @clidey/deptrust install --claude-code-mcp
npx @clidey/deptrust skills install
pnpx @clidey/deptrust@latest install --codex-mcp
pnpx @clidey/deptrust@latest install --claude-code-mcp
pnpx @clidey/deptrust@latest skills install

قبل سرد أو مقارنة أو التوصية بإصدارات حزم محددة، تحقق منها باستخدام deptrust. يشمل ذلك الإجابة على "ما الذي يمكنني تحديثه" - لا تقدم توصيات بالإصدارات حتى بعد التحقق من الثغرات الأمنية المعروفة.

/absolute/path/to/deptrust mcp

{
  "mcpServers": {
    "deptrust": {
      "command": "/absolute/path/to/deptrust",
      "args": ["mcp"]
    }
  }
}

codex mcp add deptrust -- /absolute/path/to/deptrust mcp

claude mcp add --transport stdio deptrust -- /absolute/path/to/deptrust mcp

{
  "ecosystem": "npm",
  "package": "lodash",
  "version": "4.17.20"
}

{
  "ecosystem": "npm",
  "package": "vite",
  "version": "7.0.0",
  "latest_version": "8.0.16",
  "known_vulnerabilities_found": true,
  "safe_to_use": false,
  "should_install": false,
  "risk_score": 80,
  "classification": "vulnerable",
  "recommendation": "block",
  "reason": "Found 7 known vulnerability records.",
  "next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
  "summary": "vite 7.0.0 has 7 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
  "vulnerability_count": 7,
  "vulnerability_counts": {
    "critical": 0,
    "high": 2,
    "medium": 3,
    "low": 2,
    "unknown": 0
  },
  "highest_severity": "high",
  "checked_providers": [
    "OSV",
    "GitHub Advisory DB"
  ],
  "skipped_providers": [],
  "advisory_coverage": "full",
  "advisory_coverage_reason": "all configured vulnerability providers were checked",
  "registry_verification": "verified",
  "full_response_command": "deptrust check --json npm vite 7.0.0"
}

{
  "ecosystem": "npm",
  "package": "lodash"
}

{
  "ecosystem": "npm",
  "package": "lodash",
  "from_version": "4.17.20",
  "to_version": "4.17.21"
}

npx @clidey/deptrust skills install

export PATH="$HOME/.local/bin:$PATH"

which deptrust