Антивирусная проверка файлов

Discuse проверяет файлы на вредоносное ПО до того, как они попадут к вашим пользователям. Вызвать проверку можно двумя способами: включить check_antivirus в POST /api/v2/check, чтобы сканировать URL документов вместе с другими проверками, или использовать отдельный endpoint 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

Отдельный 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. 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 (отдельный 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.