cataract 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f107809adb744598338be592626fc5ebbfdb81c2813957c7e5ed1652f37a607
-  data.tar.gz: 810a6aadbe0a8c2ce4eff7c307c17c9de354f1a3bc0d9509ae4e83f1d7e1c8b0
+  metadata.gz: b2245bc15a5bd5029bcf6d0cb056a97a896d2855ef247dcc34a3764bba009e89
+  data.tar.gz: 170bd30c28c2f1c5405ea742a9398dad5aaba2115cd424c73e17572bed8399d8
 SHA512:
-  metadata.gz: b7e85ed2f9ad0b9154e78c795bc0548ca1eaeb55f8f24b2b644852394a506173afb64042f55a3c02c13c21e1b539738695a83c8f774aaf0311bdda8f00da42b9
-  data.tar.gz: f6ea7361ad3d180aaf9e4faa72bf686906a0f81345df59f70856734e50f17b79d4dc20823d0fae520279767cd289fb8e42bbd619230f095d1d26f9ed95aa1094
+  metadata.gz: 329b054911204add270ac0f2853f0d79c0d12c0b549a34acb672fe6b71416b521f500b36403567f65afa620d165b980f6bc0068c661defe75226602b394c4791
+  data.tar.gz: b252e03c315de4885224f2bfdd9841ca94e7294b43a80c3c1e27a77d236d451b3ed1a779ad95d956a0445a90d6733d11c8d1ca45ad93d5a693304e7410673d72

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [0.6.0] - 2026-07-30
+
+- Security: `ImportResolver.validate_url`'s `dangerous_path_prefixes` check now canonicalizes the `file://` path (via `File.expand_path`) before comparing against blocked prefixes, instead of comparing the raw path string. Previously a path containing `..` that didn't literally start with a blocked prefix (e.g. `file:///var/../etc/passwd`) bypassed the check entirely, even though the file was actually read from the resolved location. Reachable via `Stylesheet#load_uri`/`#load_file` (file scheme allowed by default) and via `@import` when a caller opts `file` into `allowed_schemes`.
+- Security/Breaking: `@import` and `Stylesheet#load_uri`/`#load_file` HTTP(S) fetches are now validated with the [ssrf_filter](https://rubygems.org/gems/ssrf_filter) gem, which blocks loopback, private-network, link-local, and cloud metadata addresses by default and re-validates on every redirect hop. Previously only URL scheme and file extension were checked, so an allowed `https://` URL (or a redirect target) could still reach an internal-only host. Set `allow_local_network: true` to restore the old, unfiltered behavior. Adds `ssrf_filter` as a new runtime dependency.
+
 ## [0.5.0] - 2026-07-09
 
 - Feature: `@supports (condition) { ... }` now preserves its condition and the rules it wraps through parse -> serialize, in both backends - previously the condition was discarded entirely and the wrapped rules were silently flattened into the surrounding document with no trace of ever being conditional.

data/README.md

@@ -14,7 +14,6 @@ A performant CSS parser for accurate parsing of complex CSS structures.
 - **CSS Color Level 4**: Parses and preserves modern color formats (hex, rgb, hsl, hwb, oklab, oklch, lab, lch, named colors). Optional color conversion utility for transforming between formats.
 - **Specificity Calculation**: Automatic CSS specificity computation
 - **Media Query Filtering**: Query rules by media type
-- **Zero Runtime Dependencies**: Pure C extension with no runtime gem dependencies
 
 ## Installation
 
@@ -269,7 +268,8 @@ sheet = Cataract::Stylesheet.parse(css, import: {
   extensions: ['css'],                   # Default: ['css']
   max_depth: 3,                          # Default: 5
   timeout: 10,                           # Default: 10 seconds
-  follow_redirects: true                 # Default: true
+  follow_redirects: true,                # Default: true
+  allow_local_network: false             # Default: false
 })
 ```
 
@@ -278,6 +278,7 @@ sheet = Cataract::Stylesheet.parse(css, import: {
 - Non-CSS file extensions
 - Circular references
 - Excessive nesting depth
+- SSRF - HTTP(S) fetches are validated with the [ssrf_filter](https://rubygems.org/gems/ssrf_filter) gem, which blocks loopback, private-network, link-local, and cloud metadata addresses by default (re-checked on every redirect hop). Set `allow_local_network: true` to opt out.
 
 ## Development
 

data/cataract.gemspec

@@ -27,6 +27,8 @@ Gem::Specification.new do |spec|
     end
   end
 
+  spec.add_dependency 'ssrf_filter', '~> 1.5'
+
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']

data/lib/cataract/import_resolver.rb

@@ -2,6 +2,7 @@
 
 require 'uri'
 require 'open-uri'
+require 'ssrf_filter'
 
 module Cataract
   # Error raised during import resolution
@@ -38,6 +39,8 @@ module Cataract
         raise ImportError, "HTTP error fetching import: #{url} (#{e.message})"
       rescue SocketError => e
         raise ImportError, "Network error fetching import: #{url} (#{e.message})"
+      rescue SsrfFilter::Error => e
+        raise ImportError, "Import blocked by SSRF protection: #{url} (#{e.message})"
       rescue StandardError => e
         raise ImportError, "Error fetching import: #{url} (#{e.class}: #{e.message})"
       end
@@ -46,7 +49,16 @@ module Cataract
 
       # Fetch content via HTTP/HTTPS
       def fetch_http(uri, options)
-        # Use open-uri with timeout
+        if options[:allow_local_network]
+          fetch_http_unfiltered(uri, options)
+        else
+          fetch_http_ssrf_safe(uri, options)
+        end
+      end
+
+      # Plain open-uri fetch, no SSRF protection - only reachable when the
+      # caller explicitly opted in via allow_local_network: true.
+      def fetch_http_unfiltered(uri, options)
         open_uri_options = {
           read_timeout: options[:timeout],
           redirect: options[:follow_redirects]
@@ -55,6 +67,23 @@ module Cataract
         # Use uri.open instead of URI.open to avoid shell command injection
         uri.open(open_uri_options, &:read)
       end
+
+      # Fetch via the ssrf_filter gem, which resolves the hostname and rejects
+      # loopback/private/link-local/metadata addresses (re-checked on every
+      # redirect hop, since a redirect can point anywhere) before connecting.
+      def fetch_http_ssrf_safe(uri, options)
+        response = SsrfFilter.get(
+          uri,
+          http_options: { read_timeout: options[:timeout], open_timeout: options[:timeout] },
+          max_redirects: options[:follow_redirects] ? SsrfFilter::DEFAULT_MAX_REDIRECTS : 0
+        )
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise OpenURI::HTTPError.new("#{response.code} #{response.message}", response)
+        end
+
+        response.body
+      end
     end
 
     # Default options for safe import resolution (@import statements
@@ -68,7 +97,8 @@ module Cataract
       base_path: nil,                    # Base path for resolving relative file imports
       base_uri: nil,                     # Base URI for resolving relative HTTP imports
       fetcher: nil,                      # Custom fetcher (defaults to DefaultFetcher)
-      dangerous_path_prefixes: ['/etc/', '/proc/', '/sys/', '/dev/'] # Blocked file:// path prefixes
+      dangerous_path_prefixes: ['/etc/', '/proc/', '/sys/', '/dev/'], # Blocked file:// path prefixes
+      allow_local_network: false # Block loopback/private/link-local/metadata addresses (via ssrf_filter)
     }.freeze
 
     # Default options for an explicitly caller-invoked load (Stylesheet#load_uri
@@ -158,7 +188,6 @@ module Cataract
 
       # Additional security checks for file:// scheme
       if uri.scheme == 'file'
-        # Resolve to absolute path to prevent directory traversal
         file_path = uri.path
 
         # Check file exists and is readable
@@ -166,9 +195,18 @@ module Cataract
           raise ImportError, "Import file not found or not readable: #{file_path}"
         end
 
+        # Resolve to a canonical, "..".-free path before the prefix check below -
+        # otherwise a path like '/var/../etc/hosts' doesn't literally start with
+        # '/etc/' and would slip past it, even though File.exist?/File.read above
+        # resolve it to the same file '/etc/hosts' would. Use expand_path (lexical
+        # only) rather than realpath: realpath also follows symlinks, and on
+        # macOS '/etc' itself is a symlink to '/private/etc', which would make
+        # every real path fail to start with '/etc/' and defeat this check entirely.
+        canonical_file_path = File.expand_path(file_path)
+
         # Prevent reading sensitive files (basic check, configurable via
         # options[:dangerous_path_prefixes] - pass [] to disable)
-        if options[:dangerous_path_prefixes]&.any? { |prefix| file_path.start_with?(prefix) }
+        if options[:dangerous_path_prefixes]&.any? { |prefix| canonical_file_path.start_with?(prefix) }
           raise ImportError, "Import of sensitive system files not allowed: #{file_path}"
         end
       end

data/lib/cataract/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cataract
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: cataract
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - James Cook
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ssrf_filter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
 description: A performant CSS parser with C extensions for accurate parsing of complex
   CSS structures including media queries, nested selectors, and CSS Color Level 4
 email: