"
ammonia-3.1.2/examples/ammonia-cat.rs 0000644 0000000 0000000 00000001446 00000000000 0015604 0 ustar 0000000 0000000 use ammonia::Builder;
use std::env;
use std::fs::File;
use std::io::{self, Read, Write};
use std::process;
fn run() -> io::Result<()> {
let input = env::args().nth(1).unwrap_or_else(|| String::from("-"));
let output = env::args().nth(2).unwrap_or_else(|| String::from("-"));
let mut rdr: Box = if input == "-" {
Box::new(io::stdin())
} else {
Box::new(File::open(input)?)
};
let mut wrt: Box = if output == "-" {
Box::new(io::stdout())
} else {
Box::new(File::create(output)?)
};
Builder::new()
.clean_from_reader(&mut rdr)?
.write_to(&mut wrt)?;
Ok(())
}
fn main() {
env_logger::init();
if let Err(ref e) = run() {
println!("error: {}", e);
process::exit(1);
}
}
ammonia-3.1.2/src/lib.rs 0000644 0000000 0000000 00000361201 00000000000 0013133 0 ustar 0000000 0000000 // Copyright (C) Michael Howell and others
// this library is released under the same terms as Rust itself.
#![forbid(unsafe_code)]
#![forbid(missing_docs)]
//! Ammonia is a whitelist-based HTML sanitization library. It is designed to
//! prevent cross-site scripting, layout breaking, and clickjacking caused
//! by untrusted user-provided HTML being mixed into a larger web page.
//!
//! Ammonia uses [html5ever] to parse and serialize document fragments the same way browsers do,
//! so it is extremely resilient to syntactic obfuscation.
//!
//! Ammonia parses its input exactly according to the HTML5 specification;
//! it will not linkify bare URLs, insert line or paragraph breaks, or convert `(C)` into ©.
//! If you want that, use a markup processor before running the sanitizer, like [pulldown-cmark].
//!
//! # Examples
//!
//! ```
//! let result = ammonia::clean(
//! "![]()
I'm not trying to XSS you"
//! );
//! assert_eq!(result, "![](\"\")
I'm not trying to XSS you");
//! ```
//!
//! [html5ever]: https://github.com/servo/html5ever "The HTML parser in Servo"
//! [pulldown-cmark]: https://github.com/google/pulldown-cmark "CommonMark parser"
use html5ever::interface::Attribute;
use html5ever::serialize::{serialize, SerializeOpts};
use html5ever::tree_builder::{NodeOrText, TreeSink};
use html5ever::{driver as html, local_name, namespace_url, ns, QualName};
use lazy_static::lazy_static;
use maplit::{hashmap, hashset};
use markup5ever_rcdom::{Handle, NodeData, RcDom, SerializableHandle};
use matches::matches;
use std::borrow::{Borrow, Cow};
use std::cmp::max;
use std::collections::{HashMap, HashSet};
use std::fmt;
use std::io;
use std::iter::IntoIterator as IntoIter;
use std::mem::replace;
use std::rc::Rc;
use std::str::FromStr;
use tendril::stream::TendrilSink;
use tendril::StrTendril;
use tendril::{format_tendril, ByteTendril};
pub use url::Url;
use html5ever::buffer_queue::BufferQueue;
use html5ever::tokenizer::{Token, TokenSink, TokenSinkResult, Tokenizer};
pub use url;
lazy_static! {
static ref AMMONIA: Builder<'static> = Builder::default();
}
/// Clean HTML with a conservative set of defaults.
///
/// * [tags](struct.Builder.html#defaults)
/// * [attributes on specific tags](struct.Builder.html#defaults-1)
/// * [attributes on all tags](struct.Builder.html#defaults-2)
/// * [url schemes](struct.Builder.html#defaults-3)
/// * [relative URLs are passed through, unchanged, by default](struct.Builder.html#defaults-4)
/// * [links are marked `noopener noreferrer` by default](struct.Builder.html#defaults-5)
/// * [all `class=""` settings are blocked by default](struct.Builder.html#defaults-6)
/// * [comments are stripped by default](struct.Builder.html#defaults-7)
///
/// [opener]: https://mathiasbynens.github.io/rel-noopener/
/// [referrer]: https://en.wikipedia.org/wiki/HTTP_referer
///
/// # Examples
///
/// assert_eq!(ammonia::clean("XSS"), "XSS")
pub fn clean(src: &str) -> String {
AMMONIA.clean(src).to_string()
}
/// Turn an arbitrary string into unformatted HTML.
///
/// This function is roughly equivalent to PHP's `htmlspecialchars` and `htmlentities`.
/// It is as strict as possible, encoding every character that has special meaning to the
/// HTML parser.
///
/// # Warnings
///
/// This function cannot be used to package strings into a `", clean_text(untrusted));
///
/// `", clean_text(untrusted))).to_string();
/// assert_eq!("", sanitized);
/// // This is a good version
/// // The user put two newlines at the beginning, and we add a third one,
/// // so the result still has two
/// let sanitized = b.clean(&format!("", clean_text(untrusted))).to_string();
/// assert_eq!("", sanitized);
/// // This version is also often considered good
/// // For many applications, leading and trailing whitespace is probably unwanted
/// let sanitized = b.clean(&format!("", clean_text(untrusted.trim()))).to_string();
/// assert_eq!("", sanitized);
///
/// It also does not make user text safe for HTML attribute microsyntaxes such as `class` or `id`.
/// Only use this function for places where HTML accepts unrestricted text such as `title` attributes
/// and paragraph contents.
pub fn clean_text(src: &str) -> String {
let mut ret_val = String::with_capacity(max(4, src.len()));
for c in src.chars() {
let replacement = match c {
// this character, when confronted, will start a tag
'<' => "<",
// in an unquoted attribute, will end the attribute value
'>' => ">",
// in an attribute surrounded by double quotes, this character will end the attribute value
'\"' => """,
// in an attribute surrounded by single quotes, this character will end the attribute value
'\'' => "'",
// in HTML5, returns a bogus parse error in an unquoted attribute, while in SGML/HTML, it will end an attribute value surrounded by backquotes
'`' => "`",
// in an unquoted attribute, this character will end the attribute
'/' => "/",
// starts an entity reference
'&' => "&",
// if at the beginning of an unquoted attribute, will get ignored
'=' => "=",
// will end an unquoted attribute
' ' => " ",
'\t' => " ",
'\n' => "
",
'\r' => "",
// a spec-compliant browser will perform this replacement anyway, but the middleware might not
'\0' => "�",
// ALL OTHER CHARACTERS ARE PASSED THROUGH VERBATIM
_ => {
ret_val.push(c);
continue;
}
};
ret_val.push_str(replacement);
}
ret_val
}
/// Determine if a given string contains HTML
///
/// This function is parses the full string into HTML and checks if the input contained any
/// HTML syntax.
///
/// # Note
/// This function cannot will return positively for strings that contain invalid HTML syntax like
/// `` and even `Vec::::new()`.
pub fn is_html(input: &str) -> bool {
let santok = SanitizationTokenizer::new();
let mut chunk = ByteTendril::new();
chunk.push_slice(input.as_bytes());
let mut input = BufferQueue::new();
input.push_back(chunk.try_reinterpret().unwrap());
let mut tok = Tokenizer::new(santok, Default::default());
let _ = tok.feed(&mut input);
tok.end();
tok.sink.was_sanitized
}
#[derive(Copy, Clone)]
struct SanitizationTokenizer {
was_sanitized: bool,
}
impl SanitizationTokenizer {
pub fn new() -> SanitizationTokenizer {
SanitizationTokenizer {
was_sanitized: false,
}
}
}
impl TokenSink for SanitizationTokenizer {
type Handle = ();
fn process_token(&mut self, token: Token, _line_number: u64) -> TokenSinkResult<()> {
match token {
Token::CharacterTokens(_) | Token::EOFToken | Token::ParseError(_) => {}
_ => {
self.was_sanitized = true;
}
}
TokenSinkResult::Continue
}
fn end(&mut self) {}
}
/// An HTML sanitizer.
///
/// Given a fragment of HTML, Ammonia will parse it according to the HTML5
/// parsing algorithm and sanitize any disallowed tags or attributes. This
/// algorithm also takes care of things like unclosed and (some) misnested
/// tags.
///
/// # Examples
///
/// use ammonia::{Builder, UrlRelative};
///
/// let a = Builder::default()
/// .link_rel(None)
/// .url_relative(UrlRelative::PassThrough)
/// .clean("test")
/// .to_string();
/// assert_eq!(
/// a,
/// "test");
///
/// # Panics
///
/// Running [`clean`] or [`clean_from_reader`] may cause a panic if the builder is
/// configured with any of these (contradictory) settings:
///
/// * The `rel` attribute is added to [`generic_attributes`] or the
/// [`tag_attributes`] for the `` tag, and [`link_rel`] is not set to `None`.
///
/// For example, this is going to panic, since [`link_rel`] is set to
/// `Some("noopener noreferrer")` by default,
/// and it makes no sense to simultaneously say that the user is allowed to
/// set their own `rel` attribute while saying that every link shall be set to
/// a particular value:
///
/// ```should_panic
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// Builder::default()
/// .generic_attributes(hashset!["rel"])
/// .clean("");
/// # }
/// ```
///
/// This, however, is perfectly valid:
///
/// ```
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// Builder::default()
/// .generic_attributes(hashset!["rel"])
/// .link_rel(None)
/// .clean("");
/// # }
/// ```
///
/// * The `class` attribute is in [`allowed_classes`] and is in the
/// corresponding [`tag_attributes`] or in [`generic_attributes`].
///
/// This is done both to line up with the treatment of `rel`,
/// and to prevent people from accidentally allowing arbitrary
/// classes on a particular element.
///
/// This will panic:
///
/// ```should_panic
/// use ammonia::Builder;
/// use maplit::{hashmap, hashset};
///
/// # fn main() {
/// Builder::default()
/// .generic_attributes(hashset!["class"])
/// .allowed_classes(hashmap!["span" => hashset!["hidden"]])
/// .clean("");
/// # }
/// ```
///
/// This, however, is perfectly valid:
///
/// ```
/// use ammonia::Builder;
/// use maplit::{hashmap, hashset};
///
/// # fn main() {
/// Builder::default()
/// .allowed_classes(hashmap!["span" => hashset!["hidden"]])
/// .clean("");
/// # }
/// ```
///
/// * A tag is in either [`tags`] or [`tag_attributes`] while also
/// being in [`clean_content_tags`].
///
/// Both [`tags`] and [`tag_attributes`] are whitelists but
/// [`clean_content_tags`] is a blacklist, so it doesn't make sense
/// to have the same tag in both.
///
/// For example, this will panic, since the `aside` tag is in
/// [`tags`] by default:
///
/// ```should_panic
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// Builder::default()
/// .clean_content_tags(hashset!["aside"])
/// .clean("");
/// # }
/// ```
///
/// This, however, is valid:
///
/// ```
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// Builder::default()
/// .rm_tags(&["aside"])
/// .clean_content_tags(hashset!["aside"])
/// .clean("");
/// # }
/// ```
///
/// [`clean`]: #method.clean
/// [`clean_from_reader`]: #method.clean_from_reader
/// [`generic_attributes`]: #method.generic_attributes
/// [`tag_attributes`]: #method.tag_attributes
/// [`generic_attributes`]: #method.generic_attributes
/// [`link_rel`]: #method.link_rel
/// [`allowed_classes`]: #method.allowed_classes
/// [`id_prefix`]: #method.id_prefix
/// [`tags`]: #method.tags
/// [`clean_content_tags`]: #method.clean_content_tags
#[derive(Debug)]
pub struct Builder<'a> {
tags: HashSet<&'a str>,
clean_content_tags: HashSet<&'a str>,
tag_attributes: HashMap<&'a str, HashSet<&'a str>>,
tag_attribute_values: HashMap<&'a str, HashMap<&'a str, HashSet<&'a str>>>,
set_tag_attribute_values: HashMap<&'a str, HashMap<&'a str, &'a str>>,
generic_attributes: HashSet<&'a str>,
url_schemes: HashSet<&'a str>,
url_relative: UrlRelative,
attribute_filter: Option>,
link_rel: Option<&'a str>,
allowed_classes: HashMap<&'a str, HashSet<&'a str>>,
strip_comments: bool,
id_prefix: Option<&'a str>,
generic_attribute_prefixes: Option>,
}
impl<'a> Default for Builder<'a> {
fn default() -> Self {
#[cfg_attr(rustfmt, rustfmt_skip)]
let tags = hashset![
"a", "abbr", "acronym", "area", "article", "aside", "b", "bdi",
"bdo", "blockquote", "br", "caption", "center", "cite", "code",
"col", "colgroup", "data", "dd", "del", "details", "dfn", "div",
"dl", "dt", "em", "figcaption", "figure", "footer", "h1", "h2",
"h3", "h4", "h5", "h6", "header", "hgroup", "hr", "i", "img",
"ins", "kbd", "kbd", "li", "map", "mark", "nav", "ol", "p", "pre",
"q", "rp", "rt", "rtc", "ruby", "s", "samp", "small", "span",
"strike", "strong", "sub", "summary", "sup", "table", "tbody",
"td", "th", "thead", "time", "tr", "tt", "u", "ul", "var", "wbr"
];
let clean_content_tags = hashset!["script", "style"];
let generic_attributes = hashset!["lang", "title"];
let tag_attributes = hashmap![
"a" => hashset![
"href", "hreflang"
],
"bdo" => hashset![
"dir"
],
"blockquote" => hashset![
"cite"
],
"col" => hashset![
"align", "char", "charoff", "span"
],
"colgroup" => hashset![
"align", "char", "charoff", "span"
],
"del" => hashset![
"cite", "datetime"
],
"hr" => hashset![
"align", "size", "width"
],
"img" => hashset![
"align", "alt", "height", "src", "width"
],
"ins" => hashset![
"cite", "datetime"
],
"ol" => hashset![
"start"
],
"q" => hashset![
"cite"
],
"table" => hashset![
"align", "char", "charoff", "summary"
],
"tbody" => hashset![
"align", "char", "charoff"
],
"td" => hashset![
"align", "char", "charoff", "colspan", "headers", "rowspan"
],
"tfoot" => hashset![
"align", "char", "charoff"
],
"th" => hashset![
"align", "char", "charoff", "colspan", "headers", "rowspan", "scope"
],
"thead" => hashset![
"align", "char", "charoff"
],
"tr" => hashset![
"align", "char", "charoff"
],
];
let tag_attribute_values = hashmap![];
let set_tag_attribute_values = hashmap![];
let url_schemes = hashset![
"bitcoin",
"ftp",
"ftps",
"geo",
"http",
"https",
"im",
"irc",
"ircs",
"magnet",
"mailto",
"mms",
"mx",
"news",
"nntp",
"openpgp4fpr",
"sip",
"sms",
"smsto",
"ssh",
"tel",
"url",
"webcal",
"wtai",
"xmpp"
];
let allowed_classes = hashmap![];
Builder {
tags,
clean_content_tags,
tag_attributes,
tag_attribute_values,
set_tag_attribute_values,
generic_attributes,
url_schemes,
url_relative: UrlRelative::PassThrough,
attribute_filter: None,
link_rel: Some("noopener noreferrer"),
allowed_classes,
strip_comments: true,
id_prefix: None,
generic_attribute_prefixes: None,
}
}
}
impl<'a> Builder<'a> {
/// Sets the tags that are allowed.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// let tags = hashset!["my-tag"];
/// let a = Builder::new()
/// .tags(tags)
/// .clean("")
/// .to_string();
/// assert_eq!(a, "test mess").to_string();
/// assert_eq!("test mess", a);
pub fn add_tags, I: IntoIter- >(
&mut self,
it: I,
) -> &mut Self {
self.tags.extend(it.into_iter().map(Borrow::borrow));
self
}
/// Remove already-whitelisted tags.
///
/// Does nothing if the tags is already gone.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .rm_tags(&["span"])
/// .clean("").to_string();
/// assert_eq!("", a);
pub fn rm_tags<'b, T: 'b + ?Sized + Borrow
, I: IntoIter- >(
&mut self,
it: I,
) -> &mut Self {
for i in it {
self.tags.remove(i.borrow());
}
self
}
/// Returns a copy of the set of whitelisted tags.
///
/// # Examples
///
/// use maplit::hashset;
///
/// let tags = hashset!["my-tag-1", "my-tag-2"];
///
/// let mut b = ammonia::Builder::default();
/// b.tags(Clone::clone(&tags));
/// assert_eq!(tags, b.clone_tags());
pub fn clone_tags(&self) -> HashSet<&'a str> {
self.tags.clone()
}
/// Sets the tags whose contents will be completely removed from the output.
///
/// Adding tags which are whitelisted in `tags` or `tag_attributes` will cause
/// a panic.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// let tag_blacklist = hashset!["script", "style"];
/// let a = Builder::new()
/// .clean_content_tags(tag_blacklist)
/// .clean("")
/// .to_string();
/// assert_eq!(a, "");
/// # }
///
/// # Defaults
///
/// No tags have content removed by default.
pub fn clean_content_tags(&mut self, value: HashSet<&'a str>) -> &mut Self {
self.clean_content_tags = value;
self
}
/// Add additonal blacklisted clean-content tags without overwriting old ones.
///
/// Does nothing if the tag is already there.
///
/// Adding tags which are whitelisted in `tags` or `tag_attributes` will cause
/// a panic.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .add_clean_content_tags(&["my-tag"])
/// .clean("
test mess").to_string();
/// assert_eq!("mess", a);
pub fn add_clean_content_tags, I: IntoIter- >(
&mut self,
it: I,
) -> &mut Self {
self.clean_content_tags
.extend(it.into_iter().map(Borrow::borrow));
self
}
/// Remove already-blacklisted clean-content tags.
///
/// Does nothing if the tags aren't blacklisted.
///
/// # Examples
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// let tag_blacklist = hashset!["script"];
/// let a = ammonia::Builder::default()
/// .clean_content_tags(tag_blacklist)
/// .rm_clean_content_tags(&["script"])
/// .clean("").to_string();
/// assert_eq!("XSS", a);
/// # }
pub fn rm_clean_content_tags<'b, T: 'b + ?Sized + Borrow
, I: IntoIter- >(
&mut self,
it: I,
) -> &mut Self {
for i in it {
self.clean_content_tags.remove(i.borrow());
}
self
}
/// Returns a copy of the set of blacklisted clean-content tags.
///
/// # Examples
/// # use maplit::hashset;
///
/// let tags = hashset!["my-tag-1", "my-tag-2"];
///
/// let mut b = ammonia::Builder::default();
/// b.clean_content_tags(Clone::clone(&tags));
/// assert_eq!(tags, b.clone_clean_content_tags());
pub fn clone_clean_content_tags(&self) -> HashSet<&'a str> {
self.clean_content_tags.clone()
}
/// Sets the HTML attributes that are allowed on specific tags.
///
/// The value is structured as a map from tag names to a set of attribute names.
///
/// If a tag is not itself whitelisted, adding entries to this map will do nothing.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::{hashmap, hashset};
///
/// # fn main() {
/// let tags = hashset!["my-tag"];
/// let tag_attributes = hashmap![
/// "my-tag" => hashset!["val"]
/// ];
/// let a = Builder::new().tags(tags).tag_attributes(tag_attributes)
/// .clean("
")
/// .to_string();
/// assert_eq!(a, "test mess").to_string();
/// assert_eq!("test mess", a);
pub fn add_tag_attributes<
T: 'a + ?Sized + Borrow,
U: 'a + ?Sized + Borrow,
I: IntoIter- ,
>(
&mut self,
tag: &'a U,
it: I,
) -> &mut Self {
self.tag_attributes
.entry(tag.borrow())
.or_insert_with(|| HashSet::new())
.extend(it.into_iter().map(Borrow::borrow));
self
}
/// Remove already-whitelisted tag-specific attributes.
///
/// Does nothing if the attribute is already gone.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .rm_tag_attributes("a", &["href"])
/// .clean("").to_string();
/// assert_eq!("", a);
pub fn rm_tag_attributes<
'b,
'c,
T: 'b + ?Sized + Borrow
,
U: 'c + ?Sized + Borrow,
I: IntoIter- ,
>(
&mut self,
tag: &'c U,
it: I,
) -> &mut Self {
if let Some(tag) = self.tag_attributes.get_mut(tag.borrow()) {
for i in it {
tag.remove(i.borrow());
}
}
self
}
/// Returns a copy of the set of whitelisted tag-specific attributes.
///
/// # Examples
/// use maplit::{hashmap, hashset};
///
/// let tag_attributes = hashmap![
/// "my-tag" => hashset!["my-attr-1", "my-attr-2"]
/// ];
///
/// let mut b = ammonia::Builder::default();
/// b.tag_attributes(Clone::clone(&tag_attributes));
/// assert_eq!(tag_attributes, b.clone_tag_attributes());
pub fn clone_tag_attributes(&self) -> HashMap<&'a str, HashSet<&'a str>> {
self.tag_attributes.clone()
}
/// Sets the values of HTML attributes that are allowed on specific tags.
///
/// The value is structured as a map from tag names to a map from attribute names to a set of
/// attribute values.
///
/// If a tag is not itself whitelisted, adding entries to this map will do nothing.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::{hashmap, hashset};
///
/// # fn main() {
/// let tags = hashset!["my-tag"];
/// let tag_attribute_values = hashmap![
/// "my-tag" => hashmap![
/// "my-attr" => hashset!["val"],
/// ],
/// ];
/// let a = Builder::new().tags(tags).tag_attribute_values(tag_attribute_values)
/// .clean("
")
/// .to_string();
/// assert_eq!(a, "test mess").to_string();
/// assert_eq!("test mess", a);
pub fn add_tag_attribute_values<
T: 'a + ?Sized + Borrow,
U: 'a + ?Sized + Borrow,
V: 'a + ?Sized + Borrow,
I: IntoIter- ,
>(
&mut self,
tag: &'a U,
attribute: &'a V,
it: I,
) -> &mut Self {
self.tag_attribute_values
.entry(tag.borrow())
.or_insert_with(HashMap::new)
.entry(attribute.borrow())
.or_insert_with(HashSet::new)
.extend(it.into_iter().map(Borrow::borrow));
self
}
/// Remove already-whitelisted tag-specific attribute values.
///
/// Does nothing if the attribute or the value is already gone.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .rm_tag_attributes("a", &["href"])
/// .add_tag_attribute_values("a", "href", &["/"])
/// .rm_tag_attribute_values("a", "href", &["/"])
/// .clean("").to_string();
/// assert_eq!("", a);
pub fn rm_tag_attribute_values<
'b,
'c,
T: 'b + ?Sized + Borrow
,
U: 'c + ?Sized + Borrow,
V: 'c + ?Sized + Borrow,
I: IntoIter- ,
>(
&mut self,
tag: &'c U,
attribute: &'c V,
it: I,
) -> &mut Self {
if let Some(attrs) = self
.tag_attribute_values
.get_mut(tag.borrow())
.and_then(|map| map.get_mut(attribute.borrow()))
{
for i in it {
attrs.remove(i.borrow());
}
}
self
}
/// Returns a copy of the set of whitelisted tag-specific attribute values.
///
/// # Examples
///
/// use maplit::{hashmap, hashset};
///
/// let attribute_values = hashmap![
/// "my-attr-1" => hashset!["foo"],
/// "my-attr-2" => hashset!["baz", "bar"],
/// ];
/// let tag_attribute_values = hashmap![
/// "my-tag" => attribute_values
/// ];
///
/// let mut b = ammonia::Builder::default();
/// b.tag_attribute_values(Clone::clone(&tag_attribute_values));
/// assert_eq!(tag_attribute_values, b.clone_tag_attribute_values());
pub fn clone_tag_attribute_values(
&self,
) -> HashMap<&'a str, HashMap<&'a str, HashSet<&'a str>>> {
self.tag_attribute_values.clone()
}
/// Sets the values of HTML attributes that are to be set on specific tags.
///
/// The value is structured as a map from tag names to a map from attribute names to an
/// attribute value.
///
/// If a tag is not itself whitelisted, adding entries to this map will do nothing.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::{hashmap, hashset};
///
/// # fn main() {
/// let tags = hashset!["my-tag"];
/// let set_tag_attribute_values = hashmap![
/// "my-tag" => hashmap![
/// "my-attr" => "val",
/// ],
/// ];
/// let a = Builder::new().tags(tags).set_tag_attribute_values(set_tag_attribute_values)
/// .clean("
")
/// .to_string();
/// assert_eq!(a, "test mess").to_string();
/// assert_eq!("test mess", a);
pub fn set_tag_attribute_value<
T: 'a + ?Sized + Borrow,
A: 'a + ?Sized + Borrow,
V: 'a + ?Sized + Borrow,
>(
&mut self,
tag: &'a T,
attribute: &'a A,
value: &'a V,
) -> &mut Self {
self.set_tag_attribute_values
.entry(tag.borrow())
.or_insert_with(HashMap::new)
.insert(attribute.borrow(), value.borrow());
self
}
/// Remove existing tag-specific attribute values to be set.
///
/// Does nothing if the attribute is already gone.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// // this does nothing, since no value is set for this tag attribute yet
/// .rm_set_tag_attribute_value("a", "target")
/// .set_tag_attribute_value("a", "target", "_blank")
/// .rm_set_tag_attribute_value("a", "target")
/// .clean("").to_string();
/// assert_eq!("", a);
pub fn rm_set_tag_attribute_value<
T: 'a + ?Sized + Borrow,
A: 'a + ?Sized + Borrow,
>(
&mut self,
tag: &'a T,
attribute: &'a A,
) -> &mut Self {
if let Some(attributes) = self.set_tag_attribute_values.get_mut(tag.borrow()) {
attributes.remove(attribute.borrow());
}
self
}
/// Returns the value that will be set for the attribute on the element, if any.
///
/// # Examples
///
/// let mut b = ammonia::Builder::default();
/// b.set_tag_attribute_value("a", "target", "_blank");
/// let value = b.get_set_tag_attribute_value("a", "target");
/// assert_eq!(value, Some("_blank"));
pub fn get_set_tag_attribute_value<
T: 'a + ?Sized + Borrow,
A: 'a + ?Sized + Borrow,
>(
&self,
tag: &'a T,
attribute: &'a A,
) -> Option<&'a str> {
self.set_tag_attribute_values
.get(tag.borrow())
.and_then(|map| map.get(attribute.borrow()))
.copied()
}
/// Returns a copy of the set of tag-specific attribute values to be set.
///
/// # Examples
///
/// use maplit::{hashmap, hashset};
///
/// let attribute_values = hashmap![
/// "my-attr-1" => "foo",
/// "my-attr-2" => "bar",
/// ];
/// let set_tag_attribute_values = hashmap![
/// "my-tag" => attribute_values,
/// ];
///
/// let mut b = ammonia::Builder::default();
/// b.set_tag_attribute_values(Clone::clone(&set_tag_attribute_values));
/// assert_eq!(set_tag_attribute_values, b.clone_set_tag_attribute_values());
pub fn clone_set_tag_attribute_values(&self) -> HashMap<&'a str, HashMap<&'a str, &'a str>> {
self.set_tag_attribute_values.clone()
}
/// Sets the prefix of attributes that are allowed on any tag.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// let prefixes = hashset!["data-"];
/// let a = Builder::new()
/// .generic_attribute_prefixes(prefixes)
/// .clean("")
/// .to_string();
/// assert_eq!(a, "");
/// # }
///
/// # Defaults
///
/// ```notest
/// lang, title
/// ```
pub fn generic_attribute_prefixes(&mut self, value: HashSet<&'a str>) -> &mut Self {
self.generic_attribute_prefixes = Some(value);
self
}
/// Add additional whitelisted attribute prefix without overwriting old ones.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .add_generic_attribute_prefixes(&["my-"])
/// .clean("mess").to_string();
/// assert_eq!("mess", a);
pub fn add_generic_attribute_prefixes<
T: 'a + ?Sized + Borrow,
I: IntoIter- ,
>(
&mut self,
it: I,
) -> &mut Self {
self.generic_attribute_prefixes
.get_or_insert_with(HashSet::new)
.extend(it.into_iter().map(Borrow::borrow));
self
}
/// Remove already-whitelisted attribute prefixes.
///
/// Does nothing if the attribute prefix is already gone.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .add_generic_attribute_prefixes(&["data-", "code-"])
/// .rm_generic_attribute_prefixes(&["data-"])
/// .clean("").to_string();
/// assert_eq!("", a);
pub fn rm_generic_attribute_prefixes<
'b,
T: 'b + ?Sized + Borrow
,
I: IntoIter- ,
>(
&mut self,
it: I,
) -> &mut Self {
if let Some(true) = self.generic_attribute_prefixes.as_mut().map(|prefixes| {
for i in it {
let _ = prefixes.remove(i.borrow());
}
prefixes.is_empty()
}) {
self.generic_attribute_prefixes = None;
}
self
}
/// Returns a copy of the set of whitelisted attribute prefixes.
///
/// # Examples
///
/// use maplit::hashset;
///
/// let generic_attribute_prefixes = hashset!["my-prfx-1-", "my-prfx-2-"];
///
/// let mut b = ammonia::Builder::default();
/// b.generic_attribute_prefixes(Clone::clone(&generic_attribute_prefixes));
/// assert_eq!(Some(generic_attribute_prefixes), b.clone_generic_attribute_prefixes());
pub fn clone_generic_attribute_prefixes(&self) -> Option
> {
self.generic_attribute_prefixes.clone()
}
/// Sets the attributes that are allowed on any tag.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// let attributes = hashset!["data-val"];
/// let a = Builder::new()
/// .generic_attributes(attributes)
/// .clean("")
/// .to_string();
/// assert_eq!(a, "");
/// # }
///
/// # Defaults
///
/// ```notest
/// lang, title
/// ```
pub fn generic_attributes(&mut self, value: HashSet<&'a str>) -> &mut Self {
self.generic_attributes = value;
self
}
/// Add additonal whitelisted attributes without overwriting old ones.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .add_generic_attributes(&["my-attr"])
/// .clean("mess").to_string();
/// assert_eq!("mess", a);
pub fn add_generic_attributes, I: IntoIter- >(
&mut self,
it: I,
) -> &mut Self {
self.generic_attributes
.extend(it.into_iter().map(Borrow::borrow));
self
}
/// Remove already-whitelisted attributes.
///
/// Does nothing if the attribute is already gone.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .rm_generic_attributes(&["title"])
/// .clean("").to_string();
/// assert_eq!("", a);
pub fn rm_generic_attributes<'b, T: 'b + ?Sized + Borrow
, I: IntoIter- >(
&mut self,
it: I,
) -> &mut Self {
for i in it {
self.generic_attributes.remove(i.borrow());
}
self
}
/// Returns a copy of the set of whitelisted attributes.
///
/// # Examples
///
/// use maplit::hashset;
///
/// let generic_attributes = hashset!["my-attr-1", "my-attr-2"];
///
/// let mut b = ammonia::Builder::default();
/// b.generic_attributes(Clone::clone(&generic_attributes));
/// assert_eq!(generic_attributes, b.clone_generic_attributes());
pub fn clone_generic_attributes(&self) -> HashSet<&'a str> {
self.generic_attributes.clone()
}
/// Sets the URL schemes permitted on `href` and `src` attributes.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// let url_schemes = hashset![
/// "http", "https", "mailto", "magnet"
/// ];
/// let a = Builder::new().url_schemes(url_schemes)
/// .clean("zero-length file")
/// .to_string();
///
/// // See `link_rel` for information on the rel="noopener noreferrer" attribute
/// // in the cleaned HTML.
/// assert_eq!(a,
/// "zero-length file");
/// # }
///
/// # Defaults
///
/// ```notest
/// bitcoin, ftp, ftps, geo, http, https, im, irc,
/// ircs, magnet, mailto, mms, mx, news, nntp,
/// openpgp4fpr, sip, sms, smsto, ssh, tel, url,
/// webcal, wtai, xmpp
/// ```
pub fn url_schemes(&mut self, value: HashSet<&'a str>) -> &mut Self {
self.url_schemes = value;
self
}
/// Add additonal whitelisted URL schemes without overwriting old ones.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .add_url_schemes(&["my-scheme"])
/// .clean("mess").to_string();
/// assert_eq!("mess", a);
pub fn add_url_schemes
, I: IntoIter- >(
&mut self,
it: I,
) -> &mut Self {
self.url_schemes.extend(it.into_iter().map(Borrow::borrow));
self
}
/// Remove already-whitelisted attributes.
///
/// Does nothing if the attribute is already gone.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .rm_url_schemes(&["ftp"])
/// .clean("").to_string();
/// assert_eq!("", a);
pub fn rm_url_schemes<'b, T: 'b + ?Sized + Borrow
, I: IntoIter- >(
&mut self,
it: I,
) -> &mut Self {
for i in it {
self.url_schemes.remove(i.borrow());
}
self
}
/// Returns a copy of the set of whitelisted URL schemes.
///
/// # Examples
/// use maplit::hashset;
///
/// let url_schemes = hashset!["my-scheme-1", "my-scheme-2"];
///
/// let mut b = ammonia::Builder::default();
/// b.url_schemes(Clone::clone(&url_schemes));
/// assert_eq!(url_schemes, b.clone_url_schemes());
pub fn clone_url_schemes(&self) -> HashSet<&'a str> {
self.url_schemes.clone()
}
/// Configures the behavior for relative URLs: pass-through, resolve-with-base, or deny.
///
/// # Examples
///
/// use ammonia::{Builder, UrlRelative};
///
/// let a = Builder::new().url_relative(UrlRelative::PassThrough)
/// .clean("Home")
/// .to_string();
///
/// // See `link_rel` for information on the rel="noopener noreferrer" attribute
/// // in the cleaned HTML.
/// assert_eq!(
/// a,
/// "Home");
///
/// # Defaults
///
/// ```notest
/// UrlRelative::PassThrough
/// ```
pub fn url_relative(&mut self, value: UrlRelative) -> &mut Self {
self.url_relative = value;
self
}
/// Allows rewriting of all attributes using a callback.
///
/// The callback takes name of the element, attribute and its value.
/// Returns `None` to remove the attribute, or a value to use.
///
/// Rewriting of attributes with URLs is done before `url_relative()`.
///
/// # Panics
///
/// If more than one callback is set.
///
/// # Examples
///
/// ```rust
/// use ammonia::Builder;
/// let a = Builder::new()
/// .attribute_filter(|element, attribute, value| {
/// match (element, attribute) {
/// ("img", "src") => None,
/// _ => Some(value.into())
/// }
/// })
/// .link_rel(None)
/// .clean("
")
/// .to_string();
/// assert_eq!(a,
/// r#"![Home]()
"#);
/// ```
pub fn attribute_filter<'cb, CallbackFn>(&mut self, callback: CallbackFn) -> &mut Self
where
CallbackFn: for<'u> Fn(&str, &str, &'u str) -> Option> + Send + Sync + 'static,
{
assert!(
self.attribute_filter.is_none(),
"attribute_filter can be set only once"
);
self.attribute_filter = Some(Box::new(callback));
self
}
/// Returns `true` if the relative URL resolver is set to `Deny`.
///
/// # Examples
///
/// use ammonia::{Builder, UrlRelative};
/// let mut a = Builder::default();
/// a.url_relative(UrlRelative::Deny);
/// assert!(a.is_url_relative_deny());
/// a.url_relative(UrlRelative::PassThrough);
/// assert!(!a.is_url_relative_deny());
pub fn is_url_relative_deny(&self) -> bool {
matches!(self.url_relative, UrlRelative::Deny)
}
/// Returns `true` if the relative URL resolver is set to `PassThrough`.
///
/// # Examples
///
/// use ammonia::{Builder, UrlRelative};
/// let mut a = Builder::default();
/// a.url_relative(UrlRelative::Deny);
/// assert!(!a.is_url_relative_pass_through());
/// a.url_relative(UrlRelative::PassThrough);
/// assert!(a.is_url_relative_pass_through());
pub fn is_url_relative_pass_through(&self) -> bool {
matches!(self.url_relative, UrlRelative::PassThrough)
}
/// Returns `true` if the relative URL resolver is set to `Custom`.
///
/// # Examples
///
/// use ammonia::{Builder, UrlRelative};
/// use std::borrow::Cow;
/// fn test(a: &str) -> Option> { None }
/// # fn main() {
/// let mut a = Builder::default();
/// a.url_relative(UrlRelative::Custom(Box::new(test)));
/// assert!(a.is_url_relative_custom());
/// a.url_relative(UrlRelative::PassThrough);
/// assert!(!a.is_url_relative_custom());
/// a.url_relative(UrlRelative::Deny);
/// assert!(!a.is_url_relative_custom());
/// # }
pub fn is_url_relative_custom(&self) -> bool {
matches!(self.url_relative, UrlRelative::Custom(_))
}
/// Configures a `rel` attribute that will be added on links.
///
/// If `rel` is in the generic or tag attributes, this must be set to `None`.
/// Common `rel` values to include:
///
/// * `noopener`: This prevents [a particular type of XSS attack],
/// and should usually be turned on for untrusted HTML.
/// * `noreferrer`: This prevents the browser from [sending the source URL]
/// to the website that is linked to.
/// * `nofollow`: This prevents search engines from [using this link for
/// ranking], which disincentivizes spammers.
///
/// To turn on rel-insertion, call this function with a space-separated list.
/// Ammonia does not parse rel-attributes;
/// it just puts the given string into the attribute directly.
///
/// [a particular type of XSS attack]: https://mathiasbynens.github.io/rel-noopener/
/// [sending the source URL]: https://en.wikipedia.org/wiki/HTTP_referer
/// [using this link for ranking]: https://en.wikipedia.org/wiki/Nofollow
///
/// # Examples
///
/// use ammonia::Builder;
///
/// let a = Builder::new().link_rel(None)
/// .clean("Rust")
/// .to_string();
/// assert_eq!(
/// a,
/// "Rust");
///
/// # Defaults
///
/// ```notest
/// Some("noopener noreferrer")
/// ```
pub fn link_rel(&mut self, value: Option<&'a str>) -> &mut Self {
self.link_rel = value;
self
}
/// Returns the settings for links' `rel` attribute, if one is set.
///
/// # Examples
///
/// use ammonia::{Builder, UrlRelative};
/// let mut a = Builder::default();
/// a.link_rel(Some("a b"));
/// assert_eq!(a.get_link_rel(), Some("a b"));
pub fn get_link_rel(&self) -> Option<&str> {
self.link_rel.clone()
}
/// Sets the CSS classes that are allowed on specific tags.
///
/// The values is structured as a map from tag names to a set of class names.
///
/// If the `class` attribute is itself whitelisted for a tag, then adding entries to
/// this map will cause a panic.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::{hashmap, hashset};
///
/// # fn main() {
/// let allowed_classes = hashmap![
/// "code" => hashset!["rs", "ex", "c", "cxx", "js"]
/// ];
/// let a = Builder::new()
/// .allowed_classes(allowed_classes)
/// .clean(",
U: 'a + ?Sized + Borrow,
I: IntoIter- ,
>(
&mut self,
tag: &'a U,
it: I,
) -> &mut Self {
self.allowed_classes
.entry(tag.borrow())
.or_insert_with(|| HashSet::new())
.extend(it.into_iter().map(Borrow::borrow));
self
}
/// Remove already-whitelisted attributes.
///
/// Does nothing if the attribute is already gone.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .add_allowed_classes("span", &["active"])
/// .rm_allowed_classes("span", &["active"])
/// .clean("").to_string();
/// assert_eq!("", a);
pub fn rm_allowed_classes<
'b,
'c,
T: 'b + ?Sized + Borrow
,
U: 'c + ?Sized + Borrow,
I: IntoIter- ,
>(
&mut self,
tag: &'c U,
it: I,
) -> &mut Self {
if let Some(tag) = self.allowed_classes.get_mut(tag.borrow()) {
for i in it {
tag.remove(i.borrow());
}
}
self
}
/// Returns a copy of the set of whitelisted class attributes.
///
/// # Examples
///
/// use maplit::{hashmap, hashset};
///
/// let allowed_classes = hashmap![
/// "my-tag" => hashset!["my-class-1", "my-class-2"]
/// ];
///
/// let mut b = ammonia::Builder::default();
/// b.allowed_classes(Clone::clone(&allowed_classes));
/// assert_eq!(allowed_classes, b.clone_allowed_classes());
pub fn clone_allowed_classes(&self) -> HashMap<&'a str, HashSet<&'a str>> {
self.allowed_classes.clone()
}
/// Configures the handling of HTML comments.
///
/// If this option is false, comments will be preserved.
///
/// # Examples
///
/// use ammonia::Builder;
///
/// let a = Builder::new().strip_comments(false)
/// .clean("")
/// .to_string();
/// assert_eq!(
/// a,
/// "");
///
/// # Defaults
///
/// `true`
pub fn strip_comments(&mut self, value: bool) -> &mut Self {
self.strip_comments = value;
self
}
/// Returns `true` if comment stripping is turned on.
///
/// # Examples
///
/// let mut a = ammonia::Builder::new();
/// a.strip_comments(true);
/// assert!(a.will_strip_comments());
/// a.strip_comments(false);
/// assert!(!a.will_strip_comments());
pub fn will_strip_comments(&self) -> bool {
self.strip_comments
}
/// Prefixes all "id" attribute values with a given string. Note that the tag and
/// attribute themselves must still be whitelisted.
///
/// # Examples
///
/// use ammonia::Builder;
/// use maplit::hashset;
///
/// # fn main() {
/// let attributes = hashset!["id"];
/// let a = Builder::new()
/// .generic_attributes(attributes)
/// .id_prefix(Some("safe-"))
/// .clean("")
/// .to_string();
/// assert_eq!(a, "");
/// # }
///
/// # Defaults
///
/// `None`
pub fn id_prefix(&mut self, value: Option<&'a str>) -> &mut Self {
self.id_prefix = value;
self
}
/// Constructs a [`Builder`] instance configured with the [default options].
///
/// # Examples
///
/// use ammonia::{Builder, Url, UrlRelative};
/// # use std::error::Error;
///
/// # fn do_main() -> Result<(), Box
> {
/// let input = "This is an Ammonia example using the > {
/// let input = "This is an Ammonia example using the > {
/// let a = Builder::new()
/// .clean_from_reader(&b""[..])? // notice the `b`
/// .to_string();
/// assert_eq!(a, "");
/// # Ok(()) }
/// # fn main() { do_main().unwrap() }
///
/// [`String::from_utf8_lossy`]: https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8_lossy
pub fn clean_from_reader(&self, mut src: R) -> io::Result
where
R: io::Read,
{
let parser = Self::make_parser().from_utf8();
let dom = parser.read_from(&mut src)?;
Ok(self.clean_dom(dom))
}
/// Clean a post-parsing DOM.
///
/// This is not a public API because RcDom isn't really stable.
/// We want to be able to take breaking changes to html5ever itself
/// without having to break Ammonia's API.
fn clean_dom(&self, mut dom: RcDom) -> Document {
let mut stack = Vec::new();
let mut removed = Vec::new();
let link_rel = self
.link_rel
.map(|link_rel| format_tendril!("{}", link_rel));
if link_rel.is_some() {
assert!(self.generic_attributes.get("rel").is_none());
assert!(self
.tag_attributes
.get("a")
.and_then(|a| a.get("rel"))
.is_none());
}
assert!(self.allowed_classes.is_empty() || !self.generic_attributes.contains("class"));
for (tag_name, _classes) in &self.allowed_classes {
assert!(self
.tag_attributes
.get(tag_name)
.and_then(|a| a.get("class"))
.is_none());
}
for tag_name in &self.clean_content_tags {
assert!(!self.tags.contains(tag_name));
assert!(!self.tag_attributes.contains_key(tag_name));
}
let url_base = if let UrlRelative::RewriteWithBase(ref base) = self.url_relative {
Some(base)
} else {
None
};
let body = {
let children = dom.document.children.borrow();
children[0].clone()
};
stack.extend(
replace(&mut *body.children.borrow_mut(), Vec::new())
.into_iter()
.rev(),
);
// This design approach is used to prevent pathological content from producing
// a stack overflow. The `stack` contains to-be-cleaned nodes, while `remove`,
// of course, contains nodes that need to be dropped (we can't just drop them,
// because they could have a very deep child tree).
while let Some(mut node) = stack.pop() {
let parent = node.parent
.replace(None).expect("a node in the DOM will have a parent, except the root, which is not processed")
.upgrade().expect("a node's parent will be pointed to by its parent (or the root pointer), and will not be dropped");
if self.clean_node_content(&node) {
removed.push(node);
continue;
}
let pass_clean = self.clean_child(&mut node, url_base);
let pass = pass_clean && self.check_expected_namespace(&parent, &node);
if pass {
self.adjust_node_attributes(&mut node, &link_rel, url_base, self.id_prefix);
dom.append(&parent.clone(), NodeOrText::AppendNode(node.clone()));
} else {
for sub in node.children.borrow_mut().iter_mut() {
sub.parent.replace(Some(Rc::downgrade(&parent)));
}
}
stack.extend(
replace(&mut *node.children.borrow_mut(), Vec::new())
.into_iter()
.rev(),
);
if !pass {
removed.push(node);
}
}
// Now, imperatively clean up all of the child nodes.
// Otherwise, we could wind up with a DoS, either caused by a memory leak,
// or caused by a stack overflow.
while let Some(node) = removed.pop() {
removed.extend_from_slice(&replace(&mut *node.children.borrow_mut(), Vec::new())[..]);
}
Document(dom)
}
/// Returns `true` if a node and all its content should be removed.
fn clean_node_content(&self, node: &Handle) -> bool {
match node.data {
NodeData::Text { .. }
| NodeData::Comment { .. }
| NodeData::Doctype { .. }
| NodeData::Document
| NodeData::ProcessingInstruction { .. } => false,
NodeData::Element { ref name, .. } => self.clean_content_tags.contains(&*name.local),
}
}
/// Remove unwanted attributes, and check if the node should be kept or not.
///
/// The root node doesn't need cleaning because we create the root node ourselves,
/// and it doesn't get serialized, and ... it just exists to give the parser
/// a context (in this case, a div-like block context).
fn clean_child(&self, child: &mut Handle, url_base: Option<&Url>) -> bool {
match child.data {
NodeData::Text { .. } => true,
NodeData::Comment { .. } => !self.strip_comments,
NodeData::Doctype { .. }
| NodeData::Document
| NodeData::ProcessingInstruction { .. } => false,
NodeData::Element {
ref name,
ref attrs,
..
} => {
if self.tags.contains(&*name.local) {
let attr_filter = |attr: &html5ever::Attribute| {
let whitelisted = self.generic_attributes.contains(&*attr.name.local)
|| self.generic_attribute_prefixes.as_ref().map(|prefixes| {
prefixes.iter().any(|&p| attr.name.local.starts_with(p))
}) == Some(true)
|| self
.tag_attributes
.get(&*name.local)
.map(|ta| ta.contains(&*attr.name.local))
== Some(true)
|| self
.tag_attribute_values
.get(&*name.local)
.and_then(|tav| tav.get(&*attr.name.local))
.map(|vs| {
let attr_val = attr.value.to_lowercase();
vs.iter().any(|v| v.to_lowercase() == attr_val)
})
== Some(true);
if !whitelisted {
// If the class attribute is not whitelisted,
// but there is a whitelisted set of allowed_classes,
// do not strip out the class attribute.
// Banned classes will be filtered later.
&*attr.name.local == "class"
&& self.allowed_classes.contains_key(&*name.local)
} else if is_url_attr(&*name.local, &*attr.name.local) {
let url = Url::parse(&*attr.value);
if let Ok(url) = url {
self.url_schemes.contains(url.scheme())
} else if url == Err(url::ParseError::RelativeUrlWithoutBase) {
if matches!(self.url_relative, UrlRelative::Deny) {
false
} else if let Some(url_base) = url_base {
url_base.join(&*attr.value).is_ok()
} else {
true
}
} else {
false
}
} else {
true
}
};
attrs.borrow_mut().retain(attr_filter);
true
} else {
false
}
}
}
}
// Check for unexpected namespace changes.
//
// The issue happens if developers added to the list of allowed tags any
// tag which is parsed in RCDATA state, PLAINTEXT state or RAWTEXT state,
// that is:
//
// * title
// * textarea
// * xmp
// * iframe
// * noembed
// * noframes
// * plaintext
// * noscript
// * style
// * script
//
// An example in the wild is Plume, that allows iframe [1]. So in next
// examples I'll assume the following policy:
//
// Builder::new()
// .add_tags(&["iframe"])
//
// In HTML namespace `![]()
">test
//
// It is parsed into:
//
// svg
// └─ iframe
// └─ a title="![]()
"
// └─ #text: test
//
// This DOM tree is harmless from ammonia point of view because the piece
// of code that looks like XSS is in a title attribute. Hence, the
// resulting "safe" HTML from ammonia would be:
//
// ![]()
" rel="noopener
// noreferrer">test
//
// However, at this point, the information about namespace is lost, which
// means that the browser will parse this snippet into:
//
// ├─ iframe
// │ └─ #text: test
//
// Leading to XSS.
//
// To solve this issue, check for unexpected namespace switches after cleanup.
// Elements which change namespace at an unexpected point are removed.
// This function returns `true` if `child` should be kept, and `false` if it
// should be removed.
//
// [1]: https://github.com/Plume-org/Plume/blob/main/plume-models/src/safe_string.rs#L21
fn check_expected_namespace(&self, parent: &Handle, child: &Handle) -> bool {
let (parent, child) = match (&parent.data, &child.data) {
(NodeData::Element { name: pn, .. }, NodeData::Element { name: cn, .. }) => (pn, cn),
_ => return true,
};
// The only way to switch from html to svg is with the
fn main() {}")
/// .to_string();
/// assert_eq!(
/// a,
/// "fn main() {}");
/// # }
///
/// # Defaults
///
/// The set of allowed classes is empty by default.
pub fn allowed_classes(&mut self, value: HashMap<&'a str, HashSet<&'a str>>) -> &mut Self {
self.allowed_classes = value;
self
}
/// Add additonal whitelisted classes without overwriting old ones.
///
/// # Examples
///
/// let a = ammonia::Builder::default()
/// .add_allowed_classes("a", &["onebox"])
/// .clean("mess").to_string();
/// assert_eq!("mess", a);
pub fn add_allowed_classes<
T: 'a + ?Sized + Borrownew() function.";
/// let output = "This is an Ammonia example using the new() function.";
///
/// let result = Builder::new() // <--
/// .url_relative(UrlRelative::RewriteWithBase(Url::parse("https://docs.rs/ammonia/1.0/ammonia/")?))
/// .clean(input)
/// .to_string();
/// assert_eq!(result, output);
/// # Ok(())
/// # }
/// # fn main() { do_main().unwrap() }
///
/// [default options]: fn.clean.html
/// [`Builder`]: struct.Builder.html
pub fn new() -> Self {
Self::default()
}
/// Sanitizes an HTML fragment in a string according to the configured options.
///
/// # Examples
///
/// use ammonia::{Builder, Url, UrlRelative};
/// # use std::error::Error;
///
/// # fn do_main() -> Result<(), Boxnew() function.";
/// let output = "This is an Ammonia example using the new() function.";
///
/// let result = Builder::new()
/// .url_relative(UrlRelative::RewriteWithBase(Url::parse("https://docs.rs/ammonia/1.0/ammonia/")?))
/// .clean(input)
/// .to_string(); // <--
/// assert_eq!(result, output);
/// # Ok(())
/// # }
/// # fn main() { do_main().unwrap() }
pub fn clean(&self, src: &str) -> Document {
let parser = Self::make_parser();
let dom = parser.one(src);
self.clean_dom(dom)
}
/// Sanitizes an HTML fragment from a reader according to the configured options.
///
/// The input should be in UTF-8 encoding, otherwise the decoding is lossy, just
/// like when using [`String::from_utf8_lossy`].
///
/// To avoid consuming the reader, a mutable reference can be passed to this method.
///
/// # Examples
///
/// use ammonia::Builder;
/// # use std::error::Error;
///
/// # fn do_main() -> Result<(), Box