defensio 0.9.0

data/.gitignore

@@ -0,0 +1,2 @@
+pkg
+.DS_Store

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Websense Inc.
+
+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.

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rake'
+require 'rake/testtask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "defensio"
+    gemspec.summary = "Official Ruby library for Defensio 2.0"
+    gemspec.description = "Official Ruby library for Defensio 2.0"
+    gemspec.email = "support@defensio.com"
+    gemspec.homepage = "http://github.com/defensio/defensio-ruby"
+    gemspec.authors = ["Carl Mercier"]
+    gemspec.add_dependency('patron', '>= 0.4.4')
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler -s http://gemcutter.org"
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+ 
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+0.9.0

data/lib/defensio.rb

@@ -0,0 +1,173 @@
+#
+#  Defensio-Ruby version 0.1
+#  Written by the Defensio team at Websense, Inc.
+#
+#  Make sure to install the necessary gems by running the following commands:
+#  $ sudo gem install patron -v 0.4.4
+#  On Linux, you'll also need to install the libcurl development package. On Ubuntu, simply do:
+#  $ sudo apt-get install libcurl4-openssl-dev
+#
+
+require 'rubygems'
+require 'patron'
+require 'uri'
+
+class Defensio
+  # You shouldn't modify these values unless you really know what you are doing. And then again...
+  API_VERSION   = 2.0
+  API_HOST      = "http://api.defensio.com"
+
+  # You should't modify anything below this line.
+  LIB_VERSION   = "0.9"
+  ROOT_NODE     = "defensio-result"
+  FORMAT        = :yaml
+  USER_AGENT    = "Defensio-Ruby #{LIB_VERSION}"
+  CLIENT        = "Defensio-Ruby | #{LIB_VERSION} | Carl Mercier | cmercier@websense.com"
+  KEEP_ALIVE    = false
+  
+  attr_reader :http_session, :client
+  
+  def initialize(api_key, client = CLIENT)
+    @client = client
+    @api_key = api_key
+  end
+
+  # Get information about the api key
+  def get_user
+    call :get, api_url
+  end
+  
+  # Create and analyze a new document
+  # @param [Hash] data The parameters to be sent to Defensio. Keys can either be Strings or Symbols
+  # @return [Array] An array containing 2 values: the HTTP status code & a Hash with the values returned by Defensio
+  def post_document(data)
+    data = { :client => @client }.merge(data)
+    call :post, api_url("documents"), data
+  end
+  
+  # Get the status of an existing document
+  # @param [String] signature The signature of the document to retrieve
+  # @return [Array] An array containing 2 values: the HTTP status code & a Hash with the values returned by Defensio
+  def get_document(signature)
+    call :get, api_url("documents", signature)
+  end
+  
+  # Modify the properties of an existing document
+  # @param [String] signature The signature of the document to modify
+  # @param [Hash] data The parameters to be sent to Defensio. Keys can either be Strings or Symbols
+  # @return [Array] An array containing 2 values: the HTTP status code & a Hash with the values returned by Defensio
+  def put_document(signature, data)
+    call :put, api_url("documents", signature), data
+  end
+  
+  # Get basic statistics for the current user
+  # @return [Array] An array containing 2 values: the HTTP status code & a Hash with the values returned by Defensio
+  def get_basic_stats
+    call :get, api_url("basic-stats")
+  end
+
+  # Get more exhaustive statistics for the current user
+  # @param [Hash] data The parameters to be sent to Defensio. Keys can either be Strings or Symbols
+  # @return [Array] An array containing 2 values: the HTTP status code & a Hash with the values returned by Defensio
+  def get_extended_stats(data)
+    result = call(:get, api_url("extended-stats"), data)
+    0.upto(result[1]["data"].size - 1) do |i|
+      result[1]["data"][i]["date"] = Date.parse(result[1]["data"][i]["date"])
+    end
+      
+    result
+  end
+
+  # Filter a set of values based on a pre-defined dictionary
+  def post_profanity_filter(data)
+    call :post, api_url("profanity-filter"), data
+  end
+  
+  # Takes the request object (Rails, Sinatra, Merb) of an async request callback and returns a hash
+  # containing the status of the document being analyzed.
+  # @param [ActionController::Request, Sinatra::Request, String] request The request object created after Defensio POSTed to your site, or a string representation of the POST data.
+  # @return [Hash] Status of the document
+  def handle_post_document_async_callback(request)
+    if request.is_a?(String)
+      data = request
+    elsif request.respond_to?(:body) && request.body.is_a?(StringIO)
+      data = request.body.read
+    else
+      raise ArgumentError, "Unknown request type: #{request.class}"
+    end
+
+    parse_body(data)
+  end
+  
+  # See handle_post_document_async_callback
+  def self.handle_post_document_async_callback(request)
+    Defensio.new(nil).handle_post_document_async_callback(request)
+  end
+
+  protected
+    def api_url(action = nil, id = nil)
+      path = "#{API_HOST}/#{API_VERSION}/users/#{@api_key}"
+      path += "/#{action}" if action
+      path += "/#{id}" if id
+      path += ".#{FORMAT}"
+    end
+  
+    def http_session
+      return @http_session if KEEP_ALIVE && @http_session
+      @http_session = Patron::Session.new
+      @http_session.timeout = 20
+      @http_session.headers['User-Agent'] = USER_AGENT
+      @http_session.headers['Content-Type'] = "text/#{FORMAT}"
+      @http_session
+    end
+
+    def http_session=(session)
+      @http_session = session
+    end
+    
+    def call(method, url, data = nil)
+      data = hash_to_query_string(data) if data.is_a?(Hash)
+      url = url + "?#{data}" unless data.nil? || data.empty?
+
+      response = case method
+      when :get
+        http_session.get(url)
+      when :delete
+        http_session.delete(url)
+      when :post
+        http_session.post(url, {})
+      when :put
+        http_session.put(url, {})
+      else
+        raise(ArgumentError, "Invalid HTTP method: #{method}")
+      end
+      
+      http_session = nil unless KEEP_ALIVE
+      
+      [response.status, parse_body(response.body)]
+    end
+
+    def parse_body(str)
+      if FORMAT == :yaml
+        return YAML::load(str)[ROOT_NODE]
+      else
+        raise(NotImplementedError, "This library doesn't support this format: #{FORMAT}")
+      end
+    end
+
+    def hash_to_query_string(data)
+      return nil unless data.is_a?(Hash)
+      out = ""
+      sort_hash_by_key(data).each do |item|
+        k, v = item[0], item[1]
+        out += "&" unless out.empty?
+        k = k.to_s.gsub(/_/, "-") if k.is_a?(Symbol)
+        out += "#{k}=#{URI.escape(v.to_s)}"
+      end
+      out
+    end
+
+    def sort_hash_by_key(hash)
+      hash.keys.sort_by {|s| s.to_s}.map {|key| [key, hash[key]] }
+    end
+end

data/test/defensio_test.rb

@@ -0,0 +1,288 @@
+require File.dirname(__FILE__) + "/../lib/defensio"
+DEFENSIO_ENV = "test"
+require 'test/unit'
+require 'mocha'
+require 'redgreen'
+require 'ostruct'
+
+class DefensioTest < Test::Unit::TestCase
+  MOCK_RESPONSE = true
+  API_KEY       = "1234567890"
+  OWNER_URL     = "http://example.org"
+  SIGNATURE     = "abcdefghijklmnop"
+
+  API_VERSION = 2.0
+  API_HOST    = "http://api.defensio.com"
+  FORMAT      = :yaml
+  HEADERS     = {"User-Agent" => "Defensio-Ruby #{Defensio::LIB_VERSION}", "Content-Type" => "text/yaml"}
+
+  # API METHOD TESTS -- Useful to learn how to use the library
+  def test_get_user
+    if MOCK_RESPONSE
+      Patron::Session.any_instance.expects(:get).with("#{API_HOST}/#{API_VERSION}/users/#{API_KEY}.#{FORMAT}").once.returns(FakePatronResponse.new(200, user_body))
+    end
+    
+    status, body = @d.get_user
+    assert body.is_a?(Hash)
+    assert_equal 200, status
+    assert_equal "success", body["status"]
+  end
+
+  def test_post_document
+    if MOCK_RESPONSE
+      query = "client=Defensio-Ruby%20%7C%20#{Defensio::LIB_VERSION}%20%7C%20Carl%20Mercier%20%7C%20cmercier@websense.com&content=We%20sell%20cheap%20Viagra!%20[spam,0.95]&platform=my_awesome_app&type=test"
+      Patron::Session.any_instance.expects(:post).with("#{API_HOST}/#{API_VERSION}/users/#{API_KEY}/documents.#{FORMAT}?#{query}", {}).once.returns(FakePatronResponse.new(200, document_body(SIGNATURE)))
+    end
+
+    data = { :content => "We sell cheap Viagra! [spam,0.95]", :platform => "my_awesome_app", :type => "test" }
+    status, body = @d.post_document(data)
+    assert body.is_a?(Hash)
+    assert_equal 200, status
+    assert_equal "success", body["status"]
+    assert body["signature"].is_a?(String)
+  end
+  
+  def test_get_document
+    if MOCK_RESPONSE
+      Patron::Session.any_instance.expects(:get).with("#{API_HOST}/#{API_VERSION}/users/#{API_KEY}/documents/#{SIGNATURE}.#{FORMAT}").once.returns(FakePatronResponse.new(200, document_body(SIGNATURE)))
+    end
+    
+    status, body = @d.get_document(SIGNATURE)
+    assert body.is_a?(Hash)
+    assert_equal 200, status
+    assert_equal "success", body["status"]
+    assert_equal SIGNATURE, body["signature"]
+  end
+
+  def test_put_document
+    if MOCK_RESPONSE
+      query = "allow=true"
+      Patron::Session.any_instance.expects(:put).with("#{API_HOST}/#{API_VERSION}/users/#{API_KEY}/documents/#{SIGNATURE}.#{FORMAT}?#{query}", {}).once.returns(FakePatronResponse.new(200, document_body_allowed(SIGNATURE)))
+    end
+
+    status, body = @d.put_document(SIGNATURE, :allow => true)
+    assert body.is_a?(Hash)
+    assert_equal 200, status
+    assert_equal "success", body["status"]
+    assert_equal SIGNATURE, body["signature"]
+    assert_equal true, body["allow"]
+  end
+  
+  def test_get_basic_stats
+    if MOCK_RESPONSE
+      Patron::Session.any_instance.expects(:get).with("#{API_HOST}/#{API_VERSION}/users/#{API_KEY}/basic-stats.#{FORMAT}").once.returns(FakePatronResponse.new(200, basic_stats_body))
+    end
+    
+    status, body = @d.get_basic_stats
+    assert body.is_a?(Hash)
+    assert_equal 200, status
+    assert_equal "success", body["status"]
+    assert body["unwanted"]["total"].is_a?(Integer)
+  end
+
+  def test_get_extended_stats
+    if MOCK_RESPONSE
+      query="from=2009-09-01&to=2009-09-03"
+      Patron::Session.any_instance.expects(:get).with("#{API_HOST}/#{API_VERSION}/users/#{API_KEY}/extended-stats.#{FORMAT}?#{query}").once.returns(FakePatronResponse.new(200, extended_stats_body))
+    end
+    
+    status, body = @d.get_extended_stats(:from => Date.new(2009, 9, 1), :to => Date.new(2009, 9, 3))
+    assert body.is_a?(Hash)
+    assert_equal 200, status
+    assert_equal "success", body["status"]
+    assert body["data"].is_a?(Array)
+    assert body["data"][0]["date"].is_a?(Date)
+  end
+  
+  def test_post_profanity_filter
+    if MOCK_RESPONSE
+      query="OtherField=hello%20again&field1=hello%20world"
+      Patron::Session.any_instance.expects(:post).with("#{API_HOST}/#{API_VERSION}/users/#{API_KEY}/profanity-filter.#{FORMAT}?#{query}", {}).once.returns(FakePatronResponse.new(200, profanity_filter_body))
+    end
+    
+    status, body = @d.post_profanity_filter("field1"=>"hello world", "OtherField"=>"hello again")
+    assert body.is_a?(Hash)
+    assert_equal 200, status
+    assert_equal "success", body["status"]
+    assert body["filtered"].is_a?(Hash)
+    assert body["filtered"].keys.include?("field1")
+    assert body["filtered"].keys.include?("OtherField")
+  end
+  
+  def test_handle_post_document_async_callback__string
+    result = { "api-version"       => API_VERSION, 
+               "status"            => "success", 
+               "message"           => nil, 
+               "signature"         => SIGNATURE,
+               "allow"             => false,
+               "classification"    => "malicious",
+               "spaminess"         => 0.95,
+               "profanity-match"  => true }
+
+    assert_equal result, @d.class.handle_post_document_async_callback(document_body(SIGNATURE))
+    assert_equal result, @d.handle_post_document_async_callback(document_body(SIGNATURE))
+  end
+
+  def test_handle_post_document_async_callback__request_object
+    result = { "api-version"       => API_VERSION, 
+               "status"            => "success", 
+               "message"           => nil, 
+               "signature"         => SIGNATURE,
+               "allow"             => false,
+               "classification"    => "malicious",
+               "spaminess"         => 0.95,
+               "profanity-match"  => true }
+    
+    fake_request_object = OpenStruct.new(:body => StringIO.new(document_body(SIGNATURE)))
+    assert_equal result, @d.class.handle_post_document_async_callback(fake_request_object)
+
+    fake_request_object = OpenStruct.new(:body => StringIO.new(document_body(SIGNATURE)))
+    assert_equal result, @d.handle_post_document_async_callback(fake_request_object)
+  end
+
+  def test_handle_post_document_async_callback__invalid_object_type
+    assert_raise(ArgumentError) { @d.class.handle_post_document_async_callback(nil) }
+    assert_raise(ArgumentError) { @d.handle_post_document_async_callback(nil) }
+  end
+
+  
+  # OTHER TESTS
+  def test_http_session
+    s = @d.send(:http_session)
+    assert s.is_a?(Patron::Session)
+    if @d.class.class_eval("KEEP_ALIVE")
+      assert_equal s, @d.send(:http_session) # make sure sessions are reused when KEEP_ALIVE is true
+    else
+      assert_not_equal s, @d.send(:http_session) # make sure sessions are dropped when KEEP_ALIVE is false
+    end
+    
+    assert_equal HEADERS, s.headers
+  end
+
+  def test_api_url
+    assert_equal "#{API_HOST}/#{API_VERSION}/users/#{API_KEY}.yaml", @d.send(:api_url)
+    assert_equal "#{API_HOST}/#{API_VERSION}/users/#{API_KEY}/documents.yaml", @d.send(:api_url, "documents")
+    assert_equal "#{API_HOST}/#{API_VERSION}/users/#{API_KEY}/documents/abcdefghijklmnop.yaml", @d.send(:api_url, "documents", "abcdefghijklmnop")
+  end
+  
+  def test_hash_to_query_string
+    assert_equal "hello-world=true", @d.send(:hash_to_query_string, {:hello_world => true} )
+    assert_equal "hello-world=this%20has%20spaces%20and%20characters%20($%20?%20&%20%5E%20%C3%A9)%20that%20should%20be%20escaped", 
+      @d.send(:hash_to_query_string, {:hello_world => "this has spaces and characters ($ ? & ^ é) that should be escaped"} )
+    assert_equal "value1=true&value2=true&value3=true", @d.send(:hash_to_query_string, { "value1" => true, "value2" => true, :value3 => true})
+    assert_equal "date=2009-01-01", @d.send(:hash_to_query_string, { "date" => Date.new(2009,1,1) })
+    assert_nil @d.send(:hash_to_query_string, nil)
+  end
+  
+  def test_parse_body
+    parsed = {"hello"=>"world"}
+    assert_equal parsed, @d.send(:parse_body, "---\ndefensio-result:\n  hello: world")
+  end
+
+  # HELPERS AND SETUP
+  def setup
+    @d = Defensio.new(API_KEY)
+  end
+
+  def http_session
+    @d.send(:http_session)
+  end
+  
+  def base_url
+    "#{API_HOST}/#{API_VERSION}"
+  end
+
+  # MOCKING
+  class FakePatronResponse < Struct.new(:status, :body); end
+  
+  def user_body
+    { "defensio-result" => {"api-version" => API_VERSION, "status" => "success", "message" => nil, "owner-url" => OWNER_URL} }.send("to_#{FORMAT}")
+  end
+  
+  def document_body(signature)
+    { "defensio-result" => {
+        "api-version"       => API_VERSION, 
+        "status"            => "success", 
+        "message"           => nil, 
+        "signature"         => signature, 
+        "allow"             => false,
+        "classification"    => "malicious",
+        "spaminess"         => 0.95,
+        "profanity-match"  => true } 
+    }.send("to_#{FORMAT}")
+  end
+
+  def document_body_allowed(signature)
+    { "defensio-result" => {
+        "api-version"       => API_VERSION, 
+        "status"            => "success", 
+        "message"           => nil, 
+        "signature"         => signature, 
+        "allow"             => true,
+        "classification"    => "innocent",
+        "spaminess"         => 0.95,
+        "profanity-match"  => true } 
+    }.send("to_#{FORMAT}")
+  end
+  
+  def basic_stats_body
+    { "defensio-result" => {
+      "api-version"       => API_VERSION, 
+      "status"            => "success", 
+      "message"           => nil, 
+      "recent-accuracy"   => 0.9975,
+      "legitimate"        => { "total" => 100 },
+      "unwanted"          => { "total" => 100, "malicious" => 50, "spam" => 100},
+      "false-positives"   => 1,
+      "false-negatices"   => 2,
+      "learning"          => true,
+      "learning-status"   => "Details about learning mode" }
+    }.send("to_#{FORMAT}")
+  end
+  
+  def extended_stats_body
+    { "defensio-result" => {
+      "api-version"       => API_VERSION, 
+      "status"            => "success", 
+      "message"           => nil,
+      "data" => [ 
+        { "date"            => "2009-09-01",
+          "recent-accuracy" => 0.9975,
+          "legitimate"      => 100,
+          "unwanted"        => 500,
+          "false-positives" => 1,
+          "false-negatives" => 0 }, 
+        {
+          "date"            => "2009-09-02",
+          "recent-accuracy" => 0.9985,
+          "legitimate"      => 50,
+          "unwanted"        => 475,
+          "false-positives" => 0,
+          "false-negatives" => 0 }, 
+        { "date"            => "2009-09-03",
+          "recent-accuracy" => 0.9992,
+          "legitimate"      => 100,
+          "unwanted"        => 500,
+          "false-positives" => 1,
+          "false-negatives" => 0 } 
+      ],
+      "chart-urls" => {
+        "recent-accuracy" => "http://domain.com/chart/123456",
+        "total-unwanted"  => "http://domain.com/chart/abcdef",
+        "total-legitimate" => "http://domain.com/chart/xyzabc" }
+      } 
+    }.send("to_#{FORMAT}")
+  end
+  
+  def profanity_filter_body
+    { "defensio-result" => {
+      "api-version"       => API_VERSION, 
+      "status"            => "success", 
+      "message"           => nil,
+      "filtered" => 
+        { "field1"     => "hello world",
+          "OtherField" => "hello again"  }
+      }
+    }.send("to_#{FORMAT}")
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: defensio
+version: !ruby/object:Gem::Version 
+  version: 0.9.0
+platform: ruby
+authors: 
+- Carl Mercier
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-07 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: patron
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.4.4
+    version: 
+description: Official Ruby library for Defensio 2.0
+email: support@defensio.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README
+files: 
+- .gitignore
+- LICENSE
+- README
+- Rakefile
+- VERSION
+- lib/defensio.rb
+- test/defensio_test.rb
+has_rdoc: true
+homepage: http://github.com/defensio/defensio-ruby
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Official Ruby library for Defensio 2.0
+test_files: 
+- test/defensio_test.rb