svg_sentinel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 701c3e02059142d834510ee665c65a97dde302d8b6fc021b8bc9c4306a0495be
+  data.tar.gz: e29d8642b130f24120d831fd3b9f94501e1125aa1a05479125be4a06d8f0669e
+SHA512:
+  metadata.gz: 490617c8ecd277a6948d0148a831559b9f1eb8c872a1877da99ca68b963f259d44e0a05c17722ea08f32031137b58685fbb0a642205ac82817e99e873aba601c
+  data.tar.gz: c8b676b761459e0057d2df615054a941adab0897d4216c60e2b4f2e48111398ba432cf536bc55096647592bf6c6316341a23d47207b84eadc5baea0a73f31b0f

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `SvgSentinel.scan` and `SvgSentinel.safe?`.
+- `SvgSentinel.sanitize` rewrites an SVG into a safe one (allowlist-based),
+  returning the cleaned String, or nil when the threat is structural and
+  cannot be rewritten (DTD, use bomb, oversize, malformed, non-<svg> root).
+- Detection of scripts, event handlers, javascript:/vbscript:/data: URIs,
+  foreign objects, scriptable `data:` media types, nested-`<use>` render
+  bombs, and SMIL `<animate>`/`<set>` that target a sensitive attribute
+  (an `on*` handler, `href`, or `style`).
+- External-reference detection across URI attributes, presentation-attribute
+  `url()` (fill, filter, mask, ...), and CSS `url()` and `@import` (both the
+  `url()` and string forms).
+- DOCTYPE / ENTITY refusal to prevent XXE and entity-expansion attacks.
+- Strict profile is an allowlist: elements outside a conservative static-SVG
+  set are reported (`:disallowed_element`). A general profile keeps every
+  security check but drops the cosmetic ones.
+- Findings carry a `severity` (`:critical` / `:warning`), a `category`
+  (`:security` / `:policy`), and the element `path` where they occurred.
+  `Result#security_findings` / `Result#policy_findings` filter by category.
+- Rendering context: `scan(svg, context:)` re-rates findings for how the SVG
+  will be used. `:inline` (default) and `:standalone` keep full severity;
+  `:img` and `:css_background` downgrade scripting/external findings that a
+  browser runs inert in secure-static mode. XXE, use bombs, and size limits
+  are never downgraded.
+- Hostile-input hardening: input is normalised to valid UTF-8 (invalid bytes
+  become a `:malformed` finding, never an exception); a hard byte cap
+  (`hard_max_bytes`) and streaming structural limits (`max_depth`, `max_nodes`,
+  `max_attributes`) refuse pathological payloads before the tree parser runs.
+- Configuration via `.svg_sentinel.yml` (auto-discovered, or `--config PATH`):
+  profile, context, limits, per-code `severity` overrides, and `disabled`
+  codes.
+- `svg_sentinel` command-line tool with CI-friendly exit codes (0 safe,
+  1 unsafe, 2 error), STDIN support, `--sanitize`, `--context`, and
+  `--format text|json|sarif` (SARIF 2.1.0 for GitHub code scanning).
+- A YAML payload corpus (`spec/fixtures/payloads.yml`) of known XSS/XXE
+  vectors and benign controls, plus a differential-oracle harness that
+  cross-checks against a real renderer when `SVG_SENTINEL_ORACLE` is set.
+
+### Robustness
+
+- A size/structural limit of `0` (or negative) means "disabled" everywhere,
+  decided in one place, so config, CLI, and library agree.
+- `scan` and `sanitize` convert a stack overflow from pathologically nested
+  input into a finding / nil instead of raising, even with limits disabled.
+- A malformed or non-mapping `.svg_sentinel.yml` raises `SvgSentinel::ConfigError`
+  (CLI: a clean message and exit 2) instead of leaking a Psych stack trace.
+- CLI gained `--max-attributes`; config discovery from the working directory
+  is documented as a trust boundary for security-gate use.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleyman Musayev
+
+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,245 @@
+# SvgSentinel
+
+Lint or sanitize untrusted SVG before you render or embed it.
+
+SVG is XML that a browser will execute. It can carry `<script>`, `onload=`
+handlers, `javascript:` URIs, `<foreignObject>` full of HTML, references to
+remote servers, `<!ENTITY>` payloads that expand until your process falls over,
+and nested `<use>` elements that expand into millions of nodes. If you accept
+SVG from users - avatars, brand logos, uploaded icons - you need to know what is
+inside before you serve it.
+
+SvgSentinel reads an SVG and tells you what makes it dangerous, and can rewrite
+it into a safe one. It reports; you decide - or you hand it `sanitize` and let
+it clean.
+
+## Why it exists
+
+- **Catches the real risks.** Scripts, event handlers, `javascript:` and
+  scriptable `data:` URIs (including whitespace-obfuscated ones), foreign
+  objects, external references (in attributes **and** CSS `url()`), XXE via
+  `DOCTYPE`/`ENTITY`, and `<use>` expansion bombs.
+- **Safe to run on hostile input.** Input is normalised to valid UTF-8 first
+  (a stray byte can never crash the scanner), a hard byte cap and a streaming
+  structural pass (depth / node / attribute limits) refuse pathological
+  payloads before the tree parser runs, DTDs are refused so the parser can't be
+  attacked with entity expansion, and every parse failure becomes a finding
+  rather than an exception. Nothing is ever fetched over the network.
+- **Context-aware.** The same SVG is dangerous differently depending on how a
+  browser runs it. `scan(svg, context: :img)` knows that an SVG loaded through
+  `<img>` or CSS runs without scripting, and re-rates findings accordingly.
+- **Cleans, not just complains.** `SvgSentinel.sanitize` rewrites an SVG into a
+  safe one using the same allowlist, or returns `nil` when the threat is
+  structural and can't be rewritten.
+- **Strict profile is an allowlist.** `:strict` permits a conservative set of
+  static SVG elements and flags everything else - so a new dangerous element is
+  caught for simply not being on the list. It matches what a brand-mark logo
+  (BIMI "SVG Tiny 1.2 Portable/Secure") is allowed to contain. `:general` keeps
+  every security check but drops the cosmetic ones.
+- **Dependency-light.** Pure Ruby, parses with REXML. No native extensions.
+
+## Installation
+
+```ruby
+gem "svg_sentinel"
+```
+
+Then `bundle install`, or `gem install svg_sentinel`.
+
+## Usage
+
+```ruby
+require "svg_sentinel"
+
+result = SvgSentinel.scan(svg_string)
+
+result.safe?             # => false   (no critical findings means safe)
+result.critical?         # => true
+result.criticals         # => [#<Finding code=:script_element severity=:critical ...>]
+result.warnings          # => [...]
+result.security_findings # => real attack surface (any severity)
+result.policy_findings   # => strict-profile house rules (any severity)
+result.to_h              # => { safe: false, findings: [...] }
+
+# Quick predicate
+SvgSentinel.safe?(svg_string)   # => true / false
+```
+
+Each finding carries a `code`, a `severity` (`:critical` or `:warning`), a
+`category` (`:security` or `:policy`), a human `message`, an optional `detail`,
+and the element `path` where it occurred:
+
+```ruby
+SvgSentinel.scan('<svg onload="x()"><script>y()</script></svg>').findings.map(&:to_h)
+# => [
+#   { code: :event_handler, severity: :critical, category: :security,
+#     message: "Event-handler attribute onload", detail: "x()", path: "svg" },
+#   { code: :script_element, severity: :critical, category: :security,
+#     message: "Scripting element <script>", detail: nil, path: "svg/script" }
+# ]
+```
+
+`severity` and `category` are orthogonal: use `severity` (or `safe?`) to decide
+whether to render, and `category` to separate genuine security signals from
+strict-profile compliance noise.
+
+## Sanitizing
+
+`sanitize` returns cleaned SVG, or `nil` when the input carries a structural
+threat that can't be rewritten (DTD/XXE, use bomb, oversize, malformed, a
+non-`<svg>` root). Fixable problems - scripts, handlers, dangerous URIs,
+dangerous CSS - are removed.
+
+```ruby
+clean = SvgSentinel.sanitize(untrusted_svg)
+if clean
+  store(clean)   # safe to serve
+else
+  reject!        # nothing safe could be produced
+end
+```
+
+Sanitizing removes; it does not repair. A `<style>` block or `style` attribute
+that contains anything dangerous is dropped whole rather than partially
+rewritten - partial CSS rewriting is where sanitizers leak.
+
+## Rendering context
+
+An SVG in `<img src>` or a CSS `background` runs in the browser's secure-static
+mode: no scripting, no external subresources. Findings that only matter when
+the SVG can script or fetch are downgraded to warnings there, so they don't
+make the SVG "unsafe" on their own. Parser-level and denial-of-service findings
+(XXE, use bombs, oversize) are never downgraded.
+
+```ruby
+svg = '<svg onload="track()">...</svg>'
+SvgSentinel.safe?(svg)                    # => false  (context: :inline, default)
+SvgSentinel.safe?(svg, context: :img)     # => true   (onload never fires in <img>)
+```
+
+Contexts: `:inline` (default), `:standalone`, `:img`, `:css_background`.
+
+## Command line
+
+```bash
+svg_sentinel logo.svg                 # exit 0 if safe, 1 if unsafe
+cat logo.svg | svg_sentinel           # read from STDIN
+svg_sentinel --context img icons/*.svg
+svg_sentinel --format sarif *.svg     # SARIF 2.1.0 for code scanning
+svg_sentinel --sanitize logo.svg      # write cleaned SVG to stdout
+```
+
+Exit codes: **0** every input is safe, **1** at least one input is unsafe
+(so CI fails), **2** a usage/config error or an unreadable file. Run
+`svg_sentinel --help` for all options.
+
+## Configuration
+
+Settings can live in `.svg_sentinel.yml` (auto-discovered in the working
+directory, or `--config PATH`). Command-line flags override the file.
+
+```yaml
+profile: strict
+context: img
+allow_external: false
+severity:
+  external_ref: error     # treat as critical in this repo
+  raster_image: ignore    # we accept raster logos
+disabled:
+  - css_import
+```
+
+The same overrides work in code:
+
+```ruby
+SvgSentinel.scan(svg, severity_overrides: {external_ref: :error}, disabled: [:css_import])
+```
+
+**Security note on config discovery.** The CLI auto-discovers `.svg_sentinel.yml`
+from the working directory, and that file can `disable` checks or downgrade
+their `severity`. Like other linters this is convenient, but it means a config
+dropped into a directory can weaken the gate. When you run SvgSentinel as a
+**security gate over untrusted content** (e.g. scanning an upload directory or
+an untrusted checkout), pass an explicit `--config` you control and do not run
+it from a directory whose contents you don't trust.
+
+## What counts as critical vs warning
+
+**Critical** (unsafe to render or embed as-is):
+
+- `script`, `handler`, `listener` elements
+- `on*` event-handler attributes
+- SMIL `<animate>`/`<set>` targeting a sensitive attribute (`attributeName` of
+  an `on*` handler, `href`, or `style`)
+- `javascript:`, `vbscript:`, and similar URIs (whitespace/control-char
+  obfuscation is stripped before the check), in attributes and in CSS
+- `data:` URIs (unless `allow_data_uri: true`); scriptable `data:` media types
+  (`image/svg+xml`, `text/html`, `*/xml`) are refused **even with**
+  `allow_data_uri: true`
+- `foreignObject`, `iframe`, `embed`, `object`, `audio`, `video`, `canvas`
+- `DOCTYPE` or `ENTITY` declarations (XXE, entity expansion)
+- `expression(...)` or script URIs inside CSS
+- nested `<use>` that expands past ~1,000,000 nodes (render DoS)
+- input past the hard byte cap, too deeply nested, too many elements, too many
+  attributes on one element, malformed, empty, or not valid UTF-8
+
+**Warning** (safe to render, but disallowed by the strict brand-mark profile,
+or otherwise worth a look):
+
+- external `http(s)`/`ftp` references (unless `allow_external: true`), in
+  URI attributes, presentation-attribute `url()` (fill, filter, mask, ...),
+  and CSS `url()` / `@import`
+- raster `<image>` elements
+- animation elements (`animate`, `set`, ...)
+- any element outside the strict allowlist (`:disallowed_element`)
+- `@import` in CSS
+- recursive `<use>` references
+- oversize input (soft threshold, default 32 KB)
+
+## Options
+
+```ruby
+SvgSentinel.scan(svg,
+  profile: :strict,          # :strict (default) or :general
+  context: :inline,          # :inline (default), :standalone, :img, :css_background
+  allow_external: false,     # permit http(s)/ftp references
+  allow_data_uri: false,     # permit non-scriptable data: URIs
+  max_bytes: 32_768,         # soft size-warning threshold; nil to disable
+  hard_max_bytes: 5_242_880, # hard refuse-to-parse cap; nil to disable
+  max_depth: 100,            # max element nesting; nil to disable
+  max_nodes: 200_000,        # max element count; nil to disable
+  max_attributes: 512,       # max attributes on one element; nil to disable
+  severity_overrides: {},    # code => :error / :warning / :ignore
+  disabled: [])              # codes to drop entirely
+```
+
+`sanitize` accepts the same profile, `allow_external`, `allow_data_uri`, and
+size/structural options.
+
+## Scope and limits
+
+SvgSentinel is a static analyzer. No static analyzer can perfectly mirror a
+browser's HTML/SVG parser, so for genuinely hostile input the defence-in-depth
+answers still apply: serve untrusted SVG from a sandboxed origin under CSP, or
+rasterize it server-side. REXML, like any XML parser, has its own parsing-DoS
+history; the hard byte cap, the streaming structural limits, and DTD refusal
+are the mitigations - size them to your workload.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+The vector corpus lives in `spec/fixtures/payloads.yml`. To cross-check against
+a real renderer, point `SVG_SENTINEL_ORACLE` at a command that reads an SVG on
+stdin and prints `executes` or `inert`:
+
+```bash
+SVG_SENTINEL_ORACLE='node spec/support/dompurify_probe.js' bundle exec rspec
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/svg_sentinel

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "svg_sentinel/cli"
+
+exit SvgSentinel::CLI.run(ARGV)

data/lib/svg_sentinel/cli.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require_relative "../svg_sentinel"
+require_relative "config"
+require_relative "sarif"
+
+module SvgSentinel
+  # Command-line entry point. Scans one or more SVG files (or STDIN) and exits
+  # non-zero when any input is unsafe, so it drops into CI and pre-commit hooks.
+  #
+  #   svg_sentinel logo.svg                 # exit 0 if safe, 1 if unsafe
+  #   cat logo.svg | svg_sentinel           # read from STDIN
+  #   svg_sentinel --format sarif *.svg     # SARIF for code scanning
+  #   svg_sentinel --context img icons/*.svg
+  #
+  # Settings come from `.svg_sentinel.yml` (auto-discovered in the working
+  # directory, or --config PATH); command-line flags override the file.
+  #
+  # Exit codes:
+  #   0  every input scanned and safe
+  #   1  at least one input scanned as unsafe (takes precedence, so CI fails)
+  #   2  a usage/config error, or an input could not be read
+  class CLI
+    EXIT_SAFE = 0
+    EXIT_UNSAFE = 1
+    EXIT_ERROR = 2
+
+    # Options that Sanitizer accepts (context/overrides are scan-only).
+    SANITIZE_KEYS = %i[
+      profile allow_external allow_data_uri
+      max_bytes hard_max_bytes max_depth max_nodes max_attributes
+    ].freeze
+
+    def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      new(stdin: stdin, stdout: stdout, stderr: stderr).run(argv)
+    end
+
+    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @done = false
+    end
+
+    def run(argv)
+      flags = {}
+      meta = {format: :text, config: nil, sanitize: false}
+      paths = parse!(argv, flags, meta)
+      return EXIT_SAFE if @done # --help / --version already printed
+
+      scan_opts = load_config(meta[:config]).to_scan_options.merge(flags)
+      inputs = collect_inputs(paths)
+
+      return run_sanitize(inputs, scan_opts) if meta[:sanitize]
+
+      run_scan(inputs, scan_opts, meta[:format])
+    rescue OptionParser::ParseError, ConfigError => e
+      @stderr.puts("svg_sentinel: #{e.message}")
+      EXIT_ERROR
+    end
+
+    private
+
+    def run_scan(inputs, scan_opts, format)
+      results = []
+      had_error = false
+
+      inputs.each do |label, source|
+        if source.nil?
+          had_error = true
+          next
+        end
+        results << [label, SvgSentinel.scan(source, **scan_opts)]
+      end
+
+      emit(results, format)
+
+      return EXIT_UNSAFE if results.any? { |_, r| !r.safe? }
+      return EXIT_ERROR if had_error
+
+      EXIT_SAFE
+    end
+
+    # Writes cleaned SVG to stdout for each input; an input that cannot be made
+    # safe is rejected (stderr note) and makes the run exit non-zero.
+    def run_sanitize(inputs, scan_opts)
+      san_opts = scan_opts.slice(*SANITIZE_KEYS)
+      had_error = false
+      rejected = false
+
+      inputs.each do |label, source|
+        if source.nil?
+          had_error = true
+          next
+        end
+        clean = SvgSentinel.sanitize(source, **san_opts)
+        if clean
+          @stdout.puts(clean)
+        else
+          @stderr.puts("svg_sentinel: #{label}: cannot be sanitized safely; rejected")
+          rejected = true
+        end
+      end
+
+      return EXIT_UNSAFE if rejected
+      return EXIT_ERROR if had_error
+
+      EXIT_SAFE
+    end
+
+    def parse!(argv, flags, meta)
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: svg_sentinel [options] [file ...]"
+        o.separator("")
+        o.separator("Reads SVG files (or STDIN when no files are given, or for '-').")
+        o.separator("")
+        o.on("--profile PROFILE", %w[strict general], "Profile: strict (default) or general") do |v|
+          flags[:profile] = v.to_sym
+        end
+        o.on("--context CONTEXT", %w[inline standalone img css_background],
+          "Rendering context (default inline)") { |v| flags[:context] = v.to_sym }
+        o.on("--[no-]allow-external", "Permit http(s)/ftp references") { |v| flags[:allow_external] = v }
+        o.on("--[no-]allow-data-uri", "Permit non-scriptable data: URIs") { |v| flags[:allow_data_uri] = v }
+        o.on("--max-bytes N", Integer, "Soft size-warning threshold (0 disables)") do |v|
+          flags[:max_bytes] = v
+        end
+        o.on("--hard-max-bytes N", Integer, "Hard cap; refuse to parse above it (0 disables)") do |v|
+          flags[:hard_max_bytes] = v
+        end
+        o.on("--max-depth N", Integer, "Max element nesting depth (0 disables)") { |v| flags[:max_depth] = v }
+        o.on("--max-nodes N", Integer, "Max element count (0 disables)") { |v| flags[:max_nodes] = v }
+        o.on("--max-attributes N", Integer, "Max attributes on one element (0 disables)") do |v|
+          flags[:max_attributes] = v
+        end
+        o.on("--format FORMAT", %w[text json sarif], "Output format (default text)") do |v|
+          meta[:format] = v.to_sym
+        end
+        o.on("--json", "Alias for --format json") { meta[:format] = :json }
+        o.on("--config PATH", "Load settings from PATH (default .svg_sentinel.yml)") do |v|
+          meta[:config] = v
+        end
+        o.on("--sanitize", "Write cleaned SVG to stdout instead of scanning") { meta[:sanitize] = true }
+        o.on("-h", "--help", "Show this help") do
+          @stdout.puts(o)
+          @done = true
+        end
+        o.on("-v", "--version", "Show version") do
+          @stdout.puts(SvgSentinel::VERSION)
+          @done = true
+        end
+      end
+      parser.parse(argv)
+    end
+
+    def load_config(path)
+      return Config.load_file(path) if path
+
+      Config.discover(Dir.pwd)
+    rescue SystemCallError => e
+      raise ConfigError, "config: #{e.message}"
+    end
+
+    def collect_inputs(paths)
+      return [["(stdin)", read_stdin]] if paths.empty?
+
+      paths.map do |path|
+        (path == "-") ? ["(stdin)", read_stdin] : [path, read_file(path)]
+      end
+    end
+
+    def read_stdin
+      @stdin.binmode if @stdin.respond_to?(:binmode)
+      @stdin.read
+    end
+
+    def read_file(path)
+      File.binread(path)
+    rescue SystemCallError => e
+      @stderr.puts("svg_sentinel: #{path}: #{e.message}")
+      nil
+    end
+
+    def emit(results, format)
+      case format
+      when :json then emit_json(results)
+      when :sarif then emit_sarif(results)
+      else emit_text(results)
+      end
+    end
+
+    def emit_text(results)
+      results.each do |label, result|
+        status = result.safe? ? "SAFE" : "UNSAFE"
+        @stdout.puts("#{label}: #{status} (#{result.criticals.size} critical, #{result.warnings.size} warning)")
+        result.findings.each do |f|
+          location = (f.path && !f.path.empty?) ? "  (#{f.path})" : ""
+          detail = f.detail ? " - #{f.detail}" : ""
+          @stdout.puts("  [#{f.severity}/#{f.category}] #{f.code}: #{f.message}#{detail}#{location}")
+        end
+      end
+    end
+
+    def emit_json(results)
+      payload = results.map { |label, result| {file: label}.merge(result.to_h) }
+      @stdout.puts(JSON.pretty_generate(payload))
+    end
+
+    def emit_sarif(results)
+      @stdout.puts(JSON.pretty_generate(Sarif.document(results)))
+    end
+  end
+end

data/lib/svg_sentinel/config.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "errors"
+
+module SvgSentinel
+  # Loads scan settings from a `.svg_sentinel.yml` file (or a plain Hash) so a
+  # team can pin a profile, a rendering context, size limits, and - most
+  # usefully - per-finding severity, without forking the source.
+  #
+  #   # .svg_sentinel.yml
+  #   profile: strict
+  #   context: img
+  #   allow_external: false
+  #   severity:
+  #     external_ref: error     # treat as critical in this repo
+  #     raster_image: ignore    # we accept raster logos
+  #   disabled:
+  #     - css_import
+  #
+  # `to_scan_options` returns a kwargs Hash ready to splat into
+  # SvgSentinel.scan. Only keys present in the config are returned, so caller
+  # (e.g. CLI) flags can be merged on top and win.
+  class Config
+    OPTION_KEYS = %i[
+      profile context allow_external allow_data_uri
+      max_bytes hard_max_bytes max_depth max_nodes max_attributes
+    ].freeze
+
+    SYMBOL_KEYS = %i[profile context].freeze
+
+    FILENAME = ".svg_sentinel.yml"
+
+    def self.load_file(path)
+      data = YAML.safe_load_file(path) || {}
+      raise ConfigError, "#{path}: expected a mapping" unless data.is_a?(Hash)
+
+      new(data)
+    rescue Psych::SyntaxError => e
+      raise ConfigError, "#{path}: invalid YAML (#{e.message})"
+    end
+
+    def self.discover(dir = Dir.pwd)
+      path = File.join(dir, FILENAME)
+      File.file?(path) ? load_file(path) : new({})
+    end
+
+    def initialize(data = {})
+      @data = symbolize_keys(data)
+    end
+
+    def to_scan_options
+      opts = {}
+      OPTION_KEYS.each do |key|
+        next unless @data.key?(key)
+
+        value = @data[key]
+        opts[key] = (SYMBOL_KEYS.include?(key) && value) ? value.to_sym : value
+      end
+      opts[:severity_overrides] = symbolize_keys(@data[:severity]) if @data.key?(:severity)
+      opts[:disabled] = Array(@data[:disabled]).map(&:to_sym) if @data.key?(:disabled)
+      opts
+    end
+
+    private
+
+    def symbolize_keys(hash)
+      (hash || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end

data/lib/svg_sentinel/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SvgSentinel
+  # Base class for all errors this library raises deliberately.
+  class Error < StandardError; end
+
+  # Raised for a bad configuration or option: an unparseable config file, a
+  # config that is not a mapping, or an unknown severity override. Distinct
+  # from a programming ArgumentError so the CLI can report config problems
+  # cleanly (exit 2) without swallowing genuine internal errors.
+  class ConfigError < Error; end
+end

data/lib/svg_sentinel/finding.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module SvgSentinel
+  # One thing the scanner noticed.
+  #
+  # Two orthogonal axes describe a finding:
+  #
+  # * severity - :critical (unsafe to render or embed as-is) or :warning
+  #   (worth a second look, but not on its own a reason to reject).
+  # * category - :security (an actual attack surface: scripts, XXE, script
+  #   URIs, external references) or :policy (a brand-mark / strict-profile
+  #   house rule such as animation, raster images, or size).
+  #
+  # `safe?` keys off severity; the category lets a caller separate genuine
+  # security signals from profile-compliance noise.
+  #
+  # `path` is the slash-joined element path where the finding occurred
+  # (e.g. "svg/g/script"), or nil for document-level findings.
+  Finding = Struct.new(:code, :severity, :category, :message, :detail, :path, keyword_init: true) do
+    def critical?
+      severity == :critical
+    end
+
+    def warning?
+      severity == :warning
+    end
+
+    def security?
+      category == :security
+    end
+
+    def policy?
+      category == :policy
+    end
+
+    def to_h
+      {code: code, severity: severity, category: category, message: message, detail: detail, path: path}
+    end
+  end
+end