Commandes Pompelmi

Commandes complètes de l’outil Pompelmi de balayage de sécurité des téléchargements de fichiers pour la protection des applications Node.js.

Installation

Commande	Description
`npm install pompelmi`	Installer Pompelmi via npm
`yarn add pompelmi`	Installer Pompelmi via Yarn
`pnpm add pompelmi`	Installer Pompelmi via pnpm
`bun add pompelmi`	Installer Pompelmi via Bun

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

Adaptateurs de Framework

Framework	Description
`pompelmi/express`	Adaptateur de middleware Express.js
`pompelmi/koa`	Adaptateur de middleware Koa
`pompelmi/next`	Adaptateur de route API Next.js
`pompelmi/nitro`	Adaptateur Nuxt/Nitro
`pompelmi/fastify`	Adaptateur de plugin Fastify

Configuration du Scanner

Option	Description
`maxFileSize: '10mb'`	Taille maximale de fichier autorisée
`allowedExtensions: ['.pdf', '.png']`	Liste blanche des extensions autorisées
`blockedExtensions: ['.exe', '.bat']`	Liste noire des extensions bloquées
`allowedMimeTypes: ['image/png']`	Liste blanche des types MIME autorisés
`scanTimeout: 30000`	Délai d’expiration du scan en millisecondes
`tempDir: '/tmp/pompelmi'`	Répertoire temporaire pour le scanning
`preserveOriginalName: true`	Conserver le nom de fichier original

Intégration YARA

Option	Description
`yara: { enabled: true }`	Activer le scan des règles YARA
`yara: { rules: './rules/' }`	Chemin vers le répertoire des règles YARA personnalisées
`yara: { builtinRules: true }`	Utiliser les règles de détection de malwares intégrées
`yara: { timeout: 10000 }`	Délai d’expiration du scan YARA
Custom YARA rules file	Écrire des fichiers `.yar` pour la détection personnalisée

Protection d’Archives

Option	Description
`archive: { enabled: true }`	Activer l’inspection d’archives
`archive: { maxDepth: 3 }`	Profondeur maximale de récursion pour les archives imbriquées
`archive: { maxFiles: 100 }`	Nombre maximal de fichiers dans une archive
`archive: { maxRatio: 100 }`	Rapport de compression maximal (protection contre les bombes zip)
`archive: { maxSize: '100mb' }`	Taille totale maximale extraite
`archive: { formats: ['zip', 'tar', 'gz'] }`	Formats d’archives supportés

Politiques de Sécurité

Politique	Description
`policy: 'strict'`	Bloquer tout ce qui est suspect (recommandé)
`policy: 'moderate'`	Bloquer les malwares connus, avertir sur les suspects
`policy: 'permissive'`	Bloquer uniquement les malwares confirmés
Custom policy function	Définir votre propre logique accepter/rejeter

Validation du Type MIME

Vérification	Description
Extension validation	Vérifier l’extension contre la liste blanche
Magic byte detection	Vérifier le type de fichier par octets de contenu
MIME type verification	Vérification du type MIME côté serveur
Double extension detection	Détecter les astuces `file.pdf.exe`
Null byte detection	Bloquer l’injection d’octets nuls dans les noms
Content-Type mismatch	Détecter les incompatibilités extension/contenu

Hooks d’Événement

Événement	Description
`scanner.on('scan:start', fn)`	Déclenché au début du scan
`scanner.on('scan:complete', fn)`	Déclenché à la fin du scan
`scanner.on('scan:reject', fn)`	Déclenché quand le fichier est rejeté
`scanner.on('scan:accept', fn)`	Déclenché quand le fichier passe tous les contrôles
`scanner.on('scan:error', fn)`	Déclenché lors d’une erreur de scanning
`scanner.on('yara:match', fn)`	Déclenché quand une règle YARA correspond

Résultats du Scan

Propriété	Description
`result.safe`	Booléen: le fichier a passé tous les contrôles
`result.threats`	Tableau des menaces détectées
`result.mimeType`	Type MIME détecté
`result.extension`	Extension du fichier
`result.size`	Taille du fichier en octets
`result.hash`	Hash SHA-256 du fichier
`result.scanTime`	Temps de scan (ms)
`result.yaraMatches`	Correspondances de règles YARA (si activées)

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

// 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...
});

Exemple Adaptateur 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 };
});

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

Scanning CLI

Commande	Description
`npx pompelmi scan <file>`	Scanner un seul fichier
`npx pompelmi scan ./uploads/`	Scanner un répertoire de fichiers
`npx pompelmi scan --yara <file>`	Scanner avec les règles YARA
`npx pompelmi scan --json <file>`	Afficher les résultats en JSON
`npx pompelmi rules list`	Lister les règles YARA disponibles
`npx pompelmi rules update`	Mettre à jour les règles YARA intégrées

Conseils et Bonnes Pratiques

Conseil	Description
Use strict policy in production	Rejeter tout ce qui est suspect
Enable YARA rules	Détecter les signatures de malwares connues
Set archive limits	Prévenir les bombes zip et les charges imbriquées
Validate MIME types server-side	Ne pas faire confiance au Content-Type du client
Check double extensions	Bloquer les motifs `file.pdf.exe`
Set reasonable size limits	Prévenir l’épuisement des ressources
Scan in memory	Éviter d’écrire les fichiers non fiables sur le disque
Monitor scan events	Enregistrer et alerter sur les rejets
Update YARA rules regularly	Rester à jour avec l’intelligence des menaces
Use allowlists over blocklists	La liste blanche est plus sûre que la liste noire