safe_image 0.3.0 → 0.5.0

data/SECURITY.md

@@ -16,18 +16,19 @@ Safe Image assumes image input may be attacker-controlled. The library is design
 - explicit libvips loader selection for supported raster formats, with
   libvips' untrusted-operation block enabled and the ImageMagick loader
   classes blocked by name
-- a runtime libvips binding (Fiddle) that exposes only the specific
-  operations the gem invokes — there is no generic operation access
+- a compiled libvips helper process that exposes only the specific operations
+  the gem invokes — there is no generic operation access and the Ruby process
+  never loads libvips
 - no silent fallback from libvips to generic ImageMagick decoding; the
   backend is a single explicit `SafeImage.configure!` decision and formats it
   cannot decode fail closed
 - decompression-bomb ceilings enforced from container/header metadata before
   any pixel decode (128MP default, plus dedicated SVG and ICO caps)
 - restrictive ImageMagick policy disabling delegates, filters, `@file`, remote URL coders, Ghostscript-backed formats, and dangerous pseudo-formats
-- risky container formats parsed in memory-safe Ruby rather than C: SVG
-  (bounded REXML metadata and allowlist sanitising) and ICO (bounds-checked
-  directory/DIB parsing); extracted pixels are re-encoded through libvips and
-  embedded payload bytes are never copied through verbatim
+- bounded SVG metadata probing (Nokogiri SAX with explicit byte/structure caps,
+  not Landlock-contained by Safe Image) and pure-Ruby ICO directory/DIB parsing;
+  extracted ICO pixels are re-encoded through libvips and embedded payload bytes
+  are never copied through verbatim
 - letter avatar text rendering escapes the user-derived glyph before Pango
   markup parsing, and fonts come from an allowlist (the default font is
   bundled with the gem)
@@ -38,19 +39,29 @@ Safe Image assumes image input may be attacker-controlled. The library is design
 One deliberate exception to libvips' untrusted-operation block: the libjxl
 loader and saver are re-enabled because JPEG XL is part of the supported
 input surface. JXL inputs still pass extension routing, the pixel cap, and
-(optionally) the Landlock sandbox, but libjxl does parse attacker-controlled
-bytes in-process like the other raster decoders below.
+(optionally) Landlock containment around the helper process, but libjxl does
+parse attacker-controlled bytes inside that helper like the other raster
+decoders below.
 
 ## Non-goals
 
-Safe Image does not claim that parsing hostile images in-process is memory-safe. Raster decoders such as libjpeg, libpng, libwebp, libheif, libjxl, libnsgif, libvips loaders, and ImageMagick coders still parse attacker-controlled bytes. A decoder memory-corruption bug or pathological resource-consumption bug is still possible.
+Safe Image does not claim that parsing hostile images is memory-safe. Raster
+decoders such as libjpeg, libpng, libwebp, libheif, libjxl, libnsgif, libvips
+loaders, and ImageMagick coders still parse attacker-controlled bytes; so does
+Nokogiri/libxml2 for bounded SVG metadata. A parser or decoder
+memory-corruption bug or pathological resource-consumption bug is still possible.
+When `landlock: true` is configured, Safe Image contains child helpers/tools; it
+does not put Ruby orchestration or Nokogiri SVG parsing behind a Landlock
+boundary.
 
 The honest claim is defense-in-depth:
 
 - without Landlock: centralized and hardened image processing with major delegate/protocol/policy foot-guns removed
-- with Landlock: the same hardening plus a kernel containment boundary around subprocess-based public operations
+- with Landlock: the same hardening plus a kernel containment boundary around subprocess helpers/tools
 
-If your deployment needs a hard isolation boundary, configure `landlock: true` and run image processing away from your main web worker process.
+If your deployment needs a hard isolation boundary around the Ruby process as well,
+run image processing away from your main web worker process (for example in a
+separate service/container).
 
 ## Reporting vulnerabilities
 

data/docs/architecture.md

@@ -0,0 +1,63 @@
+# Safe Image architecture and safety model
+
+Safe Image is deliberately structured as a narrow boundary around untrusted image bytes. The public API lives on
+`SafeImage`, but the implementation is split by responsibility:
+
+- `lib/safe_image/api/metadata.rb` — public read-only method signatures (`probe`, `size`, `info`, animation checks,
+  etc.) that delegate to operation objects.
+- `lib/safe_image/api/transform.rb` — public image-producing method signatures. These require explicit `input:` and
+  `output:` keywords and never replace a caller's source file in place.
+- `lib/safe_image/metadata_operations.rb` and `lib/safe_image/transform_operations.rb` — inline Ruby orchestration for
+  public operations. They do not load libvips and they are not proxied through a Ruby sandbox worker.
+- `lib/safe_image/operations.rb` — private backend orchestration shared by public writers.
+- `lib/safe_image/processor.rb` and `lib/safe_image/native.rb` — libvips orchestration that shells out to the bundled
+  `safe_image_vips_helper`; the Ruby process never loads libvips.
+- `lib/safe_image/image_magick_backend.rb` — ImageMagick argv construction under the bundled policy.
+- `lib/safe_image/sandbox.rb` — optional Landlock capture for child commands/helpers, with explicit read/write grants.
+- `lib/safe_image/formats.rb` — Ruby-side format normalization and allowlists.
+- `lib/safe_image/staged_output.rb` — same-directory temporary output and staged replacement helpers.
+
+## Security invariants
+
+Changes should preserve these rules:
+
+1. `SafeImage.configure!(backend:, landlock:)` is mandatory before any operation. Backend and sandbox posture are a
+   boot-time decision, not per-call convenience flags.
+2. The configured backend is authoritative. There is no silent fallback from libvips to ImageMagick when a format fails.
+3. Untrusted local paths pass `PathSafety` checks. Symlink components are rejected, output paths may not be directories,
+   and input/output paths must be distinct.
+4. Public writers require explicit output paths. No public API mutates the input file in place or shuffles files for the
+   caller.
+5. Output replacement goes through `StagedOutput`, which writes a sibling temporary file and renames it into place so
+   callers do not observe partial output.
+6. External commands are always argv arrays. Never construct shell strings.
+7. ImageMagick paths are prefixed with explicit coders (`jpeg:`, `png:`, etc.) and run only with the bundled restrictive
+   `policy.xml`.
+8. Pixel limits are enforced before full decode: libvips probes headers first and ImageMagick uses both probe checks and
+   its `128MP` area limit.
+9. SVG metadata probing remains bounded and non-rendering: byte/depth/element/attribute caps, unsafe encoding rejection,
+   and root-dimension pixel caps all happen before parser results are trusted. This Nokogiri/libxml2 parse runs in the
+   Ruby process; Landlock containment is for child helpers and tools, not this parser.
+10. Remote fetching remains SSRF-hardened: DNS pinning, special-use IP blocking, redirect limits, and no direct decode
+    from network sockets.
+
+## Debugging model
+
+- `SafeImage::CommandError` carries `command`, `status`, `stdout`, `stderr`, `category`, and optional `operation` so CI
+  failures show whether the fault came from a timeout, output cap, exit status, sandboxed command/helper, or native
+  helper error.
+- Backend labels are centralized in `BackendLabel` so results consistently report `libvips-helper`, `imagemagick`, or
+  `libvips-helper+cjpegli`.
+- With `landlock: true`, child commands/helpers get explicit readable and writable path lists at each call site. Add new
+  tool/helper invocations deliberately; do not infer readable/writable paths from arbitrary argument strings.
+
+## Adding a new image-producing operation
+
+1. Add a public method in `api/transform.rb` with explicit keywords.
+2. Add the inline implementation to `TransformOperations`.
+3. Add private backend orchestration in `operations.rb` if it is shared across backends.
+4. Add or reuse backend-specific argv/native helpers.
+5. If the operation shells out, pass explicit Landlock `read:`/`write:` grants to the child command/helper.
+6. Route temporary outputs through `StagedOutput`.
+7. Normalize/validate formats with `Formats`.
+8. Add contract and backend tests that exercise real fixtures rather than mocks.

data/ext/safe_image_vips_helper/extconf.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rbconfig"
+
+pkg_config("vips") or abort "libvips development files are required (pkg-config vips failed)"
+
+pkg_cflags = `pkg-config --cflags vips`.strip
+pkg_libs = `pkg-config --libs vips`.strip
+cflags = [ENV["CFLAGS"] || RbConfig::CONFIG["CFLAGS"], RbConfig::CONFIG["CPPFLAGS"], pkg_cflags].compact.join(" ")
+ldflags = [ENV["LDFLAGS"] || RbConfig::CONFIG["LDFLAGS"]].compact.join(" ")
+
+helper = "safe_image_vips_helper"
+source = "safe_image_vips_helper.c"
+lib_dir = File.expand_path("../../lib/safe_image", __dir__)
+
+File.write(
+  "Makefile",
+  <<~MAKEFILE
+    SHELL = /bin/sh
+    CC = #{RbConfig::CONFIG.fetch("CC")}
+    CFLAGS = #{cflags}
+    LDFLAGS = #{ldflags}
+    LIBS = #{pkg_libs} -lm
+    INSTALL = #{RbConfig::CONFIG.fetch("INSTALL", "install")}
+
+    all: #{helper}
+
+    #{helper}: #{source}
+    	$(CC) $(CFLAGS) -o #{helper} #{source} $(LDFLAGS) $(LIBS)
+
+    install: #{helper}
+    	mkdir -p #{lib_dir}
+    	cp #{helper} #{File.join(lib_dir, helper)}
+    	chmod 0755 #{File.join(lib_dir, helper)}
+
+    clean:
+    	rm -f #{helper} *.o
+
+    distclean: clean
+    	rm -f Makefile
+  MAKEFILE
+)