Crate xss_filters

Expand description

Context-aware output encoders that prevent cross-site scripting.

Each filter encodes only the characters needed to keep an untrusted string from breaking out of a specific HTML output context. The supported contexts are HTML data, HTML comments, single/double/unquoted attribute values, and URIs placed inside any of those. URI filters normalize IPv6 hosts and block dangerous protocols such as javascript: and data:.

The design encodes the minimal set of characters required to thwart a context break, rather than entity-escaping everything. This is faster and avoids double-encoding.

§Choosing a filter

Match the filter to the exact place the value lands in the document.

use xss_filters::{in_html_data, in_double_quoted_attr, uri_in_double_quoted_attr};

// <div>{{ value }}</div>
assert_eq!(in_html_data("<script>"), "&lt;script>");

// <input value="{{ value }}">
assert_eq!(in_double_quoted_attr("a\"b"), "a&quot;b");

// <a href="{{ value }}">
assert_eq!(
    uri_in_double_quoted_attr("javascript:alert(1)"),
    "x-javascript:alert(1)"
);

§Input contract

All public functions take &str and return String. JavaScript-style coercion of non-string values is the caller’s job. Apply these filters only to UTF-8 documents. Do not apply them inside scriptable contexts such as <script>, <style>, <object>, <embed>, <svg>, or inside style and on* attributes.

§URI encoding and surrogates

The URI filters build on encoders equivalent to JavaScript encodeURI and encodeURIComponent. Those throw on a lone UTF-16 surrogate. A Rust &str is always well-formed UTF-8, so the &str entry points cannot reach that case. uri::encode_uri_units reproduces the throw for raw UTF-16 input.

Modules§

uri: Percent-encoding that matches JavaScript encodeURI and encodeURIComponent.

Functions§

in_double_quoted_attr: Encode " as " for double-quoted attribute context.
in_html_comment: Neutralize HTML comment closers for HTML comment context.
in_html_data: Encode < as < for HTML data context.
in_single_quoted_attr: Encode ' as ' for single-quoted attribute context.
in_unquoted_attr: Encode attribute-breaking characters for unquoted attribute context.
uri_component_in_double_quoted_attr: URI component inside a double-quoted attribute.
uri_component_in_html_comment: URI component in HTML comment context.
uri_component_in_html_data: URI component in HTML data context.
uri_component_in_single_quoted_attr: URI component inside a single-quoted attribute.
uri_component_in_unquoted_attr: URI component inside an unquoted attribute.
uri_fragment_in_double_quoted_attr: URI fragment inside a double-quoted attribute.
uri_fragment_in_html_comment: URI fragment in HTML comment context. Alias of the component filter.
uri_fragment_in_html_data: URI fragment in HTML data context. Alias of the component filter.
uri_fragment_in_single_quoted_attr: URI fragment inside a single-quoted attribute.
uri_fragment_in_unquoted_attr: URI fragment inside an unquoted attribute.
uri_in_double_quoted_attr: Full URI inside a double-quoted attribute.
uri_in_html_comment: Full URI in HTML comment context.
uri_in_html_data: Full URI in HTML data context. Only the URI encoder runs, since < is already %3C.
uri_in_single_quoted_attr: Full URI inside a single-quoted attribute.
uri_in_unquoted_attr: Full URI inside an unquoted attribute.
uri_path_in_double_quoted_attr: URI path or query inside a double-quoted attribute.
uri_path_in_html_comment: URI path or query in HTML comment context.
uri_path_in_html_data: URI path or query in HTML data context.
uri_path_in_single_quoted_attr: URI path or query inside a single-quoted attribute.
uri_path_in_unquoted_attr: URI path or query inside an unquoted attribute.
uri_query_in_double_quoted_attr: URI query inside a double-quoted attribute. Alias of the path filter.
uri_query_in_html_comment: URI query in HTML comment context. Alias of the path filter.
uri_query_in_html_data: URI query in HTML data context. Alias of the path filter.
uri_query_in_single_quoted_attr: URI query inside a single-quoted attribute. Alias of the path filter.
uri_query_in_unquoted_attr: URI query inside an unquoted attribute. Alias of the path filter.