Análisis antivirus de archivos

Discuse analiza los archivos en busca de malware antes de que lleguen a tus usuarios. Hay dos formas de hacerlo: habilitar check_antivirus en POST /api/v2/check para analizar URLs de documentos junto con otras comprobaciones, o usar el endpoint específico POST /api/v2/scan para analizar un solo archivo y obtener un informe completo que incluye el nombre de la amenaza y el hash SHA-256.

¿Por qué analizar los archivos subidos?

Las subidas de archivos son un vector de ataque común. Distribuir malware a través de tu plataforma pone en riesgo los datos de los usuarios, tu reputación y tu propia infraestructura. Analizar cada archivo antes de almacenarlo o servirlo cierra esa brecha.

¿Cómo funciona el análisis?

Cuando envías la URL de un archivo, Discuse descarga el archivo en un entorno aislado, lo analiza y devuelve si se encontró una amenaza. Los archivos idénticos se almacenan en caché para que los análisis repetidos sean rápidos.

Opción 1: analizar archivos dentro de una solicitud /check

Pasa las URLs de documentos en content.document_urls y habilita check_antivirus. Esta es la opción adecuada cuando estás moderando un mensaje que también incluye un archivo adjunto.

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

Una sola solicitud acepta hasta 5 URLs de documentos.

Respuesta

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

El resultado del antivirus en results.antivirus tiene tres campos: status, hit y un array details. Cada entrada de details contiene type, details (el nombre de la amenaza o el mensaje), confidence y result.

Opción 2: analizar un solo archivo con /api/v2/scan

El endpoint específico de análisis devuelve un informe más completo para un archivo, incluido el nombre de la amenaza, el hash del archivo y la duración del análisis.

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

Respuesta

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

Campos de la solicitud /api/v2/scan

Campo	Tipo	Notas
api_key	string	Opcional en el cuerpo; también puedes enviar X-API-Key
file_url	string	URL del archivo que se va a analizar
file_name	string	Nombre de archivo opcional para el informe

Proporciona file_url. Base64 file_data está definido en el esquema, pero aún no es compatible: una solicitud con solo file_data devuelve un error que te pide usar file_url.

Campos de la respuesta /api/v2/scan

Campo	Tipo	Descripción
hit	boolean	True cuando se detectó malware
status	string	OK (limpio), FOUND (malware) o ERROR
description	string	Nombre de la amenaza o un mensaje de error
file_name	string	El nombre del archivo analizado
file_hash	string	Hash SHA-256 del archivo
scan_time_ms	number	Duración del análisis en milisegundos

Límites de uso

El análisis antivirus solo está disponible en planes de pago. Cada archivo analizado cuenta una vez contra la cuota.

Plan	Análisis mensuales	Tarifa por exceso
Basic	No disponible	-
Gold	500	$0.001/análisis
Platinum	1,500	$0.00085/análisis (15% de descuento)
Ultimate	3,000	$0.00075/análisis (25% de descuento)

Si un proyecto no tiene una suscripción activa, los análisis antivirus se deniegan.

Buenas prácticas

Analiza antes de almacenar

Analiza un archivo antes de almacenarlo de forma permanente, para que un archivo infectado nunca entre en tu 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);
}

Ramifica según el estado

Distingue un archivo limpio de un análisis que falló:

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

Reutiliza URLs coherentes

Los archivos idénticos se almacenan en caché. Usar URLs de archivo estables permite que los análisis repetidos se devuelvan desde la caché en lugar de volver a descargarlos.

Ejemplos de integración

Node.js (endpoint específico de análisis)

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 específico de análisis)

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

¿Listo para proteger tu plataforma del malware? Empieza con Discuse.