Verificação antivírus de arquivos

Discuse verifica arquivos em busca de malware antes que eles cheguem aos seus usuários. Há duas formas de fazer isso: habilite check_antivirus em POST /api/v2/check para verificar URLs de documentos junto com outras verificações, ou use o endpoint dedicado POST /api/v2/scan para verificar um único arquivo e obter um relatório completo, incluindo o nome da ameaça e o hash SHA-256.

Por que verificar arquivos enviados?

Uploads de arquivos são um vetor de ataque comum. Distribuir malware pela sua plataforma coloca em risco os dados dos usuários, a sua reputação e a sua própria infraestrutura. Verificar cada arquivo antes de armazená-lo ou disponibilizá-lo fecha essa brecha.

Como a verificação funciona?

Quando você envia uma URL de arquivo, o Discuse baixa o arquivo em um ambiente isolado, faz a verificação e retorna se uma ameaça foi encontrada. Arquivos idênticos são armazenados em cache, então verificações repetidas são rápidas.

Opção 1: verificar arquivos dentro de uma solicitação /check

Passe URLs de documentos em content.document_urls e habilite check_antivirus. Esta é a opção certa quando você está moderando uma mensagem que também contém um anexo.

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
    }
  }'

Uma única solicitação aceita até 5 URLs de documentos.

Resposta

{
  "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
        }
      ]
    }
  }
}

O resultado do antivírus em results.antivirus tem três campos: status, hit e um array details. Cada entrada de details contém type, details (o nome ou a mensagem da ameaça), confidence e result.

Opção 2: verificar um único arquivo com /api/v2/scan

O endpoint dedicado de verificação retorna um relatório mais detalhado para um arquivo, incluindo o nome da ameaça, o hash do arquivo e a duração da verificação.

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"
  }'

Resposta

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

Campos da solicitação /api/v2/scan

Campo	Tipo	Observações
api_key	string	Opcional no corpo; você também pode enviar X-API-Key
file_url	string	URL do arquivo a ser verificado
file_name	string	Nome de arquivo opcional para o relatório

Forneça file_url. file_data em Base64 está definido no esquema, mas ainda não é compatível — uma solicitação apenas com file_data retorna um erro pedindo para você usar file_url.

Campos da resposta /api/v2/scan

Campo	Tipo	Descrição
hit	boolean	Verdadeiro quando malware foi detectado
status	string	OK (limpo), FOUND (malware) ou ERROR
description	string	Nome da ameaça ou uma mensagem de erro
file_name	string	O nome do arquivo verificado
file_hash	string	Hash SHA-256 do arquivo
scan_time_ms	number	Duração da verificação em milissegundos

Limites de uso

A verificação antivírus está disponível apenas em planos pagos. Cada arquivo verificado conta uma vez contra a cota.

Plano	Verificações mensais	Tarifa excedente
Basic	Não disponível	-
Gold	500	$0.001/verificação
Platinum	1,500	$0.00085/verificação (15% de desconto)
Ultimate	3,000	$0.00075/verificação (25% de desconto)

Se um projeto não tiver uma assinatura ativa, as verificações antivírus serão negadas.

Boas práticas

Verifique antes de armazenar

Verifique um arquivo antes de armazená-lo permanentemente, para que um arquivo infectado nunca entre no seu sistema:

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

Ramifique com base no status

Diferencie um arquivo limpo de uma verificação que falhou:

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

Reutilize URLs consistentes

Arquivos idênticos são armazenados em cache. Usar URLs de arquivos estáveis permite que verificações repetidas retornem do cache em vez de baixar o arquivo novamente.

Exemplos de integração

Node.js (endpoint dedicado de verificação)

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 dedicado de verificação)

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()

Pronto para proteger sua plataforma contra malware? Comece com o Discuse.