Sanitize untrusted HTML (to prevent XSS) with a configuration specified by a Whitelist
The xss package is a robust HTML sanitizer designed to prevent cross-site scripting (XSS) attacks by filtering untrusted HTML input against a configurable whitelist. Instead of attempting to blacklist dangerous patterns—an approach that historically fails as attackers find new bypasses—xss uses a whitelist strategy where only explicitly allowed HTML tags and attributes pass through. Any disallowed content is stripped or escaped, making it safe for rendering in web applications.
With over 3.5 million weekly downloads, xss has become a standard solution for Node.js and browser-based applications that need to handle user-generated HTML content. It operates on a simple principle: define what's safe rather than trying to enumerate what's dangerous. The package provides sensible defaults for common use cases (allowing basic formatting tags like ,
The library performs at approximately 22.53 MB/s, significantly outperforming older alternatives, and supports both simple function calls (xss(html)) and reusable FilterXSS instances for repeated sanitization with consistent rules. It's particularly valuable for applications that display user content—forums, CMS platforms, comment systems, email clients, and any scenario where HTML from untrusted sources must be rendered safely. Note that versions prior to 1.0.10 contained a ReDoS vulnerability, so always use 1.0.10 or later in production.
const xss = require('xss');
// Basic usage with default whitelist
const untrustedInput = '<script>alert("XSS")</script><p>Hello <b>World</b></p>';
const sanitized = xss(untrustedInput);
console.log(sanitized); // <p>Hello <b>World</b></p>
// Custom configuration with strict whitelist
const strictOptions = {
whiteList: {
p: [],
br: [],
strong: [],
em: []
},
stripIgnoreTag: true,
stripIgnoreTagBody: ['script', 'style']
};
const strictSanitized = xss('<p>Safe text</p><img src="x" onerror="alert(1)">Unsafe', strictOptions);
console.log(strictSanitized); // <p>Safe text</p>Unsafe
// Reusable instance with custom attribute handler
const myXss = new xss.FilterXSS({
whiteList: {
a: ['href', 'title', 'target'],
img: ['src', 'alt']
},
onTagAttr: (tag, name, value) => {
// Only allow https URLs in href and src
if ((name === 'href' || name === 'src') && !value.startsWith('https://')) {
return '';
}
},
onIgnoreTag: (tag, html, options) => {
// Log blocked tags for monitoring
console.log(`Blocked tag: ${tag}`);
}
});
const userContent = '<a href="https://example.com">Safe</a><a href="javascript:alert(1)">Blocked</a>';
console.log(myXss.process(userContent)); // <a href="https://example.com">Safe</a><a href>Blocked</a>User-generated content platforms: Forums, social networks, and blogging platforms use xss to sanitize user posts and comments before storing or displaying them, allowing basic formatting (bold, links, images) while blocking script injection attempts.
Content management systems: CMS applications employ xss to sanitize HTML from WYSIWYG editors, ensuring that even administrators with HTML editing privileges cannot accidentally introduce XSS vectors that could compromise other users.
Email rendering: Web-based email clients use xss to sanitize HTML emails before displaying them in the browser, stripping potentially malicious scripts while preserving legitimate formatting and inline images.
API input validation: REST APIs that accept HTML content (like article bodies, product descriptions, or rich text fields) sanitize inputs server-side with xss before persisting to databases, preventing stored XSS attacks.
Third-party content integration: Applications that embed or display content from external sources (RSS feeds, API responses, webhooks) use xss to sanitize HTML before rendering, protecting against compromised or malicious third-party sources.
npm install xsspnpm add xssbun add xss