Skip to content

Restrict HTML comments to the HTML subset with jsoup's Cleaner - #353

Open
mraible wants to merge 16 commits into
masterfrom
html-subset-jsoup
Open

mraible wants to merge 16 commits into
masterfrom
html-subset-jsoup

Conversation

@mraible

@mraible mraible commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

The HTML subset, used by the default HTMLSubset comment plugin and by HTML comment notification e-mails, was built with regular expressions. The comment was HTML-encoded, then 21 patterns turned the encoded tags in the subset back into tags and rebuilt links. Now:

  • Utilities.sanitizeToHTMLSubset runs jsoup's Cleaner with a Safelist of the same tags (a, b, blockquote, br, i, li, ol, p, pre, ul) and the same link schemes (http, https, mailto).
  • Before jsoup parses the comment, a short linear scan encodes every < that doesn't start a complete subset tag, and every & that doesn't start a complete character reference. Text such as List<String>, a<b, <[email protected]>, an unfinished <a href= or ?a=1&copy=2 is shown as typed, as before, instead of being dropped or decoded.
  • The HTMLSubset plugin and the notification e-mails call it directly.
  • transformToHTMLSubset stays for templates ($utils.transformToHTMLSubset). It decodes its HTML-encoded input and then cleans it.
  • The 21 patterns and restoreSubsetEntities are removed.

What changes for commenters:

  • A link keeps its href when it has other attributes, such as a title. The other attributes are removed.
  • A tag left open is closed at the end of the comment.
  • The output is jsoup's: <br> has no slash, and the link scheme is lowercase.

Screen and full names (UserWrapper):

  • Only the entities the sanitizer stores (&lt;, &gt;, &quot;, &#39;, &nbsp;) are decoded before the name is escaped, so an entity typed as part of a name, such as &amp;, is shown as typed. They are decoded whatever weblogAdminsUntrusted is now, since a name keeps the encoding it was saved with.
  • Apostrophes are encoded as &#39;, so a name is also safe inside a single-quoted attribute in a custom theme.

The tests cover script, style, event handler, javascript: and data: links, an entity-split javascript: scheme, SVG, inline styles, HTML comments, iframes, a quote inside an href, text that only looks like a tag, bare ampersands, names saved under either setting, and the scan's running time on long unclosed input. CHANGES.md has an entry under Bug fixes.

6.1.x keeps its current HTML subset code.

UserWrapper now returns screen and full names as HTML-escaped text, encoding them exactly once whether they were stored as typed or already encoded by the sanitizer, and the built-in feed macros turn them back into text before XML-escaping them for Atom author names and RSS dc:creator.

HTML comment notification emails escape the commenter's name and email address. WeblogEntryCommentWrapper escapes HTML comments when the HTMLSubset plugin isn't both configured and listed on the comment, and its Javadoc now describes what getContent does.

Utilities.transformToHTMLSubset and addNofollow find each link's closing bracket with one forward search and stop when none is left, so their time is linear in the input, and addNofollow now adds rel="nofollow" to links that don't already have it.

TagDataServlet writes tag names and the weblog handle with JSON and XML escaping. The planet group pages pass handles and feed URLs to their delete handlers through data attributes, and JspOutputEncodingTest rejects property values inside inline event handlers. CommentDataServlet returns comment content as JSON, which Comments.jsp reads with jQuery's json data type, and UserDataServlet declares its plain text response.
WeblogEntryCommentWrapper.getContent now HTML-escapes any comment that isn't text/html with the HTMLSubset plugin applied, including comments without a content type.
…isting rel values in addNofollow

The comment feed macros and the media file feed now turn author names back into text with unescapeHTML before XML-escaping them, as the entry author macros do, so a name like "A & B" no longer shows as "A &amp; B" in feed readers. FeedAuthorEscapingTest covers the Atom and RSS comment feeds and the media file feed.

Utilities.addNofollow adds nofollow to a link's existing rel value instead of adding a second rel attribute, and a ">" inside a quoted attribute value no longer ends the link early. The linear-time test now allows 2 seconds so it doesn't fail on slow build machines.
addNofollow looked for rel= anywhere in the tag, so a link like <a href="/x" title='foo rel=external' rel="noopener"> had nofollow added to the title text while its real rel stayed followable. It now walks the tag's attributes while tracking quotes, the same way findTagEnd finds the end of the tag, and changes only a real rel attribute. A rel with no value gets rel="nofollow".
addNofollow now parses the HTML with jsoup 1.24.1 and adds nofollow to the rel attribute of each a element with an href, instead of scanning the markup by hand. Only a link's own rel is changed, and links with no href are left alone. Text with no links is returned as is.

The result is jsoup's serialization of the fragment, so open tags are closed, attribute values are double-quoted, and a tag that never ends is dropped, as browsers do. Escaped text stays escaped.

jsoup is credited in the binary LICENSE.
The HTML subset was built with regular expressions: the comment was HTML-encoded, then 21 patterns turned the encoded tags in the subset back into tags and rebuilt links. Utilities.sanitizeToHTMLSubset now uses jsoup's Cleaner with a Safelist of the same tags (a, b, blockquote, br, i, li, ol, p, pre, ul) and the same link schemes (http, https, mailto) on the raw HTML. The HTMLSubset comment plugin and HTML comment notification e-mails call it directly. transformToHTMLSubset stays for templates and decodes its HTML-encoded input before cleaning it.

What changes for commenters:
- A tag outside the subset is removed and its text kept, instead of being shown as encoded markup. Script and style contents are removed.
- A link keeps its href when it has other attributes, such as a title; the other attributes are removed.
- The output is jsoup's: tags are balanced, <br> has no slash, and the link scheme is lowercase.

The new tests cover script, style, event handler, javascript: and data: links, an entity-split javascript: scheme, SVG, inline styles, HTML comments, iframes, and a quote inside an href.
A comment saved without a name, or a media file whose creator can't be found, made the comment and media file feeds print the template expression itself as the author, because unescapeHTML passed null through and Velocity prints a null reference as its source text. The template unescapeHTML helper now returns an empty string for null, as removeHTML does, so the author element is empty again.
Comments run through the HTML subset lost any text an HTML parser reads as a tag outside the subset: generics such as List<String>, comparisons such as a<b and c>d, <[email protected]> addresses, <http://...> URLs, XML snippets, and everything after a link tag that never ends. Before the regular expressions were replaced with jsoup, that text was shown, HTML-encoded.

sanitizeToHTMLSubset now encodes every "<" that doesn't start a complete tag of the subset before jsoup's Cleaner runs, so the parser reads it as text. A formatting tag or end tag is its name and nothing else, and a link's start tag has attributes with values and ends at a ">" outside a quoted value. The scan from each "<" stops at the next one, so it takes linear time. The Cleaner still runs last and decides what the output may contain.

transformToHTMLSubset gets the same behavior for encoded text, so &lt;script&gt;how to&lt;/script&gt; stays text. This also removes the unused replace helper and regex imports from Utilities, and updates the UtilitiesModel Javadoc for transformToHTMLSubset and addNofollow.

@snoopdave snoopdave left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review of 2e80b60fd: The comment cleaner and affected output paths are covered by focused tests. I found one name-rendering regression; this was a code-only review, with no build run.

Neither trust setting stores an ampersand encoded: trusted admins' names are stored as typed, and the sanitizer used for untrusted admins only encodes angle brackets and quotes. UserWrapper now decodes just &lt;, &gt;, &quot; and &#39;, and only when weblogAdminsUntrusted is true, before escaping, so a name typed as "Tom &amp; Jerry" displays as typed in both modes. Media file authors in the feeds go through UserWrapper too, with a new $utils.wrapUser(), instead of decoding the stored name.
jsoup's sanitizer writes a non-breaking space in a name as &nbsp;, so UserWrapper now decodes &nbsp; along with the angle bracket and quote entities when weblogAdminsUntrusted is true. The name then shows a non-breaking space, encoded once, instead of the text "&nbsp;".
jsoup reads an entity name such as &copy or &region as a character even without a semicolon, so a URL like ?a=1&copy=2 pasted into a comment came out with a symbol in it. An ampersand that doesn't start a complete character reference is now encoded before the comment is parsed, as the old code showed it.
The test failed whenever five large parses took more than two seconds of wall-clock time, which a busy build machine can cause with no change in the code. It now uses the same 30 second assertTimeoutPreemptively as HTMLSanitizerTest, so only a scan that has stopped being linear fails it.
The wrapper decodes the &#39; the sanitizer stores and escapeHtml4 leaves an apostrophe as it is, so a name reached templates with a raw apostrophe. A custom theme that printed a name inside a single-quoted attribute got markup it didn't expect. The wrapper now encodes apostrophes as &#39;, as the stored value had them.
…nges

A name keeps the encoding it was saved with, but the wrapper decoded the sanitizer's entities only while weblogAdminsUntrusted was true. After an operator turned the setting off, a name such as O'Brien saved earlier showed as O&#39;Brien on pages and in feeds. The wrapper now decodes those few entities whatever the setting is, as it decoded every entity before.
Links with other attributes now keep their href, and a tag a comment leaves open is closed at its end. A test now checks the second.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants