CLI
الأدلة
واجهة سطر الأوامر Scanverra CLI
افحص أي مستودع كود من الطرفية أو من خط أنابيب CI باستخدام @scanverra/cli. يعمل الفحص على جهازك الخاص، ولا يُرسَل إلى Scanverra سوى النتائج.
بداية سريعة
لا حاجة لتثبيت أي شيء بشكل عام، أو شغّل npm i -g @scanverra/cli للحصول على أمر scanverra دائم.
npx @scanverra/cli login # paste an API key from Dashboard > API keys npx @scanverra/cli scan .
كيف تعمل
دائمًا محدَّث
تُشغّل دائمًا أحدث الفحوصات، دون إصدار منفصل لواجهة سطر الأوامر يجب تتبعه أو تحديثه يدويًا.
نفس محرك لوحة التحكم
تتطابق النتائج مع نتائج فحص بدأ من Scanverra، أينما شغّلته.
الفحص محليًا
تُقرأ ملفاتك المصدرية على جهازك الخاص. بشكل افتراضي، تُرسَل النتائج فقط إلى Scanverra، وليس محتوى الملفات أو أسطر الكود المطابقة.
يظهر في لوحة التحكم الخاصة بك
يحصل كل فحص على ملخص مكتوب بالذكاء الاصطناعي ورابط، وهي نفس صفحة النتائج الخاصة بفحص بدأ من لوحة التحكم.
الأوامر
| الأمر | الوصف |
|---|---|
scanverra login | التحقق من مفتاح API الخاص بك وحفظه |
scanverra logout | إزالة المفتاح المحفوظ |
scanverra whoami | عرض الحساب والخطة المرتبطين بالمفتاح |
scanverra scan [path] | فحص مجلد (الافتراضي: المجلد الحالي)، وعرض النتائج ورفعها |
scanverra audit <url> | دقّق سرعة موقع منشور؛ ومع --budget يفشل عند تجاوز ميزانية محفوظة |
الخيارات الشائعة
| الخيار | الوصف |
|---|---|
--json / --sarif | مخرجات قابلة لقراءة الآلة. تعمل SARIF مع GitHub code scanning واستيراد Sonar |
--fail-on <severity> | ينتهي بفشل إذا وُجدت نتيجة بهذه الخطورة أو أعلى (الافتراضي: high) |
--fail-on-new, --baseline-branch <name>, --baseline-commit <sha> | يفشل فقط عندما يضيف هذا الفحص مشكلة حرجة أو عالية مقارنة بآخر فحص مرفوع (بوابة الشيفرة الجديدة لطلبات الدمج). أضف --baseline-branch main للمقارنة مع الفرع الهدف. إذا لم يُفحص ذلك الفرع من قبل، تُحتسب كل مشكلة حرجة أو عالية جديدة. عند معرفة الالتزام الذي بدأ منه فرعك (عبر git merge-base أو --baseline-commit <sha>) يُستخدم فحصه، حتى لا تُحتسب ضدك الإصلاحات التي أُضيفت لاحقًا إلى الفرع الهدف. يحل محل --fail-on ويتطلب رفع النتائج |
--category <list> | تضمين نتائج security أو dependency أو iac أو quality فقط |
--exclude <glob> | تخطي المسارات المطابقة. يعمل ملف .scanverraignore بالطريقة نفسها |
--no-upload | الفحص فقط، دون إرسال النتائج إلى Scanverra |
--include-code | رفع سطر الكود المطابق لكل نتيجة أيضًا (معطّل افتراضيًا) |
--offline | استخدام القواعد المخزَّنة مؤقتًا دون أي اتصال بالشبكة |
--api-key, --api-url | تجاوز بيانات الاعتماد أو الخادم، مفيد في CI |
--save-budget <file> | التدقيق: احفظ ميزانية من هذا التشغيل (حدود مع هامش + الخدمات الخارجية المسموح بها) |
--budget <file> | التدقيق: قارن بميزانية محفوظة؛ الخروج بالرمز 1 عند أي تجاوز |
ما الذي يُرفع
مسارات الملفات، أرقام الأسطر، معرّفات القواعد، العناوين، الأوصاف، اقتراحات الإصلاح، درجات الخطورة، أسماء التبعيات وإصداراتها، واسم المشروع والفرع والـ commit ورقم طلب السحب.
محتوى الملفات، وسطر الكود المطابق لكل نتيجة. لا تحمل نتائج الأسرار قيمة السر نفسها أبدًا. مرّر --include-code إذا أردت عرض الأسطر المطابقة في لوحة التحكم.
كيف تُختار الملفات
- داخل مستودع git تُستخدم الملفات المتتبَّعة وغير المتتبَّعة، ويُحترم ملف .gitignore. خارج git تُتخطى مجلدات البناء والتبعيات الشائعة.
- يضيف ملف .scanverraignore (نمط glob واحد في كل سطر) وخيارات --exclude القابلة للتكرار استثناءات إضافية.
- لإخفاء نتيجة واحدة، أضف تعليق scanverra-ignore أو nosec في السطر الذي يسبقها.
رموز الخروج
| 0 | نجاح، ولم تصل أي نتيجة إلى حد --fail-on |
| 1 | وصلت نتيجة إلى الحد، أو فشلت quality gate باستخدام --fail-on-gate، أو أضاف الفحص مشكلة حرجة أو عالية مع --fail-on-new |
| 2 | خطأ استخدام، أو رفض الخادم المفتاح أو الخطة، أو تعذر الوصول إلى قاعدة بيانات الثغرات فلم يمكن التحقق من النتيجة (أعد التشغيل) |
الاستخدام في CI
خزّن مفتاح API كسر مثلما تفعل مع أي تكامل CI آخر مع Scanverra، وخزّن مجلد القواعد مؤقتًا حتى لا يعيد العامل الجديد تنزيلها مع كل تشغيل.
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with: { node-version: 24 }
- run: npx @scanverra/cli scan . --fail-on high
env:
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}تخزين القواعد مؤقتًا بين عمليات التشغيل
- uses: actions/cache@v4
with:
path: ~/.cache/scanverra
key: scanverra-rules-${{ github.run_id }}
restore-keys: scanverra-rules-ميزانية الأداء لموقعك
احفظ في المستودع ميزانية من نشر جيد. كل تشغيل لاحق يُفشل البناء إذا أصبحت الصفحة أبطأ أو أثقل أو ظهرت خدمة خارجية جديدة.
# once, from a good deploy:
scanverra audit https://staging.example.com --save-budget perf-budget.json
# in CI, after deploying a preview:
- run: npx scanverra audit "$PREVIEW_URL" --budget perf-budget.json
env:
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}استكشاف الأخطاء وإصلاحها
| الرسالة | ماذا تفعل |
|---|---|
Not logged in | شغّل scanverra login، أو عيّن SCANVERRA_API_KEY |
API key was rejected | المفتاح غير صحيح أو تم إلغاؤه. أنشئ مفتاحًا جديدًا من API Keys |
You have reached your free scan limit | لقد استهلكت فحوصات Repo Scanner المجانية لهذا الشهر. افحص باستخدام --no-upload أو انتظر الشهر القادم أو قم بالترقية. |
Daily limit for downloading the scanner rules reached | خزّن مجلد القواعد مؤقتًا في CI، انظر أعلاه |
No scannable files found | تحقق من المسار ومن .gitignore أو .scanverraignore |
جاهز للفحص من الطرفية؟
أنشئ مفتاح API، ثم شغّل أول فحص لك في أقل من دقيقة.