API de inspección de archivos: SHA-256, MIME real, señal antivirus y metadatos en REST

API de inspección de archivos: SHA-256, MIME real, señal antivirus y metadatos en REST

Las aplicaciones que aceptan cargas suelen necesitar un pequeño control técnico antes de entregar un archivo a un analizador, un flujo de trabajo o una canalización de almacenamiento. Un marketplace puede recibir documentos de vendedores, un SaaS aceptar adjuntos de clientes y una plataforma de intercambio registrar qué entra en su sistema. Cada equipo puede construir su propio hash, detección MIME, extracción de metadatos y capa inicial de triaje, pero mantenerlos de forma coherente no siempre compensa. FileInspection reúne estas comprobaciones en un contrato REST asíncrono y devuelve un informe JSON.

La solicitud multipart

Los clientes autenticados envían una solicitud multipart a POST /api/files/start-process. Deben usar actionName=FileInspection, enviar un archivo en el campo file e incluir parameters=[] y async=true. Se acepta un solo archivo no vacío de hasta 50 MB por llamada y no se aplica una lista de extensiones. La validación del servidor comprueba la solicitud y el tamaño; el atributo accept del navegador, el nombre o el MIME declarado no son una frontera de seguridad.

La respuesta inicial representa una acción en cola, no un informe terminado. Guarda el identificador y trackingUrl y consulta /api/actions/get-action-infos/{id} con el contexto autenticado. El cliente no tiene que mantener abierta la carga mientras se ejecutan la detección MIME, el triaje de motor antivirus, la extracción de metadatos o la inspección multimedia.

Qué contiene el informe JSON

Un resultado correcto de FileInspection es un único archivo JSON. Registra el nombre original y el tamaño, un hash SHA-256 y el tipo MIME real detectado. El MIME se obtiene del contenido y no se acepta del navegador como prueba. Esto ofrece una base más fiable para registrar, enrutar o decidir si un analizador posterior debe recibir el archivo.

Cuando el formato lo permite, ExifTool puede aportar metadatos EXIF filtrados. Para audio y vídeo, FFprobe puede proporcionar códec, resolución, duración y bitrate. Las imágenes y los PDF pueden recibir una vista previa OCR limitada a 500 caracteres. Los campos dependen del formato: pueden faltar o estar vacíos sin que eso signifique que la carga falló.

Señales de triaje y límites

La sección antivirus devuelve para motor antivirus clean, infected o error. Es una señal preliminar de triaje, nunca una garantía antivirus. En concreto, clean solo significa que esa inspección no informó de una detección; nunca debe transformarse en «archivo certificado como seguro» en una interfaz o una política automática. error debe permanecer diferenciado de clean para que la aplicación pueda elegir un comportamiento prudente.

La sección reglas de detección devuelve clean, matched o not_run. El conjunto de reglas inicial es mínimo y no constituye una base exhaustiva. Un match puede enviar el archivo a revisión, mientras clean o not_run no prueban la ausencia de amenazas. Esta distinción debe conservarse en la documentación, los registros y los mensajes de producto.

Diseña una integración sólida

Guarda el ID de la acción como referencia duradera del trabajo asíncrono. Distingue al menos entre validación rechazada, procesamiento, fallo y resultado completado. Si una consulta de seguimiento agota el tiempo, recupera primero la acción existente antes de enviar otra. Crear una segunda inspección porque una petición de estado no respondió puede duplicar trabajo y gastar tokens sin necesidad.

Cuando termine correctamente, utiliza la referencia de resultado proporcionada por el servidor y el flujo autenticado para descargar el JSON. No construyas una URL de resultados solo con un ID entero ni trates un ID enviado por el cliente como autorización. Tu aplicación también debe verificar la propiedad al asociar el informe a un registro de carga. El hash ayuda a deduplicar y rastrear, pero no concede acceso al archivo.

Precio y alcance práctico

Una inspección exitosa cuesta 12 tokens. Los fallos de validación, incluido un archivo vacío o superior a 50 MB, no se facturan. Es un control técnico inicial y limitado antes del análisis o la revisión humana, no un sustituto de una plataforma completa de análisis de malware ni de una política de contenido propia.

Con una llamada REST asíncrona, la integración obtiene SHA-256, MIME real, una señal preliminar de motor antivirus, un estado de detección mínimo, metadatos filtrados y datos multimedia u OCR según el formato. La interfaz asíncrona deja que el sistema llamante continúe su propio trabajo con una referencia clara y auditable.