Module: Hanami::Helpers::EscapeHelper

Defined in:
gems/gems/hanami-helpers-1.3.1/lib/hanami/helpers/escape_helper.rb,
gems/gems/hanami-helpers-1.3.3/lib/hanami/helpers/escape_helper.rb

Overview

Escape helpers

You can include this module inside your view and the view will have access all methods.

By including Hanami::Helpers::EscapeHelper it will inject private methods as markup escape utilities.

Since:

  • 0.1.0

Instance Method Summary collapse

Instance Method Details

#escape_html(input) ⇒ String (private) Also known as: h

Escape the given HTML tag content.

This should be used only for untrusted contents: user input.

This should be used only for tag contents. To escape tag attributes please use Hanami::Helpers::EscapeHelper#escape_html_attribute.

Examples:

Basic usage

require 'hanami/helpers/escape_helper'

class MyView
  include Hanami::Helpers::EscapeHelper

  def good_content
    h "hello"
  end

  def evil_content
    h "<script>alert('xss')</script>"
  end
end

view = MyView.new

view.good_content
  # => "hello"

view.evil_content
  # => "&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;"

With HTML builder

#
# CONTENTS ARE AUTOMATICALLY ESCAPED
#
require 'hanami/helpers'

class MyView
  include Hanami::Helpers

  def evil_content
    html.div do
      "<script>alert('xss')</script>"
    end
  end
end

view = MyView.new
view.evil_content
  # => "<div>\n&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;</div>"

Parameters:

  • input (String) —

    the input

Returns:

  • (String) —

    the escaped string

See Also:

Since:

  • 0.1.0

Source: | on GitHub 

def escape_html(input)
  Utils::Escape.html(input)
end

#escape_html_attribute(input) ⇒ String (private) Also known as: ha

Escape the given HTML tag attribute.

This MUST be used for escaping HTML tag attributes.

This should be used only for untrusted contents: user input.

This can also be used to escape tag contents, but it’s slower. For this purpose use Hanami::Helpers::EscapeHelper#escape_html.

Examples:

Basic usage

require 'hanami/helpers/escape_helper'

class MyView
  include Hanami::Helpers::EscapeHelper

  def good_attribute
    attribute = "small"

    %(<span class="#{ ha(attribute) }">hello</span>
  end

  def evil_attribute
    attribute = %(" onclick="javascript:alert('xss')" id=")

    %(<span class="#{ ha(attribute) }">hello</span>
  end
end

view = MyView.new

view.good_attribute
  # => %(<span class="small">hello</span>)

view.evil_attribute
  # => %(<span class="&quot;&#x20;onclick&#x3d;&quot;javascript&#x3a;alert&#x28;&#x27;xss&#x27;&#x29;&quot;&#x20;id&#x3d;&quot;">hello</span>

With HTML builder

#
# ATTRIBUTES AREN'T AUTOMATICALLY ESCAPED
#
require 'hanami/helpers'

class MyView
  include Hanami::Helpers

  def evil_attribute
    user_input_attribute = %(" onclick="javascript:alert('xss')" id=")

    html.span id: 'greet', class: ha(user_input_attribute) do
      "hello"
    end
  end
end

view = MyView.new
view.evil_attribute
  # => %(<span class="&quot;&#x20;onclick&#x3d;&quot;javascript&#x3a;alert&#x28;&#x27;xss&#x27;&#x29;&quot;&#x20;id&#x3d;&quot;">hello</span>

Parameters:

  • input (String) —

    the input

Returns:

  • (String) —

    the escaped string

See Also:

Since:

  • 0.1.0

Source: | on GitHub 

def escape_html_attribute(input)
  Utils::Escape.html_attribute(input)
end

#escape_url(input, schemes = Utils::Escape::DEFAULT_URL_SCHEMES) ⇒ String (private) Also known as: hu

Escape an URL to be used in HTML attributes

This allows only URLs with whitelisted schemes to pass the filter. Everything else is stripped.

Default schemes are:

  • http

  • https

  • mailto

If you want to allow a different set of schemes, you should pass it as second argument.

This should be used only for untrusted contents: user input.

Examples:

Basic usage

require 'hanami/helpers/escape_helper'

class MyView
  include Hanami::Helpers::EscapeHelper

  def good_url
    url = "http://hanamirb.org"

    %(<a href="#{ hu(url) }">Hanami</a>
  end

  def evil_url
    url = "javascript:alert('xss')"

    %(<a href="#{ hu(url) }">Evil</a>
  end
end

view = MyView.new

view.good_url
  # => %(<a href="http://hanamirb.org">Hanami</a>)

view.evil_url
  # => %(<a href="">Evil</a>)

Custom schemes

require 'hanami/helpers/escape_helper'

class MyView
  include Hanami::Helpers::EscapeHelper

  def ftp_link
    schemes = ['ftp', 'ftps']
    url     = 'ftps://ftp.example.org'

    %(<a href="#{ hu(url, schemes) }">FTP</a>
  end
end

view = MyView.new

view.ftp_link
  # => %(<a href="ftps://ftp.example.org">FTP</a>)

Parameters:

  • input (String) —

    the input

  • schemes (Array<String>) (defaults to: Utils::Escape::DEFAULT_URL_SCHEMES) —

    an optional array of whitelisted schemes

Returns:

  • (String) —

    the escaped string

See Also:

Since:

  • 0.1.0

Source: | on GitHub 

def escape_url(input, schemes = Utils::Escape::DEFAULT_URL_SCHEMES)
  Utils::Escape.url(input, schemes)
end

#raw(input) ⇒ Hanami::Utils::Escape::SafeString (private)

Bypass escape.

Please notice that this can be really dangerous. Use at your own peril.

Examples:

require 'hanami/helpers/escape_helper'

class MyView
  include Hanami::Helpers::EscapeHelper

  def good_content
    raw "<p>hello</p>"
  end

  def evil_content
    raw "<script>alert('xss')</script>"
  end
end

view = MyView.new

view.good_content
  # => "<p>hello</p>"

#
# !!! WE HAVE OPENED OUR APPLICATION TO AN XSS ATTACK !!!
#
view.evil_content
  # => "<script>alert('xss')</script>"

Parameters:

  • input (String) —

    the input

Returns:

  • (Hanami::Utils::Escape::SafeString) —

    the string marked as safe string

Since:

  • 0.1.0

Source: | on GitHub 

def raw(input)
  Utils::Escape::SafeString.new(input)
end