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.

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.