Comandi Pompelmi

Comandi completi di Pompelmi per la scansione della sicurezza dei caricamenti di file per la protezione delle applicazioni Node.js.

Installazione

Comando	Descrizione
npm install pompelmi	Installa Pompelmi tramite npm
yarn add pompelmi	Installa Pompelmi tramite Yarn
pnpm add pompelmi	Installa Pompelmi tramite pnpm
bun add pompelmi	Installa Pompelmi tramite Bun

Configurazione di Base (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 });
});

Adattatori di Framework

Framework	Descrizione
pompelmi/express	Adattatore middleware Express.js
pompelmi/koa	Adattatore middleware Koa
pompelmi/next	Adattatore route API Next.js
pompelmi/nitro	Adattatore Nuxt/Nitro
pompelmi/fastify	Adattatore plugin Fastify

Configurazione dello Scanner

Opzione	Descrizione
maxFileSize: '10mb'	Dimensione massima dei file consentita
allowedExtensions: ['.pdf', '.png']	Whitelist delle estensioni di file consentite
blockedExtensions: ['.exe', '.bat']	Blacklist delle estensioni di file bloccate
allowedMimeTypes: ['image/png']	Whitelist dei tipi MIME consentiti
scanTimeout: 30000	Timeout della scansione in millisecondi
tempDir: '/tmp/pompelmi'	Directory temporanea per la scansione
preserveOriginalName: true	Mantieni il nome file originale

Integrazione YARA

Opzione	Descrizione
yara: { enabled: true }	Abilita la scansione delle regole YARA
yara: { rules: './rules/' }	Percorso della directory delle regole YARA personalizzate
yara: { builtinRules: true }	Usa le regole predefinite di rilevamento malware
yara: { timeout: 10000 }	Timeout della scansione YARA
File regole YARA personalizzate	Scrivi file .yar per il rilevamento personalizzato

Protezione dell’Archivio

Opzione	Descrizione
archive: { enabled: true }	Abilita l’ispezione dell’archivio
archive: { maxDepth: 3 }	Profondità massima di ricorsione per archivi annidati
archive: { maxFiles: 100 }	Numero massimo di file all’interno dell’archivio
archive: { maxRatio: 100 }	Rapporto di compressione massimo (protezione da zip bomb)
archive: { maxSize: '100mb' }	Dimensione totale massima estratta
archive: { formats: ['zip', 'tar', 'gz'] }	Formati di archivio supportati

Politiche di Sicurezza

Politica	Descrizione
policy: 'strict'	Blocca qualsiasi cosa sospetta (consigliato)
policy: 'moderate'	Blocca il malware noto, avvisa sul sospetto
policy: 'permissive'	Blocca solo il malware confermato
Funzione politica personalizzata	Definisci la tua logica di accettazione/rifiuto

Validazione del Tipo MIME

Controllo	Descrizione
Validazione dell’estensione	Verifica l’estensione del file rispetto alla whitelist
Rilevamento del byte magico	Verifica il tipo di file mediante i byte di contenuto
Verifica del tipo MIME	Controllo del tipo MIME lato server
Rilevamento dell’estensione doppia	Cattura i trucchi file.pdf.exe
Rilevamento del byte null	Blocca l’iniezione del byte null nei nomi file
Mancata corrispondenza Content-Type	Rileva mancate corrispondenze estensione/contenuto

Hook di Evento

Evento	Descrizione
scanner.on('scan:start', fn)	Attivato all’inizio della scansione
scanner.on('scan:complete', fn)	Attivato al termine della scansione
scanner.on('scan:reject', fn)	Attivato quando il file viene rifiutato
scanner.on('scan:accept', fn)	Attivato quando il file supera tutti i controlli
scanner.on('scan:error', fn)	Attivato in caso di errore di scansione
scanner.on('yara:match', fn)	Attivato quando una regola YARA corrisponde

Risultati della Scansione

Proprietà	Descrizione
result.safe	Booleano: il file ha superato tutti i controlli
result.threats	Array di minacce rilevate
result.mimeType	Tipo MIME rilevato
result.extension	Estensione del file
result.size	Dimensione del file in byte
result.hash	Hash SHA-256 del file
result.scanTime	Tempo impiegato per la scansione (ms)
result.yaraMatches	Corrispondenze della regola YARA (se abilitate)

Esempio 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',
});

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

// Scansione manuale
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,
    });
  }

  // Elabora il file sicuro...
});

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

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

Scansione CLI

Comando	Descrizione
npx pompelmi scan <file>	Scansiona un singolo file
npx pompelmi scan ./uploads/	Scansiona una directory di file
npx pompelmi scan --yara <file>	Scansiona con le regole YARA
npx pompelmi scan --json <file>	Esporta i risultati come JSON
npx pompelmi rules list	Elenca le regole YARA disponibili
npx pompelmi rules update	Aggiorna le regole YARA predefinite

Suggerimenti e Best Practice

Suggerimento	Descrizione
Usa una politica ristretta in produzione	Rifiuta qualsiasi cosa sospetta
Abilita le regole YARA	Rileva le firme di malware conosciute
Imposta i limiti dell’archivio	Previeni i zip bomb e i payload annidati
Convalida i tipi MIME lato server	Non fidarti del Content-Type del client
Verifica le estensioni doppie	Blocca i modelli file.pdf.exe
Imposta i limiti di dimensione ragionevoli	Previeni l’esaurimento delle risorse
Scansiona in memoria	Evita di scrivere file non affidabili su disco
Monitora gli eventi di scansione	Registra e avvisa sui rifiuti
Aggiorna regolarmente le regole YARA	Rimani aggiornato con l’intelligence sulle minacce
Usa le whitelist rispetto alle blacklist	La lista bianca è più sicura della blacklist