upload_inspector 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f372382728dc5813c7186575d5fd9ddb9586b27fac0dd4719690892ab1d087a
+  data.tar.gz: 160855eb88dac78e04a30454b325359a5094caa653a9b05ca8d5c8e229be0c25
+SHA512:
+  metadata.gz: 0160d3f7ce788421176da0b9761e9e044f3207549ae409b887915cff1586c1961b17469496b244f5ec29ce08c2333c8fd14281360403e57a3ee236e18ac61d25
+  data.tar.gz: ea6d033d6ea7842113800683075320ab514a0ae1e83bce871ba59db189656ba72fb84be85f4455ea30c4b76eae167879a4aee5fd83017d272a3894a0fa556024

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: fail-closed inspection of PDF, OOXML (docx/pptx/xlsx) and zip uploads with a
+  resource-limited sandbox process.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Minh Doan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# upload_inspector
+
+Fail-closed structural inspection of untrusted uploaded files for any Ruby or Rails app.
+
+A file is accepted only when its structure is proven to match a known-safe shape. Anything unknown,
+unparsable, encrypted, oversized, or erroring is rejected. Pure Ruby (`marcel`, `rubyzip`), no AV engine,
+no native parsers, nothing is rendered or executed.
+
+> **Not an antivirus.** It blocks structural attack vectors (disguised executables, macros, PDF
+> JavaScript, OLE objects, remote templates, DDE, zip bombs). It does not detect malware signatures or
+> exploits hidden inside otherwise valid content. Pair it with an AV scanner (e.g. Amazon GuardDuty
+> Malware Protection for S3, endpoint AV) when you need that.
+
+## What it checks
+
+| Format | Checks |
+|---|---|
+| All | real type by magic bytes (Marcel) must be allowlisted; file extension must agree with content; size limit |
+| PDF (and PDF-based `.ai`) | rejects `/JavaScript /JS /Launch /EmbeddedFile(s) /RichMedia /XFA /SubmitForm /ImportData /GoToR /GoToE /Rendition`, hex-escaped spellings included, also inside compressed object streams; rejects encrypted PDFs and unsupported object-stream filters |
+| docx / pptx / xlsx | every part name must match an allowlist; rejects VBA, `embeddings/`, `activeX/`, `externalLinks/`, macro sheets, macro content types, DTDs, external relationships other than http(s)/mailto hyperlinks, Word DDE/INCLUDE/IMPORT/LINK/QUOTE fields, PowerPoint program/macro actions, Excel DDE formulas, non-UTF-8 XML |
+| zip | path traversal, symlinks, encrypted entries, duplicates, entry/total size and compression-ratio limits, nested archives; every member extracted (bounded) and inspected with the same policy |
+| Others | rejected unless listed in `allow_unverifiable` (type + extension check only) |
+
+## Install
+
+```ruby
+gem 'upload_inspector'
+```
+
+Requires Ruby >= 3.2.
+
+## Usage
+
+```ruby
+result = UploadInspector.check(
+  '/tmp/upload.pdf',
+  filename: 'design.pdf',                      # client-supplied name
+  allowed_types: %w[application/pdf application/zip],
+)
+
+result.safe?          # => true / false
+result.reason         # => :pdf_active_content, :type_not_allowed, ... (nil when safe)
+result.detail         # => human-readable hint
+result.detected_type  # => "application/pdf"
+```
+
+### Rails / Active Storage
+
+```ruby
+result = blob.open do |file|
+  UploadInspector.check(file.path, filename: blob.filename.to_s, allowed_types: ALLOWED_TYPES)
+end
+blob.purge_later unless result.safe?
+```
+
+Run it in a background job for large files.
+
+### Policy options
+
+| Option | Default |
+|---|---|
+| `allowed_types` | `['application/pdf']` |
+| `allow_unverifiable` | `[]` |
+| `max_file_size` | 500 MB |
+| `max_zip_entries` / `max_zip_entry_size` / `max_zip_total_size` | 5 000 / 200 MB / 1 GB |
+| `max_compression_ratio` | 100 (entries ≥ 1 MB) |
+| `max_inflate_size` | 50 MB per PDF object stream / OOXML XML part |
+| `timeout` / `cpu_limit` | 60 s / 60 s |
+| `memory_limit` | 1 GB (`RLIMIT_DATA`, Linux only) |
+
+## Sandbox
+
+By default (`sandbox: true`) inspection runs in a child Ruby process with CPU, memory (Linux) and
+wall-clock limits. A crash, hang or memory blow-up kills only the child and yields a rejection
+(`:timeout`, `:resource_limit`, `:inspection_failed`), so web/job workers are unaffected.
+It is resource isolation, not a security boundary (same OS user).
+
+## Development
+
+Tests build hostile-shaped samples in memory (no real malware, no AV test signatures).
+Run them in a container or CI rather than on a workstation with endpoint AV:
+
+```sh
+docker run --rm -v "$PWD":/src:ro ruby:3.3-slim \
+  bash -c 'cp -r /src /app && cd /app && bundle install && bundle exec rake test'
+```
+
+CI runs the suite on Ruby 3.2 / 3.3 / 3.4 against rubyzip 2.3 and 3.x.
+
+### Releasing
+
+1. Bump `lib/upload_inspector/version.rb`, update `CHANGELOG.md`, merge to `main`.
+2. Actions → **Release** → *Run workflow*. It runs CI, tags `vX.Y.Z` and publishes via
+   rubygems.org Trusted Publishing.
+
+## License
+
+MIT

data/lib/upload_inspector/inspector.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module UploadInspector
+  # Detects the real type of a file and routes it to the structural inspector for that format.
+  class Inspector
+    include Rejectable
+
+    PDF_MAGIC = '%PDF-'.b
+    ZIP_MAGIC = "PK\x03\x04".b
+
+    attr_reader :policy, :depth
+
+    def initialize(policy, depth: 0)
+      @policy = policy
+      @depth = depth
+    end
+
+    # Boundary method: always returns a Result, rejecting on any error (fail closed).
+    def call(path, filename:)
+      Result.accept(verify!(path, filename))
+    rescue Rejection => e
+      Result.reject(e.reason, e.detail, detected_type: @detected_type)
+    rescue StandardError => e
+      Result.reject(:inspection_failed, "#{e.class}: #{e.message}", detected_type: @detected_type)
+    end
+
+    # Raises Rejection when the file is not proven safe; returns the detected MIME type.
+    def verify!(path, filename)
+      check_size!(path)
+      @detected_type = detect_type(path, filename)
+      reject!(:type_not_allowed, @detected_type) unless policy.permitted_type?(@detected_type)
+      check_extension!(filename, @detected_type)
+      inspect_structure!(path, @detected_type)
+      @detected_type
+    end
+
+  private
+
+    def check_size!(path)
+      size = File.size(path)
+      reject!(:empty_file) if size.zero?
+      reject!(:too_large, "#{size} bytes") if size > policy.max_file_size
+    end
+
+    # Magic bytes win over the name; the name only refines a magic match (e.g. zip -> docx).
+    def detect_type(path, filename)
+      File.open(path, 'rb') { |io| Marcel::MimeType.for(io, name: filename.to_s) }
+    end
+
+    # The client-supplied extension must describe the same format, so a file cannot be
+    # stored as one type and opened downstream as another (e.g. a PDF named x.zip).
+    def check_extension!(filename, detected)
+      by_name = Marcel::MimeType.for(name: filename.to_s)
+      return if by_name == detected
+      return if Marcel::Magic.child?(detected, by_name) || Marcel::Magic.child?(by_name, detected)
+
+      reject!(:extension_mismatch, "#{File.extname(filename.to_s)} is #{by_name}, content is #{detected}")
+    end
+
+    def inspect_structure!(path, detected)
+      head = File.binread(path, 8)
+      if head.start_with?(PDF_MAGIC)
+        PdfInspector.new(policy).verify!(path)
+      elsif head.start_with?(ZIP_MAGIC) && policy.allowed_types.include?(detected)
+        ZipInspector.new(policy, depth:).verify!(path, detected)
+      elsif !policy.allow_unverifiable.include?(detected)
+        reject!(:unverifiable_type, detected)
+      end
+    end
+  end
+end

data/lib/upload_inspector/ooxml_inspector.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module UploadInspector
+  # Allowlist inspection of Office Open XML (docx / pptx / xlsx) parts.
+  #
+  # Every part name must match a known-safe pattern. XML parts are read (bounded) and
+  # rejected for macro content types, DTDs, external relationships (remote template /
+  # Follina-style OLE links), Word field codes that fetch or run things (DDE, INCLUDETEXT...),
+  # PowerPoint program/macro actions and Excel DDE formulas.
+  class OoxmlInspector
+    include Rejectable
+
+    SEGMENT = '[A-Za-z0-9_\-.]'
+    ALLOWED_PARTS = [
+      %r{\A\[Content_Types\]\.xml\z},
+      %r{\A(?:#{SEGMENT}+/)*_rels/#{SEGMENT}*\.rels\z},
+      %r{\A(?:word|ppt|xl|customXml|docProps)/(?:#{SEGMENT}+/)*#{SEGMENT}+\.xml\z},
+      %r{\A(?:word|ppt|xl)/media/#{SEGMENT}+\.(?:png|jpe?g|gif|bmp|tiff?|emf|wmf|svg|wdp|jxr)\z}i,
+      %r{\AdocProps/thumbnail\.(?:jpe?g|png|emf|wmf)\z}i,
+      %r{\A(?:word|ppt|xl)/fonts/#{SEGMENT}+\.(?:odttf|fntdata)\z}i,
+      %r{\A(?:word|ppt|xl)/printerSettings/printerSettings\d+\.bin\z},
+    ].freeze
+    FORBIDDEN_PARTS = %r{vbaProject|vbaData|/embeddings/|/activeX/|/externalLinks/|oleObject|/macrosheets/|/dialogsheets/|attachedToolbars|customUI}i
+
+    MACRO_CONTENT_TYPE = /macroEnabled|vbaProject|ms-office\.vba|activeX|oleObject/i
+    DTD = /<!DOCTYPE|<!ENTITY/i
+    PREFIX = '(?:[\w.\-]+:)?'
+    RELATIONSHIP = /<#{PREFIX}Relationship\b([^>]*)>/n
+    ATTRIBUTE = /([\w:.\-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/n
+    INSTR_TEXT = %r{<#{PREFIX}instrText\b[^>]*>(.*?)</#{PREFIX}instrText>}mn
+    FLD_SIMPLE = /<#{PREFIX}fldSimple\b[^>]*?\b#{PREFIX}instr\s*=\s*(?:"([^"]*)"|'([^']*)')/mn
+    DANGEROUS_FIELD = /(?<![A-Z])(?:DDE|DDEAUTO|INCLUDETEXT|INCLUDEPICTURE|IMPORT|LINK|QUOTE)(?![A-Z])/
+    PPT_ACTION = %r{ppaction://(?:program|macro|ole)}i
+    DDE_FORMULA = /<#{PREFIX}f\b[^>]*>[^<]*\|/n
+    SAFE_EXTERNAL_TARGET = /\A(?:https?|mailto):/i
+    XML_ENTITIES = { 'amp' => '&', 'lt' => '<', 'gt' => '>', 'quot' => '"', 'apos' => "'" }.freeze
+
+    def initialize(policy, zip_inspector)
+      @policy = policy
+      @zip_inspector = zip_inspector
+    end
+
+    def verify!(entries)
+      reject!(:ooxml_missing_content_types) unless entries.any? { |e| e.name == '[Content_Types].xml' }
+
+      entries.each do |entry|
+        next if entry.directory?
+
+        check_part_name!(entry.name)
+        inspect_xml!(entry) if entry.name.end_with?('.xml', '.rels')
+      end
+    end
+
+  private
+
+    attr_reader :policy, :zip_inspector
+
+    def check_part_name!(name)
+      reject!(:ooxml_forbidden_part, name) if name.match?(FORBIDDEN_PARTS)
+      reject!(:ooxml_unknown_part, name) unless ALLOWED_PARTS.any? { |pattern| name.match?(pattern) }
+    end
+
+    def inspect_xml!(entry)
+      name = entry.name
+      xml = zip_inspector.read_bounded(entry, policy.max_inflate_size)
+      # Office writes UTF-8; other encodings would let patterns below be bypassed.
+      reject!(:ooxml_unsupported_encoding, name) if xml.include?("\0") || xml.start_with?("\xFF\xFE".b, "\xFE\xFF".b)
+      reject!(:ooxml_dtd, name) if xml.match?(DTD)
+      reject!(:ooxml_program_action, name) if xml.match?(PPT_ACTION)
+
+      if name == '[Content_Types].xml'
+        reject!(:ooxml_macro_content_type, name) if xml.match?(MACRO_CONTENT_TYPE)
+      elsif name.end_with?('.rels')
+        check_relationships!(xml, name)
+      elsif name.start_with?('word/')
+        check_word_fields!(xml, name)
+      elsif name.start_with?('xl/')
+        reject!(:ooxml_dde_formula, name) if xml.match?(DDE_FORMULA)
+      end
+    end
+
+    # External targets are only allowed for plain web/mail hyperlinks.
+    def check_relationships!(xml, name)
+      xml.scan(RELATIONSHIP) do |(raw_attributes)|
+        attributes = parse_attributes(raw_attributes)
+        next unless attributes['TargetMode'].to_s.casecmp?('External')
+
+        type = attributes['Type'].to_s
+        target = attributes['Target'].to_s
+        next if type.end_with?('/hyperlink') && target.match?(SAFE_EXTERNAL_TARGET)
+
+        reject!(:ooxml_external_relationship, "#{name}: #{type.split('/').last} -> #{target}")
+      end
+    end
+
+    # Field instructions may be split across runs, so all pieces are joined before matching.
+    def check_word_fields!(xml, name)
+      pieces = xml.scan(INSTR_TEXT).flatten + xml.scan(FLD_SIMPLE).flatten.compact
+      return if pieces.empty?
+
+      instructions = pieces.map { |piece| decode_entities(piece) }.join.upcase
+      match = instructions.match(DANGEROUS_FIELD)
+      reject!(:ooxml_dangerous_field, "#{name}: #{match[0]}") if match
+    end
+
+    def parse_attributes(raw)
+      raw.scan(ATTRIBUTE).to_h do |key, double_quoted, single_quoted|
+        [key.split(':').last, decode_entities(double_quoted || single_quoted)]
+      end
+    end
+
+    def decode_entities(text)
+      text.to_s.b
+          .gsub(/&#x(\h+);/n) { codepoint_bytes(Regexp.last_match(1).hex) }
+          .gsub(/&#(\d+);/n) { codepoint_bytes(Regexp.last_match(1).to_i) }
+          .gsub(/&(amp|lt|gt|quot|apos);/n) { XML_ENTITIES[Regexp.last_match(1)] }
+    end
+
+    # Invalid code points become a marker that never matches an allowed value (fail closed).
+    def codepoint_bytes(codepoint)
+      [codepoint].pack('U').b
+    rescue RangeError
+      "�".b
+    end
+  end
+end

data/lib/upload_inspector/pdf_inspector.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module UploadInspector
+  # Rejects PDFs (and PDF-based formats such as .ai) that carry active content.
+  #
+  # Streams the raw bytes looking for dangerous name tokens (hex-escaped spellings
+  # like /J#61vaScript included), then inflates every compressed object stream
+  # (/Type /ObjStm), where those keys could otherwise hide. Nothing is rendered.
+  class PdfInspector
+    include Rejectable
+
+    CHUNK_SIZE = 4 * MEGABYTE
+    INFLATE_CHUNK_SIZE = 64 * 1024
+    OVERLAP = 256 # longer than the longest fully hex-escaped token
+    OBJECT_WINDOW = 8 * 1024
+
+    ACTIVE_NAMES = %w[
+      JavaScript JS Launch EmbeddedFile EmbeddedFiles RichMedia XFA
+      SubmitForm ImportData GoToR GoToE Rendition
+    ].freeze
+    PDF_DELIMITER = '(?=[\s\x00\/<>\[\]()%{}]|\z)'
+
+    # PDF name token matching both literal and #xx-escaped characters.
+    def self.name_pattern(name)
+      chars = name.chars.map do |char|
+        hex = format('%02x', char.ord).chars.map { |h| h.match?(/[a-f]/) ? "[#{h}#{h.upcase}]" : h }.join
+        "(?:#{Regexp.escape(char)}|##{hex})"
+      end
+      "/#{chars.join}#{PDF_DELIMITER}"
+    end
+
+    ACTIVE_PATTERN = Regexp.new(ACTIVE_NAMES.map { |n| name_pattern(n) }.join('|'), Regexp::NOENCODING)
+    ENCRYPT_PATTERN = Regexp.new(name_pattern('Encrypt'), Regexp::NOENCODING)
+    OBJSTM_PATTERN = Regexp.new(name_pattern('ObjStm'), Regexp::NOENCODING)
+    OBJECT_HEADER = /\d+\s+\d+\s+obj\b/n
+    STREAM_KEYWORD = /stream(?:\r\n|\n|\r)/n
+
+    def initialize(policy)
+      @policy = policy
+    end
+
+    def verify!(path)
+      object_stream_offsets = scan_raw!(path)
+      File.open(path, 'rb') do |file|
+        object_stream_offsets.each { |offset| inspect_object_stream!(file, offset) }
+      end
+    end
+
+  private
+
+    attr_reader :policy
+
+    # Returns byte offsets of every /ObjStm token.
+    def scan_raw!(path)
+      offsets = []
+      carry = ''.b
+      consumed = 0
+      File.open(path, 'rb') do |file|
+        while (chunk = file.read(CHUNK_SIZE))
+          buffer = carry + chunk
+          base = consumed - carry.bytesize
+          scan_tokens!(buffer)
+          buffer.scan(OBJSTM_PATTERN) { offsets << base + Regexp.last_match.begin(0) }
+          carry = tail(buffer)
+          consumed += chunk.bytesize
+        end
+      end
+      offsets.uniq
+    end
+
+    def scan_tokens!(buffer)
+      reject!(:pdf_encrypted, 'encrypted PDF cannot be inspected') if buffer.match?(ENCRYPT_PATTERN)
+      match = buffer.match(ACTIVE_PATTERN)
+      reject!(:pdf_active_content, decode_name(match[0])) if match
+    end
+
+    def inspect_object_stream!(file, offset)
+      start = [offset - OBJECT_WINDOW, 0].max
+      file.seek(start)
+      before = file.read(offset - start) || ''.b
+      header_index = before.rindex(OBJECT_HEADER) || reject!(:pdf_unparsable, 'object stream header not found')
+      file.seek(offset)
+      after = file.read(OBJECT_WINDOW) || ''.b
+      stream_match = after.match(STREAM_KEYWORD) || reject!(:pdf_unparsable, 'object stream data not found')
+
+      dictionary = before.byteslice(header_index..) + after.byteslice(0, stream_match.begin(0))
+      return unless compressed_object_stream?(dictionary)
+
+      inflate_and_scan!(file, offset + stream_match.end(0))
+    end
+
+    # Only a single plain FlateDecode filter is accepted; anything else cannot be verified.
+    # Returns false for an unfiltered stream (its bytes were already covered by the raw scan).
+    def compressed_object_stream?(dictionary)
+      reject!(:pdf_unparsable, 'object stream spans objects') if dictionary.match?(/endobj|endstream/n)
+      reject!(:pdf_unparsable, 'escaped names in object stream dictionary') if dictionary.include?('#')
+      reject!(:pdf_unparsable, 'object stream decode parameters') if dictionary.include?('/DecodeParms')
+
+      filters = dictionary.scan(%r{/Filter\s*(\[[^\]]*\]|/[A-Za-z0-9]+)}n).flatten
+      return false if filters.empty?
+      return true if filters.size == 1 && filters.first.gsub(/[\[\]\s]/n, '') == '/FlateDecode'
+
+      reject!(:pdf_unparsable, "unsupported object stream filter #{filters.join(' ')}")
+    end
+
+    def inflate_and_scan!(file, data_offset)
+      file.seek(data_offset)
+      inflater = Zlib::Inflate.new
+      inflated = 0
+      carry = ''.b
+      until inflater.finished?
+        chunk = file.read(INFLATE_CHUNK_SIZE) || reject!(:pdf_unparsable, 'truncated object stream')
+        output = inflater.inflate(chunk)
+        inflated += output.bytesize
+        reject!(:pdf_inflate_limit, "object stream exceeds #{policy.max_inflate_size} bytes") if inflated > policy.max_inflate_size
+        buffer = carry + output
+        scan_tokens!(buffer)
+        carry = tail(buffer)
+      end
+    rescue Zlib::Error => e
+      reject!(:pdf_unparsable, "object stream: #{e.message}")
+    ensure
+      inflater&.close
+    end
+
+    def tail(buffer)
+      buffer.bytesize > OVERLAP ? buffer.byteslice(-OVERLAP, OVERLAP) : buffer
+    end
+
+    def decode_name(token)
+      token.gsub(/#(\h\h)/n) { Regexp.last_match(1).hex.chr }
+    end
+  end
+end

data/lib/upload_inspector/policy.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module UploadInspector
+  MEGABYTE = 1024 * 1024
+
+  # Inspection limits and allowlists. Defaults are deliberately strict (PDF only).
+  #
+  # allowed_types      - MIME types whose structure this gem can verify (PDF family, OOXML, zip).
+  # allow_unverifiable - MIME types accepted on real-type + extension match only, because their
+  #                      content cannot be inspected (e.g. image/vnd.adobe.photoshop). Opt-in risk.
+  Policy = Data.define(
+    :allowed_types, :allow_unverifiable, :max_file_size,
+    :max_zip_entries, :max_zip_entry_size, :max_zip_total_size, :max_compression_ratio,
+    :max_inflate_size, :timeout, :memory_limit, :cpu_limit
+  )
+
+  class Policy
+    DEFAULTS = {
+      allowed_types: ['application/pdf'],
+      allow_unverifiable: [],
+      max_file_size: 500 * MEGABYTE,
+      max_zip_entries: 5_000,
+      max_zip_entry_size: 200 * MEGABYTE,
+      max_zip_total_size: 1024 * MEGABYTE,
+      max_compression_ratio: 100,
+      max_inflate_size: 50 * MEGABYTE, # per PDF object stream / per OOXML XML part
+      timeout: 60, # seconds, wall clock (sandbox only)
+      memory_limit: 1024 * MEGABYTE, # RLIMIT_DATA for the sandbox child; nil disables
+      cpu_limit: 60, # seconds, RLIMIT_CPU for the sandbox child; nil disables
+    }.freeze
+
+    def initialize(**options)
+      unknown = options.keys - DEFAULTS.keys
+      raise ArgumentError, "unknown policy option(s): #{unknown.join(', ')}" if unknown.any?
+
+      merged = DEFAULTS.merge(options)
+      merged[:allowed_types] = Array(merged[:allowed_types]).map(&:to_s).freeze
+      merged[:allow_unverifiable] = Array(merged[:allow_unverifiable]).map(&:to_s).freeze
+      super(**merged)
+    end
+
+    def permitted_type?(type)
+      allowed_types.include?(type) || allow_unverifiable.include?(type)
+    end
+  end
+end

data/lib/upload_inspector/result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module UploadInspector
+  # Outcome of an inspection. +reason+ is a Symbol (nil when safe), +detail+ a human-readable hint.
+  Result = Data.define(:safe, :reason, :detail, :detected_type) do
+    def self.accept(detected_type)
+      new(safe: true, reason: nil, detail: nil, detected_type:)
+    end
+
+    def self.reject(reason, detail = nil, detected_type: nil)
+      new(safe: false, reason: reason.to_sym, detail:, detected_type:)
+    end
+
+    def safe? = safe
+  end
+
+  # Raised internally by inspectors; converted to a rejected Result at the boundary.
+  class Rejection < StandardError
+    attr_reader :reason, :detail
+
+    def initialize(reason, detail = nil)
+      @reason = reason
+      @detail = detail
+      super([reason, detail].compact.join(': '))
+    end
+  end
+
+  # Shared helper for inspectors.
+  module Rejectable
+  private
+
+    def reject!(reason, detail = nil)
+      raise Rejection.new(reason, detail)
+    end
+  end
+end

data/lib/upload_inspector/sandbox.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'io/wait'
+require 'rbconfig'
+
+module UploadInspector
+  # Runs the inspection in a separate Ruby process with CPU, memory and wall-clock limits.
+  # A crash, hang or memory blow-up kills only the child and is reported as a rejection,
+  # so the host process (web server / job worker) is never affected.
+  #
+  # This is resource isolation, not a security boundary: the child runs as the same user.
+  # Parsing is pure Ruby and never executes file content, which keeps that risk low.
+  module Sandbox
+    LIB_DIR = File.expand_path('..', __dir__)
+    CHILD_SCRIPT = "require 'upload_inspector'; UploadInspector::Sandbox.child_main(ARGV.fetch(0))"
+    READ_CHUNK_SIZE = 16 * 1024
+    MEMORY_LIMIT_SUPPORTED = RUBY_PLATFORM.include?('linux')
+
+    module_function
+
+    def run(path, filename:, policy:)
+      reader, writer = IO.pipe
+      payload = JSON.generate(path: File.expand_path(path), filename: filename.to_s, policy: policy.to_h)
+      pid = Process.spawn(RbConfig.ruby, '-I', LIB_DIR, '-e', CHILD_SCRIPT, payload,
+                          spawn_options(policy, writer))
+      writer.close
+      collect(pid, reader, policy.timeout)
+    rescue SystemCallError => e
+      Result.reject(:sandbox_failed, e.message)
+    ensure
+      writer&.close unless writer&.closed?
+      reader&.close unless reader&.closed?
+    end
+
+    # Entry point inside the child process.
+    def child_main(payload)
+      input = JSON.parse(payload, symbolize_names: true)
+      policy = Policy.new(**input.fetch(:policy))
+      result = Inspector.new(policy).call(input.fetch(:path), filename: input.fetch(:filename))
+      $stdout.write(JSON.generate(result.to_h))
+    rescue NoMemoryError
+      $stdout.write(JSON.generate(Result.reject(:resource_limit, 'memory limit').to_h))
+    end
+
+    def spawn_options(policy, writer)
+      options = { out: writer, err: File::NULL, in: File::NULL, pgroup: true, chdir: Dir.tmpdir }
+      # RLIMIT_DATA is enforced on Linux (production containers); macOS rejects lowering it.
+      options[:rlimit_data] = policy.memory_limit if policy.memory_limit && MEMORY_LIMIT_SUPPORTED
+      options[:rlimit_cpu] = policy.cpu_limit if policy.cpu_limit
+      options
+    end
+
+    def collect(pid, reader, timeout)
+      output = read_until_eof(reader, timeout)
+      if output.nil?
+        kill(pid)
+        return Result.reject(:timeout, "exceeded #{timeout}s")
+      end
+
+      _, status = Process.wait2(pid)
+      return Result.reject(:resource_limit, "child killed by signal #{status.termsig}") if status.signaled?
+      return Result.reject(:inspection_failed, "child exited with status #{status.exitstatus}") unless status.success?
+
+      parse(output)
+    end
+
+    # Returns nil when the deadline passes before the child closes its output.
+    def read_until_eof(reader, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      output = +''
+      loop do
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return nil if remaining <= 0
+        next unless reader.wait_readable(remaining)
+
+        chunk = reader.read_nonblock(READ_CHUNK_SIZE, exception: false)
+        return output if chunk.nil?
+
+        output << chunk unless chunk == :wait_readable
+      end
+    end
+
+    def kill(pid)
+      Process.kill(:KILL, -pid)
+    rescue Errno::ESRCH
+      nil
+    ensure
+      Process.wait(pid) rescue Errno::ECHILD # rubocop:disable Style/RescueModifier
+    end
+
+    def parse(output)
+      data = JSON.parse(output, symbolize_names: true)
+      Result.new(safe: data.fetch(:safe) == true, reason: data[:reason]&.to_sym,
+                 detail: data[:detail], detected_type: data[:detected_type])
+    rescue JSON::ParserError, KeyError
+      Result.reject(:inspection_failed, 'unreadable sandbox output')
+    end
+  end
+end

data/lib/upload_inspector/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UploadInspector
+  VERSION = '0.1.0'
+end

data/lib/upload_inspector/zip_inspector.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+
+module UploadInspector
+  # Validates zip containers. OOXML documents are checked part by part; plain archives
+  # have every member extracted (size-bounded, to a temp dir) and inspected with the same
+  # policy. Archives inside archives are rejected.
+  class ZipInspector
+    include Rejectable
+
+    OOXML_TYPES = %w[
+      application/vnd.openxmlformats-officedocument.wordprocessingml.document
+      application/vnd.openxmlformats-officedocument.presentationml.presentation
+      application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
+    ].freeze
+    NESTED_ARCHIVE = /\.(?:zip|7z|rar|gz|tgz|bz2|xz|zst|tar|jar|war|ear|apk|ipa|cab|iso|img|dmg|vhdx?|arj|lzh|lha|z)\z/i
+    READ_CHUNK_SIZE = 64 * 1024
+    RATIO_CHECK_MIN_SIZE = MEGABYTE # tiny files compress extremely well legitimately
+
+    def initialize(policy, depth:)
+      @policy = policy
+      @depth = depth
+    end
+
+    def verify!(path, detected_type)
+      Zip::File.open(path) do |zip|
+        entries = zip.entries
+        check_entries!(entries)
+        if OOXML_TYPES.include?(detected_type)
+          OoxmlInspector.new(policy, self).verify!(entries)
+        else
+          verify_archive_members!(entries)
+        end
+      end
+    rescue Zip::Error => e
+      reject!(:zip_unparsable, e.message)
+    end
+
+    # Reads a member fully into memory, never beyond +limit+ or its declared size.
+    def read_bounded(entry, limit)
+      reject!(:zip_inflate_limit, entry.name) if entry.size > limit
+      data = +''.b
+      each_chunk(entry) do |chunk|
+        data << chunk
+        reject!(:zip_inflate_limit, entry.name) if data.bytesize > limit
+      end
+      data
+    end
+
+  private
+
+    attr_reader :policy, :depth
+
+    def check_entries!(entries)
+      reject!(:zip_empty) if entries.empty?
+      reject!(:zip_too_many_entries, entries.size.to_s) if entries.size > policy.max_zip_entries
+      names = entries.map { |e| e.name.to_s.downcase }
+      reject!(:zip_duplicate_entry) if names.uniq.size != names.size
+
+      total = 0
+      entries.each do |entry|
+        check_entry!(entry)
+        total += entry.size.to_i
+        reject!(:zip_too_large, 'total uncompressed size') if total > policy.max_zip_total_size
+      end
+    end
+
+    def check_entry!(entry)
+      check_path!(entry.name.to_s)
+      reject!(:zip_encrypted_entry, entry.name) if entry.gp_flags.to_i.anybits?(1)
+      reject!(:zip_unsafe_path, "symlink #{entry.name}") if entry.symlink?
+      reject!(:zip_too_large, entry.name) if entry.size.to_i > policy.max_zip_entry_size
+      check_ratio!(entry)
+    end
+
+    def check_path!(name)
+      unsafe = name.empty? || name.include?("\0") || name.include?('\\') || name.start_with?('/') ||
+               name.match?(/\A[A-Za-z]:/) || name.split('/').include?('..')
+      reject!(:zip_unsafe_path, name.inspect) if unsafe
+    end
+
+    def check_ratio!(entry)
+      size = entry.size.to_i
+      return if size < RATIO_CHECK_MIN_SIZE
+
+      compressed = entry.compressed_size.to_i
+      return if compressed.positive? && size / compressed <= policy.max_compression_ratio
+
+      reject!(:zip_bomb, "#{entry.name} ratio exceeds #{policy.max_compression_ratio}")
+    end
+
+    def verify_archive_members!(entries)
+      reject!(:nested_archive, 'archive inside archive') if depth.positive?
+
+      Dir.mktmpdir('upload_inspector') do |dir|
+        entries.reject(&:directory?).each_with_index do |entry, index|
+          reject!(:nested_archive, entry.name) if entry.name.match?(NESTED_ARCHIVE)
+          member_path = File.join(dir, "member-#{index}")
+          extract_bounded!(entry, member_path)
+          verify_member!(member_path, entry.name)
+          File.delete(member_path)
+        end
+      end
+    end
+
+    def verify_member!(member_path, name)
+      Inspector.new(policy, depth: depth + 1).verify!(member_path, File.basename(name))
+    rescue Rejection => e
+      raise Rejection.new(e.reason, [name, e.detail].compact.join(': '))
+    end
+
+    # Actual inflated bytes must match the declared size (no lying headers).
+    def extract_bounded!(entry, destination)
+      written = 0
+      File.open(destination, 'wb') do |out|
+        each_chunk(entry) do |chunk|
+          written += chunk.bytesize
+          reject!(:zip_size_mismatch, entry.name) if written > entry.size.to_i
+          out.write(chunk)
+        end
+      end
+      reject!(:zip_size_mismatch, entry.name) if written != entry.size.to_i
+    end
+
+    def each_chunk(entry)
+      entry.get_input_stream do |io|
+        while (chunk = io.read(READ_CHUNK_SIZE)) && !chunk.empty?
+          yield chunk
+        end
+      end
+    end
+  end
+end

data/lib/upload_inspector.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'marcel'
+require 'zip'
+require 'zlib'
+
+require_relative 'upload_inspector/version'
+require_relative 'upload_inspector/result'
+require_relative 'upload_inspector/policy'
+require_relative 'upload_inspector/pdf_inspector'
+require_relative 'upload_inspector/ooxml_inspector'
+require_relative 'upload_inspector/zip_inspector'
+require_relative 'upload_inspector/inspector'
+require_relative 'upload_inspector/sandbox'
+
+# Fail-closed structural inspection of untrusted uploaded files.
+# Only content proven to match a known-safe structure is accepted; anything
+# unknown, unparsable, or erroring is rejected.
+module UploadInspector
+  # Inspects the file at +path+. Never raises on hostile input: always returns a Result.
+  #
+  #   UploadInspector.check('/tmp/x.pdf', filename: 'design.pdf', allowed_types: ['application/pdf'])
+  #
+  # +filename+ is the client-supplied name (its extension must agree with the real content).
+  # +sandbox+ runs the inspection in a resource-limited child process (default true).
+  # Other keywords are Policy options.
+  def self.check(path, filename:, sandbox: true, **policy_options)
+    policy = Policy.new(**policy_options)
+    return Sandbox.run(path, filename:, policy:) if sandbox
+
+    Inspector.new(policy).call(path, filename:)
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: upload_inspector
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Minh Doan
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: marcel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: |
+  Rejects uploaded files whose real type does not match the allowlist or the file extension,
+  PDFs with active content (JavaScript, launch actions, embedded files, also inside compressed
+  object streams), Office documents with macros, OLE objects, external relationships, DDE fields,
+  and dangerous zip archives. Runs in a resource-limited child process. Pure Ruby, no AV engine.
+email:
+- minhdpc@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/upload_inspector.rb
+- lib/upload_inspector/inspector.rb
+- lib/upload_inspector/ooxml_inspector.rb
+- lib/upload_inspector/pdf_inspector.rb
+- lib/upload_inspector/policy.rb
+- lib/upload_inspector/result.rb
+- lib/upload_inspector/sandbox.rb
+- lib/upload_inspector/version.rb
+- lib/upload_inspector/zip_inspector.rb
+homepage: https://github.com/akarui2004/upload_inspector
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  changelog_uri: https://github.com/akarui2004/upload_inspector/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/akarui2004/upload_inspector
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Fail-closed structural inspection of untrusted uploads (PDF, Office, zip).
+test_files: []