فحص الملفات بمضاد الفيروسات

يفحص Discuse الملفات بحثًا عن البرمجيات الخبيثة قبل أن تصل إلى مستخدميك. توجد طريقتان لاستدعاء هذه الميزة: تفعيل check_antivirus في POST /api/v2/check لفحص عناوين URL الخاصة بالمستندات إلى جانب الفحوصات الأخرى، أو استخدام نقطة النهاية المخصصة POST /api/v2/scan لفحص ملف واحد والحصول على تقرير كامل يتضمن اسم التهديد وتجزئة SHA-256.

لماذا تفحص الملفات المرفوعة؟

تُعد عمليات رفع الملفات من مسارات الهجوم الشائعة. إن توزيع البرمجيات الخبيثة عبر منصتك يعرّض بيانات المستخدمين وسمعتك وبنيتك التحتية للخطر. فحص كل ملف قبل تخزينه أو تقديمه للمستخدمين يسد هذه الثغرة.

كيف يعمل الفحص؟

عند إرسال عنوان URL لملف، يقوم Discuse بتنزيل الملف إلى بيئة معزولة، ويفحصه، ثم يعيد نتيجة توضّح ما إذا عُثر على تهديد. تُخزَّن الملفات المتطابقة مؤقتًا بحيث تكون عمليات الفحص المتكررة سريعة.

الخيار 1: فحص الملفات ضمن طلب /check

مرّر عناوين URL الخاصة بالمستندات في content.document_urls وفعّل check_antivirus. هذا هو الخيار المناسب عندما تُراجع رسالة تحتوي أيضًا على مرفق.

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "document_urls": ["https://example.com/uploaded-file.pdf"]
    },
    "settings": {
      "check_antivirus": true
    }
  }'

يقبل الطلب الواحد ما يصل إلى 5 عناوين URL لمستندات.

الاستجابة

{
  "has_violations": true,
  "cached": false,
  "message": "Malware detected in file",
  "results": {
    "hits": true,
    "antivirus": {
      "status": "FOUND",
      "hit": true,
      "details": [
        {
          "type": "malware",
          "details": "Trojan.GenericKD.12345678",
          "result": true
        }
      ]
    }
  }
}

تحتوي نتيجة مضاد الفيروسات ضمن results.antivirus على ثلاثة حقول: status وhit ومصفوفة details. يحمل كل عنصر في details الحقول type وdetails (اسم التهديد أو الرسالة) وconfidence وresult.

الخيار 2: فحص ملف واحد باستخدام /api/v2/scan

تعيد نقطة نهاية الفحص المخصصة تقريرًا أكثر تفصيلًا لملف واحد، يتضمن اسم التهديد وتجزئة الملف ومدة الفحص.

curl -X POST https://api.discuse.com/api/v2/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "file_url": "https://example.com/uploaded-file.pdf",
    "file_name": "uploaded-file.pdf"
  }'

الاستجابة

{
  "hit": true,
  "status": "FOUND",
  "description": "Trojan.GenericKD.12345678",
  "file_name": "uploaded-file.pdf",
  "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "scan_time_ms": 1250
}

حقول طلب /api/v2/scan

الحقل	النوع	ملاحظات
api_key	string	اختياري في جسم الطلب؛ يمكنك إرسال X-API-Key بدلًا منه
file_url	string	عنوان URL للملف المراد فحصه
file_name	string	اسم ملف اختياري للتقرير

قدّم file_url. تم تعريف Base64 file_data في المخطط، لكنه غير مدعوم بعد — فالطلب الذي يحتوي على file_data فقط يعيد خطأ يطلب منك استخدام file_url.

حقول استجابة /api/v2/scan

الحقل	النوع	الوصف
hit	boolean	تكون القيمة True عند اكتشاف برمجيات خبيثة
status	string	OK (نظيف)، أو FOUND (برمجيات خبيثة)، أو ERROR
description	string	اسم التهديد، أو رسالة خطأ
file_name	string	اسم الملف الذي تم فحصه
file_hash	string	تجزئة SHA-256 للملف
scan_time_ms	number	مدة الفحص بالمللي ثانية

حدود الاستخدام

يتوفر فحص مضاد الفيروسات في الخطط المدفوعة فقط. يُحتسب كل ملف يتم فحصه مرة واحدة ضمن الحصة.

الخطة	الفحوصات الشهرية	سعر التجاوز
Basic	غير متاح	-
Gold	500	$0.001/scan
Platinum	1,500	$0.00085/scan (خصم 15%)
Ultimate	3,000	$0.00075/scan (خصم 25%)

إذا لم يكن لدى المشروع اشتراك نشط، فسيتم رفض فحوصات مضاد الفيروسات.

أفضل الممارسات

افحص قبل التخزين

افحص الملف قبل تخزينه بشكل دائم، حتى لا يدخل أي ملف مصاب إلى نظامك:

async function handleFileUpload(fileUrl, fileName) {
  const result = await scanFile(fileUrl, fileName);

  if (result.hit) {
    throw new Error('Infected file detected: ' + result.description);
  }
  await storeFile(fileUrl);
}

تفرّع حسب الحالة

ميّز بين الملف النظيف والفحص الذي فشل:

const result = await scanFile(fileUrl, fileName);

switch (result.status) {
  case 'FOUND': await rejectAndNotify(fileUrl, result.description); break;
  case 'ERROR': await quarantineForReview(fileUrl); break;
  case 'OK':    await storeFile(fileUrl); break;
}

أعد استخدام عناوين URL ثابتة

تُخزَّن الملفات المتطابقة مؤقتًا. يتيح استخدام عناوين URL ثابتة للملفات إرجاع نتائج الفحوصات المتكررة من الذاكرة المؤقتة بدلًا من إعادة التنزيل.

أمثلة التكامل

Node.js (نقطة نهاية الفحص المخصصة)

async function scanFile(fileUrl, fileName) {
  const response = await fetch('https://api.discuse.com/api/v2/scan', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.DISCUSE_API_KEY
    },
    body: JSON.stringify({ file_url: fileUrl, file_name: fileName })
  });

  return response.json();
}

Python (نقطة نهاية الفحص المخصصة)

import os
import requests

def scan_file(file_url, file_name=None):
    response = requests.post(
        'https://api.discuse.com/api/v2/scan',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': os.environ['DISCUSE_API_KEY']
        },
        json={'file_url': file_url, 'file_name': file_name}
    )
    return response.json()

هل أنت مستعد لحماية منصتك من البرمجيات الخبيثة؟ ابدأ مع Discuse.