stoolie

stoolie

Content filter to determine the XSS, spam and profanity content of text

Installation

The easiest way to install is with Bundler

 gem 'stoolie'

Stoolie will work on Ruby 1.8.7+, however the development gems (such as rspec) will only work on 1.9.3+.

Configuration

In Rails, create an initializer such as config/initializers/stoolie.rb and add your SmartFilter rule key and API key

 MyApplication::Application.config.stoolie.smart_filter.api_key = 'my api key'
 MyApplication::Application.config.stoolie.smart_filter.rule_key = 'my rule key'

Otherwise, add the keys like so:

 Stoolie.configure do |config|
   config.smart_filter = {rule_key: 'rule-key', api_key: 'api-key'}
 end

Default Filter and SmartFilter Thresholds

Stoolie uses Prevoty's SmartFilter by default, but it's possible to add other clients as long as they implement stoolie's API requirements.

These are the default thresholds.

XSS

• javascript_threshold - 1
• invalid_tags_threshold - 1

Spam

• link_density_threshold - 3
• spam_features_threshold - 2

Blacklisted Phrases

• blacklisted_phrases_threshold - 1

Offensive Phrases

• flagged_phrases_threshold - 6
• profanity_threshold - 3

All thresholds can be configured using the names given above.

 MyApplication.config.stoolie.smart_filter.profanity_threshold = 5

Examples

XSS

 > result = Stoolie::Filter.new.analyze('<script>xss is bad.</script>')
 => #<Stoolie::Result>
 > result.is_insecure?
 => true

Spam

 > result = Stoolie::Filter.new.analyze('http://mylink.com http://anotherlink.com http://yetanotherlink.com')
 => #<Stoolie::Result>
 > result.is_spam?
 => true

Blacklisted Phrases

 > filter = Stoolie::Filter.new
 > result = filter.analyze('some text')
 => #<Stoolie::Result>
 > result.is_blacklisted?
 => false
 > result = filter.analyze('an incredibly racist word')
 => #<Stoolie::Result>
 > result.is_blacklisted?
 => true

Offensive Phrases

 > result = Stoolie::Filter.new.analyze('enough curse words to trip the threshold')
 => #<Stoolie::Result>
 > result.is_offensive?
 => true

Extending stoolie

If you want to add your own filter client, create one in lib/stoolie/clients/ and make sure it meets the API requirements:

Instance Attributes

• input
• output

Implement public analyze instance method

• Should accept a string argument
• Should return a Stoolie::Result object, which takes the client instance as its argument

 return @result = Stoolie::Result.new(self)

Implement these public boolean instance methods

• is_insecure?
• is_spam?
• is_blacklisted?
• is_offensive?

To use your new client instead of SmartFilter, you can set it in your configuration:

 MyApplication::Application.config.client = MyFilterClient

Or on the fly

 filter = Stoolie::Filter.new(MyFilterClient)

Contributing to stoolie

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
• Fork the project.
• Start a feature/bugfix branch.
• Commit and push until you are happy with your contribution.
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright

Copyright (c) 2014 Aaron Wallis. See LICENSE.txt for further details.