Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 95 lines (65 sloc) 3.688 kb
28a980d move to xss_terminate subdir to make installing from Rails easier
look@recursion.org authored
1 = xss_terminate
2
3 +xss_terminate+ is a plugin in that makes stripping and sanitizing HTML
4 stupid-simple. Install and forget. And forget about forgetting to <tt>h()</tt>
5 your output, because you won't need to anymore.
6
7 But +xss_terminate+ is also flexible. By default, it will strip all HTML tags
8 from user input. This is usually what you want, but sometimes you need users to be
9 able to enter HTML. The plugin allows you remove bad HTML with your choice
10 of two whitelist-based sanitizers, or to skip HTML sanitization entirely on
11 a per-field basis.
12
56ec95a install instructions
look@recursion.org authored
13 To install, do:
14
15 script/plugin install http://xssterminate.googlecode.com/svn/trunk/xss_terminate
16
28a980d move to xss_terminate subdir to make installing from Rails easier
look@recursion.org authored
17 == HTML sanitization
18
19 A note on your choices.
20
21 * Strip tags: removes all HTML using Rails's built-in +strip_tags+ method. Tags are removed, but their content is not.
22 * Rails sanitization: Removes bad HTML with Rails's built-in sanitize method. Bad tags are removed completely, including their content.
23 * HTML5lib sanitization: Removes bad HTML after parsing it with {HTML5lib}[http://code.google.com/p/html5lib/], a library that parses HTML like browsers do. It should be very tolerant of invalid HTML. Bad tags are escaped, not removed.
24 * Do nothing. You can chose not to process given fields.
25
26 == Usage
27
28 Installing the plugin creates a +before_save+ hook that will strip HTML tags
29 from all string and text fields. No further configuration is necessary if this
30 is what you want. To customize the behavior, you use the +xss_terminate+ class
31 method.
32
33 To exempt some fields from sanitization, use the <tt>:except</tt> option
34 with a list of fields not to process:
35
36 class Comment < ActiveRecord::Base
37 xss_terminate :except => [ :body ]
38 end
39
40 To sanitize HTML with Rails's built-in sanitization, use the <tt>:sanitize</tt> option:
41
42 class Review < ActiveRecord::Base
43 xss_sanitize :sanitize => [ :body, :author_name]
44 end
45
46 To sanitize HTML with {HTML5Lib}[http://code.google.com/p/html5lib/]
47 (<tt>gem install html5</tt> to get it), use the <tt>:html5lib_sanitize</tt>
48 option with a list of fields to sanitize:
49
50 class Entry < ActiveRecord::Base
51 xss_terminate :html5lib_sanitize => [ :body, :author_name ]
52 end
53
54 You can combine multiple options if you have some fields you would like skipped
55 and others sanitized. Fields not listed in the option arrays will be stripped.
56
57 class Message < ActiveRecord::Base
58 xss_terminate :except => [ :body ], :sanitize => [ :title ]
59 end
60
61 == Sanitizing existing records
62
63 After installing +xss_terminate+ and configuring it to your liking, you can
64 run <tt>rake xss_terminate MODELS=Foo,Bar,Baz</tt> to execute it against your
65 existing records. This will load each model found and save it again to invoke
66 the before_save hook.
67
68 == Unique features
69
70 +xss_terminate+ is based on +acts_as_sanitized+. Here is what's different:
71
72 * Rails 2.0-ready.
73 * Automatic. It is included with default options in <tt>ActiveReord::Base</tt> so all your models are sanitized.
74 * It works with migrations. Columns are fetched when model is saved, not when the class is loaded.
75 * You can decide whether to sanitize or strip tags on a field-by-field basis instead of model-by-model.
76 * HTML5lib support.
77
78 == TODO
79
80 * Performance tests
81 * Test suites with "real world" HTML
82 * Test/make work with Rails 1.2.x (Rails 1.2 sanitization is crap, so you'd want to use HTML5lib)
83
84 == Credits
85
86 Written by {Luke Francl}[http://railspikes.com] and based on acts_as_sanitized by
87 {Alex Payne}[http://www.al3x.net].
88
89 HTML5Lib sanitization by {Jacques Distler}[http://golem.ph.utexas.edu/~distler].
90
91 == License
92
93 MIT License, except for lib/html5lib_sanitize.rb which is under the
94 Ruby license and copyright to Jacques Distler.
Something went wrong with that request. Please try again.