Migrating to the Microsoft Anti-Cross Site Scripting Library: Step‑by‑Step Guide

Best Practices with Microsoft Anti-Cross Site Scripting Library (AntiXSS)

Overview

The Microsoft Anti-Cross Site Scripting Library (AntiXSS) provides encoding routines that use a safe-list approach to make untrusted input safe for output in HTML, attributes, JavaScript, CSS, URLs, and XML. Use AntiXSS encoders to perform context-appropriate output encoding rather than ad-hoc escaping.

Key best practices

1. Use context-specific encoders

• HTML content: AntiXssEncoder.HtmlEncode(…)
• HTML attributes: AntiXssEncoder.HtmlAttributeEncode(…) or encode attribute value then wrap in quotes
• JavaScript strings: AntiXssEncoder.JavaScriptStringEncode(…)
• CSS values: use CSS encoding routines or escape characters safely before insertion
• URLs and query values: AntiXssEncoder.UrlEncode(…) or System.Text.Encodings.Web.UrlEncoder for modern apps
• XML/JSON output: use XmlEncode/XmlAttributeEncode or JSON serializers that handle escaping

2. Encode on output, not input

• Store raw user input (if needed) and apply encoding at the point of rendering for the specific context. Do not double-encode.

3. Prefer library encoders over manual escaping

• Use AntiXSS APIs (AntiXssEncoder or, in newer frameworks, System.Text.Encodings.Web encoders) rather than string.Replace or hand-rolled routines.

4. Replace default runtime encoder in legacy ASP.NET when appropriate

• For older WebForms/MVC apps that rely on HttpUtility-style encoding, register AntiXssEncoder as the HttpEncoder via web.config:

  Code
  Copy CodeCopied
  
  

  (Test thoroughly as encoder behavior and safe-lists differ from defaults.)

5. Be explicit about where data is inserted into the DOM

• Avoid inserting untrusted strings into HTML with innerHTML or document.write(). When passing values into JavaScript, use JavaScriptStringEncode or place data in data-attributes and read via textContent or dataset.

6. Keep safe-lists restrictive; expand only when necessary

• AntiXSS uses a conservative safe-list. If your app needs additional Unicode ranges (e.g., non-Latin scripts), use MarkAsSafe carefully and only for the needed ranges.

7. Use secure frameworks and serializers for structured data

• For JSON APIs, use trusted JSON serializers (that do their own escaping) and avoid returning HTML inside JSON unless encoded for the target consumer.

8. Combine encoding with other defenses

• Input validation: enforce expected formats/lengths.
• Content Security Policy (CSP): add a strong CSP to limit script sources and reduce impact of any injection.
• HttpOnly and Secure cookies, SameSite attributes for session protection.
• Use server-side templating or frameworks that auto-encode where available.

9. Test and review

• Use automated scanners and manual penetration testing (DOM XSS tests, reflected/stored XSS scenarios).
• Add unit tests asserting that encoder output is safe for each output context (examples with script tags, quotes, non-Latin chars).

10. Prefer modern encoders for newer projects

• For ASP.NET Core and modern .NET, prefer the encoders in System.Text.Encodings.Web (HtmlEncoder, JavaScriptEncoder, UrlEncoder) exposed via DI, since AntiXSS is primarily for older frameworks.

Examples (C#)

• HTML encode:

  Code
  Copy CodeCopied
  var safe = System.Web.Security.AntiXss.AntiXssEncoder.HtmlEncode(userInput, false); 

• JavaScript string encode:

  Code
  Copy CodeCopied
  var jsSafe = System.Web.Security.AntiXss.AntiXssEncoder.JavaScriptStringEncode(userInput); 

• URL encode:

  Code
  Copy CodeCopied
  var urlSafe = System.Web.Security.AntiXss.AntiXssEncoder.UrlEncode(userInput); 

(For ASP.NET Core: inject HtmlEncoder/JavaScriptEncoder/UrlEncoder and call Encode.)

Quick checklist before deployment

• All user-supplied values encoded with a context-appropriate encoder.
• No untrusted data inserted via innerHTML/document.write or concatenated into scripts.
• CSP and other HTTP mitigations configured.
• Encoder behavior verified with unit and security tests.
• Legacy encoder replacement tested across app surface.

Further reading

• Microsoft docs for AntiXssEncoder (System.Web.Security.AntiXss)
• ASP.NET Core guidance: use System.Text.Encodings.Web HtmlEncoder/JavaScriptEncoder/UrlEncoder and follow framework recommendations