np-audit — مدقق حزم npm

تحليل أمني ثابت لحزم npm — يكتشف البرامج النصية لدورة الحياة المبهمة، الثغرات المعروفة، والأنماط الخبيثة قبل تشغيلها. بديل مباشر لـ npm install و npm ci.

لا تبعيات. فقط مكونات Node.js المضمنة. أقل من 100 كيلوبايت عند النقل.

npx np-audit scan express

npm install -g np-audit
npa scan                     # مسح جميع التبعيات
npa install                  # تدقيق ثم تثبيت
alias npm='npa'              # استخدام كبديل مباشر

---

المارشالات

الكشف مقسم إلى مارشالات معيارية — كل مارشال يكتشف إشارة هجوم واحدة:

المارشال	ما يكتشفه	الدرجة
eval/dynamic-exec	eval()، new Function()، التقييم غير المباشر، vm.*، setTimeout مع سلسلة نصية	8
obfuscator.io	أنماط تسمية المتغيرات _0x (مخرجات obfuscator.io)	9–80
high-entropy-string	سلاسل طويلة أو سلاسل ضامة ذات إنتروبيا عالية	6
hex-escape-density	تسلسلات هروب كثيفة \xNN و \uXXXX	5–50
fromCharCode	String.fromCharCode مع العديد من الوسائط، مصفوفات رموز أحرف عشرية كبيرة	7
encoded-decode	فك تشفير Base64/سداسي عشري (atob، Buffer.from) مع eval اختيارياً	3–8
child-process	require('child_process')، exec، spawn، fork، worker_threads	5
hex-array	قيم حرفية سداسية عشرية 0x بأعداد كبيرة	7–60
process-env	الوصول إلى process.env (إشارة تسريب بيانات الاعتماد)	3
network-call	require('https')، fetch()، dns، net، tls	4
filesystem-manipulation	fs.writeFile، chmod، symlink (استمرارية الباب الخلفي)	3–4
runtime-download	تنزيل وتنفيذ بيئات تشغيل خارجية (Bun، Deno)	9–50
vscode-autorun	مهام VS Code مع runOn: folderOpen (تنفيذ تلقائي)	30
known-vulnerability	ثغرات معروفة عبر واجهة Snyk API أو OSV.dev	4–6 (تحذير)، 80 (خبيث)

تتدرج الدرجات مع الشدة — العد الأعلى لمؤشرات التمويه ينتج درجات أعلى. يعتمد الحكم النهائي على أعلى درجة فردية عبر جميع المارشالات.

انظر CONTRIBUTING.md لمعرفة كيفية كتابة مارشالات مخصصة.

---

فحص الثغرات (CVE)

يتم فحص كل حزمة ممسوحة مقابل قواعد بيانات الثغرات المعروفة إلى جانب تحليل الكود.

الافتراضي: OSV.dev (لا حاجة للإعداد)

يعمل فوراً — يستعلم واجهة OSV.dev المجانية عن الثغرات المعروفة وإرشادات الحزم الخبيثة.

اختياري: Snyk API (بيانات أكثر ثراءً)

# متغير بيئي
export SNYK_API_TOKEN=your-token-here

# أو عبر واجهة Snyk CLI
snyk auth

ترتيب حل الرمز المميز: SNYK_API_TOKEN → SNYK_TOKEN → ~/.config/configstore/snyk.json

الشدة	الدرجة	الحكم
حزمة خبيثة	80	خطر
10 ثغرات فأكثر	6	تحذير
5–9 ثغرات	5	تحذير
1–4 ثغرات	4	تحذير

الثغرات غير الخبيثة (CVE) تنتج تحذيرات لكنها لا تمنع التثبيت أبدًا. فقط الحزم الخبيثة المؤكدة تؤدي إلى خطر.

---

الاستخدام

الأوامر

الأمر	الاسم المستعار	الوصف
npa install [package]	npa i	تدقيق ثم تشغيل npm install
npa ci	—	تدقيق ثم تشغيل npm ci
npa scan [package]	npa s	مسح فقط، بدون تثبيت
npa config get	npa c get	عرض الإعدادات الحالية
npa config set <key> <value>	npa c set	تحديث قيمة إعداد
npa alias --install	—	تثبيت الاسم المستعار للشل
npa alias --uninstall	—	إزالة الاسم المستعار للشل

أي أمر غير معروف يتم توجيهه إلى npm (مثل npa run test، npa publish).

العلامات

العلامة	الاختصار	تعمل مع	الوصف
--review	-r	install، ci	وضع تفاعلي — اختر البرامج النصية المسموح بها
--json	—	install، ci، scan	إخراج JSON قابل للقراءة آلياً
--no-dev	—	install، ci، scan	تخطي تبعيات التطوير
--verbose	—	الكل	إظهار تقدم الجلب وتفاصيل إضافية
--version	-v	—	طباعة الإصدار والخروج
--help	-h	—	طباعة التعليمات والخروج

وضع --review التفاعلي

npa install --review

  npa --review mode
  Use ↑/↓ to navigate, SPACE to toggle, ENTER to confirm, q to quit

  Found 3 package(s) with install scripts:

     [✓ allow] [email protected]       postinstall: post-install.js     OK
   ▶ [✗ deny ] [email protected]       postinstall: install.js          DANGER (score: 9)
     [✓ allow] @scope/[email protected]     postinstall: install.js          WARN (score: 5)

  2 allowed  1 denied

---

الإعدادات

يتم تخزين الإعدادات في ~/.npmauditor.json (عامة) ويمكن تجاوزها لكل مشروع باستخدام .npmauditor.json.

npa config get                              # عرض الإعدادات الحالية
npa config set blockScore 6                 # الحظر عند درجة 6+
npa config set skipPackages '["esbuild"]'   # الثقة بحزم محددة
npa config set skipScopes '["@types"]'      # الثقة بنطاقات كاملة

جميع مفاتيح الإعدادات

المفتاح	الافتراضي	الوصف
blockScore	7	عتبة الدرجة للخطر (الخروج 1)
warnScore	4	عتبة الدرجة للتحذير (الخروج 0)
registry	https://registry.npmjs.org	عنوان سجل npm
timeout	30000	مهلة طلب HTTP (مللي ثانية)
parallelFetches	5	التنزيلات المتزامنة
skipScopes	[]	بادئات @scope التي سيتم تخطيها
skipPackages	[]	أسماء الحزم التي سيتم تخطيها
silent	false	كتم الإخراج عند عدم العثور على مشكلات
scanSelf	true	فحص البرامج النصية لدورة الحياة للمشروع الخاص
maxTarballSize	50MB	الحد الأقصى لحجم الأرشيف المفكوك (حماية من القنابل)
checkVulnerabilities	true	فحص الحزم مقابل قواعد بيانات CVE
deepResolve	false	حل شجرة التبعية المتعدية بالكامل
disabledMarshallers	[]	أسماء المارشالات التي سيتم تخطيها أثناء المسح

تعطيل المارشالات

يمكنك تعطيل فحوصات كشف محددة عن طريق إضافة أسمائها إلى disabledMarshallers:

npa config set disabledMarshallers '["process-env", "network-call"]'