ammonia

Ammonia's sanitization process involves several internal steps to ensure HTML safety:

1. Tag and Attribute Whitelisting: It checks if a tag is in the allowed list. For attributes, it verifies if they are generic (like class), prefixed with allowed prefixes, or explicitly whitelisted for that specific tag. It also supports validating specific attribute values.
2. URL Validation: For attributes identified as URLs (e.g., href, src, action, data), Ammonia validates the scheme against a whitelist (e.g., http, https) and can handle relative URL rewriting.
3. Namespace Protection: To prevent XSS via namespace switching (e.g., moving from HTML to SVG/MathML in ways that bypass security checks), Ammonia validates that namespace transitions follow the HTML specification (e.g., <svg> is the only valid way to enter the SVG namespace from HTML).
4. Special Attribute Transformations: Ammonia can automatically:
   • Rewrite relative URLs.
   • Add rel attributes to <a> tags.
   • Prefix id attributes with a user-provided string.
   • Filter style properties against a whitelist.
   • Filter class attributes to only include allowed classes.
5. SVG Animation Handling: It includes specialized logic for SVG <animate> and <set> elements to ensure that animated attribute values (like values, from, or to) are also sanitized according to the target tag's rules.

You can control how relative URLs in attributes (like href) are handled using the url_relative method on the Builder. This is useful for preventing XSS via javascript: URIs or for normalizing links to a specific base URL.

Supported strategies via UrlRelative:

• UrlRelative::Deny: Removes the attribute if it is a relative URL.
• UrlRelative::PassThrough: Keeps the relative URL as is.
• UrlRelative::RewriteWithBase(url): Rewrites relative URLs using the provided base URL.
• UrlRelative::Custom(callback): Allows you to provide a custom function to evaluate and potentially transform or deny URLs.

// Example: Rewriting relative URLs with a base URL
let result = Builder::new()
    .url_relative(UrlRelative::RewriteWithBase(
        Url::parse("http://example.com/").unwrap(),
    ))
    .clean("<a href=test>Test</a>")
    .to_string();
// result: <a href="http://example.com/test">Test</a>

You can control how relative URLs (those lacking a full scheme) are handled in attributes like src or href using the UrlRelative enum. This policy is applied to any attribute named src or href, as well as the data attribute of an object tag.

Available policies:

• Deny: Strips relative URLs entirely.
• PassThrough: Leaves relative URLs unchanged.
• RewriteWithBase(Url): Converts relative URLs into absolute URLs using the provided base URL.
• RewriteWithRoot { root: Url, path: String }: Forces absolute and relative paths into a specific directory structure. It treats the root as the base and uses path to resolve relative paths.
• Custom(Box<dyn UrlRelativeEvaluate>): Allows you to provide a custom function to evaluate and potentially rewrite the URL.

use ammonia::{Builder, UrlRelative};
use url::Url;

// Example: Custom URL rewriting
fn evaluate(url: &str) -> Option<std::borrow::Cow<str>> {
    if url.starts_with('/') {
        Some(std::borrow::Cow::Owned(format!("/root{}", url)))
    } else {
        Some(std::borrow::Cow::Borrowed(url))
    }
}

let a = Builder::new()
    .url_relative(UrlRelative::Custom(Box::new(evaluate)))
    .clean("<a href=/test/path>fixed</a>")
    .to_string();
// Result: <a href="/root/test/path" rel="noopener noreferrer">fixed</a>

Restrict which CSS classes are allowed on specific HTML tags using a map of tag names to sets of class names.

• allowed_classes(HashMap<&str, HashSet<&str>>): Overwrites the current class whitelist.
• add_allowed_classes(tag, IntoIter<T>): Adds classes to an existing tag's whitelist.
• rm_allowed_classes(tag, IntoIter<T>): Removes classes from a tag's whitelist.
• clone_allowed_classes(): Returns the current class configuration.

Warning: If the class attribute is already whitelisted as a generic attribute, adding entries to this map will cause a panic.

use ammonia::Builder;
use maplit::{hashmap, hashset};

let allowed_classes = hashmap![
    "code" => hashset!["rs", "ex", "c", "cxx", "js"]
];
let a = Builder::new()
    .allowed_classes(allowed_classes)
    .clean("<code class=rs>fn main() {}</code>")
    .to_string();
assert_eq!(a, "<code class=\"rs\">fn main() {}</code>");