Module: Dandruff

Defined in:

lib/dandruff.rb,
lib/dandruff/tags.rb,
lib/dandruff/utils.rb,
lib/dandruff/config.rb,
lib/dandruff/version.rb,
lib/dandruff/attributes.rb,
lib/dandruff/expressions.rb

Overview

Dandruff - A robust HTML sanitizer for Ruby

Dandruff is a Ruby implementation inspired by DOMPurify, providing comprehensive XSS protection by sanitizing HTML strings and removing malicious payloads. It’s designed for excellent developer experience while maintaining battle-tested security.

## Key Features

• **Comprehensive XSS Protection**: Defends against XSS, mXSS, DOM clobbering, and protocol injection

• **Flexible Configuration**: Fine-grained control over tags, attributes, and sanitization behavior

• **Content Type Profiles**: Pre-configured settings for HTML, SVG, MathML, and HTML email

• **Hook System**: Extend sanitization with custom processing logic

• **Developer-Friendly API**: Intuitive Ruby idioms with block-based configuration

• **Battle-Tested Security**: Based on DOMPurify’s proven security model

• **Performance Optimized**: Efficient multi-pass sanitization with configurable limits

## Quick Start

## Security

Dandruff protects against multiple attack vectors:

• XSS: Removes script tags, event handlers, javascript: URIs

• mXSS: Multi-pass sanitization prevents mutation-based attacks

• **DOM Clobbering**: Blocks dangerous id/name attribute values

• **Protocol Injection**: Validates URI protocols (javascript:, vbscript:, data:text/html)

• **Namespace Confusion**: Prevents mXSS via SVG/MathML namespace attacks

• **CSS Injection**: Sanitizes inline styles and style tag content

Examples:

Basic sanitization

require 'dandruff'

dandruff = Dandruff.new
clean = dandruff.sanitize('<script>alert("xss")</script><p>Safe content</p>')
# => "<p>Safe content</p>"

Configure with block

dandruff = Dandruff.new do |config|
  config.allowed_tags = ['p', 'strong', 'em', 'a']
  config.allowed_attributes = ['href', 'title', 'class']
end

Use convenience class method

clean = Dandruff.sanitize(dirty_html, allowed_tags: ['p', 'strong'])

Profile-based configuration

dandruff = Dandruff.new do |config|
  config.use_profiles = { html: true, svg: true }
end

Per-tag attribute control

dandruff = Dandruff.new do |config|
  config.allowed_attributes_per_tag = {
    'a' => ['href', 'title'],
    'img' => ['src', 'alt', 'width', 'height']
  }
end

Custom hooks

dandruff = Dandruff.new
dandruff.add_hook(:upon_sanitize_attribute) do |node, data, config|
  # Custom attribute processing
  if data[:attr_name] == 'data-safe'
    data[:keep_attr] = true
  end
end

See Also:

• GitHub repository
• Original JavaScript implementation
• Configuration options reference
• Core sanitization engine

Defined Under Namespace

Modules: Attributes, Expressions, Tags, Utils Classes: Config, Error, Sanitizer

Constant Summary

VERSION =

'0.8.1'

Class Method Summary

• .new(cfg = {}) {|config| ... } ⇒ Sanitizer

  Builds a new sanitizer instance with optional configuration.

• .sanitize(dirty, cfg = {}) ⇒ String, Nokogiri::XML::Document (also: scrub)

  Convenience helper to sanitize with a fresh, default-configured instance.

Class Method Details

.new(cfg = {}) {|config| ... } ⇒ Sanitizer

Builds a new sanitizer instance with optional configuration

Parameters:

• cfg (Hash, Config) (defaults to: {}) —

  optional configuration to initialize with

Yields:

• (config) —

  optional block to mutate configuration before use

Returns:

• (Sanitizer) —

  a new sanitizer instance

# File 'lib/dandruff.rb', line 1089

def self.new(cfg = {}, &block)
  Sanitizer.new(cfg, &block)
end

.sanitize(dirty, cfg = {}) ⇒ String, Nokogiri::XML::Document Also known as: scrub

Convenience helper to sanitize with a fresh, default-configured instance.

Parameters:

• dirty (String, Nokogiri::XML::Node) —

  the input to sanitize

• cfg (Hash) (defaults to: {}) —

  optional configuration override

Returns:

• (String, Nokogiri::XML::Document) —

  sanitized HTML or DOM

# File 'lib/dandruff.rb', line 1098

def self.sanitize(dirty, cfg = {})
  new(cfg).sanitize(dirty)
end