ammonia

Ammonia is an allowlist-based HTML sanitization library for Rust. It is designed to prevent cross-site scripting (XSS), layout breaking, and clickjacking caused by untrusted, user-provided HTML being mixed into a larger web page. Rather than trying to blacklist dangerous constructs, it keeps only the tags and attributes you explicitly permit.

Ammonia parses and serializes document fragments with html5ever, the same parser used in Servo, so it handles malformed and deliberately obfuscated markup exactly as a browser would, making it highly resistant to evasion. A one-line clean function covers the common case, while a configurable Builder exposes fine-grained control over allowed tags, attributes, URL schemes, and link rel handling.

What You Get

• A clean() function that sanitizes an HTML string with safe defaults in one call
• A Builder for configuring allowed tags, attributes, URL schemes, and rel values
• clean_text() for escaping a string so it renders as literal text
• Browser-grade parsing via html5ever for resilience against obfuscated markup
• clean_from_reader() for sanitizing streamed HTML input

Common Use Cases

• Sanitizing HTML rendered from user-submitted Markdown before display
• Cleaning rich-text comments or forum posts to block XSS
• Restricting user HTML to a safe subset of tags and attributes
• Neutralizing untrusted HTML fragments embedded in a larger page

Under The Hood

Architecture — The core lives in src/lib.rs (~4,000 lines). The free functions clean and clean_text wrap a default Builder; the Builder struct holds the allowlist configuration (tags, generic and tag-specific attributes, URL schemes, rel, cleaned content tags, and more) and its clean/clean_from_reader methods drive the pipeline. Input is parsed into a DOM by html5ever (with a custom rcdom implementation in src/rcdom.rs), the tree is traversed and pruned of disallowed nodes and attributes, inline style is filtered through src/style.rs using cssparser, and the result is serialized back to HTML. Output is returned as a Document that derefs to the cleaned string.

Tech Stack — Rust 2021 edition, MSRV 1.80. Depends on html5ever for HTML5 parsing/serialization, cssparser for inline style filtering, url for URL validation, and maplit for allowlist literals. Dual-licensed MIT OR Apache-2.0, documented on docs.rs.

Code Quality — The project is mature and actively maintained with 34 contributors, a CHANGELOG.md, a SECURITY.md policy, a benchmarks harness, and CI via bors. Tests include version-numbers.rs plus inline unit tests, and version-sync enforces that documented versions stay consistent. The security-critical nature of the crate is reflected in its careful, browser-faithful parsing approach.

API Design — The API scales from trivial to precise: ammonia::clean(html) handles the common case with sensible defaults, while the fluent Builder lets callers tune every aspect of the allowlist without reaching into internals. Method names (add_tags, url_schemes, link_rel, clean_content_tags) are descriptive, and the crate is thoroughly documented, keeping the ramp-up short.