artmotion / xss_shield
watch download tarball
public
Forks0Right
Watchers9Right
Description: XSS Shield protects your views against cross-site scripting attacks without error-prone manual escaping with h().
Homepage: http://code.google.com/p/xss-shield/
Clone URL: git://github.com/artmotion/xss_shield.git
xss_shield / README
raw normal view history
a2f71b4d » Tomasz.Wegrzanowski 2007-12-13 Moved stuff from trunk/ to ... 1 FIXME: THIS README IS NOT UP-TO-DATE.
2
3 This plugin provides XSS protection for views coded in HAML and RHTML.
4
5 ERB templates are sometimes used for HTML, and sometimes for
6 other kinds of languages (SQL, email templates, YAML etc.).
7 XSS Shield protects only those templates with .rhtml extension,
8 leaving templates with .erb extension unprotected.
9
10 === Quick start ===
11
12 Assuming you're using HAML for all your templates.
13
14 * Install plugin.
15 * Edit all your layout files and change:
16 = @content_for_layout
17 = yield(:foo) # Foo being usually :js or :css
18 to:
19 = @content_for_layout.mark_as_xss_protected
20 = yield(:foo).mark_as_xss_protected
21 * By this point your application should be runnanble,
22 but might need some tweaking here and there to avoid potential
23 double-escaping.
24
25 === How it works ===
26
27 It works by subclassing String into SafeString.
28 When HAML engine seems a "= foo" fragment it check if result of executing "foo"
29 is a SafeString. If it is - it copies it to the output, if it's anything else
30 (String, Integer, nil and so on) it HTML-escapes it first.
31
32 To avoid double-escaping output of h is a SafeString, as is everything you
33 mark as XSS-protected.
34 = h(@foo)
35 = @foo # fully equivalent to h(@foo)
36 = "X <br /> Y".mark_as_xss_protected
37
38 It would be cumbersome to require mark_as_xss_protected every time you use
39 some helper like render :partial or link_to, so some helpers are modified
40 to return SafeString.
41
42 = render :partial => "foo"
43 = link_to "Bar", :action => :bar
44
45 If you trust your helpers, make them as XSS-protected:
46
47 module Some::Module
48 mark_helpers_as_xss_protected :text_field, :check_box
49 end
50
51 Because it is not possible to alter syntactic keywords like yield
52 or instance variables like @content_for_layout to mark them automatically
53 as secure, layout files need some manual tweaking.
54
55 === Other template engines ===
56
57 If a templates uses some templating engine other than HAML or ERB,
58 or it uses ERB but has extension .erb not .rhtml, XSS Shield does not protect it.
59
60 However some helpers like link_to and button_to are patched by XSS Shield to
61 make them more secure, and this extra security will be there even when used
62 in an otherwise unprotected context.
63
64 For example with XSS shield
65 link_to "A & B", "/foo"
66 will return (marked as safe):
67 '<a href="/foo">A &amp; B</a>'
68 not (plain String):
69 '<a href="/foo">A & B</a>'
70
71 Also - RHTML protection only works with default ERB engine (erb.rb from Ruby base).
72 If you use some alternative ERB engine it probably won't work.
73
74 Adding support for alternative templating engine should be relatively straightforward.
75 It's mostly a matter of changing to_s to to_s_xss_protected in a few places
76 in their source.