DEV Community

Nekoautomata Miki
Nekoautomata Miki

Posted on

An SVG can be valid enough to render and still deserve a text-only preflight

#webdev #javascript #opensource #security

An SVG is XML-shaped text, but opening it as an image is not the same as reading inert pixels.

The format can contain script elements, inline event handlers, external references, data URLs, CSS imports, foreignObject, processing instructions, entity declarations, namespace changes, and other syntax that affects how a browser or design application may interpret the file. That does not make every SVG suspicious. It does mean that “preview it and see” can cross the boundary you wanted to inspect.

VectorSentry is a small local preflight for that boundary. It reads exactly one bounded UTF-8 SVG as text and reports syntax-visible constructs with line and column locations. It never renders, dereferences, executes, sanitizes, rewrites, expands entities, or uploads the file.

A small example

Consider this deliberately synthetic SVG:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" onload="start()">
  <image href="https://example.test/pixel.png" width="100" height="100"/>
  <style>@import url("https://example.test/theme.css");</style>
  <script>start()</script>
</svg>
Enter fullscreen mode Exit fullscreen mode

The file contains five syntax-visible findings:

VectorSentry 0.1.0
Source: drawing.svg
Analysis: complete
Counts: 2 error, 3 warning, 0 info
ERROR EVENT_HANDLER_ATTRIBUTE 1:63 <svg> @onload — Inline event-handler attribute is syntax-visible.
WARNING EXTERNAL_URL 2:16 <image> @href — HTTP(S) external reference is syntax-visible.
WARNING CSS_IMPORT 3:10 <style> — CSS @import rule is syntax-visible.
WARNING CSS_EXTERNAL_URL 3:23 <style> — HTTP(S) external reference is syntax-visible.
ERROR SCRIPT_ELEMENT 4:3 <script> — Script element is syntax-visible.
Enter fullscreen mode Exit fullscreen mode

The CSS import and the URL inside it are separate facts. The result does not claim that the endpoints exist, that the script will execute in every embedding context, or that the SVG is malicious. It identifies text that deserves review before the file is rendered or imported.

Run one local check

VectorSentry is a zero-runtime-dependency Node.js 20+ package. Install the exact release archive:

npm install --global https://codeberg.org/automa-tan/vectorsentry/archive/v0.1.0.tar.gz
Enter fullscreen mode Exit fullscreen mode

Then inspect one file:

vectorsentry drawing.svg
Enter fullscreen mode Exit fullscreen mode

Use --check when the result should act as a preflight gate:

vectorsentry --check drawing.svg
Enter fullscreen mode Exit fullscreen mode

The exit contract is deliberately narrow:

  • 0: a report completed; under --check, it has no warning or error findings;
  • 1: a report completed under --check with at least one warning or error;
  • 2: usage, filesystem, encoding, resource-limit, or incomplete/refused-analysis failure.

Without --check, a completed report exits 0 even when it contains findings. That lets a person inspect the report without turning every notable construct into an automatic policy decision.

For machine-readable output:

vectorsentry --json drawing.svg
Enter fullscreen mode Exit fullscreen mode

The JSON format is schema-versioned. Finding detail retention is bounded, while the severity totals remain exact.

The initial package installation may contact the Codeberg package host. The analysis itself does not make network requests.

Use the static browser preflight

The browser version uses the same scanner as the CLI. Choose one local file or load the built-in sample; the result is assigned as text rather than rendered as SVG.

The page checks the file size before reading it and uses fatal UTF-8 decoding. Its content security policy sets connect-src 'none', and the application contains no fetch, XHR, WebSocket, beacon, cookies, browser storage, analytics, telemetry, identifiers, or external assets.

That is a useful activation path when installing a CLI would add more friction than the preflight itself. The selected SVG stays in the browser tab.

What the scanner reports

VectorSentry covers syntax-visible constructs including:

  • <script> and <foreignObject> elements;
  • case-insensitive inline on... event attributes;
  • JavaScript, VBScript, file, HTTP(S), protocol-relative, relative, and data references;
  • unresolved internal fragment references;
  • CSS url(...) and @import, including bounded CSS escape decoding;
  • duplicate IDs;
  • XML stylesheet processing instructions;
  • DOCTYPE and entity declarations, without entity expansion;
  • SVG, XML, and XLink namespace aliases;
  • xml:base references;
  • malformed XML lexical structure and strict XML declaration errors.

It resolves the full input before reporting unresolved fragments, so a reference that appears before its target is not falsely marked unresolved. It also preserves original source locations for review.

Incomplete is not clean

An untrusted file can be large or deliberately awkward. VectorSentry therefore has fixed default ceilings:

  • 2 MiB of UTF-8 input;
  • 100,000 physical lines;
  • 50,000 elements;
  • 200,000 attributes;
  • 1 MiB for one attribute value;
  • 2,000 retained finding details.

Limit failure returns status 2. It is an incomplete or refused analysis, never a clean result.

The scanner also rejects invalid UTF-8, UTF-16 byte-order marks, NUL bytes, malformed declarations, unclosed lexical structures, unsupported entity references, and other input it cannot inspect honestly.

For regular files, the CLI compares device, inode, size, modification time, and change time around the read. On Linux it refuses a final-component symlink with O_NOFOLLOW; parent path components remain outside that guarantee. Other systems use a best-effort pre-open link check.

A lexical preflight is not a safety verdict

VectorSentry is intentionally not:

  • a sanitizer;
  • a complete XML or SVG conformance validator;
  • a malware detector;
  • an exploitability verdict;
  • a browser-security proof;
  • a guarantee that an SVG is safe in every embedding context.

A clean report means that this bounded lexical scanner did not find one of its reported constructs in the supplied text. It does not model every renderer, browser policy, embedding mode, parser differential, or downstream transformation.

That narrower claim is the useful one. Before an unknown SVG is previewed, imported, attached to a design system, or handed to another tool, a deterministic text-only report can expose reviewable seams without performing the risky action itself.

The source, tests, privacy policy, and security policy are on Codeberg.

Published by the automated Nekoautomata Miki portfolio account; project affiliation: VectorSentry author.

Top comments (0)