secure-file-validator

Library validasi file yang aman untuk Node.js yang melakukan pengecekan signature dan validasi konten. Library ini melindungi aplikasi dari unggahan file berbahaya dengan memvalidasi tipe file, memeriksa signature file, dan memindai pola mencurigakan.

Library ini dibangun mengikuti panduan keamanan standar industri:

• OWASP Unrestricted File Upload Prevention
• CWE-434: Unrestricted Upload of File with Dangerous Type
• NIST Security Guidelines for File Uploads

Fitur

• Validasi signature file yang aman
• Pemindaian pola konten untuk kode berbahaya
• Dukungan untuk berbagai tipe file (JPEG, PNG, GIF, PDF, SVG)
• Pemeriksaan keamanan bawaan untuk file PDF dan SVG
• Fitur whitelist untuk menangani deteksi false positive
• Tanpa dependensi
• Validasi ukuran file yang dapat dikustomisasi

Instalasi

npm install secure-file-validator

Penggunaan

Penggunaan Dasar (Batas default 5MB)

import { validateFile } from "secure-file-validator";

try {
  const result = await validateFile("path/ke/file/anda.pdf");

  if (result.status) {
    console.log("File valid:", result.message);
  } else {
    console.log("Validasi file gagal:", result.message);
  }
} catch (error) {
  console.error("Error:", error);
}

Batas Ukuran File Kustom

import { validateFile } from "secure-file-validator";

// Contoh: Set batas 10MB
const TEN_MB = 10 * 1024 * 1024;

try {
  const result = await validateFile("path/ke/file/anda.pdf", {
    maxSizeInBytes: TEN_MB,
  });

  if (result.status) {
    console.log("File valid:", result.message);
  } else {
    console.log("Validasi file gagal:", result.message);
  }
} catch (error) {
  console.error("Error:", error);
}

Whitelist PDF untuk Penanganan False Positive

Library ini menyertakan pemeriksaan keamanan untuk pola PDF yang berpotensi berbahaya. Namun, beberapa PDF yang sah mungkin mengandung pola seperti /Metadata/, /OpenAction/, atau /JS/ yang ditandai sebagai mencurigakan. Anda dapat menggunakan opsi pdfWhitelist untuk mengizinkan pola tertentu:

import { validateFile } from "secure-file-validator";

const result = await validateFile("path/ke/file.pdf", {
  pdfWhitelist: ["Metadata", "OpenAction", "JS"],
});

if (result.status) {
  console.log("File valid:", result.message);
} else {
  console.log("Validasi file gagal:", result.message);
}

Pola PDF yang tersedia untuk whitelist:

• Metadata - Metadata PDF (umumnya ditemukan di PDF yang sah)
• OpenAction - Aksi otomatis saat PDF dibuka
• JS - Singkatan JavaScript
• JavaScript - Kode JavaScript
• Launch - Aksi launch
• EmbeddedFile - File yang disematkan
• XFA - XML Forms Architecture
• Annots - Anotasi

Catatan: Hanya whitelist pola yang Anda percayai. Whitelist pola mengurangi pemeriksaan keamanan dan harus dilakukan dengan hati-hati berdasarkan kasus penggunaan spesifik Anda.

Tipe File yang Didukung

Referensi API

validateFile(filePath, options)

Fungsi validasi utama yang melakukan semua pemeriksaan.

Mengembalikan: Promise<{ status: boolean, message: string }>

validateFileContent(filePath, options)

Melakukan validasi khusus konten.

Mengembalikan: Promise<{ status: boolean, message: string }>

checkFileSignature(buffer, signatures)

Memeriksa buffer file terhadap signature yang diketahui.

Mengembalikan: boolean

Contoh Hasil

// Validasi berhasil
{
  status: true,
  message: "Content validation passed"
}

// Validasi gagal (ukuran file)
{
  status: false,
  message: "File size exceeds limit of 5MB"
}

// Validasi gagal (tipe file tidak valid)
{
  status: false,
  message: "Invalid file extension"
}

// Validasi gagal (konten berbahaya)
{
  status: false,
  message: "Suspicious pattern detected: /<script/i"
}

Keterbatasan

• Hanya mendukung tipe file yang ditentukan
• Tidak ada dukungan pemrosesan stream
• Konten file binary tidak dianalisis secara mendalam
• Pencocokan pola dilakukan pada representasi string file

Kontribusi

Kontribusi sangat diterima! Silakan ajukan Pull Request. Untuk perubahan besar, silakan buka issue terlebih dahulu untuk mendiskusikan apa yang ingin Anda ubah.

Lisensi

MIT

Untuk detail lebih lanjut, silakan kunjungi repositori GitHub.