svg_sentinel 0.1.0

data/lib/svg_sentinel/policy.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "finding"
+require_relative "errors"
+
+module SvgSentinel
+  # Re-rates raw findings for the situation they will be used in. Two layers,
+  # applied in order:
+  #
+  # 1. Rendering context. The same SVG is dangerous differently depending on
+  #    how a browser will run it. Inline <svg> in the DOM has full script and
+  #    network power; an SVG loaded through <img src> or CSS background runs in
+  #    the browser's "secure static" mode - no scripting, no external
+  #    subresources - so those findings, while still worth noting, are not on
+  #    their own a reason to reject. Parser-level and denial-of-service
+  #    findings (XXE, use bombs, oversize, malformed) are context-independent
+  #    and never downgraded.
+  #
+  # 2. Explicit overrides. A team can force a code to a severity or drop it
+  #    entirely from config; this wins over the context rating.
+  class Policy
+    CONTEXTS = %i[inline standalone img css_background].freeze
+
+    # Codes whose danger depends on the SVG actually scripting or fetching.
+    # Neutralised in a secure-static context (img / css_background).
+    CONTEXT_SENSITIVE_CODES = %i[
+      script_element event_handler script_uri css_script foreign_element
+      data_uri external_ref animation animated_attribute
+    ].freeze
+
+    SECURE_STATIC_CONTEXTS = %i[img css_background].freeze
+
+    def initialize(context: :inline, overrides: {}, disabled: [])
+      @context = context
+      @overrides = normalize_overrides(overrides)
+      @disabled = Array(disabled).map(&:to_sym)
+    end
+
+    def apply(findings)
+      findings.filter_map { |finding| rerate(finding) }
+    end
+
+    private
+
+    def rerate(finding)
+      return nil if @disabled.include?(finding.code)
+
+      severity = effective_severity(finding)
+      return nil if severity == :ignore
+      return finding if severity == finding.severity
+
+      Finding.new(**finding.to_h.merge(severity: severity))
+    end
+
+    # Explicit config override wins; otherwise the context decides.
+    def effective_severity(finding)
+      return @overrides[finding.code] if @overrides.key?(finding.code)
+
+      context_severity(finding)
+    end
+
+    def context_severity(finding)
+      return finding.severity unless SECURE_STATIC_CONTEXTS.include?(@context)
+      return finding.severity unless CONTEXT_SENSITIVE_CODES.include?(finding.code)
+
+      # Present but inert in a secure-static context: keep it visible, but do
+      # not let it make the SVG "unsafe" on its own.
+      finding.critical? ? :warning : finding.severity
+    end
+
+    def normalize_overrides(overrides)
+      (overrides || {}).each_with_object({}) do |(code, level), acc|
+        acc[code.to_sym] = normalize_level(level)
+      end
+    end
+
+    def normalize_level(level)
+      case level.to_s
+      when "error", "critical" then :critical
+      when "warning", "warn" then :warning
+      when "ignore", "off", "disabled" then :ignore
+      else raise ConfigError, "unknown severity override: #{level.inspect}"
+      end
+    end
+  end
+end

data/lib/svg_sentinel/result.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SvgSentinel
+  # The outcome of a scan: the list of findings and a few convenience
+  # predicates. "Safe" means no critical findings; warnings do not, on their
+  # own, make an SVG unsafe to render.
+  class Result
+    attr_reader :findings
+
+    def initialize(findings)
+      @findings = findings
+    end
+
+    def safe?
+      criticals.empty?
+    end
+
+    def critical?
+      !criticals.empty?
+    end
+
+    def warnings
+      @findings.select(&:warning?)
+    end
+
+    def criticals
+      @findings.select(&:critical?)
+    end
+
+    # Genuine attack-surface findings (scripts, XXE, script/data URIs, external
+    # references), regardless of severity.
+    def security_findings
+      @findings.select(&:security?)
+    end
+
+    # Brand-mark / strict-profile house-rule findings (animation, raster
+    # images, size, elements outside the strict allowlist).
+    def policy_findings
+      @findings.select(&:policy?)
+    end
+
+    def to_h
+      {
+        safe: safe?,
+        findings: @findings.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/svg_sentinel/rules.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module SvgSentinel
+  # The shared security vocabulary: which elements, attributes, and URI schemes
+  # are dangerous, plus the pure string helpers that read them. Both the
+  # Scanner (which reports) and the Sanitizer (which rewrites) mix this in, so
+  # the two can never drift out of agreement about what "dangerous" means.
+  module Rules
+    module_function
+
+    SCRIPT_ELEMENTS = %w[script handler listener].freeze
+    FOREIGN_ELEMENTS = %w[foreignobject iframe embed object audio video canvas].freeze
+    ANIMATION_ELEMENTS = %w[animate animatecolor animatemotion animatetransform set mpath].freeze
+
+    # The strict profile is an allowlist, not a blocklist: any element whose
+    # local name is not here (and is not already covered by a more specific
+    # rule) is reported. This fails closed - a new dangerous element is flagged
+    # simply for not being on the list. It is a conservative set of static,
+    # non-scripting, non-foreign SVG elements. Raster <image>, animation, and
+    # foreign/script elements are deliberately absent; they have their own,
+    # more descriptive findings.
+    STRICT_ALLOWED_ELEMENTS = %w[
+      svg g defs symbol use switch view
+      title desc metadata
+      path rect circle ellipse line polyline polygon
+      text tspan textpath tref altglyph glyphref
+      lineargradient radialgradient stop
+      solidcolor color-profile
+      clippath mask pattern marker
+      style font font-face missing-glyph glyph hkern vkern
+      filter feblend fecolormatrix fecomponenttransfer fecomposite
+      feconvolvematrix fediffuselighting fedisplacementmap fedropshadow
+      feflood fegaussianblur femerge femergenode femorphology feoffset
+      fespecularlighting fetile feturbulence fedistantlight fepointlight
+      fespotlight fefunca fefuncr fefuncg fefuncb
+    ].freeze
+
+    DANGEROUS_SCHEMES = %w[javascript vbscript livescript mocha].freeze
+    URI_ATTRIBUTES = %w[href src from to values by].freeze
+    EXTERNAL_SCHEMES = %w[http https ftp].freeze
+
+    # Attributes that a SMIL <animate>/<set> must not target: writing script
+    # into an event handler, or a URI into href, is a script-injection vector
+    # regardless of the animation's `to` value.
+    SENSITIVE_ANIMATED_ATTRIBUTES = %w[href xlink:href style].freeze
+
+    # data: media types that can carry executable markup. These are refused
+    # even when data URIs are otherwise allowed - "allow data URIs" means
+    # raster images, not an SVG or HTML document smuggled in as a data: URI.
+    SCRIPTABLE_DATA_MEDIA = %w[
+      image/svg+xml text/html application/xhtml+xml text/xml application/xml
+    ].freeze
+
+    def script_element?(name)
+      SCRIPT_ELEMENTS.include?(name)
+    end
+
+    def foreign_element?(name)
+      FOREIGN_ELEMENTS.include?(name)
+    end
+
+    def animation_element?(name)
+      ANIMATION_ELEMENTS.include?(name)
+    end
+
+    def allowed_element?(name)
+      STRICT_ALLOWED_ELEMENTS.include?(name)
+    end
+
+    def event_handler_attr?(lname)
+      lname.start_with?("on")
+    end
+
+    # True when a SMIL animation's attributeName points at an attribute that
+    # can execute or fetch: an on* handler, href, or style.
+    def sensitive_animation_target?(attribute_name)
+      target = decontrol(attribute_name.to_s).downcase
+      event_handler_attr?(target) || SENSITIVE_ANIMATED_ATTRIBUTES.include?(target)
+    end
+
+    def uri_attribute?(lname)
+      return true if URI_ATTRIBUTES.include?(lname)
+
+      lname.end_with?(":href")
+    end
+
+    def dangerous_scheme?(scheme)
+      DANGEROUS_SCHEMES.include?(scheme)
+    end
+
+    def external_scheme?(scheme)
+      EXTERNAL_SCHEMES.include?(scheme)
+    end
+
+    def scriptable_data?(media)
+      !media.nil? && SCRIPTABLE_DATA_MEDIA.include?(media)
+    end
+
+    # Strip whitespace and control characters before reading a scheme, so
+    # "java\tscript:" and " javascript:" cannot slip past.
+    def uri_scheme(value)
+      cleaned = decontrol(value.to_s)
+      match = cleaned.match(/\A([a-z][a-z0-9+.-]*):/i)
+      match && match[1].downcase
+    end
+
+    def data_uri_media_type(value)
+      cleaned = decontrol(value.to_s)
+      match = cleaned.match(/\Adata:([^;,]*)/i)
+      return nil unless match
+
+      type = match[1].downcase
+      type.empty? ? "text/plain" : type
+    end
+
+    # Remove whitespace and C0 control characters (NUL through space), a common
+    # trick for hiding "javascript:" inside an attribute value.
+    def decontrol(str)
+      str.gsub(/[[:cntrl:][:space:]]/, "")
+    end
+
+    def strip_css_comments(css)
+      css.gsub(%r{/\*.*?\*/}m, "")
+    end
+
+    # Every off-document reference target in a chunk of CSS: both `url(...)`
+    # and the string form of `@import "..."` (which `url(...)` scanning alone
+    # misses). Yields each raw target string.
+    def css_reference_targets(css)
+      return enum_for(:css_reference_targets, css) unless block_given?
+
+      css.scan(/url\(\s*(['"]?)(.*?)\1\s*\)/im) { |_quote, target| yield target }
+      css.scan(/@import\s+(['"])(.*?)\1/im) { |_quote, target| yield target }
+    end
+
+    # Classify a single reference target against the current allowances.
+    # Returns :dangerous (script/scriptable-data), :external, :data, or nil
+    # (relative/internal/allowed).
+    def classify_reference(target, allow_external: false, allow_data_uri: false)
+      scheme = uri_scheme(target)
+      return nil if scheme.nil?
+      return :dangerous if dangerous_scheme?(scheme)
+
+      if scheme == "data"
+        return :dangerous if scriptable_data?(data_uri_media_type(target))
+
+        return allow_data_uri ? nil : :data
+      end
+
+      return :external if external_scheme?(scheme) && !allow_external
+
+      nil
+    end
+
+    # Normalise arbitrary bytes to valid UTF-8 so downstream byte-level checks
+    # are meaningful and no encoding error can escape. Returns
+    # [:ok, string], [:bad_utf16, nil], or [:bad_utf8, nil].
+    def to_utf8(raw)
+      str = raw.to_s
+      bytes = str.b
+      head = bytes[0, 2]
+
+      if head == "\xFF\xFE".b || head == "\xFE\xFF".b
+        src = (head == "\xFF\xFE".b) ? Encoding::UTF_16LE : Encoding::UTF_16BE
+        begin
+          return [:ok, bytes[2..].force_encoding(src).encode(Encoding::UTF_8)]
+        rescue EncodingError
+          return [:bad_utf16, nil]
+        end
+      end
+
+      utf8 = str.dup.force_encoding(Encoding::UTF_8)
+      return [:ok, utf8] if utf8.valid_encoding?
+
+      [:bad_utf8, nil]
+    end
+
+    # True when this CSS text carries something executable or off-origin. Used
+    # by the Scanner to report and by the Sanitizer to decide whether to drop
+    # a style declaration wholesale.
+    def dangerous_css?(css, allow_external: false, allow_data_uri: false)
+      raw = strip_css_comments(css.to_s)
+      compact = decontrol(raw)
+      return true if compact.match?(/expression\s*\(/i)
+      return true if DANGEROUS_SCHEMES.any? { |s| compact.match?(/#{s}\s*:/i) }
+
+      css_reference_targets(raw).any? do |target|
+        !classify_reference(target, allow_external: allow_external, allow_data_uri: allow_data_uri).nil?
+      end
+    end
+  end
+end

data/lib/svg_sentinel/sanitizer.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+require "rexml/formatters/default"
+require_relative "rules"
+require_relative "scanner"
+
+module SvgSentinel
+  # Rewrites an SVG into a safe one, using the same allowlist and scheme rules
+  # the Scanner reports against (both mix in Rules, so they cannot disagree).
+  #
+  # It removes what it can fix - scripting and foreign elements, event-handler
+  # and dangerous-URI attributes, and dangerous CSS - and returns the cleaned
+  # SVG as a String. When the input carries a *structural* threat that cannot
+  # be rewritten safely (a DTD, a use bomb, oversize or malformed input, a
+  # non-<svg> root), it returns nil: the caller must reject, not serve.
+  #
+  # Removal, not repair, is the rule for CSS: a <style> element or style
+  # attribute containing anything dangerous is dropped whole rather than
+  # partially rewritten, because partial CSS rewriting is where sanitizers leak.
+  class Sanitizer
+    include Rules
+
+    # Raw finding codes that mean "do not attempt to clean this - reject it".
+    UNSANITIZABLE = %i[
+      empty_input malformed doctype too_large too_deep too_many_nodes
+      too_many_attributes no_root not_svg use_bomb use_cycle
+    ].freeze
+
+    def initialize(profile: :strict, allow_external: false, allow_data_uri: false,
+      max_bytes: Scanner::DEFAULT_MAX_BYTES, hard_max_bytes: Scanner::DEFAULT_HARD_MAX_BYTES,
+      max_depth: Scanner::DEFAULT_MAX_DEPTH, max_nodes: Scanner::DEFAULT_MAX_NODES,
+      max_attributes: Scanner::DEFAULT_MAX_ATTRIBUTES)
+      @profile = profile
+      @allow_external = allow_external
+      @allow_data_uri = allow_data_uri
+      @scanner_opts = {
+        profile: profile, allow_external: allow_external, allow_data_uri: allow_data_uri,
+        max_bytes: max_bytes, hard_max_bytes: hard_max_bytes,
+        max_depth: max_depth, max_nodes: max_nodes, max_attributes: max_attributes
+      }
+    end
+
+    # Returns cleaned SVG as a String, or nil when the input cannot be made
+    # safe by removal alone.
+    def sanitize(svg)
+      return nil unless sanitizable?(svg)
+
+      status, utf8 = Rules.to_utf8(svg)
+      return nil unless status == :ok
+
+      doc = safe_parse(utf8)
+      return nil if doc.nil?
+
+      root = doc.root
+      return nil if root.nil? || !root.name.casecmp?("svg")
+
+      strip!(root)
+      serialize(doc)
+    rescue SystemStackError
+      nil
+    end
+
+    private
+
+    # The Scanner is the single source of truth for "is this structurally
+    # unfixable". Run it with a neutral policy so the raw codes are visible.
+    def sanitizable?(svg)
+      codes = Scanner.new(**@scanner_opts).scan(svg).findings.map(&:code)
+      (codes & UNSANITIZABLE).empty?
+    end
+
+    def safe_parse(svg)
+      REXML::Document.new(svg)
+    rescue StandardError, SystemStackError
+      nil
+    end
+
+    def strip!(element)
+      removals = []
+      element.elements.each do |child|
+        if remove_element?(child)
+          removals << child
+        else
+          strip!(child)
+        end
+      end
+      removals.each { |child| element.delete_element(child) }
+
+      strip_attributes!(element)
+    end
+
+    def remove_element?(element)
+      name = element.name.downcase
+      return true if script_element?(name) || foreign_element?(name)
+      # A SMIL animation aimed at an event handler / href / style is a script
+      # injection regardless of profile.
+      if animation_element?(name) && sensitive_animation_target?(element.attributes["attributeName"].to_s)
+        return true
+      end
+      if strict? && (name == "image" || animation_element?(name) || !allowed_element?(name))
+        return true
+      end
+      return true if name == "style" && dangerous_style?(element_css(element))
+
+      false
+    end
+
+    def strip_attributes!(element)
+      removable = []
+      element.attributes.each do |name, value|
+        lname = name.downcase
+        if event_handler_attr?(lname)
+          removable << name
+        elsif lname == "style" && dangerous_style?(value)
+          removable << name
+        elsif uri_attribute?(lname) && dangerous_uri?(value)
+          removable << name
+        elsif lname != "style" && dangerous_style?(value)
+          # A url(...) or @import external/scheme reference hidden in a
+          # presentation attribute (fill, filter, mask, ...).
+          removable << name
+        end
+      end
+      removable.each { |name| element.delete_attribute(name) }
+    end
+
+    def dangerous_uri?(value)
+      scheme = uri_scheme(value)
+      return false if scheme.nil?
+      return true if dangerous_scheme?(scheme)
+
+      if scheme == "data"
+        return !@allow_data_uri || scriptable_data?(data_uri_media_type(value))
+      end
+
+      external_scheme?(scheme) && !@allow_external
+    end
+
+    def dangerous_style?(css)
+      Rules.dangerous_css?(css, allow_external: @allow_external, allow_data_uri: @allow_data_uri)
+    end
+
+    def element_css(element)
+      element.texts.join
+    end
+
+    def serialize(doc)
+      out = +""
+      REXML::Formatters::Default.new.write(doc, out)
+      out
+    end
+
+    def strict?
+      @profile == :strict
+    end
+  end
+end

data/lib/svg_sentinel/sarif.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "version"
+
+module SvgSentinel
+  # Builds a SARIF 2.1.0 log from scan results so findings drop straight into
+  # GitHub code scanning and other SARIF-aware tooling. Severity maps to SARIF
+  # level (critical -> error, warning -> warning); the element path becomes a
+  # logical location.
+  module Sarif
+    module_function
+
+    SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+    INFORMATION_URI = "https://github.com/msuliq/svg_sentinel"
+
+    LEVELS = {critical: "error", warning: "warning"}.freeze
+
+    # entries: an Array of [label, Result].
+    def document(entries)
+      results = []
+      rules = {}
+
+      entries.each do |label, result|
+        result.findings.each do |finding|
+          rules[finding.code] ||= rule_for(finding)
+          results << result_for(label, finding)
+        end
+      end
+
+      {
+        "version" => "2.1.0",
+        "$schema" => SCHEMA,
+        "runs" => [
+          {
+            "tool" => {
+              "driver" => {
+                "name" => "svg_sentinel",
+                "version" => SvgSentinel::VERSION,
+                "informationUri" => INFORMATION_URI,
+                "rules" => rules.values
+              }
+            },
+            "results" => results
+          }
+        ]
+      }
+    end
+
+    def rule_for(finding)
+      {
+        "id" => finding.code.to_s,
+        "name" => finding.code.to_s,
+        "shortDescription" => {"text" => finding.message},
+        "properties" => {"category" => finding.category.to_s}
+      }
+    end
+
+    def result_for(label, finding)
+      location = {
+        "physicalLocation" => {
+          "artifactLocation" => {"uri" => label}
+        }
+      }
+      if finding.path && !finding.path.empty?
+        location["logicalLocations"] = [{"fullyQualifiedName" => finding.path}]
+      end
+
+      {
+        "ruleId" => finding.code.to_s,
+        "level" => LEVELS.fetch(finding.severity, "note"),
+        "message" => {"text" => message_text(finding)},
+        "locations" => [location]
+      }
+    end
+
+    def message_text(finding)
+      finding.detail ? "#{finding.message} (#{finding.detail})" : finding.message
+    end
+  end
+end