xss_shield

= XSS Shield

This Rails plugin provides automatic cross site scripting ({XSS}[http://en.wikipedia.org/wiki/Cross-site_scripting]) protection for your views. Once installed, you no longer have to manually and painstakingly sanitize all your views with HTML escaping (eg. <%= h(foo) %>). Currently only {ERB}[http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/index.html] templates are supported.

For example with XSS Shield: <%= link_to "A & B", "/foo" %> will return a +SafeString+: A & B and not a plain, unsafe +String+: A & B

This version has been tested to work with Rails 2.3.4. Your milage may vary.

DISCLAIMER: Note that while no effort is spared to ensure that this plugin works as advertised, we cannot guarantee that all your views are 100% XSS safe. Use it at your own risk, but remember that {bug reports}[http://github.com/jamestyj/xss_shield/issues] and patches are welcomed.

== How it works

It works by subclassing +String+ into +SafeString+. When the ERB engine sees a <%= foo %> fragment, it checks if the result of executing +foo+ is a +SafeString+. If so, it just uses it. Otherwise the string is HTML escaped first.

The use of +SafeString+ avoids potential double-escaping. For example, with XSS Shield, <%= @foo %> is the same as <%= h(@foo) %>.

If your string contains HTML that you don't want to escape (and you trust it), just append .xss_safe: <%= "foobar".xss_safe %>

It would be cumbersome to require xss_safe every time you use some helper like render(:partial) or +link_to+, so some helpers are modified to return +SafeString+.

If you trust your helpers, you can mark them as XSS safe:

module Some::Module mark_methods_as_xss_safe :text_field, :check_box end

You may need to manually tweak your helpers, views and layouts to avoid unnecessary escaping.

== Other template engines

Currently only ERB templates is supported, but support for other templating engines should be relatively straightforward. It's mostly a matter of changing to_s to to_xss_safe in a few places in their source.

Patches that add support for other templating engines (along with supporting tests) are welcomed.

== Running tests

This plugin monkey patches ERB in order to do its magic, so it's a good idea to at least run the included tests to verify that things work in your environment.

You can run the XSS Shield tests by simply running:

rake

which should generate output looking like this:

(in /xss_shield) /usr/bin/ruby -I"lib:lib" "/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake/rake_test_loader.rb" ... Loaded suite /usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake/rake_test_loader Started .......................................................................................... Finished in 0.163422 seconds.

90 tests, 135 assertions, 0 failures, 0 errors

If you place this plugin inside the vendor/plugin directory of your Rails application, the test suite will load your application environment by requiring RAILS_ROOT/test/test_helper.rb.

Of course, you should also verify that your existing application tests still pass with XSS Shield enabled.

== Bugs and feedback

Please report bugs and feature requests {here}[http://github.com/jamestyj/xss_shield/issues]. Patches and suggestions are welcomed too.

== Authors

• Updated to support Rails 2.1 and maintained by {James Tan}[http://github.com/jamestyj], Novell.
• {Original code}[http://code.google.com/p/xss-shield/] written by {Tomasz Wegrzanowski}[http://code.google.com/u/Tomasz.Wegrzanowski/], Trampoline Systems.

== License

Copyright (c) 2009 Novell. See MIT-LICENSE in this directory.