واجهة سطر الأوامر VulnCheck CLI

vulncheck هو وصول إلى VulnCheck API عبر سطر الأوامر. يجلب تصفح الفهرس، وإدارة النسخ الاحتياطية، وفحص الثغرات الأمنية إلى الطرفية.

التثبيت

نصوص التثبيت المتوفرة

يمكنك تثبيت vulncheck بسهولة باستخدام نص تثبيت. اختر النص والطريقة التي تتوافق مع نظام التشغيل لديك:

macOS وLinux

افتح طرفية ونفّذ:

curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash

سيطلب منك هذا الاختيار بين التثبيت على مستوى النظام (يتطلب sudo) أو التثبيت المحلي للمستخدم.

[!NOTE] يدعم سكربت التثبيت أيضًا خيارات التثبيت غير التفاعلي:

• --sudo للتثبيت على مستوى النظام دون مطالبات
• --non-sudo للتثبيت المحلي للمستخدم دون مطالبات
• --help أو -h لعرض جميع الخيارات المتاحة

curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash -s -- --help

Windows

افتح PowerShell ونفّذ:

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.ps1'))

لتمكين إكمال الجدولة (tab completion)، قم بعمل dot-source للسكربت المرفق من ملف تعريف PowerShell الخاص بك:

Add-Content -Path $PROFILE -Value ". '$env:LOCALAPPDATA\Programs\vulncheck\share\powershell\vulncheck.ps1'"

تتوفر أيضًا ملفات vulncheck الثنائية لأنظمة MacOS وLinux وWindows. يمكنك تنزيل الملفات الثنائية المُجمَّعة مسبقًا من صفحة الإصدارات الخاصة بنا

التحقق من التثبيت

بعد التثبيت، تأكد من أن الملف الثنائي يطبع الإصدار المطلوب:

vulncheck version

يجب أن ترى الإصدار، وتاريخ البناء، ورابط سجل التغييرات. إذا ظهرت لك رسالة "command not found"، فأعد فتح الطرفية (shell) ليتم التقاط PATH الجديد، ثم حاول مرة أخرى.

الإعدادات

• شغّل vulncheck auth login للمصادقة باستخدام حساب VulnCheck الخاص بك.
• بدلاً من ذلك، سيحترم vulncheck متغير البيئة VULNCHECK_API_TOKEN — وهو الاسم نفسه المستخدم في VulnCheck SDKs وخادم MCP. كما أن VC_TOKEN القديم لا يزال يعمل، وله الأولوية عند تعيين كليهما.
• سيُظهر vulncheck auth بمفرده خيارات أخرى مثل التحقق من حالتك وتسجيل الخروج.

أي من متغيري البيئة يتغلب على ملف الإعدادات المحفوظ. ولهذا السبب، يرفض auth login وauth logout العمل أثناء تعيين أحدهما — وإلا لأبلغا عن النجاح دون تغيير أي شيء فعّال. شغّل vulncheck auth status لمعرفة المصدر، وأي متغير، جاء منه الرمز المميز النشط.

الاستخدام الوكيلي / البرمجي

صُمم CLI ليكون آمناً للقيادة من السكربتات ووكلاء الذكاء الاصطناعي. هذا القسم هو العقد — الأسطح أدناه مقصود بها أن تبقى مستقرة عبر الإصدارات (الإضافات ليست تغييرات كاسرة؛ إعادة التسمية / الإزالة كذلك).

الأعلام العامة

العلم	التأثير
--json	إخراج JSON على stdout؛ توجيه سطور المعلومات/التقدم إلى stderr؛ إخراج الأخطاء كمغلّف منظّم.
--quiet	كتم الإخراج المعلوماتي. لا تزال الأخطاء والحمولات تُعرض.
--no-color	تعطيل تنسيق ANSI. يحترم أيضاً متغير البيئة NO_COLOR.
--no-interactive	رفض التوقف عند مطالبات TUI؛ الأوامر التي تحتاج إلى مطالبة تُرجع خطأً بدلاً من ذلك. يُستدل به من --json، وstdin/stdout غير TTY، وأي من متغيرات البيئة CI / BUILD_NUMBER / RUN_ID.

متغيرات البيئة

المتغير	التأثير
VULNCHECK_API_TOKEN	رمز API، والاسم الموصى به — مشترك مع VulnCheck SDKs وخادم MCP. له الأولوية على ~/.config/vulncheck/vulncheck.yaml؛ أثناء تعيينه، يرفض auth login وauth logout بدلاً من كتابة ملف سيُتجاهل.
VC_TOKEN	اسم بديل قديم، لا يزال مدعوماً بالكامل وله الأولوية على VULNCHECK_API_TOKEN عند تعيين كليهما، لذا لا يغيّر أي إعداد قائم بيانات الاعتماد. امسح كليهما للرجوع إلى ملف الإعدادات. يبلّغ auth status عن أيّهما قيد الاستخدام.
NO_COLOR	أي قيمة غير فارغة تعطّل تنسيق ANSI.
CI / BUILD_NUMBER / RUN_ID	تعيين أي منها يعني الوضع غير التفاعلي (بدون مطالبات).

رموز الخروج

الرمز	المعنى
0	نجاح.
1	خطأ عام / داخلي.
2	فشل التحقق (وسائط سيئة، علم مطلوب مفقود، طلب مشوّه).
3	فشل المصادقة (لا يوجد رمز، أو رفض الخادم الرمز).
4	المورد غير موجود (HTTP 404، لا يوجد فهرس كهذا).
5	محدود المعدل (HTTP 429).
6	فشل الشبكة (DNS، رفض الاتصال، انتهاء المهلة).
130	أُلغي بواسطة SIGINT (POSIX 128 + 2).

مغلّف الأخطاء

في وضع --json، تُخرَج الأخطاء إلى stdout على النحو التالي:

{
  "schema_version": 1,
  "error": {
    "code": "auth_required",
    "message": "...",
    "http_status": 401,
    "hint": "..."
  }
}

code هو واحد من: internal، validation، auth_required، auth_invalid، not_found، rate_limited، network، bad_request، cancelled. يتم حذف http_status لأخطاء غير HTTP. hint هو سياق معالجة اختياري، يُعرض فقط عندما لا تكون الرسالة وحدها قابلة للتنفيذ (على سبيل المثال تسمية المتغير الذي قدّم رمزًا مرفوضًا). يُعرض على stderr بصيغة hint: ... خارج وضع --json.

أوامر الفحص

استخدم هذه لفحص CLI نفسه قبل إرسال العمل:

vulncheck version --json
# {"schema_version": 1, "version": "...", "build_date": "...", "changelog_url": "..."}

vulncheck auth status --json
# {"schema_version": 1, "authenticated": true, "token_source": "env",
#  "token_env_var": "VC_TOKEN", "user": "...", "email": "..."}
# Exit 0 even when authenticated=false — agents dispatch on the bool.
# token_env_var names which variable supplied the token when token_source is
# "env"; omitted otherwise. Set when authenticated=false too, so a rejected
# token can be traced to the variable holding it.
# token_shadowed: true is added when an environment token is overriding a
# *different* token saved in vulncheck.yaml — the usual cause of "I logged
# in but nothing changed". Omitted otherwise, so the CI shape (env token
# only, no config file) never reports shadowing.

vulncheck commands
# {"schema_version": 1, "root": {"name":"vulncheck", "subcommands":[...]}, ...}
# Machine-readable dump of the whole command tree — every subcommand,
# every flag (with type + default + usage), aliases, deprecation. Use
# this instead of parsing --help. Auth is not required.

ترقيم الصفحات

vulncheck token list --json --limit 10 --page 2
vulncheck token list --json --all       # auto-paginate, single combined array
vulncheck index list <index> --json --all

إدخال دفعي

يقبل purl وcpe وtag وpdns مدخلات متعددة عبر الوسائط الموضعية، أو stdin (عند التمرير عبر أنبوب)، أو --from-file <path>. يتم تجاهل الأسطر الفارغة والتعليقات التي تبدأ بـ # في الملف. يتطلب الوضع الدفعي --json.

# Stdin
cat purls.txt | vulncheck purl --json