HTML Guard — Best Practices for Safe HTML Rendering

Document the allowed set of tags, attributes, and URI schemes.

Sanitization vs. Escaping

• Escaping converts special characters (e.g., < to <) and is used when you want to display raw text as plain content.
• Sanitization removes or transforms unsafe markup while preserving allowed HTML. Use a sanitizer when you want to allow some HTML.

For inputs that will be inserted into different contexts (HTML body, attribute, JS), always use context-appropriate escaping on output, even after sanitization.

Practical server-side techniques

1. Use a vetted sanitizer library
   • Do not write your own from scratch unless you have security expertise.
   • Examples by language: DOMPurify (JS), Bleach (Python), OWASP Java HTML Sanitizer, AntiSamy (Java), HtmlSanitizer (.NET).
2. Configure allowlists
   • Explicitly list allowed tags and permitted attributes per tag.
   • For links, allow only safe protocols (http, https, mailto) and disallow javascript:, data:, vbscript:.
3. Attribute validation
   • For attributes that accept URLs, validate or rewrite them to safe forms.
   • For src/href, consider proxying images or disallowing remote resources.
4. Strip dangerous attributes
   • Remove event handlers (on*), style attributes (unless you sanitize CSS), and any attributes that can inject code.
5. Handle images carefully
   • Consider disallowing data: URIs to avoid embedded payloads and leakage.
   • Limit image sizes or proxy through your server to control content.
6. Sanitize CSS if needed
   • If you allow style attributes or style tags, use a CSS sanitizer to remove expressions, url() to remote resources, and other risky constructs.
7. Normalize input
   • Decode HTML entities and percent-encoding before sanitization, then re-apply encoding as needed.
8. Store the sanitized result
   • Persist the cleaned HTML; do not re-sanitize on every render unless necessary.

Client-side and runtime protections

• Content Security Policy (CSP)
  • Use CSP to limit script execution sources, disallow inline scripts (nonce/hashes), restrict frames and image sources.
• HTTP-only and SameSite cookies
  • Reduce session theft risk via XSS.
• Trusted Types (for browsers that support them)
  • Restrict creation of dangerous sinks like innerHTML in client code.
• Avoid innerHTML with untrusted input
  • Prefer DOM methods that create elements and set textContent when inserting untrusted content.
• Sandboxed iframes
  • For rich third-party content, use sandboxed iframes with a strict allow list and force a different origin when possible.

Rendering strategies

• Escape everything by default and selectively unescape sanitized fragments.
• Use template engines that auto-escape by default; mark sanitized HTML as safe only after robust checks.
• When rendering links, add rel=“noopener noreferrer” and target=“_blank” only when appropriate.
• Consider progressive enhancement: store raw text and a sanitized HTML preview.

Testing and verification

• Unit and integration tests covering:
  • Allowed tags/attributes pass.
  • Known XSS vectors are blocked (on*, javascript:, encoded payloads).
• Fuzz testing with malformed or obfuscated payloads.
• Automated security scanners and manual code review.
• Use OWASP XSS Cheat Sheet to generate test cases.
• Monitor production for CSP violations and unexpected MIME types.

Example configuration (conceptual)

Allowed tags:

• p, br, b, strong, i, em, u, ul, ol, li, a, img

Allowed attributes:

• a: href, title, rel
• img: src, alt, title, width, height

Allowed protocols:

• http, https, mailto

Strip:

• style, on*, script, iframe, object, embed, form

Performance considerations

• Sanitization can be CPU-intensive; batch or async sanitize on input rather than on every request.
• Cache sanitized results for identical inputs.
• For large content, stream parsing/sanitization to avoid high memory usage.

Common pitfalls

• Relying solely on client-side sanitization.
• Allowing style attributes or inline event handlers without strong sanitization.
• Not normalizing input encoding before checks.
• Trusting user-supplied URLs without validation or proxying.

Example workflow summary

1. Decide allowed features (tags, attributes, protocols).
2. Canonicalize input (decode entities, percent-encoding).
3. Run a vetted sanitizer with strict allowlists.
4. Validate attributes and rewrite/normalize URLs.
5. Store sanitized HTML and render using context-appropriate escaping.
6. Add CSP, Trusted Types, and secure cookie flags to reduce impact of any gaps.
7. Test with known XSS vectors and monitor.

Conclusion

An effective “HTML Guard” combines principled policies, vetted libraries, and layered runtime defenses. Restrict what you allow, canonicalize and sanitize inputs, and apply output encoding and browser-level protections. With these measures you can preserve useful HTML formatting while keeping users and applications safe.