Comandos de Pompelmi

Comandos completos de escaneo de seguridad de carga de archivos Pompelmi para la protección de aplicaciones Node.js.

Instalación

Comando	Descripción
npm install pompelmi	Instalar Pompelmi vía npm
yarn add pompelmi	Instalar Pompelmi vía Yarn
pnpm add pompelmi	Instalar Pompelmi vía pnpm
bun add pompelmi	Instalar Pompelmi vía Bun

Configuración Básica (Express)

const express = require('express');
const { createScanner } = require('pompelmi');

const app = express();
const scanner = createScanner({
  maxFileSize: '10mb',
  allowedExtensions: ['.pdf', '.png', '.jpg', '.docx'],
});

app.post('/upload', scanner.middleware(), (req, res) => {
  res.json({ files: req.files });
});

Adaptadores de Framework

Framework	Descripción
pompelmi/express	Adaptador de middleware Express.js
pompelmi/koa	Adaptador de middleware Koa
pompelmi/next	Adaptador de ruta de API Next.js
pompelmi/nitro	Adaptador Nuxt/Nitro
pompelmi/fastify	Adaptador de plugin Fastify

Configuración del Escáner

Opción	Descripción
maxFileSize: '10mb'	Tamaño máximo de archivo permitido
allowedExtensions: ['.pdf', '.png']	Lista blanca de extensiones de archivo permitidas
blockedExtensions: ['.exe', '.bat']	Lista negra de extensiones bloqueadas
allowedMimeTypes: ['image/png']	Lista blanca de tipos MIME permitidos
scanTimeout: 30000	Tiempo de espera de escaneo en milisegundos
tempDir: '/tmp/pompelmi'	Directorio temporal para escaneo
preserveOriginalName: true	Mantener nombre de archivo original

Integración YARA

Opción	Descripción
yara: { enabled: true }	Habilitar escaneo de reglas YARA
yara: { rules: './rules/' }	Ruta al directorio de reglas YARA personalizadas
yara: { builtinRules: true }	Usar reglas de detección de malware incorporadas
yara: { timeout: 10000 }	Tiempo de espera de escaneo YARA
Custom YARA rules file	Escribir archivos .yar para detección personalizada

Protección de Archivo

Opción	Descripción
archive: { enabled: true }	Habilitar inspección de archivo
archive: { maxDepth: 3 }	Profundidad de recursión máxima para archivos anidados
archive: { maxFiles: 100 }	Archivos máximos dentro del archivo
archive: { maxRatio: 100 }	Relación de compresión máxima (protección contra bomba zip)
archive: { maxSize: '100mb' }	Tamaño total máximo extraído
archive: { formats: ['zip', 'tar', 'gz'] }	Formatos de archivo compatibles

Políticas de Seguridad

Política	Descripción
policy: 'strict'	Bloquear cualquier cosa sospechosa (recomendado)
policy: 'moderate'	Bloquear malware conocido, advertir sobre sospechoso
policy: 'permissive'	Bloquear solo malware confirmado
Custom policy function	Definir su propia lógica de aceptar/rechazar

Validación de Tipo MIME

Verificación	Descripción
Extension validation	Verificar extensión de archivo contra lista blanca
Magic byte detection	Verificar tipo de archivo por bytes de contenido
MIME type verification	Verificación de tipo MIME del lado del servidor
Double extension detection	Atrapar trucos file.pdf.exe
Null byte detection	Bloquear inyección de byte nulo en nombres de archivo
Content-Type mismatch	Detectar desajustes de extensión/contenido

Hooks de Evento

Evento	Descripción
scanner.on('scan:start', fn)	Se dispara cuando comienza el escaneo
scanner.on('scan:complete', fn)	Se dispara cuando termina el escaneo
scanner.on('scan:reject', fn)	Se dispara cuando se rechaza un archivo
scanner.on('scan:accept', fn)	Se dispara cuando un archivo pasa todas las verificaciones
scanner.on('scan:error', fn)	Se dispara en error de escaneo
scanner.on('yara:match', fn)	Se dispara cuando coincide una regla YARA

Resultados de Escaneo

Propiedad	Descripción
result.safe	Boolean: archivo pasó todas las verificaciones
result.threats	Array de amenazas detectadas
result.mimeType	Tipo MIME detectado
result.extension	Extensión de archivo
result.size	Tamaño del archivo en bytes
result.hash	Hash SHA-256 del archivo
result.scanTime	Tiempo dedicado al escaneo (ms)
result.yaraMatches	Coincidencias de regla YARA (si está habilitado)

Ejemplo de Middleware de Express

const { createScanner } = require('pompelmi');

const scanner = createScanner({
  maxFileSize: '5mb',
  allowedExtensions: ['.pdf', '.png', '.jpg'],
  yara: { enabled: true, builtinRules: true },
  archive: { enabled: true, maxDepth: 2 },
  policy: 'strict',
});

// As middleware
app.post('/upload', scanner.middleware(), handleUpload);

// Manual scanning
app.post('/upload', async (req, res) => {
  const result = await scanner.scan(req.file.buffer, {
    filename: req.file.originalname,
  });

  if (!result.safe) {
    return res.status(400).json({
      error: 'File rejected',
      threats: result.threats,
    });
  }

  // Process safe file...
});

Ejemplo de Adaptador Koa

const { createScanner } = require('pompelmi/koa');

const scanner = createScanner({
  maxFileSize: '10mb',
  allowedMimeTypes: ['application/pdf', 'image/*'],
});

router.post('/upload', scanner.middleware(), async (ctx) => {
  ctx.body = { files: ctx.request.files };
});

Ejemplo de Ruta de API Next.js

import { createScanner } from 'pompelmi/next';

const scanner = createScanner({
  maxFileSize: '5mb',
  allowedExtensions: ['.pdf', '.png'],
});

export default scanner.handler(async (req, res) => {
  const files = req.files;
  res.json({ uploaded: files.length });
});

Escaneo CLI

Comando	Descripción
npx pompelmi scan <file>	Escanear un archivo único
npx pompelmi scan ./uploads/	Escanear directorio de archivos
npx pompelmi scan --yara <file>	Escanear con reglas YARA
npx pompelmi scan --json <file>	Resultados de salida como JSON
npx pompelmi rules list	Listar reglas YARA disponibles
npx pompelmi rules update	Actualizar reglas YARA incorporadas

Consejos y Mejores Prácticas

Consejo	Descripción
Use strict policy in production	Rechazar cualquier cosa sospechosa
Enable YARA rules	Detectar firmas de malware conocidas
Set archive limits	Prevenir bombas zip y cargas anidadas
Validate MIME types server-side	No confiar en Content-Type del cliente
Check double extensions	Bloquear patrones file.pdf.exe
Set reasonable size limits	Prevenir agotamiento de recursos
Scan in memory	Evitar escribir archivos que no son de confianza en disco
Monitor scan events	Registrar y alertar sobre rechazos
Update YARA rules regularly	Manténgase actualizado con inteligencia de amenazas
Use allowlists over blocklists	La lista blanca es más segura que la lista negra