Pompelmi 명령어

Node.js 애플리케이션 보호를 위한 종합 Pompelmi 파일 업로드 보안 스캔 명령어입니다.

설치

명령어	설명
`npm install pompelmi`	npm을 통해 Pompelmi 설치
`yarn add pompelmi`	Yarn을 통해 Pompelmi 설치
`pnpm add pompelmi`	pnpm을 통해 Pompelmi 설치
`bun add pompelmi`	Bun을 통해 Pompelmi 설치

기본 설정 (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 });
});

프레임워크 어댑터

프레임워크	설명
`pompelmi/express`	Express.js 미들웨어 어댑터
`pompelmi/koa`	Koa 미들웨어 어댑터
`pompelmi/next`	Next.js API 경로 어댑터
`pompelmi/nitro`	Nuxt/Nitro 어댑터
`pompelmi/fastify`	Fastify 플러그인 어댑터

스캐너 설정

옵션	설명
`maxFileSize: '10mb'`	최대 허용 파일 크기
`allowedExtensions: ['.pdf', '.png']`	허용된 파일 확장자 화이트리스트
`blockedExtensions: ['.exe', '.bat']`	차단된 확장자 블랙리스트
`allowedMimeTypes: ['image/png']`	허용된 MIME 유형 화이트리스트
`scanTimeout: 30000`	스캔 타임아웃 (밀리초)
`tempDir: '/tmp/pompelmi'`	스캔을 위한 임시 디렉토리
`preserveOriginalName: true`	원래 파일명 유지

YARA 통합

옵션	설명
`yara: { enabled: true }`	YARA 규칙 스캔 활성화
`yara: { rules: './rules/' }`	사용자 정의 YARA 규칙 디렉토리 경로
`yara: { builtinRules: true }`	기본 제공 악성코드 탐지 규칙 사용
`yara: { timeout: 10000 }`	YARA 스캔 타임아웃
Custom YARA rules file	사용자 정의 탐지를 위한 `.yar` 파일 작성

아카이브 보호

옵션	설명
`archive: { enabled: true }`	아카이브 검사 활성화
`archive: { maxDepth: 3 }`	중첩 아카이브의 최대 재귀 깊이
`archive: { maxFiles: 100 }`	아카이브 내 최대 파일
`archive: { maxRatio: 100 }`	최대 압축 비율 (집 폭탄 보호)
`archive: { maxSize: '100mb' }`	최대 총 추출 크기
`archive: { formats: ['zip', 'tar', 'gz'] }`	지원되는 아카이브 형식

보안 정책

정책	설명
`policy: 'strict'`	의심스러운 항목 차단 (권장)
`policy: 'moderate'`	알려진 악성코드 차단, 의심스러운 항목 경고
`policy: 'permissive'`	확인된 악성코드만 차단
Custom policy function	고유한 허락/거부 논리 정의

MIME 유형 검증

확인	설명
Extension validation	파일 확장자를 허용 목록과 확인
Magic byte detection	콘텐츠 바이트로 파일 유형 확인
MIME type verification	서버 측 MIME 유형 확인
Double extension detection	`file.pdf.exe` 트릭 포착
Null byte detection	파일명에서 null 바이트 주입 차단
Content-Type mismatch	확장자/콘텐츠 불일치 감지

이벤트 훅

이벤트	설명
`scanner.on('scan:start', fn)`	스캔 시작 시 발생
`scanner.on('scan:complete', fn)`	스캔 완료 시 발생
`scanner.on('scan:reject', fn)`	파일 거부 시 발생
`scanner.on('scan:accept', fn)`	파일이 모든 확인을 통과할 때 발생
`scanner.on('scan:error', fn)`	스캔 오류 시 발생
`scanner.on('yara:match', fn)`	YARA 규칙이 일치할 때 발생

스캔 결과

속성	설명
`result.safe`	불: 파일이 모든 확인을 통과함
`result.threats`	감지된 위협 배열
`result.mimeType`	감지된 MIME 유형
`result.extension`	파일 확장자
`result.size`	파일 크기 (바이트)
`result.hash`	파일의 SHA-256 해시
`result.scanTime`	스캔 시간 (ms)
`result.yaraMatches`	YARA 규칙 일치 (활성화된 경우)

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

// 미들웨어로서
app.post('/upload', scanner.middleware(), handleUpload);

// 수동 스캔
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,
    });
  }

  // 안전한 파일 처리...
});

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

Next.js API 경로 예제

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

CLI 스캔

명령어	설명
`npx pompelmi scan <file>`	단일 파일 스캔
`npx pompelmi scan ./uploads/`	파일 디렉토리 스캔
`npx pompelmi scan --yara <file>`	YARA 규칙으로 스캔
`npx pompelmi scan --json <file>`	결과를 JSON으로 출력
`npx pompelmi rules list`	사용 가능한 YARA 규칙 나열
`npx pompelmi rules update`	기본 제공 YARA 규칙 업데이트

팁 및 모범 사례

팁	설명
Use strict policy in production	의심스러운 항목 거부
Enable YARA rules	알려진 악성코드 서명 탐지
Set archive limits	집 폭탄 및 중첩 페이로드 방지
Validate MIME types server-side	클라이언트 Content-Type 신뢰하지 않기
Check double extensions	`file.pdf.exe` 패턴 차단
Set reasonable size limits	리소스 고갈 방지
Scan in memory	신뢰할 수 없는 파일을 디스크에 쓰지 않기
Monitor scan events	거부에 대한 로그 및 경고
Update YARA rules regularly	위협 인텔리전스 최신 상태 유지
Use allowlists over blocklists	블랙리스트보다 화이트리스트가 더 안전