Zexplorer's HTML/CSS sanitizer provides defense-in-depth against XSS, mXSS, CSS injection, DOM clobbering, and protocol-based attacks. It operates structurally on the parsed DOM and CSS AST — not with regex or string replacement — making it resistant to parser differentials and encoding tricks.

The architecture follows a parse → annotate → batch-remove pattern: the document is parsed into a full DOM tree (via Lexbor), walked once to collect dangerous nodes and attributes, then all removals are applied in reverse order in a second pass. This avoids iterator corruption and use-after-free issues that plague in-place removal approaches.

The sanitizer operates on the live Lexbor DOM and CSS AST — there is no serialize/re-parse step, so there is no parse-differential surface for mXSS. HTML character references are decoded by Lexbor at parse time, before the sanitizer sees any attribute value.

The pipeline:

Raw HTML / SVG / CSS
        │
        ▼
  Lexbor parse ── entities decoded, DOM + CSSOM built
        │
        ├─── DOM node tree ──────────────────────┐
        │    walk every node                     │
        │    • remove dangerous elements         │
        │    • strip unsafe attributes           │    merge sanitized
        │    • inline style → CSS sanitizer      │    CSS back into DOM
        │                                        │
        └─── CSS AST (stylesheets + style="")  ──┘
             • remove dangerous at-rules
             • strip unsafe properties
             • validate URIs structurally

        ▼
  Sanitized DOM — safe for rendering or serialization

Policy decisions and known trade-offs:

Custom mode exposes SanitizeOptions for fine-grained control:

pub const SanitizeOptions = struct {
    remove_scripts: bool = true,
    remove_styles: bool = false,        // false = sanitize CSS instead of stripping
    sanitize_inline_styles: bool = true,
    skip_comments: bool = true,
    strict_uri_validation: bool = false,
    allow_custom_elements: bool = true,
    allow_framework_attrs: bool = true,
    sanitize_dom_clobbering: bool = true,
    allow_embeds: bool = false,
    allow_iframes: bool = false,
};

A single depth-first walk visits every node. For each element, a multi-layer validation pipeline runs:

Node
 ├─ Comment → remove if skip_comments
 ├─ Text → always safe (already parsed, no re-interpretation)
 └─ Element
     ├─ Template → recurse into fragment content separately
     ├─ Script → remove if remove_scripts
     ├─ Style → remove OR sanitize CSS content
     ├─ SVG context → SVG allowlist + attribute filter
     ├─ MathML context → MathML allowlist
     ├─ Known element → validate attributes (see below)
     └─ Unknown element
         ├─ Custom element (has hyphen, e.g. <my-widget>) → allow if configured
         └─ Otherwise → remove

Dangerous nodes and attributes are collected into lists — never removed during the walk.

After the walk completes:

1. Remove attributes flagged as dangerous
2. Update attributes with sanitized values (e.g. cleaned inline styles)
3. Recurse into <template> fragments (separate document fragments with their own walk)
4. Remove nodes in reverse discovery order — children are removed before their parents, preventing double-free

A single arena allocator backs all temporary strings and lists, deallocated in one call at the end.

Each attribute passes through up to five layers:

DANGEROUS_ATTRIBUTES is a StaticStringMap with O(1) lookup, plus a generic on* pattern catch for any event handler not explicitly listed:

• Named event handlers: onclick, onload, onerror, onfocus, onblur, onchange, onsubmit, onkeydown, onkeyup, onmouseover, onmouseenter, onmouseleave, onresize, onmessage, onstorage, onunload, onbeforeunload, onhashchange
• Generic on* pattern: any attribute starting with on followed by an alphabetic character is removed — catches all 72+ event handler variants without needing to enumerate them
• HTML injection: innerHTML, outerHTML, insertAdjacentHTML
• Framework HTML injection: x-html, v-html, ng-bind-html
• Legacy/dangerous: formaction, background, autofocus, integrity

Attribute values are checked for mutation XSS patterns — strings that, when re-parsed by the browser, change meaning:

• Tag breakouts: </style>, </script>, </title>, </textarea>, </noscript>
• CDATA/comment closers: ]]>, -->, --!>
• Namespace injection: xmlns=, xmlns:
• HTML5 quirks: <![, <!-, <%, %>

• Inline styles: sanitized via CSS sanitizer or removed based on config
• DOM clobbering: id and name attributes checked against DOM_CLOBBERING_NAMES
• Framework attributes: allowed/blocked per framework config, with JS pattern scanning on values

Each HTML element has a spec defining its allowed attributes and valid values:

• Enum validation: attributes like type, rel, target are checked against a list of valid values
• URI validation: href, src, action pass through validateUri
• SVG URI validation: xlink:href allows fragment-only references (#icon)
• Unknown attributes are removed (allowlist principle)

• target="_blank" requires rel containing noopener or noreferrer
• Missing dependency → attribute removed

URIs in href, src, action, poster, data, background attributes are normalized and validated:

1. HTML entity decoding (prevents javascript: bypasses)
2. Unicode whitespace trimming (prevents \u200E javascript: bypasses)
3. Control character stripping (prevents tab/newline injection in protocols)

Blocked protocols: javascript:, vbscript:, file:

Blocked data URIs: data:text/html, data:text/javascript, data:text/xml, data:application/xhtml, data:image/svg+xml

Allowed data URIs: data:image/* (except SVG) — images only

Strict mode additionally blocks: protocol-relative URLs (//evil.com), path traversal (../)

CSS is sanitized structurally, not with pattern matching. Two paths exist:

CSS is parsed into a Lexbor AST. Each rule is walked:

1. At-rules: @import, @charset, @namespace are always removed (external resource loading / encoding attacks). @keyframes, @media, @font-face are configurable.
2. Properties: checked against SAFE_CSS_PROPERTIES allowlist (whitelist approach) or DANGEROUS_CSS_PROPERTIES blocklist. Dangerous properties: behavior, -moz-binding, -webkit-user-modify, -o-link, -o-link-source, filter (with progid:).
3. Values: validated by the CssValueScanner.

The scanner is a compile-time generic parameterized by a CssFunctionRuleset:

const Scanner = CssValueScanner(specs.DEFAULT_RULESET);

It uses a two-state machine (NORMAL / IN_STRING) to distinguish:

• Function calls in normal context → classified and validated
• String literal content → skipped entirely (safe, cannot execute)

This prevents false positives like content: "expression() is not code" while still catching width: expression(alert(1)).

Each CSS function is classified at compile time:

Unknown functions are blocked (allowlist principle in DEFAULT_RULESET).

Three built-in rulesets are provided:

• DEFAULT_RULESET: allowlist approach with ~50 standard CSS functions. Unknown → blocked.
• STRICT_RULESET: minimal function set, maximum security.
• PERMISSIVE_RULESET: blocklist approach. Unknown → allowed. Only expression/eval/progid blocked.

Custom rulesets can be defined at compile time:

const my_ruleset = specs.CssFunctionRuleset{
    .functions = &.{
        .{ "expression", .blocked },
        .{ "url", .url_validate },
        .{ "calc", .allowed },
        .{ "var", .allowed },
        .{ "rgb", .allowed },
    },
    .unknown_function_policy = .blocked,
};

SVG elements use a dual allowlist/blocklist approach:

Allowed elements (allowlist, ~50 elements): shapes (rect, circle, path, polygon...), text (text, tspan), gradients, filters (feGaussianBlur, feBlend...), clipping/masking, containers (g, defs, symbol).

Blocked elements: script, animate, animateMotion, animateTransform, set, foreignObject (arbitrary HTML embedding), feImage (external resource loading), switch, view.

SVG attribute handling:

• Event handlers (on*) → always removed
• href / xlink:href → fragment-only validation (only #id references allowed, no external URLs)
• Unknown attributes → removed (allowlist)

When sanitize_dom_clobbering is enabled, id and name attributes are checked against a blocklist of names that shadow browser globals:

• Window/Document: location, document, window, self, top, parent, frames, history, navigator, screen, event
• Dangerous properties: eval, execScript, Function, Object, Array, __proto__, constructor
• HTML elements: form, iframe, image, embed, object, body, head, style, script
• Navigation: alert, confirm, prompt, open

Example: <img id="location"> is sanitized because it shadows window.location.

When allow_framework_attrs is enabled, framework-specific attributes are preserved with safety checks:

Framework attribute values are additionally scanned for dangerous JS patterns: eval(, import(, fetch(, javascript:, ${, =>, document.write, __proto__, etc.

Parser differential attacks exploit differences between the sanitizer's parser and the browser's parser. Defenses:

1. Lexbor HTML parser — same HTML5 spec-compliant parser used for both sanitization and rendering
2. mXSS pattern detection in attribute values and CSS
3. Template content isolation — <template> fragments are sanitized separately
4. No innerHTML re-serialization for security decisions — the sanitizer works on the DOM tree, not on re-serialized HTML strings

The sanitizer is validated against 350+ attack vectors from multiple sources:

Tests fail hard — any unhandled vector is a test failure:

zig build test -- --test-filter "sanitizer vector"

Zexplorer's ScriptEngine confines all local file access — JS module imports, file reads — to a sandbox root directory. This is an application-level sandbox using kernel-enforced file APIs, not OS-level sandboxing (seccomp, pledge, containers). It provides defense-in-depth: even if path normalization is bypassed, the kernel rejects the escape.

The Sandbox struct opens the root directory once at init and holds the file descriptor for the lifetime of the engine. All subsequent file operations use openat() relative to this FD — never constructing absolute paths from user input.

var sandbox = try Sandbox.init(allocator, "/path/to/project");
defer sandbox.deinit();

Optional import map support:

var sandbox = try Sandbox.initWithImportMap(allocator, root, import_map_json);

File opens go through openFileNoSymlinkEscape, which enforces four layers of protection:

The directory walk uses a fixed-size stack (16 levels deep), preventing allocation and bounding traversal depth.

Before any file I/O, isSafePath provides a fast logical check:

• Absolute paths: must start with the current working directory + / separator (blocks /home/user/sandbox_evil matching /home/user/sandbox)
• Relative paths: must not start with .. (blocks upward traversal)

• No process isolation: JS code runs in-process via QuickJS. A bug in the Zig/C layer could bypass the sandbox.
• No network isolation: Network access is controlled separately (see below), not by the filesystem sandbox.
• No resource limits: CPU/memory limits are not enforced at the sandbox level (QuickJS has its own memory limit API).

The JS module system (import ... from "...") uses a two-phase security model: normalize (path resolution) then load (file access or network fetch).

Resolves import specifiers to canonical paths without touching the filesystem:

Relative imports within remote modules (e.g., import "../react/+esm" from https://cdn.jsdelivr.net/npm/react-dom/+esm) are resolved as URL-relative, not filesystem-relative.

The normalizer also tries .js extension appending when the exact path doesn't exist.

Loads module content with security enforcement based on the source type:

Local files:

1. Opened via openFileNoSymlinkEscape (all sandbox protections apply)
2. Size-limited to 5 MB
3. Compiled as ES module by QuickJS

Remote modules:

Import maps support Subresource Integrity (SRI) hashes for supply-chain protection:

{
  "imports": {
    "solid-js": "https://cdn.jsdelivr.net/npm/solid-js@1.8/+esm"
  },
  "integrity": {
    "https://cdn.jsdelivr.net/npm/solid-js@1.8/+esm": "sha384-<base64hash>"
  }
}

Supported hash algorithms: SHA-256, SHA-384, SHA-512. If an integrity entry exists for a URL and the fetched content doesn't match, the module load fails.

All outbound HTTP requests — fetch(), module loading, image loading — are hardened via hardenEasy() applied to every curl handle.

These limits are unconditional — they apply in all modes, not just sanitize mode.

isBlockedUrl provides a pre-flight check that detects requests targeting internal infrastructure. It is enforced at runtime in all three outbound network paths when sanitize_enabled is true (untrusted content mode). When sanitize_enabled is false (trusted/local dev mode), all URLs including localhost are allowed.

Blocked targets:

The SSRF filter operates on the extracted hostname before DNS resolution, so it cannot be bypassed by DNS rebinding to private IPs. However, it only checks the initial URL — redirect targets are constrained by curl's protocol restriction (http,https only) and redirect hop limit, but not by the SSRF filter.

Not blocked in local dev mode: trusted code can freely fetch localhost for development workflows.

hardenEasy() (timeouts, size limits, protocol restrictions) is applied unconditionally at all four curl call sites. isBlockedUrl() SSRF filtering is enforced at the three JS-facing entry points, gated on sanitize_enabled:

The module loader already enforces HTTPS-only for remote imports, which implicitly blocks http://localhost and similar internal targets.

If you discover a sanitizer bypass, please report it responsibly. Open an issue or contact the maintainers directly. Include:

1. The input HTML/CSS payload
2. The sanitizer mode and options used
3. What dangerous content survives sanitization