Permalink
Browse files

move to xss_terminate subdir to make installing from Rails easier

git-svn-id: http://xssterminate.googlecode.com/svn/trunk/xss_terminate@3 503a6658-bc44-0410-a8bd-599819d3de0a
  • Loading branch information...
0 parents commit 28a980dafa4a34ddd21c89c9252a646bce331cd9 look@recursion.org committed Jan 27, 2008
@@ -0,0 +1,20 @@
+Copyright (c) 2008 Luke Francl
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
90 README
@@ -0,0 +1,90 @@
+= xss_terminate
+
++xss_terminate+ is a plugin in that makes stripping and sanitizing HTML
+stupid-simple. Install and forget. And forget about forgetting to <tt>h()</tt>
+your output, because you won't need to anymore.
+
+But +xss_terminate+ is also flexible. By default, it will strip all HTML tags
+from user input. This is usually what you want, but sometimes you need users to be
+able to enter HTML. The plugin allows you remove bad HTML with your choice
+of two whitelist-based sanitizers, or to skip HTML sanitization entirely on
+a per-field basis.
+
+== HTML sanitization
+
+A note on your choices.
+
+* Strip tags: removes all HTML using Rails's built-in +strip_tags+ method. Tags are removed, but their content is not.
+* Rails sanitization: Removes bad HTML with Rails's built-in sanitize method. Bad tags are removed completely, including their content.
+* 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.
+* Do nothing. You can chose not to process given fields.
+
+== Usage
+
+Installing the plugin creates a +before_save+ hook that will strip HTML tags
+from all string and text fields. No further configuration is necessary if this
+is what you want. To customize the behavior, you use the +xss_terminate+ class
+method.
+
+To exempt some fields from sanitization, use the <tt>:except</tt> option
+with a list of fields not to process:
+
+ class Comment < ActiveRecord::Base
+ xss_terminate :except => [ :body ]
+ end
+
+To sanitize HTML with Rails's built-in sanitization, use the <tt>:sanitize</tt> option:
+
+ class Review < ActiveRecord::Base
+ xss_sanitize :sanitize => [ :body, :author_name]
+ end
+
+To sanitize HTML with {HTML5Lib}[http://code.google.com/p/html5lib/]
+(<tt>gem install html5</tt> to get it), use the <tt>:html5lib_sanitize</tt>
+option with a list of fields to sanitize:
+
+ class Entry < ActiveRecord::Base
+ xss_terminate :html5lib_sanitize => [ :body, :author_name ]
+ end
+
+You can combine multiple options if you have some fields you would like skipped
+and others sanitized. Fields not listed in the option arrays will be stripped.
+
+ class Message < ActiveRecord::Base
+ xss_terminate :except => [ :body ], :sanitize => [ :title ]
+ end
+
+== Sanitizing existing records
+
+After installing +xss_terminate+ and configuring it to your liking, you can
+run <tt>rake xss_terminate MODELS=Foo,Bar,Baz</tt> to execute it against your
+existing records. This will load each model found and save it again to invoke
+the before_save hook.
+
+== Unique features
+
++xss_terminate+ is based on +acts_as_sanitized+. Here is what's different:
+
+* Rails 2.0-ready.
+* Automatic. It is included with default options in <tt>ActiveReord::Base</tt> so all your models are sanitized.
+* It works with migrations. Columns are fetched when model is saved, not when the class is loaded.
+* You can decide whether to sanitize or strip tags on a field-by-field basis instead of model-by-model.
+* HTML5lib support.
+
+== TODO
+
+* Performance tests
+* Test suites with "real world" HTML
+* Test/make work with Rails 1.2.x (Rails 1.2 sanitization is crap, so you'd want to use HTML5lib)
+
+== Credits
+
+Written by {Luke Francl}[http://railspikes.com] and based on acts_as_sanitized by
+{Alex Payne}[http://www.al3x.net].
+
+HTML5Lib sanitization by {Jacques Distler}[http://golem.ph.utexas.edu/~distler].
+
+== License
+
+MIT License, except for lib/html5lib_sanitize.rb which is under the
+Ruby license and copyright to Jacques Distler.
@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the xss_terminate plugin.'
+Rake::TestTask.new(:test) do |t|
+ t.libs << 'lib'
+ t.pattern = 'test/**/*_test.rb'
+ t.verbose = true
+end
+
+desc 'Generate documentation for the xss_terminate plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+ rdoc.rdoc_dir = 'rdoc'
+ rdoc.title = 'xss_terminate'
+ rdoc.options << '--line-numbers' << '--inline-source'
+ rdoc.rdoc_files.include('README')
+ rdoc.rdoc_files.include('lib/**/*.rb')
+end
@@ -0,0 +1,2 @@
+require 'xss_terminate'
+ActiveRecord::Base.send(:include, XssTerminate)
@@ -0,0 +1 @@
+# Install hook code here
Oops, something went wrong.

0 comments on commit 28a980d

Please sign in to comment.