Module: SanitizeUrl

Defined in:
lib/sanitize-url.rb

Overview

Helper methods in this module are module methods so that they won’t pollute the namespace into which the module is mixed in.

Constant Summary collapse

ALPHANUMERIC_CHAR_CODES = 
(48..57).to_a + (65..90).to_a + (97..122).to_a
VALID_OPAQUE_SPECIAL_CHARS = 
['!', '*', "'", '(', ')', ';', ':', '@', '&', '=', '+', '$', ',', '/', '?', '%', '#', '[', ']', '-', '_', '.', '~']
VALID_OPAQUE_SPECIAL_CHAR_CODES = 
VALID_OPAQUE_SPECIAL_CHARS.collect { |c| c[0].is_a?(String) ? c.ord : c[0] }
VALID_OPAQUE_CHAR_CODES = 
ALPHANUMERIC_CHAR_CODES + VALID_OPAQUE_SPECIAL_CHAR_CODES
VALID_SCHEME_SPECIAL_CHARS = 
['+', '.', '-']
VALID_SCHEME_SPECIAL_CHAR_CODES = 
VALID_SCHEME_SPECIAL_CHARS.collect { |c| c[0].is_a?(String) ? c.ord : c[0] }
VALID_SCHEME_CHAR_CODES = 
ALPHANUMERIC_CHAR_CODES + VALID_SCHEME_SPECIAL_CHAR_CODES
HTTP_STYLE_SCHEMES =

Common schemes whose format should be “scheme://” instead of “scheme:”

['http', 'https', 'ftp', 'ftps', 'svn', 'svn+ssh', 'git']

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.char_or_url_encoded(code) ⇒ Object

Return either the literal char or the URL-encoded equivalent, depending on our normalization rules. Requires a decimal code point. Code point can be outside the single-byte range.



94
95
96
97
98
99
100
101
102
 
# File 'lib/sanitize-url.rb', line 94

def self.char_or_url_encoded(code) #:nodoc:
	if url_encode?(code)
		utf_8_str = ([code.to_i].pack('U'))
		length = utf_8_str.respond_to?(:bytes) ? utf_8_str.bytes.to_a.length : utf_8_str.length
		'%' + utf_8_str.unpack('H2' * length).join('%').upcase
	else
		code.chr
	end
end

.dereference_numerics(str) ⇒ Object

:nodoc:



80
81
82
83
84
85
86
87
88
89
 
# File 'lib/sanitize-url.rb', line 80

def self.dereference_numerics(str) #:nodoc:
	# Decimal code points, e.g. j &#106 j &#0000106
	str = str.gsub(/&#([a-fA-f0-9]+);?/) do
		char_or_url_encoded($1.to_i)
	end
	# Hex code points, e.g. j &#x6A
	str.gsub(/&#[xX]([a-fA-f0-9]+);?/) do
		char_or_url_encoded($1.to_i(16))
	end		
end

.url_encode?(code) ⇒ Boolean

Should we URL-encode the byte? Must receive an integer code point

Returns:

  • (Boolean) 


106
107
108
109
110
111
112
113
 
# File 'lib/sanitize-url.rb', line 106

def self.url_encode?(code) #:nodoc:
	!(
		(code >= 48 and code <= 57)  or   # Numbers
		(code >= 65 and code <= 90)  or   # Uppercase
		(code >= 97 and code <= 122) or   # Lowercase
		VALID_OPAQUE_CHAR_CODES.include?(code)
	)
end

Instance Method Details

#sanitize_url(url, options = {}) ⇒ Object

Sanitize the URL. Example usage:

sanitize_url('javascript:alert("XSS")')
sanitize_url('javascript:alert("XSS")', :replace_evil_with => 'Replaced')
sanitize_url('ftp://example.com', :schemes => ['http', 'https'])

Raises:

  • (ArgumentError) 


20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/sanitize-url.rb', line 20

def sanitize_url(url, options = {})
	raise(ArgumentError, 'options[:schemes] must be an array') if options.has_key?(:schemes) and !options[:schemes].is_a?(Array)
	options = {
		:replace_evil_with => '',
		:schemes => ['http', 'https', 'ftp', 'ftps', 'mailto', 'svn', 'svn+ssh', 'git']
	}.merge(options)
	
	url = SanitizeUrl.dereference_numerics(url)
	
	# Schemes can consist of letters, digits, or any of the following special chars: + . -
	# The scheme must begin with a letter and be terminated by a colon.
	# Everything after the scheme is opaque for our purposes. (See http://www.w3.org/DesignIssues/Axioms.html#opaque)
	
	# Try to match a URI with a scheme. We check for percent-encoded characters in the scheme.
	url.match(/^(.+?)(:|%3A)(.*)$/)
	dirty_scheme = $1
	if dirty_scheme
		unescaped_opaque = $3
		return options[:replace_evil_with] if unescaped_opaque.nil? or unescaped_opaque.empty? or unescaped_opaque.match(/^\/+$/)
	else
		# Use http as the best guest, and the rest of the URL will be considered opaque
		dirty_scheme = 'http'
		unescaped_opaque = url
	end
	# Remove URL encoding from the scheme
	dirty_scheme.gsub!(/%([a-zA-Z0-9]{2})/) do
		code = $1.to_i(16)
		VALID_SCHEME_CHAR_CODES.include?(code) ? code.chr : ''
	end
	
	# Clean the scheme by removing invalid characters
	scheme = ''
	dirty_scheme.each_byte do |code|
		scheme << code.chr if VALID_SCHEME_CHAR_CODES.include?(code)
	end
	
	# URL-encode the opaque portion as necessary. Only encode those bytes that are absolutely not allowed in URLs.
	opaque = ''
	unescaped_opaque.each_byte do |code|
		if SanitizeUrl.url_encode?(code)
			opaque << '%' << code.to_s(16).upcase
		else
			opaque << code.chr
		end
	end
	
	if options[:schemes].collect { |s| s.to_s }.include?(scheme.downcase)
		if HTTP_STYLE_SCHEMES.include?(scheme.downcase) and !opaque.match(/^\/\//)
			# It's an HTTP-like scheme, but the two slashes are missing. We'll fix that as a courtesy.
			url = scheme + '://' + opaque
		else
			# Either the scheme doesn't need the two slashes, or the opaque portion already has them.
			url = scheme + ':' + opaque
		end
		return url
	else
		return options[:replace_evil_with]
	end
end