controls 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d97c792ec22e7db59c7f591f023942e40b9cf6c
-  data.tar.gz: 59d3fafbcb9633a88a43935c72e90c5d66ea8878
+  metadata.gz: f428c9a710108971da0e6995f4f0ca0032caeed4
+  data.tar.gz: e727ddbd5d77bc6afdfd84ef51a81bc57bc8dfc4
 SHA512:
-  metadata.gz: eee56d732f6779946baa87cc77afeb38587d5abe8ac004cad782da8c5f9d6ee39ce711d932da15cfe1ab51bbb13ac5daa24fecf8edac6e7e6bc1e17c660c594b
-  data.tar.gz: 6e6a7ae9442977487ba0d449a0fc5ecd500360b038c920f4477b1f5e2f15d818eb766dbbe4ab68edc057c947a3cf13884c80d9e9648562bcff69a0fd3fbab1e4
+  metadata.gz: 1455b974d58516093e986277014a653b157ab5f1a0da5d22742b7554a5671074f001ae458ab14cff15cf18ffdc7a5b7c1742c713aea4eb0a41b21bae8466d111
+  data.tar.gz: fd418654c0932982591cd8d717354796194dd376a7214397fb553f348b1d742f5cedd64cddc18237bd6e2eb3dbf280a4c890a05fb36d2901f1c9d18595efb99d

data/README.md

@@ -1,5 +1,5 @@
 # controlsinsight client gem
-The **controls**insight (controls) gem interfaces with [Rapid7's **controls**insight API](http://rapid7.viewdocs.io/controlsinsight.rb).
+The **controls**insight (controls) gem interfaces with [Rapid7's **controls**insight API](http://rapid7.github.io/controlsinsight.rb).
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -15,7 +15,7 @@ Or install it yourself as:
     $ gem install controls
 
 ## Documentation
-* [viewdocs.io API documentation](http://rapid7.viewdocs.io/controlsinsight.rb)
+* [API documentation](http://rapid7.github.io/controlsinsight.rb)
 * [YARD documentation for the Ruby client](http://www.rubydoc.info/github/rapid7/controlsinsight.rb)
 
 ## Basic Resources
@@ -101,4 +101,4 @@ Controls.configuration_trends('configuration-name-here')
 ```
 
 ## License
-This project was created by [Erran Carey (@ipwnstuff)](http://ipwnstuff.github.io) and licensed under [the MIT License](LICENSE.md).
+This project was created by [Erran Carey (@erran)](http://erran.github.io) and licensed under [the MIT License](LICENSE.md).

data/controls.gemspec

@@ -18,9 +18,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = %w[lib]
 
-  spec.add_dependency 'activesupport'
+  spec.add_dependency 'dish'
   spec.add_dependency 'faraday', '< 0.9'
-  spec.add_dependency 'nokogiri'
+  spec.add_dependency 'rack'
 
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'netrc'

data/lib/controls.rb

@@ -3,6 +3,8 @@ require 'controls/default'
 
 # A Ruby client for the **controls**insight API
 module Controls
+  Error = Class.new(StandardError)
+
   class << self
     include Controls::Configurable
 

data/lib/controls/client.rb

@@ -1,6 +1,7 @@
-require 'faraday'
 require 'json'
+require 'faraday'
 require 'nokogiri'
+require 'rack/utils'
 require 'controls/authentication'
 require 'controls/configurable'
 require 'controls/client/assessments'
@@ -88,8 +89,16 @@ module Controls
       headers = connection_options[:headers].merge(headers)
       url = URI.escape(File.join(api_endpoint, path))
       resp = middleware.get(url, params, headers)
+      @_last_request = {
+        response: resp,
+        path: path
+      }
+
+      if !resp.headers['content-type'].eql?("application/json;charset=UTF-8")
+        fail exception('Invalid content-type error')
+      end
 
-      Response.parse(resp.body)
+      Response.parse(resp.body, path)
     rescue Faraday::Error::ConnectionFailed => e
       if e.message =~ /^SSL_connect/
         warn(*SSL_WARNING)
@@ -105,8 +114,16 @@ module Controls
       headers = connection_options[:headers].merge(headers)
       url = URI.escape(File.join(api_endpoint, path))
       resp = middleware.put(url, body, headers, &block)
+      @_last_request = {
+        response: resp,
+        path: path
+      }
 
-      Response.parse(resp.body)
+      if !resp.headers['content-type'].eql?("application/json;charset=UTF-8")
+        fail exception('Invalid content-type error')
+      end
+
+      Response.parse(resp.body, path)
     rescue Faraday::Error::ConnectionFailed => e
       if e.message =~ /^SSL_connect/
         warn(*SSL_WARNING)
@@ -134,11 +151,7 @@ module Controls
     # @param [String] version the API version to collect documentation from
     def references(version = '1.0')
       version = '1.0' unless version =~ /\d.\d/
-
-       web_get "/api/#{version}"
-
-       # [review] - Use Response#generate_ruby
-      @references = Hash[Response.parse(resp.body).sort]
+      web_get "/api/#{version}"
     rescue Faraday::Error::ConnectionFailed => e
       if e.message =~ /^SSL_connect/
         warn(*SSL_WARNING)
@@ -176,8 +189,16 @@ module Controls
       headers = connection_options[:headers].merge(headers)
       url = URI.escape(File.join(web_endpoint, path))
       resp = middleware.get(url, params, headers)
+      @_last_request = {
+        response: resp,
+        path: path
+      }
 
-      Response.parse(resp.body)
+      if !resp.headers['content-type'].eql?("application/json;charset=UTF-8")
+        fail exception('Invalid content-type error')
+      end
+
+      JSON.parse(resp.body)
     rescue Faraday::Error::ConnectionFailed => e
       if e.message =~ /^SSL_connect/
         warn(*SSL_WARNING)
@@ -185,5 +206,19 @@ module Controls
         raise e
       end
     end
+
+    def exception(message = "HTTP Error")
+      last_request = _last_request
+      if last_request
+        message << ": #{last_request[:response].status} #{Rack::Utils::HTTP_STATUS_CODES[last_request[:response].status]} #{last_request[:path]}"
+      else
+        message = 'Unknown error'
+      end
+
+      Controls::Error.new(message)
+    end
+
+    private
+    attr_reader :_last_request
   end
 end

data/lib/controls/default.rb

@@ -65,7 +65,6 @@ module Controls
         @middleware ||= Faraday.new(api_endpoint, connection_options) do |conn|
           conn.adapter Faraday.default_adapter
           conn.response :logger if ENV['CONTROLS_DEBUG']
-          conn.use Controls::Response::RaiseError
         end
       end
 

data/lib/controls/ext/dish/plate.rb

@@ -0,0 +1,46 @@
+module Dish
+  class Plate
+    def method_missing(method, *args, &block)
+      method = method.to_s
+      camel_case_key = method.split('_').map(&:capitalize).join
+      camel_case_key[0] = camel_case_key[0].downcase
+
+      if method.end_with?('?')
+        key = camel_case_key[0..-2]
+        _check_for_presence(key)
+      else
+        value = _get_value(camel_case_key)
+        if value.nil?
+          super(method.to_sym, *args, &block)
+        else
+          value
+        end
+      end
+    end
+
+    def methods()
+      valid_keys = as_hash.keys.map do |key|
+        key.to_s.gsub(/([^A-Z])([A-Z]+)/, '\1_\2').downcase.to_sym
+      end
+
+      valid_keys + super
+    end
+
+    def inspect
+      hash = as_hash
+      keys_to_snake_case = hash.keys.map { |key|
+        [key, key.to_s.gsub(/([^A-Z])([A-Z]+)/, '\1_\2').downcase]
+      }.to_h
+
+      vars = hash.map do |key, value|
+        "#{keys_to_snake_case[key]}: #{_get_value(key)}"
+      end
+
+      "#<#{self.class}: #{vars.join(', ')}>"
+    end
+
+    def to_json(*args)
+      as_hash.to_json(*args)
+    end
+  end
+end

data/lib/controls/objects.rb

@@ -0,0 +1,11 @@
+require 'dish'
+require 'controls/ext/dish/plate'
+require 'controls/objects/assessment'
+require 'controls/objects/asset'
+require 'controls/objects/configuration'
+require 'controls/objects/guidance'
+require 'controls/objects/security_control'
+require 'controls/objects/security_control_coverage'
+require 'controls/objects/threat'
+require 'controls/objects/threat_vector'
+require 'controls/objects/trend'

data/lib/controls/objects/assessment.rb

@@ -0,0 +1,9 @@
+module Controls
+  class Assessment < Dish::Plate
+    coerce :timestamp, ->(value) { Time.at(value / 1000) if value }
+
+    def to_s
+      id.to_s
+    end
+  end
+end

data/lib/controls/objects/asset.rb

@@ -0,0 +1,36 @@
+require 'controls/objects/security_control_finding'
+
+module Controls
+  class Asset < Dish::Plate
+    coerce :discoveredAt, ->(value) { Time.at(value / 1000) if value }
+    coerce :securityControlFindings, Controls::SecurityControlFinding
+
+    def to_s
+      %(#{host_name} (#{ipaddress}) - #{operating_system})
+    end
+  end
+
+  class AssetCollection < Dish::Plate
+    coerce :resources, Asset
+
+    def map(*args, &block)
+      resources.map(*args, &block)
+    end
+
+    def first
+      resources.first
+    end
+
+    def last
+      resources.last
+    end
+
+    def [](index)
+      resources[index]
+    end
+
+    def to_s
+      resources.sort_by(&:ipaddress).map(&:to_s).join("\n")
+    end
+  end
+end

data/lib/controls/objects/configuration.rb

@@ -0,0 +1,9 @@
+module Controls
+  class Configuration < Dish::Plate
+    coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+
+    def to_s
+      title
+    end
+  end
+end

data/lib/controls/objects/configuration_finding.rb

@@ -0,0 +1,9 @@
+module Controls
+  class ConfigurationFinding < Dish::Plate
+    coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+
+    def to_s
+      "#{state}: #{reason.strip}"
+    end
+  end
+end

data/lib/controls/objects/guidance.rb

@@ -0,0 +1,17 @@
+module Controls
+  Guidance = Class.new(Dish::Plate)
+  Guidance::Reference = Class.new(Dish::Plate)
+  Guidance::Section = Class.new(Dish::Plate)
+
+  class Guidance
+    coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+    coerce :references, Reference
+    coerce :sections, Section
+
+    def to_s
+      title
+    end
+  end
+
+  PrioritizedGuidance = Class.new(Guidance)
+end

data/lib/controls/objects/security_control.rb

@@ -0,0 +1,7 @@
+module Controls
+  class SecurityControl < Dish::Plate
+    def to_s
+      name
+    end
+  end
+end

data/lib/controls/objects/security_control_coverage.rb

@@ -0,0 +1,9 @@
+module Controls
+  class SecurityControlCoverage < Dish::Plate
+    coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+
+    def to_s
+      title
+    end
+  end
+end

data/lib/controls/objects/security_control_finding.rb

@@ -0,0 +1,12 @@
+require 'controls/objects/configuration_finding'
+
+module Controls
+  class SecurityControlFinding < Dish::Plate
+    coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+    coerce :configurationFindings, Controls::ConfigurationFinding
+
+    def to_s
+      "#{security_control_name}: #{configuration_findings.map { |finding| "\n  #{finding}"  }.join}"
+    end
+  end
+end

data/lib/controls/objects/threat.rb

@@ -0,0 +1,9 @@
+module Controls
+  class Threat < Dish::Plate
+    coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+
+    def to_s
+      title
+    end
+  end
+end

data/lib/controls/objects/threat_vector.rb

@@ -0,0 +1,9 @@
+module Controls
+  class ThreatVector < Dish::Plate
+    coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+
+    def to_s
+      title
+    end
+  end
+end

data/lib/controls/objects/trend.rb

@@ -0,0 +1,9 @@
+module Controls
+  class Trend < Dish::Plate
+    coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+
+    def to_s
+      format('%05.2f', grade)
+    end
+  end
+end

data/lib/controls/response.rb

@@ -1,76 +1,32 @@
-require 'active_support/core_ext/string/inflections'
-require 'active_support/core_ext/hash/keys'
-require 'controls/response/raise_error'
+require 'controls/objects'
 
 module Controls
-  # A namespace for response related classes
+  # A module to encapsulate middleware customization
   module Response
-    # @param [String] response the response body as a JSON String provided by
-    #   the ControlsInsight API
-    # @return [Array,Hash] the response after being parsed into an Array or
-    #   Hash
-    def self.parse(response)
-      response = JSON.parse(response)
-    end
+    def self.parse(obj, path = nil)
+      hash_or_array = JSON.parse(obj)
 
-    # @param [Array,Hash] response the Array or Hash to convert into a ruby
-    #  style object
-    def self.generate_ruby(response)
-      if response.is_a? String
-        response = JSON.parse(response)
+      if hash_or_array.is_a?(Hash) && hash_or_array.key?('message') && hash_or_array.key?('documentationUrl')
+        type = Controls::Error
       end
 
-      # TODO: Determine the specific format, or create a new, recursive (w/
-      #       array support) deep method
-      # NOTE: If the ControlsInsight API begins returning more complex JSON
-      #       this conditional must be updated.
-      if response.is_a? Hash
-        response.deep_transform_keys! { |key| key.underscore }
-
-        if response.has_key? 'resources'
-          response['resources'].each do |hash|
-            hash.deep_transform_keys! { |key| key.underscore }
-
-            if hash.has_key? 'security_control_findings'
-              hash['security_control_findings'].each do |subhash|
-                subhash.deep_transform_keys! { |key| key.underscore }
-
-                if subhash.has_key? 'configuration_findings'
-                  subhash['configuration_findings'].each do |subhash_two|
-                    subhash_two.deep_transform_keys! { |key| key.underscore }
-                  end
-                end
-              end
-            end
-          end
+      type ||=
+        case path
+        when %r(^(?:/\d.\d)?/coverage/security_controls)
+          Controls::SecurityControlCoverage
+        when /(configuration|event|guidance|prioritized_guidance|security_control|threat_vector|trend)s?$/
+          Controls.const_get(Regexp.last_match[1].split('_').map(&:capitalize).join)
+        when %r(^(?:/\d.\d)?\/(assessment|configuration|threat|threat_vector)s)
+          Controls.const_get(Regexp.last_match[1].split('_').map(&:capitalize).join)
+        when /((?:applicable|miconfigured|uncovered|undefended)?_?asset)s$/
+          Controls.const_get('AssetCollection')
+        when %r(^/((?:applicable|miconfigured|uncovered|undefended)?_?asset)s/)
+          Controls.const_get('Asset')
+        else
+          Dish::Plate
         end
-      elsif response.is_a? Array
-        response.each do |element|
-          if element.is_a? Hash
-            element.deep_transform_keys! { |key| key.underscore }
-
-            if element.has_key? 'resources'
-              element['resources'].each do |hash|
-                hash.deep_transform_keys! { |key| key.underscore }
-
-                if hash.has_key? 'security_control_findings'
-                  hash['security_control_findings'].each do |subhash|
-                    subhash.deep_transform_keys! { |key| key.underscore }
-
-                    if subhash.has_key? 'configuration_findings'
-                      subhash['configuration_findings'].each do |subhash_two|
-                        subhash_two.deep_transform_keys! { |key| key.underscore }
-                      end
-                    end
-                  end
-                end
-              end
-            end
-          end
-        end
-      end
 
-      response
+      Dish(hash_or_array, type)
     end
   end
 end

data/lib/controls/version.rb

@@ -1,4 +1,4 @@
 module Controls
   # The version of the Controls gem
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: controls
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Erran Carey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-04 00:00:00.000000000 Z
+date: 2014-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: dish
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.9'
 - !ruby/object:Gem::Dependency
-  name: nokogiri
+  name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -175,9 +175,20 @@ files:
 - lib/controls/client/trends.rb
 - lib/controls/configurable.rb
 - lib/controls/default.rb
-- lib/controls/error.rb
+- lib/controls/ext/dish/plate.rb
+- lib/controls/objects.rb
+- lib/controls/objects/assessment.rb
+- lib/controls/objects/asset.rb
+- lib/controls/objects/configuration.rb
+- lib/controls/objects/configuration_finding.rb
+- lib/controls/objects/guidance.rb
+- lib/controls/objects/security_control.rb
+- lib/controls/objects/security_control_coverage.rb
+- lib/controls/objects/security_control_finding.rb
+- lib/controls/objects/threat.rb
+- lib/controls/objects/threat_vector.rb
+- lib/controls/objects/trend.rb
 - lib/controls/response.rb
-- lib/controls/response/raise_error.rb
 - lib/controls/version.rb
 - spec/controls_spec.rb
 - spec/helper.rb

data/lib/controls/error.rb

@@ -1,132 +0,0 @@
-module Controls
-  # A namespace for errors in the Controls module
-  class Error < StandardError
-    # @!attribute [r] error_message
-    #   @return [String] the error message
-    # @!attribute [r] error_status
-    #   @return [Fixnum] the error message
-    # @!attribute [r] error_json
-    #   @return [Hash] the JSON body from the error message
-    attr_reader :error_json
-    attr_reader :error_message
-    attr_reader :error_status
-
-    # @raise [BadRequest,Unauthorized,NotFound,InternalServerError] a subclass
-    #   of {Controls::Error}
-    # @return [nil] if no error was raised
-    def self.from_response(response)
-      error = case response[:status].to_i
-              when 302
-                # TODO: Nexpose/ControlsInsight returns 302 when you either visit a
-                # none existant path (Nexpose) or unauthenticated
-                # (ControlsInsight).
-                Found # if response[:body].empty?
-              when 400 then BadRequest
-              when 401 then Unauthorized
-              when 404 then NotFound
-              when 500 then InternalServerError
-              end
-
-      error.new(response) if error
-    end
-
-    # @return [self] generates an error and passes it to super
-    def initialize(response = nil)
-      @response = response
-      super(generate_error)
-    end
-
-    private
-
-    # @return [String] an error message to be used by {#generate_error}
-    def response_message
-      return @response_message if @response_message
-
-      resp = @response[:response]
-
-      if resp.headers['content-type']
-        resp.headers['content-type'][/(\S+);charset=utf-8/i]
-        html = Regexp.last_match && Regexp.last_match[1].eql?('text/html')
-      end
-
-      @response_message = if html
-        doc = Nokogiri::XML.parse(resp.body)
-
-        if doc.css('title').text.eql? 'ControlsInsight'
-          message = ['message'].zip(doc.css('h1').map(&:text))
-          reason = ['reason'].zip([doc.css('p').map(&:text)])
-          Hash[message + reason]
-        else
-          Hash[doc.css('HR').children.map { |elem| elem.text.split(' ', 2) }]
-        end
-      else
-        if resp.body.empty?
-          @error_json = {}
-        else
-          @error_json = JSON.parse(resp.body)
-          @error_message = @error_json['message']
-          @error_status = @error_json['status'].to_i
-
-          @error_json
-        end
-      end
-    end
-
-    # @return [String] the error message passed to super on {#initialize}
-    def generate_error
-      return unless @response
-
-      message = "#{@response[:method]} ".upcase
-      message << "#{@response[:url].path}"
-
-      if response_message.is_a? Hash
-        message << ": #{response_message['message']}\n" if response_message['message']
-
-        if response_message['reason'].respond_to?(:join)
-          message << response_message['reason'].join("\n")
-        elsif response_message['reason']
-          message << response_message['reason'].to_s
-        end
-      elsif response_message.is_a? String
-        message << response_message
-      else
-        message << "#{@response[:status]} -"
-        message << self.class.to_s.split('::', 2).last
-      end
-
-      message.strip
-    end
-  end
-
-  # @!group Generic errors
-
-  # TODO REVIEW: To be raised when a user hasn't explicitly supplied credentials or set up
-  # any environment defaults.
-  Unauthenticated = Class.new(StandardError)
-
-  # @!endgroup
-
-  # @!group HTTP errors
-
-  # @return [Found] an error to be raised when a status code of 401 is
-  #   returned by the API
-  Found = Class.new(Error)
-
-  # @return [Unauthorized] an error to be raised when a status code of 401 is
-  #   returned by the API
-  Unauthorized = Class.new(Error)
-
-  # @return [BadRequest] an error to be raised when a status code of 400 is
-  #   returned by the API
-  BadRequest = Class.new(Error)
-
-  # @return [NotFound] an error to be raised when a status code of 404 is
-  #   returned by the API
-  NotFound = Class.new(Error)
-
-  # @return [InternalServerError] an error to be raised when a status code of
-  # 500 is returned by the API
-  InternalServerError = Class.new(Error)
-
-  # @!endgroup
-end

data/lib/controls/response/raise_error.rb

@@ -1,21 +0,0 @@
-require 'controls/error'
-
-module Controls
-  module Response
-    # A middleware plugin that hooks into the Faraday client used by this gem
-    class RaiseError < Faraday::Response::Middleware
-      private
-
-      # Implements the {#on_complete} hook used by Faraday's middleware
-      #
-      # @raise [Controls::Error] a subclass of Controls::Error if any errors
-      #   were encountered
-      # @return [nil] if no error was found
-      def on_complete(response)
-        if error = Controls::Error.from_response(response)
-          raise error
-        end
-      end
-    end
-  end
-end