filebouncer — Structural file security for Node.js,…

Pitch

Description

Comments

About this project

filebouncer provides robust file inspection for Node.js applications. By detecting structural threats, MIME mismatches, and risky file contents, it enhances the security of file uploads. Ideal for any application that processes untrusted files, it prioritizes safety without replacing traditional antivirus solutions.

filebouncer provides a robust solution for detecting file anomalies that may compromise application security. This tool is designed for structural file security within Node.js upload pipelines, ensuring that untrusted files do not contain hidden threats.

Key Features

Structural Analysis: Inspects uploaded files for metadata and structural threats, identifying issues such as MIME mismatches, unsafe archives, risky spreadsheet behaviors, and polyglot files that could lead to exploitation.

Command Line Interface (CLI): Easily scan any file without the need for application code:

npx @filebouncer/core ./your-file.jpg

Example output when a file is a polyglot (e.g., a JPEG that contains a ZIP):

filebouncer v0.6.1

File: polyglot.jpg
Size: 38137 bytes
Detected MIME: image/jpeg

Findings:
  high     POLYGLOT_DETECTED
           File appears to match more than one format (image/jpeg and application/zip @ 38115)

Result: BLOCK

Importance of Structural File Checks

Simply verifying a filename or Content-Type is insufficient. A file purported to be photo.jpg might actually contain another file format. For example, a concatenation of a valid JPEG and a valid ZIP archive can masquerade as an image:

photo.jpg + secret.zip
        ↓
   polyglot.jpg

This leads to security vulnerabilities that filebouncer is specifically designed to catch before further processing occurs.

Approach	Problem
Extension / MIME header only	Vulnerable to spoofing
Hand-rolled archive checks	Miss potential edge cases
Antivirus alone	Not equipped for structural upload issues
Heavy security platforms	Often excessive for a Node upload endpoint

How It Works

filebouncer integrates seamlessly into Express, Fastify, or other Node.js frameworks, providing lightweight, typed checks for file uploads. It is not a malware scanner like ClamAV but instead focuses on structural integrity to identify potential risks before they reach your main application logic.

Results and Behavior

The results from filebouncer are structured for clarity and can include findings such as MIME_MISMATCH, UNSAFE_ENTRY_PATH, and other threats. Scan failures are also recorded, ensuring that all potential issues are reported back to the application for review.

Installation and Usage

To install, run:

npm install @filebouncer/core

The configuration allows for defining custom scanners, input shapes, and strict MIME checks, making it highly adaptable to different use cases.

Conclusion

filebouncer is an essential tool for any Node.js application that manages file uploads. With its ability to detect various structural and metadata anomalies, it significantly enhances the security of upload processes, ensuring that applications are better protected against abusive and deceptive files.