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

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'))

لتمكين إكمال التبويب، قم بعمل 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"، أعد فتح الصدفة الخاصة بك ليتم التقاط PATH الجديد، ثم حاول مرة أخرى.

الإعداد

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

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

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

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

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

العلم	التأثير
--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.

أوامر الفحص

استخدم هذه لفحص واجهة سطر الأوامر نفسها قبل إرسال العمل:

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

# File
vulncheck cpe --from-file ./cpes.txt --json