malmal 0.4.0-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 828be05ba683c9884d41da8ffde51a01900da877a318094d952644e214b60a5b
+  data.tar.gz: 92fa55431c07a71f31aa7a9f65f7369cf0d170dcbf3a0ee7d3972801efbea98e
+SHA512:
+  metadata.gz: 33dc1e02ef51136f2ce357cd540dbfa3a7399b8eae47ecb5916dccb742735d01f458cce36c676bfc7ca2df20a81559e6f2b7e808733990c41fb6c9bb83953342
+  data.tar.gz: ed1f13aedf48df13ecdc537603d382ca7eed63eed4de0ac3927722b74bf7968d492156aabce80c49b0ac9a58edefe7bd5dcd1a9a4f4757d11b2777947412fa73

data/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 nguyenthuan155632
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nguyenthuan155632
+
+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,131 @@
+# malmal for Ruby
+
+The [malmal](https://github.com/nguyenthuan155632/malmal) upload scanner for any Ruby
+program. It calls `libmalmal_ffi` through the `ffi` gem, and the platform gems carry
+that library, so installing it needs no Rust. For Rails, see
+[malmal-rails](../malmal-rails/README.md).
+
+```ruby
+require "malmal"
+
+SCANNER = Malmal::Scanner.new          # build once, share between threads
+report = SCANNER.scan(upload, filename: "a.png", content_type: "image/png")
+reject(report.codes) unless report.clean?
+```
+
+Anything but `clean?`, including a `Malmal::ScanError`, means the file is not accepted.
+A scan releases the GVL, so the other threads of a Puma worker carry on while it runs.
+
+## Installing
+
+```bash
+bundle add malmal
+```
+
+RubyGems picks the gem for the machine:
+
+| Platform | For |
+|---|---|
+| `x86_64-linux-gnu`, `aarch64-linux-gnu` | Linux with glibc 2.17 or newer (Debian, Ubuntu, RHEL) |
+| `x86_64-linux-musl`, `aarch64-linux-musl` | Alpine |
+| `arm64-darwin`, `x86_64-darwin` | macOS |
+| `ruby` | anything else, with a library of your own at `MALMAL_LIBRARY` |
+
+The gem loads the library at `MALMAL_LIBRARY` if that is set, else the one it carries,
+else `libmalmal_ffi` from the system's library path. It has to be of the gem's version,
+except at `MALMAL_LIBRARY`; otherwise `Malmal::LoadError` says what was found. A library
+for the `ruby` gem is built from a checkout of malmal with:
+
+```bash
+cargo build --release -p malmal-ffi
+export MALMAL_LIBRARY=$PWD/target/release/libmalmal_ffi.so
+```
+
+Ruby 3.2 or newer.
+
+## Scanning
+
+```ruby
+scanner = Malmal::Scanner.new(
+  policy: :documents,                 # or :default, :strict
+  allow: %w[pdf.xfa],                 # codes that do not count against a file
+  types: %i[jpeg png pdf],            # accepted file types; every supported one if nil
+  hashlist: File.read("blocklist.txt"),
+  pdf_passwords: ["statement-password"],
+  max_size: 20 << 20, scan_timeout: 5, # also max_decompressed, max_pixels, max_depth
+  max_memory: 256 << 20,              # what one scan may hold; 512 MiB if not given
+  wait: 30                            # answer within 30 s whatever the file does
+)
+```
+
+An unknown option, policy, type or code raises `ArgumentError`. With `wait`, a scan that
+has not ended in time is reported with `limit.time`, never clean, and left running on
+its thread; `scanner.overdue` counts those, and above 0 the process is due a restart.
+
+`scan` takes a String or an IO. An IO is read up to `max_size` and one byte past it, so
+that a file too large is reported as such. The `Malmal::Report` it returns has `verdict`
+(`:clean`, `:suspicious` or `:malicious`), `clean?`, `suspicious?`, `malicious?`,
+`detected_type`, `declared_types`, `size`, `sha256`, `findings`, `codes` and `to_h`.
+Each `Malmal::Finding` has `code`, `severity` (`:info` to `:critical`), `message` and
+`offset`.
+
+## Rebuilding files
+
+`sanitize` scans and then writes a clean file anew from what it draws, so that nothing
+else is kept:
+
+```ruby
+begin
+  image = scanner.sanitize(upload, filename: "a.png", jpeg_quality: 85)
+rescue Malmal::Rejected => e       # the scan did not come back clean
+  reject(e.report.codes)
+rescue Malmal::NotRebuilt          # clean, but not a file that can be rebuilt
+  reject
+else
+  store(image.data, image.content_type, "a#{image.extension}")
+end
+```
+
+The type can change: a BMP, TIFF or ICO comes out as a PNG. `Malmal::Sanitized` has
+`data`, `file_type`, `content_type`, `extension`, `width`, `height`, `frames` and
+`report`. `sanitize` also takes `types`, `pdf_dpi`, `pdf_jpeg`, `pdf_text` and
+`pdf_vector_text`; PDFs are rebuilt only by a library built with `cdr-pdf`. Both
+exceptions are a `Malmal::SanitizeError`.
+
+## Speed
+
+A scan from Ruby costs 10 to 16 µs more than the same scan from Rust: the copy of the
+data, the report as JSON, and releasing the GVL. From some 20 KB up, the difference is
+within 5%. `ruby -Ilib bench/throughput.rb FILE...` measures it on your files.
+
+## With malmald
+
+`Malmal::Client` answers as `Scanner` does, from a running `malmald`. It is for
+deployments that want what only the daemon gives: the sandbox, and `--hard-timeout`
+ending a scan that does not end.
+
+```ruby
+client = Malmal::Client.new("http://127.0.0.1:8080", token: ENV["MALMAL_TOKEN"])
+client.scan(upload, filename: "a.png").clean?
+client.healthy?
+```
+
+The scanning options are then the daemon's flags. `sanitize` takes `types` only, checked
+against the type of the rebuilt file. A daemon that cannot be reached, or does not answer
+with a report, raises `Malmal::ScanError`.
+
+## Development
+
+```bash
+cargo build --release -p malmal-ffi
+cd bindings/ruby/malmal
+bundle install
+MALMAL_LIBRARY=../../../target/release/libmalmal_ffi.so bundle exec rake test
+```
+
+With `MALMALD` set to a `malmald` binary, the client tests run against it too.
+`bindings/ruby/build_gem.sh <rust-target>` builds a platform gem into `bindings/ruby/pkg`.
+
+## License
+
+MIT or Apache-2.0, at your option.

data/lib/malmal/client.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Malmal
+  # The scanner of a running malmald, over its HTTP endpoint. It answers as
+  # Scanner does, and is for deployments that want what only the daemon
+  # gives: the sandbox, and --hard-timeout ending a scan that does not.
+  #
+  #   client = Malmal::Client.new("http://127.0.0.1:8080", token: ENV["MALMAL_TOKEN"])
+  #   client.scan(upload, filename: "a.png").clean?
+  class Client
+    attr_reader :url
+
+    # +url+ is the daemon's base URL; +token+ the one it was started with
+    # (--token-file), if any. +open_timeout+ and +read_timeout+ are seconds;
+    # the read timeout has to cover the longest scan.
+    def initialize(url, token: nil, open_timeout: 5, read_timeout: 120)
+      @url = URI(url.to_s.chomp("/"))
+      @token = token
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # As Scanner#scan. Anything but an answer with a report raises ScanError.
+    def scan(data, filename: nil, content_type: nil)
+      response = post("/scan", data, filename, content_type)
+      body = parse(response)
+      unless response.code == "200" && body["ok"] && body["report"]
+        raise ScanError, "malmald did not scan the file: #{response.code} #{body["error"]}".strip
+      end
+
+      Report.from_h(body["report"])
+    end
+
+    # As Scanner#sanitize, with the daemon's own options of the rebuild
+    # (the --jpeg-quality and --pdf-* flags it was started with). +types+ is
+    # checked here, against the type of the rebuilt file: one of another type
+    # raises NotRebuilt. Any other option raises ArgumentError.
+    def sanitize(data, filename: nil, content_type: nil, types: nil, **options)
+      unless options.empty?
+        raise ArgumentError, "#{options.keys.join(", ")} cannot be sent to malmald; start the daemon with them instead"
+      end
+
+      response = post("/sanitize", data, filename, content_type)
+      case response.code
+      when "200"
+        file_type = Sanitized::CONTENT_TYPES.key(response["Content-Type"].to_s.split(";").first) || :unknown
+        if types && !Array(types).map(&:to_sym).include?(file_type)
+          raise NotRebuilt, "a #{file_type} file is not among the types to rebuild"
+        end
+
+        # The daemon does not send the report of a file it rebuilt; the
+        # rebuilt file was clean, or it would not have been sent.
+        report = Report.new(verdict: :clean, detected_type: file_type)
+        Sanitized.new(data: response.body.b, file_type: file_type, report: report)
+      when "422"
+        body = parse(response)
+        raise Rejected, Report.from_h(body["report"]) if body["report"]
+
+        raise NotRebuilt, body["error"].to_s
+      when "415", "501"
+        raise NotRebuilt, parse(response)["error"].to_s
+      else
+        raise ScanError, "malmald did not rebuild the file: #{response.code} #{parse(response)["error"]}".strip
+      end
+    end
+
+    # Whether the daemon answers GET /healthz.
+    def healthy?
+      request(Net::HTTP::Get.new(path("/healthz"))).code == "200"
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def path(name)
+      "#{@url.path}#{name}"
+    end
+
+    def post(name, data, filename, content_type)
+      bytes = data.respond_to?(:read) ? data.read.to_s : data.to_s
+      data.rewind if data.respond_to?(:rewind)
+      request = Net::HTTP::Post.new(path(name))
+      request["Content-Type"] = content_type.to_s.empty? ? "application/octet-stream" : content_type.to_s
+      request["X-Filename"] = URI.encode_www_form_component(filename.to_s).gsub("+", "%20") if filename
+      request.body = bytes.b
+      request(request)
+    end
+
+    def request(request)
+      request["Authorization"] = "Bearer #{@token}" if @token
+      Net::HTTP.start(@url.host, @url.port, use_ssl: @url.scheme == "https",
+                                            open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
+        http.request(request)
+      end
+    rescue SystemCallError, IOError, Timeout::Error, OpenSSL::SSL::SSLError => e
+      raise ScanError, "malmald could not be reached: #{e.message}"
+    end
+
+    def parse(response)
+      JSON.parse(response.body.to_s)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/malmal/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Malmal
+  # The base of every error the gem raises.
+  class Error < StandardError; end
+
+  # The file was not scanned. Treat it as not accepted.
+  class ScanError < Error; end
+
+  # There is no rebuilt file, and the original is not to be kept in its place.
+  class SanitizeError < Error; end
+
+  # The scan of the upload, or of the file made from it, did not come back
+  # clean; +report+ is the one that was not.
+  class Rejected < SanitizeError
+    attr_reader :report
+
+    def initialize(report)
+      @report = report
+      super("file is not clean: #{report.codes.join(", ")}")
+    end
+  end
+
+  # The file is clean but is not of a type that can be rebuilt, is too large,
+  # or does not decode.
+  class NotRebuilt < SanitizeError; end
+
+  # libmalmal_ffi could not be found or is not the version this gem needs.
+  class LoadError < Error; end
+end

data/lib/malmal/native.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Malmal
+  # The functions of libmalmal_ffi, as declared in malmal.h. Each that scans
+  # releases the GVL, so other Ruby threads run while a file is scanned.
+  module Native
+    extend FFI::Library
+
+    CLEAN = 0
+    SUSPICIOUS = 1
+    MALICIOUS = 2
+    ERROR = 3
+    NOT_REBUILT = 4
+
+    NAMES = %w[libmalmal_ffi.so libmalmal_ffi.dylib malmal_ffi.dll].freeze
+    LOCK = Mutex.new
+    private_constant :LOCK
+
+    class << self
+      # Where the library was loaded from.
+      attr_reader :path
+
+      # The library this gem carries, else the one at MALMAL_LIBRARY, else
+      # whatever the system loader finds.
+      def candidates
+        bundled = NAMES.map { |name| File.join(__dir__, name) }.select { |file| File.file?(file) }
+        [ENV.fetch("MALMAL_LIBRARY", nil), *bundled, "malmal_ffi"].compact.reject(&:empty?)
+      end
+
+      # The version of the loaded library.
+      def version
+        malmal_version.dup.force_encoding(Encoding::UTF_8)
+      end
+
+      # Load the library once, whichever thread asks first.
+      def load!
+        return if @loaded
+
+        LOCK.synchronize { load_once! unless @loaded }
+      end
+
+      private
+
+      def load_once!
+        errors = []
+        candidates.each do |candidate|
+          ffi_lib(candidate)
+          @path = candidate
+          break
+        rescue ::LoadError => e
+          errors << e.message
+        end
+        unless @path
+          raise Malmal::LoadError,
+                "libmalmal_ffi was not found (#{errors.join("; ")}). This gem has no library for " \
+                "#{RUBY_PLATFORM}; build one with `cargo build --release -p malmal-ffi` and set " \
+                "MALMAL_LIBRARY to its path."
+        end
+        attach!
+        check_version!
+        @loaded = true
+      end
+
+      def attach!
+        attach_function :malmal_version, [], :string
+        attach_function :malmal_scanner_new_json, %i[string pointer], :pointer
+        attach_function :malmal_scanner_overdue, [:pointer], :uint64
+        attach_function :malmal_scanner_free, [:pointer], :void
+        attach_function :malmal_scan, %i[pointer pointer size_t string string pointer], :int, blocking: true
+        attach_function :malmal_sanitize_json,
+                        %i[pointer pointer size_t string string string pointer pointer pointer], :int,
+                        blocking: true
+        attach_function :malmal_string_free, [:pointer], :void
+        attach_function :malmal_bytes_free, %i[pointer size_t], :void
+      rescue FFI::NotFoundError => e
+        raise Malmal::LoadError, "#{@path} is older than this gem (#{e.message}); it needs #{Malmal::VERSION}"
+      end
+
+      # The library this gem carries has to be its own version; one given
+      # with MALMAL_LIBRARY only has to have the functions.
+      def check_version!
+        return if version == Malmal::VERSION
+        return if ENV["MALMAL_LIBRARY"].to_s == @path
+
+        raise Malmal::LoadError, "#{@path} is version #{version}, and this gem is #{Malmal::VERSION}"
+      end
+    end
+  end
+end

data/lib/malmal/report.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Malmal
+  # Severities from least to most serious.
+  SEVERITIES = %i[info low medium high critical].freeze
+
+  # One thing the scanner noticed about a file. +code+ is stable (the codes
+  # are listed in docs/findings.md); the wording of +message+ is not.
+  Finding = Struct.new(:code, :severity, :message, :offset, keyword_init: true) do
+    def self.from_h(fields)
+      new(
+        code: fields.fetch("code"),
+        severity: fields.fetch("severity").to_sym,
+        message: fields.fetch("message", ""),
+        offset: fields["offset"]
+      )
+    end
+
+    def to_h
+      { code: code, severity: severity, message: message, offset: offset }
+    end
+  end
+
+  # What a scan found. Anything but a clean verdict means the file is not to
+  # be accepted.
+  class Report
+    attr_reader :verdict, :detected_type, :declared_types, :size, :sha256, :findings
+
+    def self.from_h(fields)
+      new(
+        verdict: fields.fetch("verdict").to_sym,
+        detected_type: fields.fetch("detected_type").to_sym,
+        declared_types: fields.fetch("declared_types", []).map(&:to_sym),
+        size: fields.fetch("size", 0),
+        sha256: fields.fetch("sha256", ""),
+        findings: fields.fetch("findings", []).map { |finding| Finding.from_h(finding) }
+      )
+    end
+
+    def initialize(verdict:, detected_type:, declared_types: [], size: 0, sha256: "", findings: [])
+      @verdict = verdict
+      @detected_type = detected_type
+      @declared_types = declared_types.freeze
+      @size = size
+      @sha256 = sha256
+      @findings = findings.freeze
+      freeze
+    end
+
+    def clean?
+      verdict == :clean
+    end
+
+    def suspicious?
+      verdict == :suspicious
+    end
+
+    def malicious?
+      verdict == :malicious
+    end
+
+    # The codes of the findings that count against the file: those above
+    # +info+, in the order they were found.
+    def codes
+      findings.reject { |finding| finding.severity == :info }.map(&:code).uniq
+    end
+
+    def to_h
+      {
+        verdict: verdict,
+        detected_type: detected_type,
+        declared_types: declared_types,
+        size: size,
+        sha256: sha256,
+        findings: findings.map(&:to_h)
+      }
+    end
+
+    def inspect
+      "#<Malmal::Report #{verdict} #{detected_type} codes=#{codes.inspect}>"
+    end
+  end
+
+  # A file written anew from a clean upload: an image from its pixels, an SVG
+  # from what draws in it, a PDF as pictures of its pages.
+  class Sanitized
+    CONTENT_TYPES = {
+      jpeg: "image/jpeg",
+      png: "image/png",
+      gif: "image/gif",
+      webp: "image/webp",
+      svg: "image/svg+xml",
+      pdf: "application/pdf"
+    }.freeze
+
+    EXTENSIONS = { jpeg: ".jpg", png: ".png", gif: ".gif", webp: ".webp", svg: ".svg", pdf: ".pdf" }.freeze
+
+    # +data+ is the file to keep; +file_type+ its type, which is not always
+    # the type of the upload. +width+ and +height+ are 0 for an SVG or a PDF;
+    # +frames+ counts the frames of an animation or the pages of a PDF.
+    attr_reader :data, :file_type, :width, :height, :frames, :report
+
+    def initialize(data:, file_type:, report:, width: 0, height: 0, frames: 1)
+      @data = data
+      @file_type = file_type.to_sym
+      @width = width
+      @height = height
+      @frames = frames
+      @report = report
+      freeze
+    end
+
+    def content_type
+      CONTENT_TYPES.fetch(file_type, "application/octet-stream")
+    end
+
+    def extension
+      EXTENSIONS.fetch(file_type, "")
+    end
+
+    def inspect
+      "#<Malmal::Sanitized #{file_type} #{data.bytesize} bytes>"
+    end
+  end
+end

data/lib/malmal/scanner.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Malmal
+  # A configured scanner. One instance may be shared by every thread of the
+  # process: it holds no per-scan state.
+  #
+  #   scanner = Malmal::Scanner.new(policy: :documents, types: %i[jpeg png pdf])
+  #   report = scanner.scan(upload, filename: "a.pdf", content_type: "application/pdf")
+  #   raise "rejected: #{report.codes.join(", ")}" unless report.clean?
+  class Scanner
+    POLICIES = %i[default strict documents].freeze
+    LIMITS = %i[max_size max_decompressed max_pixels max_depth scan_timeout].freeze
+    SANITIZE_OPTIONS = %i[types pdf_dpi pdf_jpeg pdf_text pdf_vector_text].freeze
+    DEFAULT_MAX_MEMORY = 512 << 20
+
+    # The handle is freed when the scanner is collected, unless #close
+    # freed it first.
+    class Handle < FFI::AutoPointer
+      def self.release(pointer)
+        Native.malmal_scanner_free(pointer)
+      end
+    end
+    private_constant :Handle
+
+    attr_reader :options
+
+    # +policy+:: +:default+, +:strict+ or +:documents+ (XFA forms and
+    #            attachments in PDFs do not count; what they hold does).
+    # +allow+:: finding codes reported at +:info+, such as
+    #           <tt>%w[pdf.xfa]</tt>; an unknown code, or a +limit.*+ one,
+    #           raises ArgumentError.
+    # +types+:: the accepted file types, such as <tt>%i[jpeg png pdf]</tt>;
+    #           every supported type when nil.
+    # +hashlist+:: a SHA-256 blocklist as text, one hex digest per line.
+    # +pdf_passwords+:: passwords to try on encrypted PDFs.
+    # +max_size+, +max_decompressed+, +max_pixels+, +max_depth+,
+    # +scan_timeout+ (seconds):: the limits of one scan.
+    # +max_memory+:: bytes one scan may hold; nil or 0 for no limit.
+    # +without_hash+:: leave the SHA-256 out of reports.
+    # +wait+:: seconds after which #scan stops waiting and reports
+    #          +limit.time+ even if a step of the scan never ends; the scan
+    #          is left running on its thread (see #overdue).
+    def initialize(policy: :default, allow: [], types: nil, hashlist: nil, pdf_passwords: [],
+                   max_memory: DEFAULT_MAX_MEMORY, without_hash: false, wait: nil, **limits)
+      unknown = limits.keys - LIMITS
+      raise ArgumentError, "unknown option #{unknown.first.inspect}" unless unknown.empty?
+      raise ArgumentError, "max_memory cannot be negative" if max_memory&.negative?
+
+      Native.load!
+      @options = {
+        policy: policy.to_s,
+        allow: Array(allow).flat_map { |code| code.to_s.split(/[,|]/) }.map(&:strip).reject(&:empty?),
+        pdf_passwords: Array(pdf_passwords).map { |password| password_json(password) },
+        max_memory: max_memory || 0,
+        without_hash: without_hash ? true : false
+      }
+      @options[:types] = Array(types).map(&:to_s) if types
+      @options[:hashlist] = hashlist.to_s if hashlist
+      @options[:wait] = wait if wait
+      @options.merge!(limits)
+      @handle = build(JSON.generate(@options))
+      @mutex = Mutex.new
+    end
+
+    # Scan +data+: a String of bytes, or an IO read up to the size limit and
+    # one byte past it. +filename+ and +content_type+ are what the uploader
+    # claimed. Returns a Report; raises ScanError if the file was not scanned.
+    def scan(data, filename: nil, content_type: nil)
+      bytes = read(data)
+      with_input(bytes) do |pointer|
+        report = FFI::MemoryPointer.new(:pointer)
+        verdict = Native.malmal_scan(handle, pointer, bytes.bytesize, claim(filename), claim(content_type), report)
+        json = take_string(report.read_pointer)
+        raise ScanError, "the scanner failed; the file was not scanned" if verdict == Native::ERROR || json.nil?
+
+        Report.from_h(JSON.parse(json))
+      end
+    end
+
+    # Scan +data+ and, if it is clean and of a type that can be, write it
+    # anew. Returns a Sanitized whose +data+ is the file to keep in place of
+    # the upload. Raises Rejected, NotRebuilt or ScanError otherwise; in
+    # every case the upload is not to be kept.
+    #
+    # +jpeg_quality+ (1 to 100), +types+, +pdf_dpi+, +pdf_jpeg+, +pdf_text+
+    # and +pdf_vector_text+ are the options of the rebuild.
+    def sanitize(data, filename: nil, content_type: nil, jpeg_quality: nil, **options)
+      unknown = options.keys - SANITIZE_OPTIONS
+      raise ArgumentError, "unknown option #{unknown.first.inspect}" unless unknown.empty?
+
+      options[:types] = Array(options[:types]).map(&:to_s) if options.key?(:types)
+      options[:jpeg_quality] = jpeg_quality if jpeg_quality
+      bytes = read(data)
+      with_input(bytes) do |pointer|
+        image = FFI::MemoryPointer.new(:pointer)
+        length = FFI::MemoryPointer.new(:size_t)
+        info = FFI::MemoryPointer.new(:pointer)
+        status = Native.malmal_sanitize_json(handle, pointer, bytes.bytesize, claim(filename), claim(content_type),
+                                             JSON.generate(options), image, length, info)
+        rebuilt = take_bytes(image.read_pointer, length.read(:size_t))
+        json = take_string(info.read_pointer)
+        sanitized(status, rebuilt, json ? JSON.parse(json) : {})
+      end
+    end
+
+    # Scans that +wait+ stopped waiting for and that are still running.
+    # Above 0, restart the process when it can be.
+    def overdue
+      Native.malmal_scanner_overdue(handle)
+    end
+
+    # The version of the loaded libmalmal_ffi.
+    def library_version
+      Native.version
+    end
+
+    # Free the scanner now rather than when it is collected.
+    def close
+      @mutex.synchronize do
+        @handle&.free
+        @handle = nil
+      end
+    end
+
+    def closed?
+      @handle.nil?
+    end
+
+    def inspect
+      "#<Malmal::Scanner policy=#{@options[:policy]}#{" closed" if closed?}>"
+    end
+
+    private
+
+    def build(json)
+      error = FFI::MemoryPointer.new(:pointer)
+      pointer = Native.malmal_scanner_new_json(json, error)
+      if pointer.null?
+        message = take_string(error.read_pointer) || "the scanner could not be created"
+        raise ArgumentError, message
+      end
+      Handle.new(pointer)
+    end
+
+    def handle
+      @handle or raise ScanError, "the scanner is closed"
+    end
+
+    def password_json(password)
+      text = password.to_s
+      return text if text.encoding != Encoding::BINARY && text.valid_encoding?
+
+      utf8 = text.dup.force_encoding(Encoding::UTF_8)
+      utf8.valid_encoding? ? utf8 : text.bytes
+    end
+
+    def read(data)
+      return data.b if data.is_a?(String)
+
+      if data.respond_to?(:read)
+        data.rewind if data.respond_to?(:rewind)
+        limit = (@options[:max_size] || (64 << 20)) + 1
+        bytes = data.read(limit) || +""
+        data.rewind if data.respond_to?(:rewind)
+        return bytes.b
+      end
+      raise TypeError, "scan takes a String or an IO, not #{data.class}"
+    end
+
+    # A NUL would end the C string early; it is dropped, as the C library
+    # would drop what follows it.
+    def claim(text)
+      text&.to_s&.delete("\0")
+    end
+
+    def with_input(bytes)
+      pointer = FFI::MemoryPointer.new(:uint8, [bytes.bytesize, 1].max)
+      pointer.put_bytes(0, bytes)
+      yield pointer
+    ensure
+      pointer&.free
+    end
+
+    def take_string(pointer)
+      return nil if pointer.null?
+
+      pointer.read_string.force_encoding(Encoding::UTF_8)
+    ensure
+      Native.malmal_string_free(pointer) unless pointer.null?
+    end
+
+    def take_bytes(pointer, length)
+      return nil if pointer.null?
+
+      pointer.read_bytes(length)
+    ensure
+      Native.malmal_bytes_free(pointer, length) unless pointer.null?
+    end
+
+    def sanitized(status, rebuilt, fields)
+      case status
+      when Native::CLEAN
+        raise ScanError, "the scanner failed; there is no rebuilt file" unless rebuilt
+
+        image = fields.fetch("image")
+        Sanitized.new(data: rebuilt, file_type: image.fetch("file_type"), width: image.fetch("width", 0),
+                      height: image.fetch("height", 0), frames: image.fetch("frames", 1),
+                      report: Report.from_h(fields.fetch("report")))
+      when Native::NOT_REBUILT
+        raise NotRebuilt, fields.fetch("error", "the file was not rebuilt")
+      when Native::SUSPICIOUS, Native::MALICIOUS
+        raise Rejected, Report.from_h(fields.fetch("report"))
+      else
+        raise ArgumentError, fields["error"] if fields["error"]
+
+        raise ScanError, "the scanner failed; the file was not scanned"
+      end
+    end
+  end
+end

data/lib/malmal/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Malmal
+  # The version of the gem, which is also the version of the library it loads.
+  VERSION = "0.4.0"
+end

data/lib/malmal.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "malmal/version"
+require_relative "malmal/errors"
+require_relative "malmal/report"
+require_relative "malmal/native"
+require_relative "malmal/scanner"
+require_relative "malmal/client"
+
+# Checks uploaded images, SVG, PDF and PostScript files before an
+# application processes them. Anything but a clean report, including an
+# exception, means the file is not accepted.
+module Malmal
+end

data/sig/malmal.rbs

@@ -0,0 +1,101 @@
+module Malmal
+  VERSION: String
+  SEVERITIES: Array[Symbol]
+
+  type input = String | IO | StringIO
+  type verdict = :clean | :suspicious | :malicious
+
+  class Error < StandardError
+  end
+
+  class ScanError < Error
+  end
+
+  class SanitizeError < Error
+  end
+
+  class Rejected < SanitizeError
+    attr_reader report: Report
+    def initialize: (Report report) -> void
+  end
+
+  class NotRebuilt < SanitizeError
+  end
+
+  class LoadError < Error
+  end
+
+  class Finding
+    attr_accessor code: String
+    attr_accessor severity: Symbol
+    attr_accessor message: String
+    attr_accessor offset: Integer?
+    def self.from_h: (Hash[String, untyped] fields) -> Finding
+    def initialize: (?code: String, ?severity: Symbol, ?message: String, ?offset: Integer?) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Report
+    attr_reader verdict: verdict
+    attr_reader detected_type: Symbol
+    attr_reader declared_types: Array[Symbol]
+    attr_reader size: Integer
+    attr_reader sha256: String
+    attr_reader findings: Array[Finding]
+    def self.from_h: (Hash[String, untyped] fields) -> Report
+    def initialize: (verdict: verdict, detected_type: Symbol, ?declared_types: Array[Symbol],
+                     ?size: Integer, ?sha256: String, ?findings: Array[Finding]) -> void
+    def clean?: () -> bool
+    def suspicious?: () -> bool
+    def malicious?: () -> bool
+    def codes: () -> Array[String]
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Sanitized
+    CONTENT_TYPES: Hash[Symbol, String]
+    EXTENSIONS: Hash[Symbol, String]
+    attr_reader data: String
+    attr_reader file_type: Symbol
+    attr_reader width: Integer
+    attr_reader height: Integer
+    attr_reader frames: Integer
+    attr_reader report: Report
+    def initialize: (data: String, file_type: Symbol | String, report: Report, ?width: Integer, ?height: Integer,
+                     ?frames: Integer) -> void
+    def content_type: () -> String
+    def extension: () -> String
+  end
+
+  class Scanner
+    POLICIES: Array[Symbol]
+    LIMITS: Array[Symbol]
+    SANITIZE_OPTIONS: Array[Symbol]
+    DEFAULT_MAX_MEMORY: Integer
+
+    attr_reader options: Hash[Symbol, untyped]
+
+    def initialize: (?policy: Symbol | String, ?allow: Array[String] | String, ?types: Array[Symbol | String]?,
+                     ?hashlist: String?, ?pdf_passwords: Array[String], ?max_memory: Integer?,
+                     ?without_hash: bool, ?wait: Numeric?, ?max_size: Integer, ?max_decompressed: Integer,
+                     ?max_pixels: Integer, ?max_depth: Integer, ?scan_timeout: Numeric) -> void
+    def scan: (input data, ?filename: String?, ?content_type: String?) -> Report
+    def sanitize: (input data, ?filename: String?, ?content_type: String?, ?jpeg_quality: Integer?,
+                   ?types: Array[Symbol | String], ?pdf_dpi: Integer, ?pdf_jpeg: bool, ?pdf_text: bool,
+                   ?pdf_vector_text: bool) -> Sanitized
+    def overdue: () -> Integer
+    def library_version: () -> String
+    def close: () -> void
+    def closed?: () -> bool
+  end
+
+  class Client
+    attr_reader url: URI::Generic
+
+    def initialize: (String | URI::Generic url, ?token: String?, ?open_timeout: Numeric,
+                     ?read_timeout: Numeric) -> void
+    def scan: (input data, ?filename: String?, ?content_type: String?) -> Report
+    def sanitize: (input data, ?filename: String?, ?content_type: String?, ?types: Array[Symbol | String]?) -> Sanitized
+    def healthy?: () -> bool
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: malmal
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: x86_64-linux-musl
+authors:
+- nguyenthuan155632
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+description: |
+  Checks uploaded files before your application processes them: whether the content is
+  what the name and Content-Type claim, whether it carries active content (scripts,
+  actions, embedded files, shell commands), and whether it is well formed. It can also
+  rebuild an image, SVG or PDF from what it draws. A file that cannot be analyzed
+  completely is never reported clean.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE-APACHE
+- LICENSE-MIT
+- README.md
+- lib/malmal.rb
+- lib/malmal/client.rb
+- lib/malmal/errors.rb
+- lib/malmal/libmalmal_ffi.so
+- lib/malmal/native.rb
+- lib/malmal/report.rb
+- lib/malmal/scanner.rb
+- lib/malmal/version.rb
+- sig/malmal.rbs
+homepage: https://github.com/nguyenthuan155632/malmal
+licenses:
+- MIT
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/nguyenthuan155632/malmal
+  source_code_uri: https://github.com/nguyenthuan155632/malmal/tree/main/bindings/ruby/malmal
+  changelog_uri: https://github.com/nguyenthuan155632/malmal/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/nguyenthuan155632/malmal/issues
+  rubygems_mfa_required: 'true'
+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: Upload scanner for images, SVG, PDF and PostScript files
+test_files: []