svg_sentinel 0.1.0

data/lib/svg_sentinel/scanner.rb

@@ -0,0 +1,400 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+require_relative "rules"
+require_relative "policy"
+require_relative "structure_listener"
+require_relative "finding"
+require_relative "result"
+require_relative "errors"
+
+module SvgSentinel
+  # The scanner. It reads an SVG string and reports what makes it unsafe.
+  #
+  # The rules come from two public sources: general SVG cross-site-scripting
+  # knowledge (no scripts, no event handlers, no javascript: URIs, no foreign
+  # objects, no XXE) and the BIMI "SVG Tiny 1.2 Portable/Secure" profile used
+  # for brand-mark logos (no scripting, no animation, no external references,
+  # no raster images). Nothing here is fetched over the network.
+  #
+  # It is built to survive hostile input: input is normalised to valid UTF-8
+  # first, a hard byte cap and streaming structural limits refuse oversized or
+  # pathologically shaped payloads before the tree parser runs, DOCTYPE /
+  # ENTITY declarations are refused so the parser is never exposed to
+  # entity-expansion or external-entity attacks, and every parse failure
+  # becomes a finding rather than an exception.
+  #
+  # Raw findings are re-rated by a Policy for the rendering context and any
+  # configured severity overrides before they reach the Result.
+  class Scanner
+    include Rules
+
+    DEFAULT_MAX_BYTES = 32_768 # BIMI recommends brand-mark SVGs stay small.
+    DEFAULT_HARD_MAX_BYTES = 5_242_880 # 5 MiB: refuse to parse anything larger.
+
+    DEFAULT_MAX_DEPTH = 100
+    DEFAULT_MAX_NODES = 200_000
+    DEFAULT_MAX_ATTRIBUTES = 512
+
+    # Nested <use> can expand exponentially ("SVG use bomb"). If the fully
+    # expanded node count would exceed this, the SVG is a render-DoS risk.
+    USE_EXPANSION_LIMIT = 1_000_000
+
+    def initialize(profile: :strict, allow_external: false, allow_data_uri: false,
+      max_bytes: DEFAULT_MAX_BYTES, hard_max_bytes: DEFAULT_HARD_MAX_BYTES,
+      max_depth: DEFAULT_MAX_DEPTH, max_nodes: DEFAULT_MAX_NODES,
+      max_attributes: DEFAULT_MAX_ATTRIBUTES,
+      context: :inline, severity_overrides: {}, disabled: [])
+      @profile = profile
+      @allow_external = allow_external
+      @allow_data_uri = allow_data_uri
+      # A limit of 0 (or negative, or nil) means "disabled" - the single place
+      # this is decided, so config, CLI, and the library agree.
+      @max_bytes = limit(max_bytes)
+      @hard_max_bytes = limit(hard_max_bytes)
+      @max_depth = limit(max_depth)
+      @max_nodes = limit(max_nodes)
+      @max_attributes = limit(max_attributes)
+      @policy = Policy.new(context: context, overrides: severity_overrides, disabled: disabled)
+      @findings = []
+      @current_path = nil
+    end
+
+    def scan(svg)
+      @findings = []
+      @current_path = nil
+      collect(svg)
+      Result.new(@policy.apply(@findings))
+    rescue SystemStackError
+      # Recursion (parser or tree walk) overflowed the stack on pathologically
+      # nested input. Only reachable when structural limits are disabled; the
+      # contract is still that scan returns a Result, never raises.
+      @current_path = nil
+      add_security(:too_deep, :critical, "SVG nesting overflowed the stack")
+      Result.new(@policy.apply(@findings))
+    end
+
+    private
+
+    def limit(value)
+      value if value&.positive?
+    end
+
+    # Populates @findings with raw (un-re-rated) findings. Returns early at the
+    # first check that makes further inspection pointless or unsafe.
+    def collect(svg)
+      return add_security(:empty_input, :critical, "SVG is nil or empty") if svg.nil?
+
+      svg = normalize_encoding(svg)
+      return if svg.nil? # encoding already flagged
+      return add_security(:empty_input, :critical, "SVG is nil or empty") if svg.strip.empty?
+
+      return unless check_size(svg)
+      return unless check_no_doctype(svg)
+      return unless check_structure(svg)
+
+      doc = parse(svg)
+      return if doc.nil?
+
+      check_root(doc)
+      id_map = {}
+      saw_use = false
+      each_element(doc) do |element, path|
+        id = element.attributes["id"]
+        id_map[id] = element if id
+        saw_use = true if element.name.casecmp?("use")
+        inspect_element(element, path)
+      end
+      check_use_bomb(doc, id_map) if saw_use
+    end
+
+    def normalize_encoding(svg)
+      status, utf8 = Rules.to_utf8(svg)
+      case status
+      when :ok then utf8
+      when :bad_utf16
+        add_security(:malformed, :critical, "SVG declares a UTF-16 BOM but is not valid UTF-16")
+        nil
+      else
+        add_security(:malformed, :critical, "SVG is not valid UTF-8")
+        nil
+      end
+    end
+
+    # A hard cap refuses oversized input before REXML sees it. The soft cap is
+    # a brand-mark house rule and only warns. Returns false when scanning must
+    # stop.
+    def check_size(svg)
+      bytes = svg.bytesize
+      if @hard_max_bytes && bytes > @hard_max_bytes
+        add_security(:too_large, :critical,
+          "SVG exceeds hard limit of #{@hard_max_bytes} bytes; refusing to parse", "#{bytes} bytes")
+        return false
+      end
+      if @max_bytes && bytes > @max_bytes
+        add_policy(:oversize, :warning, "SVG exceeds #{@max_bytes} bytes", "#{bytes} bytes")
+      end
+      true
+    end
+
+    # Refuse DTDs outright. A DOCTYPE can define entities (billion-laughs) or
+    # pull in external ones (XXE). Comments and CDATA are stripped first so a
+    # harmless "<!DOCTYPE" mentioned there is not a false positive; neither
+    # construct can nest or contain its own terminator, so the strip is safe.
+    def check_no_doctype(svg)
+      markup = svg.gsub(/<!--.*?-->/m, "").gsub(/<!\[CDATA\[.*?\]\]>/m, "")
+      if markup.match?(/<!DOCTYPE/i) || markup.match?(/<!ENTITY/i)
+        add_security(:doctype, :critical, "SVG contains a DOCTYPE or ENTITY declaration (XXE risk)")
+        return false
+      end
+      true
+    end
+
+    # Bound the document's shape on a streaming pass before building a DOM. A
+    # limit breach is fatal; a parse error is left for the tree parser to
+    # report as :malformed.
+    def check_structure(svg)
+      listener = StructureListener.new(
+        max_depth: @max_depth, max_nodes: @max_nodes, max_attributes: @max_attributes
+      )
+      REXML::Parsers::StreamParser.new(svg, listener).parse
+      true
+    rescue StructureListener::LimitExceeded
+      add_security(listener.breach.code, :critical, listener.breach.message)
+      false
+    rescue
+      true
+    end
+
+    # Any parse failure becomes a finding, never an exception - including a
+    # stack overflow from deeply nested input when the depth limit is off.
+    def parse(svg)
+      REXML::Document.new(svg)
+    rescue StandardError, SystemStackError => e
+      add_security(:malformed, :critical, "SVG could not be parsed safely", e.message.to_s[0, 200])
+      nil
+    end
+
+    def check_root(doc)
+      root = doc.root
+      if root.nil?
+        add_security(:no_root, :critical, "SVG has no root element")
+      elsif !root.name.casecmp?("svg")
+        add_policy(:not_svg, :warning, "Root element is <#{root.name}>, not <svg>")
+      end
+    end
+
+    def inspect_element(element, path)
+      @current_path = path.join("/")
+      name = element.name.downcase
+
+      inspect_element_name(element, name)
+      inspect_animation_target(element, name)
+      inspect_attributes(element)
+      inspect_inline_style(element)
+    end
+
+    # A SMIL <animate>/<set> that targets an event handler, href, or style can
+    # inject script or a URI whatever its `to` value is - the value-scheme
+    # check alone misses `to="alert(1)"` written into onclick.
+    def inspect_animation_target(element, name)
+      return unless animation_element?(name)
+
+      target = element.attributes["attributeName"]
+      return if target.nil? || !sensitive_animation_target?(target)
+
+      add_security(:animated_attribute, :critical,
+        "Animation targets sensitive attribute #{target}", target.to_s[0, 60])
+    end
+
+    def inspect_element_name(element, name)
+      if script_element?(name)
+        add_security(:script_element, :critical, "Scripting element <#{element.name}>")
+      elsif foreign_element?(name)
+        add_security(:foreign_element, :critical, "Foreign-content element <#{element.name}>")
+      elsif name == "image"
+        add_policy(:raster_image, :warning, "Raster <image> element (disallowed by strict profile)") if strict?
+      elsif animation_element?(name)
+        add_policy(:animation, :warning, "Animation element <#{element.name}> (disallowed by strict profile)") if strict?
+      elsif strict? && !allowed_element?(name)
+        add_policy(:disallowed_element, :warning, "Element <#{element.name}> is not in the strict allowlist")
+      end
+    end
+
+    def inspect_attributes(element)
+      element.attributes.each do |attr_name, value|
+        lname = attr_name.downcase
+
+        if event_handler_attr?(lname)
+          add_security(:event_handler, :critical, "Event-handler attribute #{attr_name}", value.to_s[0, 120])
+          next
+        end
+
+        inspect_uri_attribute(attr_name, lname, value)
+        inspect_attribute_urls(attr_name, lname, value)
+      end
+    end
+
+    # Presentation attributes (fill, stroke, filter, mask, clip-path,
+    # marker-*, ...) carry url(...) references that reach the network or a
+    # scheme just like href does. The style attribute is handled separately by
+    # the CSS pass.
+    def inspect_attribute_urls(attr_name, lname, value)
+      return if lname == "style"
+
+      css_reference_targets(value.to_s) do |target|
+        inspect_reference(target, "#{attr_name} attribute")
+      end
+    end
+
+    def inspect_uri_attribute(attr_name, lname, value)
+      return unless uri_attribute?(lname)
+
+      scheme = uri_scheme(value)
+      return if scheme.nil? # relative refs and #fragments are fine
+
+      if dangerous_scheme?(scheme)
+        add_security(:script_uri, :critical, "#{scheme}: URI in #{attr_name}", value.to_s[0, 120])
+      elsif scheme == "data"
+        inspect_data_uri(value, attr_name)
+      elsif external_scheme?(scheme) && !@allow_external
+        add_security(:external_ref, :warning, "External reference in #{attr_name}", value.to_s[0, 120])
+      end
+    end
+
+    def inspect_data_uri(value, where)
+      media = data_uri_media_type(value)
+      if scriptable_data?(media)
+        add_security(:data_uri, :critical, "Scriptable data: URI (#{media}) in #{where}", value.to_s[0, 60])
+      elsif !@allow_data_uri
+        add_security(:data_uri, :critical, "data: URI in #{where}", value.to_s[0, 60])
+      end
+    end
+
+    def inspect_inline_style(element)
+      style = element.attributes["style"]
+      scan_css(style, "style attribute") if style
+
+      return unless element.name.casecmp?("style")
+
+      css = element.texts.join
+      scan_css(css, "<style> element")
+    end
+
+    def scan_css(css, where)
+      raw = strip_css_comments(css.to_s)
+      compact = decontrol(raw)
+
+      add_security(:css_script, :critical, "Scriptable CSS in #{where}", "expression(") if compact.match?(/expression\s*\(/i)
+      DANGEROUS_SCHEMES.each do |scheme|
+        add_security(:css_script, :critical, "#{scheme}: in #{where}") if compact.match?(/#{scheme}\s*:/i)
+      end
+
+      css_reference_targets(raw) do |target|
+        inspect_reference(target, where)
+      end
+
+      add_policy(:css_import, :warning, "@import in #{where}") if strict? && compact.match?(/@import/i)
+    end
+
+    # A url(...) or @import target reaches the network just like a href does,
+    # and can also carry javascript:/data: schemes. Attribute-level URI checks
+    # miss these, so CSS and presentation attributes both route through here.
+    def inspect_reference(target, where)
+      scheme = uri_scheme(target)
+      return if scheme.nil?
+
+      if dangerous_scheme?(scheme)
+        add_security(:css_script, :critical, "#{scheme}: URL in #{where}", target.to_s[0, 120])
+      elsif scheme == "data"
+        inspect_data_uri(target, where)
+      elsif external_scheme?(scheme) && !@allow_external
+        add_security(:external_ref, :warning, "External reference in #{where}", target.to_s[0, 120])
+      end
+    end
+
+    # Walk <use> references and compute the fully expanded node count with
+    # memoisation (so the linter itself stays linear even on a use bomb). A
+    # reference cycle is reported separately; expansion past the limit is a
+    # render-DoS.
+    def check_use_bomb(doc, id_map)
+      @current_path = nil
+      memo = {}
+      visiting = {}
+      cyclic = false
+      bombed = false
+
+      expand = lambda do |element|
+        return 0 if element.nil?
+
+        oid = element.object_id
+        return memo[oid] if memo.key?(oid)
+        if visiting[oid]
+          cyclic = true
+          return 0
+        end
+        visiting[oid] = true
+
+        total = 1
+        element.elements.each do |child|
+          total += expand.call(child)
+          break if total > USE_EXPANSION_LIMIT
+        end
+
+        if element.name.casecmp?("use") && total <= USE_EXPANSION_LIMIT
+          target = id_map[use_target_id(element)]
+          total += expand.call(target) if target
+        end
+
+        visiting.delete(oid)
+        bombed = true if total > USE_EXPANSION_LIMIT
+        memo[oid] = total
+        total
+      end
+
+      expand.call(doc.root)
+
+      add_security(:use_cycle, :warning, "Recursive <use> reference (rendering may loop)") if cyclic
+      if bombed
+        add_security(:use_bomb, :critical,
+          "Nested <use> expands to over #{USE_EXPANSION_LIMIT} nodes (render DoS)")
+      end
+    end
+
+    def use_target_id(element)
+      href = element.attributes["href"] || element.attributes["xlink:href"]
+      return nil if href.nil?
+
+      match = href.to_s.strip.match(/\A#(.+)\z/m)
+      match && match[1]
+    end
+
+    def each_element(node, path = [], &block)
+      node.elements.each do |element|
+        current = path + [element.name]
+        block.call(element, current)
+        each_element(element, current, &block)
+      end
+    end
+
+    def strict?
+      @profile == :strict
+    end
+
+    def add(code, severity, category, message, detail = nil)
+      @findings << Finding.new(
+        code: code, severity: severity, category: category,
+        message: message, detail: detail, path: @current_path
+      )
+      nil
+    end
+
+    def add_security(code, severity, message, detail = nil)
+      add(code, severity, :security, message, detail)
+    end
+
+    def add_policy(code, severity, message, detail = nil)
+      add(code, severity, :policy, message, detail)
+    end
+  end
+end

data/lib/svg_sentinel/structure_listener.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rexml/streamlistener"
+require "rexml/parsers/streamparser"
+require "rexml/parsers/baseparser"
+
+module SvgSentinel
+  # A streaming (SAX) listener that bounds the *shape* of the document -
+  # nesting depth, total element count, per-element attribute count - without
+  # ever building a DOM. It runs before the tree parser so a pathologically
+  # deep or wide payload is refused early, on a memory-bounded pass, instead of
+  # being fully materialised. The byte cap limits raw size; this limits the
+  # structural cost that a small byte count can still hide (deep nesting,
+  # attribute floods).
+  class StructureListener
+    include REXML::StreamListener
+
+    LimitExceeded = Class.new(StandardError)
+
+    Breach = Struct.new(:code, :message)
+
+    attr_reader :breach
+
+    def initialize(max_depth:, max_nodes:, max_attributes:)
+      @max_depth = max_depth
+      @max_nodes = max_nodes
+      @max_attributes = max_attributes
+      @depth = 0
+      @nodes = 0
+      @breach = nil
+    end
+
+    def tag_start(_name, attributes)
+      @nodes += 1
+      @depth += 1
+
+      if @max_nodes && @nodes > @max_nodes
+        breach!(:too_many_nodes, "document has more than #{@max_nodes} elements")
+      end
+      if @max_depth && @depth > @max_depth
+        breach!(:too_deep, "element nesting is deeper than #{@max_depth} levels")
+      end
+      if @max_attributes && attributes && attributes.size > @max_attributes
+        breach!(:too_many_attributes, "an element has more than #{@max_attributes} attributes")
+      end
+    end
+
+    def tag_end(_name)
+      @depth -= 1
+    end
+
+    private
+
+    def breach!(code, message)
+      @breach = Breach.new(code, message)
+      raise LimitExceeded
+    end
+  end
+end

data/lib/svg_sentinel/version.rb

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

data/lib/svg_sentinel.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "svg_sentinel/version"
+require_relative "svg_sentinel/errors"
+require_relative "svg_sentinel/rules"
+require_relative "svg_sentinel/finding"
+require_relative "svg_sentinel/result"
+require_relative "svg_sentinel/policy"
+require_relative "svg_sentinel/scanner"
+require_relative "svg_sentinel/sanitizer"
+
+# SvgSentinel lints untrusted SVG before you render or embed it. It flags the
+# constructs that make SVG dangerous - scripts, event handlers, javascript:
+# URIs, foreign objects, external references, and XXE via DOCTYPE or ENTITY -
+# and, in its strict profile, the extras that a brand-mark logo (BIMI-style)
+# must not contain, such as animation and raster images.
+#
+#   result = SvgSentinel.scan(svg_string)
+#   result.safe?      # => false
+#   result.findings   # => [#<Finding code=:script_element severity=:critical ...>]
+#
+# Findings are re-rated for a rendering context (:inline by default, or :img /
+# :css_background where a browser runs SVG without scripting). To clean rather
+# than reject, use SvgSentinel.sanitize, which rewrites the SVG or returns nil
+# when the threat is structural and cannot be safely rewritten.
+module SvgSentinel
+  module_function
+
+  # Scan an SVG string and return a Result. Options are passed through to
+  # Scanner: profile (:strict or :general), allow_external, allow_data_uri,
+  # max_bytes (soft brand-mark warning), hard_max_bytes (hard refuse-to-parse
+  # cap), max_depth / max_nodes / max_attributes (structural limits), context
+  # (:inline, :standalone, :img, :css_background), severity_overrides, disabled.
+  def scan(svg, **options)
+    Scanner.new(**options).scan(svg)
+  end
+
+  # Convenience predicate: true when the SVG has no critical findings.
+  def safe?(svg, **options)
+    scan(svg, **options).safe?
+  end
+
+  # Rewrite an SVG into a safe one. Returns cleaned SVG as a String, or nil
+  # when the input carries a structural threat that cannot be rewritten
+  # (DTD/XXE, use bomb, oversize, malformed, non-<svg> root). Options: profile,
+  # allow_external, allow_data_uri, and the size/structural limits.
+  def sanitize(svg, **options)
+    Sanitizer.new(**options).sanitize(svg)
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: svg_sentinel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Suleyman Musayev
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-07-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: 'A small, dependency-light Ruby tool for untrusted SVG. It flags the
+  things that make SVG dangerous to render or embed: scripts, event handlers, javascript:
+  URIs, external references (including inside CSS), scriptable data: URIs, foreign
+  objects, XXE via DOCTYPE or ENTITY declarations, and nested-<use> render bombs.
+  It can also sanitize - rewrite an SVG into a safe one - and re-rates findings for
+  the rendering context (inline vs <img>). Normalises encoding, caps size, and bounds
+  structural shape on a streaming pass so it is safe to point at hostile input. Ships
+  a strict allowlist profile for brand-mark logos (BIMI-style), a general profile,
+  YAML config, and a CLI with CI-friendly exit codes and SARIF output. Pure Ruby,
+  parses with REXML, no native extensions.'
+email:
+- slmusayev@gmail.com
+executables:
+- svg_sentinel
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/svg_sentinel
+- lib/svg_sentinel.rb
+- lib/svg_sentinel/cli.rb
+- lib/svg_sentinel/config.rb
+- lib/svg_sentinel/errors.rb
+- lib/svg_sentinel/finding.rb
+- lib/svg_sentinel/policy.rb
+- lib/svg_sentinel/result.rb
+- lib/svg_sentinel/rules.rb
+- lib/svg_sentinel/sanitizer.rb
+- lib/svg_sentinel/sarif.rb
+- lib/svg_sentinel/scanner.rb
+- lib/svg_sentinel/structure_listener.rb
+- lib/svg_sentinel/version.rb
+homepage: https://github.com/msuliq/svg_sentinel
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/msuliq/svg_sentinel
+  source_code_uri: https://github.com/msuliq/svg_sentinel
+  changelog_uri: https://github.com/msuliq/svg_sentinel/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/msuliq/svg_sentinel/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Lint or sanitize untrusted SVG for scripts, external references, and other
+  unsafe content
+test_files: []