vulndbhq 0.0.1.beta → 0.1.0

data/.rspec

@@ -1,2 +1,3 @@
 --color
 --order random
+--format documentation

data/.travis.yml

@@ -2,6 +2,9 @@ language: ruby
 matrix:
   allow_failures:
     - rvm: ruby-head
+    # There is a problem in fraday 0.8 with jruby + ssl
+    - rvm: jruby-18mode
+    - rvm: jruby-19mode
 rvm:
   - jruby-18mode
   - jruby-19mode
@@ -13,4 +16,4 @@ rvm:
   - ruby-head
 notifications:
   email:
-    - daniel@securityroots.com
+    - daniel@securityroots.com

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in vulndbhq.gemspec
 gemspec
+
+gem 'faraday', :github => 'technoweenie/faraday'

data/README.md

@@ -7,13 +7,6 @@ This gem provides a Ruby wrapper to the VulnDB HQ API (http://vulndbhq.com).
 
 ## Installation
 
-DANGER, WILL ROBINSON!
-DANGER, WILL ROBINSON!
-DANGER, WILL ROBINSON!
-THIS GEM IS IN EARLY BETA STAGE. EVERYTHING CAN CHANGE AT ANY POINT!!
-
-THIS GEM USES API v2 WHICH WILL BE AVAILABLE SOON
-
 Add this line to your application's Gemfile:
 
     gem 'vulndbhq'
@@ -40,11 +33,21 @@ client.user = 'your@email.com'
 client.password = 'password'
 ```
 
+Or provide configuration in line:
+
+```ruby
+client = VulnDBHQ::Client.new(host: 'https://your.vulndbhq.com', user: 'your@email.com', password: 'password')
+```
+
 ## Usage examples
 
-Return the first PrivatePage:
+Return the all PrivatePage:
+
+    client.private_pages
+
+Return private pages containing `XSS`
 
-    VulnDBHQ.private_pages
+    client.private_pages(q: 'XSS')
 
 Get a PrivatePage by id:
 
@@ -55,6 +58,15 @@ puts private_page.name
 puts private_page.content
 ```
 
+Return all the PublicPages:
+
+    client.public_pages
+
+
+See the [VulnDB HQ API docs][api] for the full list of available methods.
+
+[api]: http://support.securityroots.com/vulndbhq_api_v2.html
+
 ## Contributing
 
 1. Fork it
@@ -62,3 +74,18 @@ puts private_page.content
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+
+## Copyright
+
+Copyright (c) 2012 Daniel Martin, Security Roots Ltd.
+See [LICENSE][license] for details.
+
+[license]: https://github.com/securityroots/vulndbhq/blob/master/LICENSE
+
+## Acknowledgements
+
+This gem uses the [Faraday][faraday] gem for the HTTP layer and is inspired by the [Twitter][twitter] gem architecture.
+
+[faraday]: http://rubygems.org/gems/faraday
+[twitter]: http://rubygems.org/gems/twitter

data/lib/vulndbhq/base.rb

@@ -1,6 +1,10 @@
 require 'vulndbhq/identity_map'
 
 module VulnDBHQ
+
+  # Provides some common facilities for all VulnDBHQ objects including the
+  # ability to store attributes and to use an identity map to prevent
+  # re-loading the same object multiple times.
   class Base
     attr_reader :attrs
     alias to_hash attrs

data/lib/vulndbhq/client.rb

@@ -4,8 +4,11 @@ require 'multi_json'
 require 'vulndbhq/base'
 require 'vulndbhq/configurable'
 require 'vulndbhq/default'
+require 'vulndbhq/error'
 require 'vulndbhq/private_page'
+require 'vulndbhq/public_page'
 require 'vulndbhq/response/parse_json'
+require 'vulndbhq/response/raise_client_error'
 require 'vulndbhq/version'
 
 module VulnDBHQ
@@ -22,10 +25,13 @@ module VulnDBHQ
     # @return [VulnDBHQ::Client]
     def initialize(options={})
       VulnDBHQ::Configurable.keys.each do |key|
-        instance_variable_set("@#{key}", options[key] || VulnDBHQ.options[key])
+        instance_variable_set(:"@#{key}", options[key] || VulnDBHQ.instance_variable_get(:"@#{key}"))
       end
     end
 
+
+    # ************************************************************* PrivatePage
+
     # Returns a private page
     #
     # @see http://support.securityroots.com/vulndbhq_api_v2.html#model-private-page
@@ -54,9 +60,46 @@ module VulnDBHQ
     # VulnDBHQ.private_pages
     def private_pages(options={})
       response = get("/api/private_pages", options)
-      # collection_from_array(response[:body], VulnDBHQ::PrivatePage)
+      collection_from_array(response[:body], VulnDBHQ::PrivatePage)
     end
 
+
+    # ************************************************************** PublicPage
+
+    # Returns a public page
+    #
+    # @see http://support.securityroots.com/vulndbhq_api_v2.html#model-public-page
+
+    # @authentication_required Yes
+    # @raise [VulnDBHQ::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+    # @return [VulnDBHQ::PublicPage] The requested messages.
+    # @param id [Integer] A VulnDB HQ private page ID.
+    # @param options [Hash] A customizable set of options.
+    # @example Return the public page with the id 87
+    # VulnDBHQ.public_page(87)
+    def public_page(id, options={})
+      response = get("/api/public_pages/#{id}", options)
+      VulnDBHQ::PublicPage.from_response(response)
+    end
+
+    # Returns the collection of VulnDBHQ::PublicPage available at the moment
+    #
+    # @see http://support.securityroots.com/vulndbhq_api_v2.html#model-public-page
+    # @authentication_required Yes
+    # @raise [VulnDBHQ::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+    # @return [Array<VulnDBHQ::PublicPage>] PrivatePages in the account associated with this user.
+    # @param options [Hash] A customizable set of options.
+    # @option options [nil] no options are supported yet.
+    # @example Return the public pages available in the system
+    # VulnDBHQ.public_pages
+    def public_pages(options={})
+      response = get("/api/public_pages", options)
+      collection_from_array(response[:body], VulnDBHQ::PublicPage)
+    end
+
+
+    # ********************************************************* Support methods
+
     # Perform an HTTP GET request
     def get(path, params={}, options={})
       request(:get, path, params, options)

data/lib/vulndbhq/configurable.rb

@@ -2,12 +2,6 @@ module VulnDBHQ
   # Defines constants and methods related to configuration
   module Configurable
 
-    # Convenience method to allow configuration options to be set in a block
-    def configure
-      yield self
-      self
-    end
-
     # An array of valid keys in the options hash when configuring a {VulnDBHQ::Client}
     CONFIG_KEYS = [
       :connection_options,
@@ -25,5 +19,28 @@ module VulnDBHQ
     def self.keys
       @keys ||= CONFIG_KEYS + AUTH_KEYS
     end
+
+    # Convenience method to allow configuration options to be set in a block
+    def configure
+      yield self
+      self
+    end
+
+    def cache_key
+      options.hash
+    end
+
+    def reset!
+      VulnDBHQ::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", VulnDBHQ::Default.options[key])
+      end
+      self
+    end
+    alias setup reset!
+
+    private
+    def options
+      Hash[VulnDBHQ::Configurable.keys.map{|key| [key, instance_variable_get(:"@#{key}")]}]
+    end
   end
 end

data/lib/vulndbhq/default.rb

@@ -26,6 +26,7 @@ module VulnDBHQ
       @middleware ||= Faraday::Builder.new(
         &Proc.new do |builder|
           builder.use Faraday::Request::UrlEncoded # Convert request params as "www-form-urlencoded"
+          builder.use VulnDBHQ::Response::RaiseClientError # Handle 4xx server responses
           builder.use VulnDBHQ::Response::ParseJson # Parse JSON response bodies using MultiJson
           builder.adapter Faraday.default_adapter # Set Faraday's HTTP adapter
         end

data/lib/vulndbhq/error/base.rb

@@ -0,0 +1,36 @@
+module VulnDBHQ
+  module Error
+
+    # Custom error class for rescuing from all VulnDBHQ errors
+    class Base < StandardError
+
+      attr_reader :wrapped_exception
+
+      def self.errors
+        @errors ||= Hash[descendants.map{|klass| [klass.const_get(:HTTP_STATUS_CODE), klass]}]
+      end
+
+      def self.descendants
+        ObjectSpace.each_object(::Class).select{|klass| klass < self}
+      end
+
+      # Initializes a new Error object
+      #
+      # @param exception [Exception, String]
+      # @return [VulnDBHQ::Error]
+      def initialize(exception=$!)
+        if exception.respond_to?(:backtrace)
+          super(exception.message)
+          @wrapped_exception = exception
+        else
+          super(exception.to_s)
+        end
+      end
+
+      def backtrace
+        @wrapped_exception ? @wrapped_exception.backtrace : super
+      end
+    end
+
+  end
+end

data/lib/vulndbhq/error/client_error.rb

@@ -0,0 +1,26 @@
+module VulnDBHQ
+  module Error
+    # Raised when VulnDBHQ returns a 4xx HTTP status code or there's an error in Faraday
+    class ClientError < Base
+
+      # Create a new error from an HTTP environment
+      #
+      # @param body [Hash]
+      # @return [VulnDBHQ::Error]
+      def self.from_response_body(body)
+        new(parse_error(body))
+      end
+
+      private
+
+      def self.parse_error(body)
+        if body.nil?
+          ''
+        elsif body[:message]
+          body[:message]
+        end
+      end
+
+    end
+  end
+end

data/lib/vulndbhq/error/failed_dependency.rb

@@ -0,0 +1,8 @@
+module VulnDBHQ
+  module Error
+    # Raised when VulnDBHQ returns the HTTP status code 424
+    class FailedDependency < ClientError
+      HTTP_STATUS_CODE = 424
+    end
+  end
+end

data/lib/vulndbhq/error/not_found.rb

@@ -0,0 +1,8 @@
+module VulnDBHQ
+  module Error
+    # Raised when VulnDBHQ returns the HTTP status code 404
+    class NotFound < ClientError
+      HTTP_STATUS_CODE = 404
+    end
+  end
+end

data/lib/vulndbhq/error/unauthorized.rb

@@ -0,0 +1,8 @@
+module VulnDBHQ
+  module Error
+    # Raised when VulnDBHQ returns the HTTP status code 401
+    class Unauthorized < ClientError
+      HTTP_STATUS_CODE = 401
+    end
+  end
+end

data/lib/vulndbhq/error.rb

@@ -0,0 +1,5 @@
+require 'vulndbhq/error/base'
+require 'vulndbhq/error/client_error'
+require 'vulndbhq/error/failed_dependency'
+require 'vulndbhq/error/not_found'
+require 'vulndbhq/error/unauthorized'

data/lib/vulndbhq/public_page.rb

@@ -0,0 +1,5 @@
+module VulnDBHQ
+  class PublicPage < Base
+    attr_reader :name, :content
+  end
+end

data/lib/vulndbhq/response/raise_client_error.rb

@@ -0,0 +1,13 @@
+module VulnDBHQ
+  module Response
+    class RaiseClientError < Faraday::Response::Middleware
+
+      def on_complete(env)
+        status_code = env[:status].to_i
+        error_class = VulnDBHQ::Error::ClientError.errors[status_code]
+        raise error_class.from_response_body(env[:body]) if error_class
+      end
+
+    end
+  end
+end

data/lib/vulndbhq/version.rb

@@ -1,9 +1,9 @@
 module VulnDBHQ
   class Version #:nodoc:
     MAJOR = 0
-    MINOR = 0
-    TINY = 1
-    PRE = "beta"
+    MINOR = 1
+    TINY = 0
+    PRE = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')
 

data/lib/vulndbhq.rb

@@ -6,7 +6,11 @@ module VulnDBHQ
     include VulnDBHQ::Configurable
 
     def client
-      VulnDBHQ::Client.new(options)
+      if @client && @client.cache_key == options.hash
+        @client
+      else
+        @client = VulnDBHQ::Client.new(options)
+      end
     end
 
     # Delegate to a VulnDBHQ::Client
@@ -14,21 +18,11 @@ module VulnDBHQ
       self.client.respond_to?(method, include_private) || super
     end
 
-    def options
-      @options = {}
-      VulnDBHQ::Configurable.keys.each do |key|
-        @options[key] = instance_variable_get("@#{key}")
-      end
-      @options
-    end
-
-    def reset!
-      VulnDBHQ::Configurable.keys.each do |key|
-        instance_variable_set("@#{key}", VulnDBHQ::Default.options[key])
-      end
-      self
+    private
+    def method_missing(method, *args, &block)
+      return super unless self.client.respond_to?(method)
+      self.client.send(method, *args, &block)
     end
-    alias setup reset!
 
   end
 end

data/spec/faraday_spec.rb

@@ -1,3 +1,5 @@
+require 'spec_helper'
+
 describe 'Faraday response' do
 
   context "for valid object" do
@@ -17,9 +19,4 @@ describe 'Faraday response' do
       response.body[:b].should eq('dos')
     end
   end
-
-  context "for invalid object" do
-    let(:client) { VulnDBHQ::Client.new }
-    pending "handles 404 responses"
-  end
 end

data/spec/vulndbhq/client_spec.rb

@@ -9,5 +9,12 @@ describe VulnDBHQ::Client do
   #     subject.request(:get, "/path", {}, {})
   #   end.should raise_error(VulnDBHQ::Error::ClientError, "Oups")
   # end
-
+  pending "catches MultiJson::DecodeError errrors"
+  # it "catches MultiJson::DecodeError errors" do
+  #   subject.stub!(:connection).and_raise(MultiJson::DecodeError.new("unexpected token", [], "<!DOCTYPE html>"))
+  #   lambda do
+  #     subject.request(:get, "/path")
+  #   end.should raise_error(Twitter::Error::DecodeError, "unexpected token")
+  # end
+  pending "raises an exception if no host endpoint has been provided"
 end

data/spec/vulndbhq/error/client_error_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+
+describe VulnDBHQ::Error::ClientError do
+  before do
+    @client = VulnDBHQ::Client.new(:host => TEST_ENDPOINT)
+  end
+
+  VulnDBHQ::Error::ClientError.errors.each do |status, exception|
+    context "when HTTP status is #{status}" do
+      before do
+        body_message = '{"message":"Client Error"}'
+        stub_get("/api/private_pages/1").
+          to_return(:status => status, :body => body_message)
+      end
+      it "raises #{exception.name}" do
+        lambda do
+          @client.private_page(1)
+        end.should raise_error(exception)
+      end
+    end
+  end
+end

data/spec/vulndbhq/private_page_spec.rb

@@ -7,8 +7,7 @@ describe VulnDBHQ::PrivatePage do
     to_return(:status => 200,
       :body => "{\"content\":\"#[Title]#\\r\\nThis is my Private Page\\r\\n\\r\\n\",\"id\":1,\"name\":\"MyPrivatePage\"}",
       :headers => {'Content-Type' => 'application/json; charset=utf-8'})
-    client = VulnDBHQ::client
-    client.host = TEST_ENDPOINT
+    client = VulnDBHQ::Client.new(:host => TEST_ENDPOINT)
 
     private_page = client.private_page(1)
     private_page.should be
@@ -17,4 +16,17 @@ describe VulnDBHQ::PrivatePage do
     private_page.content.should eq("#[Title]#\r\nThis is my Private Page\r\n\r\n")
   end
 
+  it "loads a collection of PrivatePages" do
+    stub_get('/api/private_pages').
+    to_return(:status => 200,
+      :body => "[{\"content\":\"#[Title]#\\r\\nThis is my Private Page\\r\\n\\r\\n\",\"id\":1,\"name\":\"MyPrivatePage1\"}," +
+                  "{\"content\":\"#[Title]#\\r\\nThis is another Private Page\\r\\n\\r\\n\",\"id\":2,\"name\":\"MyPrivatePage2\"}]",
+      :headers => {'Content-Type' => 'application/json; charset=utf-8'})
+    client = VulnDBHQ::Client.new(:host => TEST_ENDPOINT)
+
+    collection = client.private_pages
+    collection.should be
+    collection.length.should eq(2)
+    collection.last.name.should eq('MyPrivatePage2')
+  end
 end

data/spec/vulndbhq/public_page_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe VulnDBHQ::PublicPage do
+
+  it "loads :name and :content from the server's JSON body" do
+    stub_get('/api/public_pages/1').
+    to_return(:status => 200,
+      :body => "{\"content\":\"#[Title]#\\r\\nThis is my Public Page\\r\\n\\r\\n\",\"id\":1,\"name\":\"MyPublicPage\"}",
+      :headers => {'Content-Type' => 'application/json; charset=utf-8'})
+    client = VulnDBHQ::Client.new(:host => TEST_ENDPOINT)
+
+    public_page = client.public_page(1)
+    public_page.should be
+    public_page.should be_a(VulnDBHQ::PublicPage)
+    public_page.name.should eq('MyPublicPage')
+    public_page.content.should eq("#[Title]#\r\nThis is my Public Page\r\n\r\n")
+  end
+
+  it "loads a collection of PublicPages" do
+    stub_get('/api/public_pages').
+    to_return(:status => 200,
+      :body => "[{\"content\":\"#[Title]#\\r\\nThis is my Public Page\\r\\n\\r\\n\",\"id\":1,\"name\":\"MyPublicPage1\"}," +
+                  "{\"content\":\"#[Title]#\\r\\nThis is another Public Page\\r\\n\\r\\n\",\"id\":2,\"name\":\"MyPublicPage2\"}]",
+      :headers => {'Content-Type' => 'application/json; charset=utf-8'})
+    client = VulnDBHQ::Client.new(:host => TEST_ENDPOINT)
+
+    collection = client.public_pages
+    collection.should be
+    collection.length.should eq(2)
+    collection.last.name.should eq('MyPublicPage2')
+  end
+end

data/spec/vulndbhq_spec.rb

@@ -1,6 +1,9 @@
 require 'spec_helper'
 
 describe VulnDBHQ do
+  after do
+    VulnDBHQ.reset!
+  end
 
   describe '.respond_to?' do
     it "delegates to VulnDBHQ::Client" do
@@ -15,6 +18,21 @@ describe VulnDBHQ do
     it "returns a VulnDBHQ::Client" do
       VulnDBHQ.client.should be_a VulnDBHQ::Client
     end
+    context "when the options don't change" do
+      it "caches the client" do
+        VulnDBHQ.client.should eq VulnDBHQ.client
+      end
+    end
+    context "when the options change" do
+      it "busts the cache" do
+        client1 = VulnDBHQ.client
+        VulnDBHQ.configure do |config|
+          config.host = TEST_ENDPOINT
+        end
+        client2 = VulnDBHQ.client
+        client1.should_not eq client2
+      end
+    end
   end
 
   describe ".configure" do
@@ -23,7 +41,7 @@ describe VulnDBHQ do
         VulnDBHQ.configure do |config|
           config.send("#{key}=", key)
         end
-        VulnDBHQ.instance_variable_get("@#{key}").should eq key
+        VulnDBHQ.instance_variable_get(:"@#{key}").should eq key
       end
     end
   end

data/vulndbhq.gemspec

@@ -15,6 +15,8 @@ Gem::Specification.new do |gem|
   gem.require_paths = ['lib']
   gem.version       = VulnDBHQ::Version
 
+  # gem.add_runtime_dependency 'faraday', '~> 0.8'
+  # see https://github.com/technoweenie/faraday/commit/b0d9a144596e96861a18d68f2418b7d74e7b791d
   gem.add_runtime_dependency 'faraday', '~> 0.8'
   gem.add_runtime_dependency 'multi_json', '~> 1.3'
 

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: vulndbhq
 version: !ruby/object:Gem::Version
-  version: 0.0.1.beta
-  prerelease: 6
+  version: 0.1.0
+  prerelease: 
 platform: ruby
 authors:
 - Daniel Martin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-15 00:00:00.000000000 Z
+date: 2012-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -110,16 +110,26 @@ files:
 - lib/vulndbhq/client.rb
 - lib/vulndbhq/configurable.rb
 - lib/vulndbhq/default.rb
+- lib/vulndbhq/error.rb
+- lib/vulndbhq/error/base.rb
+- lib/vulndbhq/error/client_error.rb
+- lib/vulndbhq/error/failed_dependency.rb
+- lib/vulndbhq/error/not_found.rb
+- lib/vulndbhq/error/unauthorized.rb
 - lib/vulndbhq/identity_map.rb
 - lib/vulndbhq/private_page.rb
+- lib/vulndbhq/public_page.rb
 - lib/vulndbhq/response/parse_json.rb
+- lib/vulndbhq/response/raise_client_error.rb
 - lib/vulndbhq/version.rb
 - spec/faraday_spec.rb
 - spec/spec_helper.rb
 - spec/support/webmock.rb
 - spec/vulndbhq/base_spec.rb
 - spec/vulndbhq/client_spec.rb
+- spec/vulndbhq/error/client_error_spec.rb
 - spec/vulndbhq/private_page_spec.rb
+- spec/vulndbhq/public_page_spec.rb
 - spec/vulndbhq_spec.rb
 - vulndbhq.gemspec
 homepage: http://vulndbhq.com
@@ -136,13 +146,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4202230674895239362
+      hash: -1225293818451848289
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
+      segments:
+      - 0
+      hash: -1225293818451848289
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -155,5 +168,7 @@ test_files:
 - spec/support/webmock.rb
 - spec/vulndbhq/base_spec.rb
 - spec/vulndbhq/client_spec.rb
+- spec/vulndbhq/error/client_error_spec.rb
 - spec/vulndbhq/private_page_spec.rb
+- spec/vulndbhq/public_page_spec.rb
 - spec/vulndbhq_spec.rb