اسکن آنتی‌ویروس فایل‌ها

Discuse فایل‌ها را پیش از آن‌که به دست کاربران شما برسند، از نظر بدافزار اسکن می‌کند. برای فراخوانی آن دو راه وجود دارد: فعال‌کردن check_antivirus در POST /api/v2/check برای اسکن URLهای سند در کنار سایر بررسی‌ها، یا استفاده از endpoint اختصاصی POST /api/v2/scan برای اسکن یک فایل واحد و دریافت گزارشی کامل شامل نام تهدید و هش SHA-256.

چرا فایل‌های آپلودشده را اسکن کنیم؟

آپلود فایل یکی از مسیرهای رایج حمله است. انتشار بدافزار از طریق پلتفرم شما، داده‌های کاربران، اعتبار شما و زیرساخت خودتان را در معرض خطر قرار می‌دهد. اسکن هر فایل پیش از ذخیره‌سازی یا ارائه آن، این شکاف امنیتی را می‌بندد.

اسکن چگونه کار می‌کند؟

وقتی URL یک فایل را ارسال می‌کنید، Discuse فایل را در یک محیط ایزوله دانلود می‌کند، آن را اسکن می‌کند و نتیجه می‌دهد که آیا تهدیدی پیدا شده است یا نه. فایل‌های یکسان کش می‌شوند تا اسکن‌های تکراری سریع انجام شوند.

گزینه ۱: اسکن فایل‌ها داخل یک درخواست /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
    }
  }'

هر درخواست حداکثر ۵ 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 است.

گزینه ۲: اسکن یک فایل واحد با /api/v2/scan

endpoint اختصاصی اسکن، برای یک فایل گزارشی کامل‌تر برمی‌گرداند که شامل نام تهدید، هش فایل و مدت‌زمان اسکن است.

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 را ارائه کنید. file_data به‌صورت Base64 در schema تعریف شده است، اما هنوز پشتیبانی نمی‌شود — درخواستی که فقط 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% discount)
Ultimate	3,000	$0.00075/scan (25% discount)

اگر پروژه‌ای اشتراک فعال نداشته باشد، اسکن‌های آنتی‌ویروس رد می‌شوند.

بهترین روش‌ها

پیش از ذخیره‌سازی اسکن کنید

فایل را پیش از ذخیره‌سازی دائمی اسکن کنید تا فایل آلوده هرگز وارد سیستم شما نشود:

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);
}

بر اساس status مسیر را جدا کنید

فایل پاک را از اسکن ناموفقی که انجام نشده یا خطا داده است، متمایز کنید:

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 (endpoint اختصاصی اسکن)

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 (endpoint اختصاصی اسکن)

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.