secure-file-check

CLI + API for file type validation and suspicious Office detection

A lightweight utility to validate file types by comparing extensions against magic bytes and detecting potentially malicious Office documents (e.g., VBA macros). This tool is designed for security-conscious Node.js applications that handle user uploads, ensuring that a file is exactly what it claims to be.

Features

• Magic Byte Validation: Verifies file content against extensions to prevent spoofing.
• Suspicious Office Detection: Identifies the presence of VBA projects or macros in documents like .docx or .xlsx.
• Parallel Processing: Scans folders in parallel using system CPU cores for maximum speed.
• Structured Output: Emits JSON or JSON-lines for easy integration with CI/CD and log aggregators.
• Audit Logging: Writes structured JSON audit lines to stderr or a dedicated log file.
• Supported Types: png, jpg, jpeg, pdf, docx, xlsx, gif, bmp, tiff, mp3, wav, svg.

Installation

Install the package using your preferred manager:

# npm
npm install --save secure-file-check

# yarn
yarn add secure-file-check

# pnpm
pnpm add secure-file-check

# run without installing via npx
npx secure-file-check --file=path/to/file

CLI Usage & Output

The CLI allows for single-file checks or recursive folder scans.

1. Scan a single file

secure-file-check --file=path/to/file

Example stdout:

{"timestamp":"2026-03-24T09:49:49.386Z","file":"uploads/a.png","status":"valid","ext":"png","size":1024,"suspicious":false}

2. Scan a folder

secure-file-check --folder=uploads

Example stdout (per-file JSON lines):

{"timestamp":"2026-03-24T09:49:49.405Z","file":"uploads/1.png","status":"valid","ext":"png","size":1024,"suspicious":false}
{"timestamp":"2026-03-24T09:49:49.406Z","file":"uploads/2.jpg","status":"valid","ext":"jpg","size":2048,"suspicious":false}
{"timestamp":"2026-03-24T09:49:49.407Z","file":"uploads/fake.docx","status":"invalid","ext":"docx","size":512,"reason":"Invalid ZIP (no EOCD)"}

3. JSON output for folder scan

Use --json to output a single formatted JSON array (great for CI).

secure-file-check --folder=uploads --json

4. Audit log

The CLI writes structured JSON audit lines to stderr. Use --log=FILE to append these audit lines to a specific file.

{"timestamp":"2026-03-24T09:49:49.386Z","file":"uploads/a.png","status":"valid"}
{"timestamp":"2026-03-24T09:49:49.390Z","file":"uploads/fake.png","status":"invalid","reason":"File content invalid"}

CLI Options

| Option | Description | | :--- | :--- | | --file=PATH | Validate a single file. | | --folder=PATH | Validate files recursively in a folder. | | --allow=ext1,ext2 | Restrict allowed extensions (comma-separated, no dots). | | --ignore=PATTERN | Ignore files/folders matching a specific pattern. | | --json | Output results as a single JSON array on stdout. | | --log=FILE | Append structured audit log lines to a file. | | --parallel=N | Specify number of parallel scans (defaults to CPU cores). | | --fail-fast | Exit immediately with code 1 on the first invalid file. | | --quiet | Suppress human-readable output and summaries. | | --report=FILE | Write a JSON results report to FILE (artifact for CI). | | --ci | Shortcut for CI: implies --json and --fail-fast. |

Exit codes:

• 0 — all files valid
• 1 — at least one file invalid or an error occurred

Allowed File Types

The CLI and API both support restricting scans to an explicit whitelist of file extensions. Default allowed types: png, jpg, jpeg, pdf, docx, xlsx, gif, bmp, tiff, mp3, wav, svg.

CLI example (allow only images):

secure-file-check --folder=uploads --allow=png,jpg,gif,svg

Programmatic API

Import the validateFile function to integrate security checks directly into your Node.js backend.

import { validateFile } from 'secure-file-check';

const res = await validateFile('/path/to/file', {
  allowedTypes: ['png','jpg','pdf'],
  maxSize: 10 * 1024 * 1024, // 10MB
  detectSuspicious: true,
});

console.log(res);
// Output: { ext: 'png', size: 1024, suspicious: false, status: 'valid' }

Integration Example

Example of validating a multipart file upload (e.g., in Next.js/Express):

import formidable from 'formidable';
import { validateFile } from 'secure-file-check';
import fs from 'fs/promises';

export default async function handler(req, res) {
  const form = new formidable.IncomingForm({ uploadDir: '/tmp' });
  
  const { files } = await new Promise((resolve, reject) => {
    form.parse(req, (err, fields, files) => (err ? reject(err) : resolve({ files })));
  });

  const filepath = files.file?.filepath || files.file?.path;
  const validation = await validateFile(filepath);

  if (validation.status === 'invalid' || validation.suspicious) {
    await fs.unlink(filepath); // Remove unsafe file
    return res.status(400).json({ error: 'File validation failed' });
  }

  res.status(200).json(validation);
}

Automation & Background Scanning

For automated background audits, use the following helper script to manage logs and timestamped results.

scripts/scan-uploads.sh

#!/usr/bin/env bash
set -euo pipefail

FOLDER=${1:-uploads}
OUTDIR=${2:-./scan-output}
PARALLEL=${3:-4}

mkdir -p "$OUTDIR"
TIMESTAMP=$(date -u +%Y%m%dT%H%M%SZ)
RESULTS="$OUTDIR/results-$TIMESTAMP.json"
LOG="$OUTDIR/scan-$TIMESTAMP.log"

echo "Scanning folder: $FOLDER"
echo "Results -> $RESULTS"
echo "Audit log -> $LOG"

# Call the package via npx
npx secure-file-check --folder="$FOLDER" --json --log="$LOG" --parallel="$PARALLEL" > "$RESULTS"

echo "Done"

Scheduling with Cron

Add this to your crontab to run an hourly audit:

0 * * * * /usr/bin/env bash /path/to/scripts/scan-uploads.sh /var/www/uploads /var/log/secure-check

Development

• Testing: Run the suite locally with npm test.
• Architecture:
  • bin/cli.js: CLI entrypoint.
  • src/validator.js: Core validation logic.
  • src/detectors.js: Magic-byte signature matching.
  • src/zip.js: Office/ZIP structure parsing for macro detection.

Keywords

node.js, file-validation, security, magic-bytes, antivirus, vba-detection, macro-detection, malware-analysis, file-upload-security, npm-package, cli-tool, office-security, mime-type-checker, cybersecurity, file-signature, upload-scanner, devsecops, cybersecurity, file-signature, upload-scanner, devsecops, nextjs-security, express-security, ci-cd-integration

License

MIT