NeatHtml™ Manual
by Dean
Brettle
Last updated
Table of Contents
4.1 Using NeatHtml with the Visual Studio Web Form Designer
4.2 Using NeatHtml without the Visual Studio Web Form Designer
5.2 Removing rel=”nofollow” from links
5.3 Displaying untrusted tables to users that don't support scripting
NeatHtml™ is a highly-portable open source website component that displays untrusted content securely, efficiently, and accessibly. Untrusted content is any content that is not trusted by the website owner. Typical examples include blog comments, forum posts, or user pages on social networking sites. NeatHtml uses an “accept only known good” (whitelist) approach to security to help prevent attacks which are not yet known. It focuses on preventing Cross-Site Scripting (XSS) attacks but can also prevent phishing attacks and remove automated Cross-Site Request Forgery (CSRF) attacks. In this context, phishing attacks are attacks which try to display untrusted content where the user would trust it, and automated CSRF attacks are CSRF attacks that do not require any user action beyond viewing the untrusted content.
NeatHtml is licensed under the Lesser General Public License (LGPL), a business-friendly open source license. NeatHtml is currently available for download as a mature development snapshot. It primarily needs independent testing before an official release. Bug reports, feature requests, questions, comments, and other contributions are welcome.
NeatHtml consists of the NeatHtml.js JavaScript library and a small server-side component for ASP.NET. The server-side component is compatible with .NET Framework version 1.1 or higher as well as Mono. The JavaScript library should work with any browser that supports both JavaScript 1.3 and a few DOM APIs. It does not use the browser's internal XML/HTML parser to parse the untrusted content, thereby eliminating many browser compatibility issues. It has been tested against:
Microsoft Internet Explorer (IE) version 7.
Microsoft Internet Explorer (IE) version 6.
Mozilla Firefox (FF) versions 1.5 and 2.0.
Opera 9.21.
Netscape 7.2.
Mac Safari versions 1.2, 1.3, and 2.0.
Konqueror 3.4.0-5 and 3.5.7.
Installing NeatHtml is simple:
If you haven't
already, download the release and extract it wherever you want. All
the files will be extracted into a subdirectory named “NeatHtml-
version”, where version is the version of the release you
are installing.
(Optional) To see the demo running on your server, configure IIS, mod_mono, or XSP so that “NeatHtml-version \dotnet” is a web application. Then point your browser at the Demo.aspx on that website. To use NeatHtml in your own web application, continue with the remaining installation steps.
If you will be using the Visual Studio Web Form Designer, add the NeatHtml controls to your toolbox. To do that, right-click on the Toolbox, click “Add/Remove Items” or “Choose Items”, Browse to “NeatHtml-version\dotnet\bin\Brettle.Web.NeatHtml.dll”, click Open, and then click OK. A reference to Brettle.Web.NeatHtml.dll will automatically be added to your project the first time you use the designer to add the NeatHtml UntrustedContent control to a form.
If you won't be using the Visual Studio Web Form Designer, add a reference to your web application that refers to the “NeatHtml-version\dotnet\bin\Brettle.Web.NeatHtml.dll”.
Create a
NeatHtml\ subdirectory in your web application by
copying “NeatHtml-version\dotnet\NeatHtml\” and its
contents.
(Optional) Copy “Demo.aspx” and “Demo.aspx.cs” from “NeatHtml-version\dotnet\” into your application. Point your browser at “Demo.aspx” and verify that the demo functions properly.
To use the Visual Studio web form designer to add NeatHtml to a web form, follow these steps:
If you are using Visual Studio 2005 or later, rebuild NeatHtml against the .NET 2.0 runtime with the preprocessing symbol “NET_2_0” defined.
Drag the UntrustedContent control from the toolbox onto your web form wherever you want the untrusted content to be displayed.
Drag whatever control(s) you want to use to render the untrusted content onto the UntrustedContent control. For example, you could drag a Literal control onto the UntrustedContent control and edit its contents.
To use NeatHtml on a web form without using the Visual Studio designer, follow these steps:
Add the following to the top of your page:
<%@ Register TagPrefix="NeatHtml" Namespace="Brettle.Web.NeatHtml" Assembly="Brettle.Web.NeatHtml" %>
Place whatever controls you use to display the untrusted content inside the UntrustedContent control, like this:
<NeatHtml:UntrustedContent runat="server">
controls to render the raw untrusted content (e.g. a LiteralControl)
</NeatHtml:UntrustedContent>
By default, no IMG elements are displayed because they can be used to mount CSRF attacks. If there are particular images with URLs that you trust, you can set the TrustedImageUrlPattern property to the regular expression pattern string that the SRC attribute of an IMG element must match in order for the image to be displayed. For example, to allow images in your top-level “images” folder to be displayed, you might set TrustedImageUrlPattern to something like “^/images/[a-zA-Z0-9]+\.(png|jpg|jpeg|gif)$”. If you are confident that your entire site is not susceptible to CSRF attacks, you could allow any image on your site to be displayed in untrusted content by using “^[/.].*$”. To completely disable NeatHtml's removal of automated CSRF attacks and allow display of any image on any website, you might use “^.*$”.
By default, NeatHtml adds rel=”nofollow” to any allowed element that contains an HREF attribute. This discourages link spam in untrusted content because most search engines ignore such links when building their indices. Links will still display properly and users can follow them, but the links won't be indexed by most search engines. If there are particular links that you want to allow search engines to index, you can set the SpamFreeLinkUrlPattern property to the regular expression pattern string that the HREF attribute must match in order for it to be indexed. NeatHtml will not add the rel=”nofollow” to link URLs which match the pattern. For example, to allow relative links to pages on your own site, you might set SpamFreeLinkUrlPattern to something like “^[/.].*$”. To completely disable this feature of NeatHtml and allow indexing of all links, you might use “^.*$”.
The algorithm used to allow tables has not been extensively tested and using it involves taking an unnecessary risk if benign content is not expected to contain TABLE elements. For that reason, support for displaying untrusted tables to no-script users is optional, and disabled by default. To enable that support, set the SupportNoScriptTables property to “true”.
If you prefer to put NeatHtml.js in a location other than the “NeatHtml” subdirectory in your application root, set the ClientScriptUrl property to the URL of NeatHtml.js. If the URL starts with "~", the "~" will be replaced with the web application root.
NeatHtml was designed to take time proportional to the size of the untrusted content, but the constant of proportionality can be high if the untrusted content contains a very large number of “<” characters, or “&” characters, or attributes. Processing is slow in these cases because they cause a large number of regex matches and subsequent function calls. To restrict the amount of processing required, NeatHtml tracks the number of regex matches that have occurred. When a configurable limit is exceeded, NeatHtml stops processing and instead of displaying the untrusted content, simply displays, "The content that belongs here is too complex to display securely." To change the limit, set the MaxComplexity property to the desired limit. By default, the limit is 10000.