Comandos Pompelmi

Comandos abrangentes de escaneamento de segurança de upload de arquivo Pompelmi para proteção de aplicação Node.js.

Instalação

Comando	Descrição
npm install pompelmi	Instalar Pompelmi via npm
yarn add pompelmi	Instalar Pompelmi via Yarn
pnpm add pompelmi	Instalar Pompelmi via pnpm
bun add pompelmi	Instalar Pompelmi via Bun

Setup Básico (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	Descrição
pompelmi/express	Adaptador de middleware Express.js
pompelmi/koa	Adaptador de middleware Koa
pompelmi/next	Adaptador de rota de API Next.js
pompelmi/nitro	Adaptador Nuxt/Nitro
pompelmi/fastify	Adaptador de plugin Fastify

Configuração do Scanner

Opção	Descrição
maxFileSize: '10mb'	Tamanho máximo de arquivo permitido
allowedExtensions: ['.pdf', '.png']	Lista branca de extensões de arquivo permitidas
blockedExtensions: ['.exe', '.bat']	Lista negra de extensões bloqueadas
allowedMimeTypes: ['image/png']	Lista branca de tipos MIME permitidos
scanTimeout: 30000	Timeout de scan em milissegundos
tempDir: '/tmp/pompelmi'	Diretório temporário para scanning
preserveOriginalName: true	Manter nome de arquivo original

Integração YARA

Opção	Descrição
yara: { enabled: true }	Habilitar escaneamento de regra YARA
yara: { rules: './rules/' }	Caminho para diretório de regras YARA customizadas
yara: { builtinRules: true }	Usar regras de detecção de malware built-in
yara: { timeout: 10000 }	Timeout de scan YARA
Arquivo de regras YARA customizada	Escrever arquivos .yar para detecção customizada

Proteção de Arquivo

Opção	Descrição
archive: { enabled: true }	Habilitar inspeção de arquivo
archive: { maxDepth: 3 }	Profundidade máxima de recursão para arquivos aninhados
archive: { maxFiles: 100 }	Máximo de arquivos dentro de arquivo
archive: { maxRatio: 100 }	Relação de compressão máxima (proteção contra zip bomb)
archive: { maxSize: '100mb' }	Tamanho total máximo extraído
archive: { formats: ['zip', 'tar', 'gz'] }	Formatos de arquivo suportados

Políticas de Segurança

Política	Descrição
policy: 'strict'	Bloquear qualquer coisa suspeita (recomendado)
policy: 'moderate'	Bloquear malware conhecido, avisar em suspeito
policy: 'permissive'	Bloquear apenas malware confirmado
Função de política customizada	Definir lógica customizada de aceitar/rejeitar

Validação de Tipo MIME

Verificação	Descrição
Validação de extensão	Verificar extensão de arquivo contra lista permitida
Detecção de magic byte	Verificar tipo de arquivo por bytes de conteúdo
Verificação de tipo MIME	Verificação de tipo MIME lado do servidor
Detecção de extensão dupla	Pegar truques file.pdf.exe
Detecção de null byte	Bloquear injeção de null byte em nomes de arquivo
Incompatibilidade de conteúdo	Detectar incompatibilidades entre extensão e conteúdo

Event Hooks

Evento	Descrição
scanner.on('scan:start', fn)	Disparado quando scan começa
scanner.on('scan:complete', fn)	Disparado quando scan termina
scanner.on('scan:reject', fn)	Disparado quando arquivo é rejeitado
scanner.on('scan:accept', fn)	Disparado quando arquivo passa em todas as verificações
scanner.on('scan:error', fn)	Disparado em erro de scanning
scanner.on('yara:match', fn)	Disparado quando regra YARA corresponde

Resultados de Scan

Propriedade	Descrição
result.safe	Booleano: arquivo passou em todas as verificações
result.threats	Array de ameaças detectadas
result.mimeType	Tipo MIME detectado
result.extension	Extensão de arquivo
result.size	Tamanho de arquivo em bytes
result.hash	Hash SHA-256 do arquivo
result.scanTime	Tempo levado para scan (ms)
result.yaraMatches	Correspondências de regra YARA (se habilitado)

Exemplo de Middleware 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',
});

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

// Scanning manual
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,
    });
  }

  // Processar arquivo seguro...
});

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

Exemplo de Rota 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 });
});

Escaneamento por CLI

Comando	Descrição
npx pompelmi scan <file>	Escanear arquivo único
npx pompelmi scan ./uploads/	Escanear diretório de arquivos
npx pompelmi scan --yara <file>	Escanear com regras YARA
npx pompelmi scan --json <file>	Saída de resultados como JSON
npx pompelmi rules list	Listar regras YARA disponíveis
npx pompelmi rules update	Atualizar regras YARA built-in

Dicas e Boas Práticas

Dica	Descrição
Usar política strict em produção	Rejeitar qualquer coisa suspeita
Habilitar regras YARA	Detectar assinaturas de malware conhecido
Definir limites de arquivo	Prevenir zip bombs e payloads aninhados
Validar tipos MIME no servidor	Não confiar em Content-Type do cliente
Verificar extensões duplas	Bloquear padrões file.pdf.exe
Definir limites de tamanho razoáveis	Prevenir esgotamento de recursos
Escanear na memória	Evitar escrever arquivos não confiáveis no disco
Monitorar eventos de scan	Registrar e alertar em rejeições
Atualizar regras YARA regularmente	Manter-se atualizado com inteligência de ameaças
Usar listas de permissão sobre listas negras	Whitelist é mais seguro que blacklist