أوامر Pompelmi

أوامر الفحص الأمني الشامل لتحميل الملفات Pompelmi لحماية تطبيقات Node.js.

التثبيت

الأمر	الوصف
`npm install pompelmi`	تثبيت Pompelmi عبر npm
`yarn add pompelmi`	تثبيت Pompelmi عبر Yarn
`pnpm add pompelmi`	تثبيت Pompelmi عبر pnpm
`bun add pompelmi`	تثبيت Pompelmi عبر Bun

الإعداد الأساسي (Express)

const express = require('express');
const { createScanner } = require('pompelmi');

const app = express();
const scanner = createScanner({
  maxFileSize: '10mb',
  allowedExtensions: ['.pdf', '.png', '.jpg', '.docx'],
});

app.post('/upload', scanner.middleware(), (req, res) => {
  res.json({ files: req.files });
});

محولات الإطار

الإطار	الوصف
`pompelmi/express`	محول وسيط Express.js
`pompelmi/koa`	محول وسيط Koa
`pompelmi/next`	محول مسار API Next.js
`pompelmi/nitro`	محول Nuxt/Nitro
`pompelmi/fastify`	محول مكون Fastify الإضافي

تكوين الماسح الضوئي

الخيار	الوصف
`maxFileSize: '10mb'`	أقصى حجم ملف مسموح
`allowedExtensions: ['.pdf', '.png']`	قائمة بيضاء لامتدادات الملفات المسموحة
`blockedExtensions: ['.exe', '.bat']`	قائمة سوداء لامتدادات الملفات المحظورة
`allowedMimeTypes: ['image/png']`	قائمة بيضاء لأنواع MIME المسموحة
`scanTimeout: 30000`	انتهاء مهلة الفحص بالميلي ثانية
`tempDir: '/tmp/pompelmi'`	دليل مؤقت للفحص
`preserveOriginalName: true`	الاحتفاظ باسم الملف الأصلي

تكامل YARA

الخيار	الوصف
`yara: { enabled: true }`	تفعيل فحص قواعد YARA
`yara: { rules: './rules/' }`	المسار إلى دليل قواعد YARA المخصصة
`yara: { builtinRules: true }`	استخدام قواعد كشف البرامج الضارة المدمجة
`yara: { timeout: 10000 }`	مهلة فحص YARA
ملف قواعد YARA مخصصة	كتابة ملفات `.yar` للكشف المخصص

حماية الأرشيف

الخيار	الوصف
`archive: { enabled: true }`	تفعيل فحص الأرشيف
`archive: { maxDepth: 3 }`	أقصى عمق تكرار للأرشيفات المتداخلة
`archive: { maxFiles: 100 }`	أقصى ملفات داخل الأرشيف
`archive: { maxRatio: 100 }`	نسبة الضغط القصوى (حماية قنبلة الضغط)
`archive: { maxSize: '100mb' }`	أقصى حجم مستخرج إجمالي
`archive: { formats: ['zip', 'tar', 'gz'] }`	تنسيقات أرشيف مدعومة

سياسات الأمان

السياسة	الوصف
`policy: 'strict'`	حجب أي شيء مريب (مستحسن)
`policy: 'moderate'`	حجب البرامج الضارة المعروفة، تحذير من المريب
`policy: 'permissive'`	حجب البرامج الضارة المؤكدة فقط
دالة سياسة مخصصة	تحديد منطقك الخاص للقبول/الرفض

التحقق من نوع MIME

الفحص	الوصف
التحقق من الامتداد	فحص امتداد الملف مقابل قائمة بيضاء
كشف بايت السحر	التحقق من نوع الملف حسب بايتات المحتوى
التحقق من نوع MIME	فحص نوع MIME من جانب الخادم
كشف الامتداد المزدوج	اكتشاف حيل `file.pdf.exe`
كشف بايت Null	حجب حقن بايت Null في أسماء الملفات
عدم تطابق المحتوى والنوع	اكتشاف عدم تطابق الامتداد/المحتوى

hooks للأحداث

الحدث	الوصف
`scanner.on('scan:start', fn)`	يتم تشغيله عند بدء الفحص
`scanner.on('scan:complete', fn)`	يتم تشغيله عند انتهاء الفحص
`scanner.on('scan:reject', fn)`	يتم تشغيله عند رفض الملف
`scanner.on('scan:accept', fn)`	يتم تشغيله عند نجاح الملف في جميع الفحوصات
`scanner.on('scan:error', fn)`	يتم تشغيله عند خطأ الفحص
`scanner.on('yara:match', fn)`	يتم تشغيله عند مطابقة قاعدة YARA

نتائج الفحص

الخاصية	الوصف
`result.safe`	منطقي: نجح الملف في جميع الفحوصات
`result.threats`	مصفوفة من التهديدات المكتشفة
`result.mimeType`	نوع MIME المكتشف
`result.extension`	امتداد الملف
`result.size`	حجم الملف بالبايتات
`result.hash`	SHA-256 hash للملف
`result.scanTime`	الوقت المستغرق للفحص (ms)
`result.yaraMatches`	مطابقات قواعد YARA (إن كانت مفعلة)

مثال على وسيط Express

const { createScanner } = require('pompelmi');

const scanner = createScanner({
  maxFileSize: '5mb',
  allowedExtensions: ['.pdf', '.png', '.jpg'],
  yara: { enabled: true, builtinRules: true },
  archive: { enabled: true, maxDepth: 2 },
  policy: 'strict',
});

// كوسيط
app.post('/upload', scanner.middleware(), handleUpload);

// الفحص اليدوي
app.post('/upload', async (req, res) => {
  const result = await scanner.scan(req.file.buffer, {
    filename: req.file.originalname,
  });

  if (!result.safe) {
    return res.status(400).json({
      error: 'تم رفض الملف',
      threats: result.threats,
    });
  }

  // معالجة الملف الآمن...
});

مثال على محول Koa

const { createScanner } = require('pompelmi/koa');

const scanner = createScanner({
  maxFileSize: '10mb',
  allowedMimeTypes: ['application/pdf', 'image/*'],
});

router.post('/upload', scanner.middleware(), async (ctx) => {
  ctx.body = { files: ctx.request.files };
});

مثال على مسار API Next.js

import { createScanner } from 'pompelmi/next';

const scanner = createScanner({
  maxFileSize: '5mb',
  allowedExtensions: ['.pdf', '.png'],
});

export default scanner.handler(async (req, res) => {
  const files = req.files;
  res.json({ uploaded: files.length });
});

الفحص عبر CLI

الأمر	الوصف
`npx pompelmi scan <file>`	فحص ملف واحد
`npx pompelmi scan ./uploads/`	فحص دليل من الملفات
`npx pompelmi scan --yara <file>`	فحص باستخدام قواعد YARA
`npx pompelmi scan --json <file>`	إخراج النتائج بصيغة JSON
`npx pompelmi rules list`	قائمة قواعد YARA المتاحة
`npx pompelmi rules update`	تحديث قواعد YARA المدمجة

نصائح وأفضل الممارسات

النصيحة	الوصف
استخدم سياسة صارمة في الإنتاج	احجب أي شيء مريب
فعّل قواعد YARA	اكتشف التوقيعات المعروفة للبرامج الضارة
عيّن حدود الأرشيف	منع قنابل الضغط والحمولات المتداخلة
تحقق من أنواع MIME من جانب الخادم	لا تثق بـ Content-Type للعميل
افحص الامتدادات المزدوجة	احجب أنماط `file.pdf.exe`
عيّن حدود حجم معقولة	منع الاستنزاف الموارد
فحص في الذاكرة	تجنب كتابة الملفات غير الموثوقة على القرص
راقب أحداث الفحص	سجل التنبيهات عند الرفض
حدّث قواعد YARA بانتظام	ابق محدثاً مع خط ذكاء التهديدات
استخدم قوائم بيضاء على قوائم سوداء	القائمة البيضاء أكثر أماناً من القائمة السوداء