controls 1.7.0.beta.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa017f4f3585d9259d937543ea48e9491d59954d
-  data.tar.gz: abe2acf9f7704682b07cef385dba35e3e59aaeae
+  metadata.gz: 5c68ebb70f4ca7eb870f510d30c18ab95cad9c44
+  data.tar.gz: 72f79ad7b6814653b8e1b2ac9e1fa75cdaa2bfdb
 SHA512:
-  metadata.gz: 42d0bc45400ab1278e705ff15b097dc0106e139c5eb3e855bf8250809f6bde5d250618d07a5d903a7a73908794aaa24574ba767eb112e346414bd655be041010
-  data.tar.gz: 2793dcd70a0dab72a895485694245356a6eeaf5b6ab37edc84e6f7ff27fa8d6cf51f2a97b835cdc21e71e0cf737030a4a8c8f13f006d5744e75fb3251cd8650f
+  metadata.gz: 7189f9747d18096cbd4eacff03f2b0ddbfaf8ce2ead46364b8406fda8778315b74a6bbe51ca779d99bdc25022382788bc1b548093ee9dded5e599a4c6f5f54da
+  data.tar.gz: df937e63a59fc5bed775f39ea0c58f1b369ec3218778248c893a470a844e47cc8374e69369a3ea960e857945dba50a9df8f24e9d27d65320a0c7014a419e42db

data/.yardopts

@@ -1 +1,2 @@
 - LICENSE.md
+--exclude=lib/controls/ext

data/lib/controls.rb

@@ -3,8 +3,6 @@ require 'controls/default'
 
 # A Ruby client for the **controls**insight API
 module Controls
-  Error = Class.new(StandardError)
-
   class << self
     include Controls::Configurable
 
@@ -20,11 +18,19 @@ module Controls
       @client
     end
 
+    # Yields the global client to configure in a block
+    #
     # @yield [client]
     def configure
       yield client
     end
 
+    # Overrides the respond_to_missing method to act as a proxy for
+    # {Controls::Client}
+    #
+    # @param [Symbol,String] method_name the method name to check for
+    # @param [Boolean] include_private to include private methods when checking for method response
+    # @return [Boolean] whether {Controls} responds to the method
     def respond_to_missing?(method_name, include_private = false)
       client.respond_to?(method_name, include_private)
     end

data/lib/controls/client.rb

@@ -216,6 +216,10 @@ module Controls
       end
     end
 
+    # Creates an error from the last request
+    #
+    # @param [String] message the message to prepend to the response code/status
+    # @return [Controls::Error] the generated error message
     def exception(message = "HTTP Error")
       last_request = _last_request
       if last_request

data/lib/controls/client/coverage.rb

@@ -1,6 +1,14 @@
 module Controls
   class Client
+    # A module to encapsulate API methods related to coverage
+    # @since API v1.0
+    # [todo] - this version is obviously off
+    # @version v1.0.0
     module Coverage
+      # Either returns coverage for all security controls or one by name
+      #
+      # @param [String] security_control_name the security control to return coverage for
+      # @return [Array<Controls::SecurityControlCoverage>,Controls::SecurityControlCoverage]
       def security_control_coverage(security_control_name = nil)
         if security_control_name
           get "/coverage/security_controls/#{security_control_name}"

data/lib/controls/client/findings.rb

@@ -2,7 +2,8 @@ module Controls
   class Client
     # A module to encapsulate API methods related to assets
     # @since API v1.0
-    # @version v1.0.0
+    # [todo] - this version is obviously off
+    # @version v1.7.0
     module Findings
       # @!group Security Control/Configuration Findings Methods
 

data/lib/controls/client/security_controls.rb

@@ -33,7 +33,7 @@ module Controls
 
       # Updates the specified security control(s)
       #
-      # @param [Array[Hash{String=>String,Boolean}] controls a list of controls to update
+      # @param [Array[Hash{String=>String,Boolean}]] controls a list of controls to update
       # @return [void]
       def update_security_controls(controls)
         # [review] - this style is a discouraged for Arrays, but we want to treat controls as an Array of Hashes

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

@@ -1,25 +1,5 @@
 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)
-      elsif method.end_with? '='
-        key = camel_case_key[0..-2]
-        _set_value(key, args.first)
-      else
-        if @_original_hash.key?(camel_case_key)
-          _get_value(camel_case_key)
-        else
-          super(method.to_sym, *args, &block)
-        end
-      end
-    end
-
     def methods(all = true)
       valid_keys = as_hash.keys.map do |key|
         key.to_s.gsub(/([^A-Z])([A-Z]+)/, '\1_\2').downcase.to_sym
@@ -53,5 +33,25 @@ module Dish
       value = _convert_value(value, self.class.coercions[key])
       @_original_hash[key] = value
     end
+
+    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)
+      elsif method.end_with? '='
+        key = camel_case_key[0..-2]
+        _set_value(key, args.first)
+      else
+        if @_original_hash.key?(camel_case_key)
+          _get_value(camel_case_key)
+        else
+          super(method.to_sym, *args, &block)
+        end
+      end
+    end
   end
 end

data/lib/controls/objects/assessment.rb

@@ -1,7 +1,9 @@
 module Controls
+  # A representation of the Assessment resource
   class Assessment < Dish::Plate
     coerce :timestamp, ->(value) { Time.at(value / 1000) if value }
 
+    # The assessment ID as a string
     def to_s
       id.to_s
     end

data/lib/controls/objects/asset.rb

@@ -1,6 +1,7 @@
 require 'controls/objects/security_control_finding'
 
 module Controls
+  # A representation of the Asset resource
   class Asset < Dish::Plate
     coerce :discoveredAt, ->(value) { Time.at(value / 1000) if value }
 
@@ -8,30 +9,57 @@ module Controls
       Controls.client.findings_by_asset_uuid(uuid)
     end
 
+    # Returns the hostname, IP, and OS of the asset
+    #
+    # @example
+    #   "jdoe.local (192.168.1.23) - Windows 7 Professional Edition"
+    #
+    # @return [String]
     def to_s
       %(#{host_name} (#{ipaddress}) - #{operating_system})
     end
   end
 
+  # A collection of Asset resources
   class AssetCollection < Dish::Plate
     coerce :resources, Asset
 
-    def map(*args, &block)
+    # [todo] - metaprogram any proxy methods?
+    #        - be sure to define method_missing AND respond_to_missing?
+
+    # Acts as a proxy to resources.map
+    #
+    # @yield [resource] gives three resources
+    def map(&block)
       resources.map(*args, &block)
     end
 
+    # Acts as a proxy to resources.first
+    #
+    # @return [Controls::Asset]
     def first
       resources.first
     end
 
+    # Acts as a proxy to resources.last
+    #
+    # @return [Controls::Asset] the last asset in the
+    #   {Controls::AssetCollection}
     def last
       resources.last
     end
 
+    # Acts as a proxy to resources.[]
+    #
+    # @param [Fixnum] index the index of the asset to fetch
+    # @return [Controls::Asset] the asset by index
     def [](index)
       resources[index]
     end
 
+    # Returns a comma separated list of IP addresses
+    #
+    # @return [String]
     def to_s
       resources.sort_by(&:ipaddress).map(&:to_s).join("\n")
     end

data/lib/controls/objects/configuration.rb

@@ -1,10 +1,14 @@
 require 'controls/objects/coverage_information'
 
 module Controls
+  # A representation of the Configuration resource w/ coverage information
   class Configuration < Dish::Plate
     coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
     coerce :coverage, Controls::CoverageInformation
 
+    # The title of the configuration
+    #
+    # @return [String]
     def to_s
       title
     end

data/lib/controls/objects/configuration_finding.rb

@@ -1,5 +1,11 @@
 module Controls
+  # A representation of the ConfigurationFinding resource
   class ConfigurationFinding < Dish::Plate
+    coerce :reason, ->(value) { value.strip! }
+
+    # Returns the name, state, and reason data for the configuration finding
+    #
+    # "antivirus-installed: state: TRUE reason: Endpoint Security installed"
     def to_s
       "#{name}: state: #{state} reason: #{reason.strip}"
     end

data/lib/controls/objects/coverage_information.rb

@@ -1,7 +1,7 @@
 module Controls
+  # A representation of the CoverageInformation for SecurityControl or
+  # Configuration coverage
   class CoverageInformation < Dish::Plate
-    def to_s
-      "#<#{self.class}: total: #{total}, covered: #{covered}, uncovered: #{uncovered}, percent_covered: #{percent_covered}>"
-    end
+    alias_method :to_s, :inspect
   end
 end

data/lib/controls/objects/error.rb

@@ -0,0 +1,12 @@
+module Controls
+  # A class under the Controls namespace to wrap API errors
+  class Error < StandardError
+    # @!attribute message
+    #   The message related to the error
+    attr_accessor :message
+
+    # @!attribute message
+    #   The status code for the error response
+    attr_accessor :status
+  end
+end

data/lib/controls/objects/event.rb

@@ -1,16 +1,29 @@
 module Controls
+  # A representation of the Event resource
   class Event < Dish::Plate
     coerce :createdAt, ->(value) { Time.at(value / 1000) if value }
 
+    # Coerces the payload into the appropriate type
+    #
+    # @return [Controls::SecurityControlChangeEventPayload,Controls::SiteChangeEventPayload,Controls::ProductEventPayload]
+    #   the payload respective of the event type
     def payload
       value = _get_value('payload')
       Dish(value, Controls.const_get("#{type}Payload"))
     end
 
+    # Overrides #inspect to use the proper event type
+    #
+    # @return [String] the result of super with the corrected event type
     def inspect
       super.sub('Event', type)
     end
 
+    # Returns the event type
+    #
+    # [todo] - is the type all we want to return?
+    #
+    # @return [string] the event type
     def to_s
       type
     end

data/lib/controls/objects/product_change_event_payload.rb

@@ -1,4 +1,4 @@
 module Controls
-  class ProductChangeEventPayload < Dish::Plate
-  end
+  # A representation of a given ProductChangeEvent's payload
+  ProductChangeEventPayload = Class.new(Dish::Plate)
 end

data/lib/controls/objects/security_control_change_event_payload.rb

@@ -1,4 +1,4 @@
 module Controls
-  class SecurityControlChangeEventPayload < Dish::Plate
-  end
+  # A representation of a given SecurityControlChangeEvent's payload
+  SecurityControlChangeEventPayload = Class.new(Dish::Plate)
 end

data/lib/controls/objects/site_change_event_payload.rb

@@ -1,4 +1,4 @@
 module Controls
-  class SiteChangeEventPayload < Dish::Plate
-  end
+  # A representation of a given SiteChangeEventPayload's payload
+  SiteChangeEventPayload = Class.new(Dish::Plate)
 end

data/lib/controls/response.rb

@@ -3,11 +3,20 @@ require 'controls/objects'
 module Controls
   # A module to encapsulate middleware customization
   module Response
-    def self.parse(obj, path = nil)
+    module_function
+
+    # Returns the parsed JSON response after marshaling through Dish
+    #
+    # @param [String] obj the JSON object to parse
+    # @param [String] path the requested API endpoint's path
+    # @return [Dish::Plate,Object] a marshaled representation of the JSON response
+    def parse(obj, path = nil)
       hash_or_array = JSON.parse(obj)
 
       if hash_or_array.is_a?(Hash) && hash_or_array.key?('message') && hash_or_array.key?('documentationUrl')
         type = Controls::Error
+      elsif hash_or_array.is_a?(Hash) && hash_or_array.key?('message') && hash_or_array.key?('status')
+        type = Controls::Error
       end
 
       type ||=

data/lib/controls/version.rb

@@ -1,4 +1,4 @@
 module Controls
   # The version of the Controls gem
-  VERSION = '1.7.0.beta.1'
+  VERSION = '1.7.0'
 end

data/spec/controls/client/assessments_spec.rb

@@ -7,7 +7,9 @@ describe '/api/assessments' do
     it 'returns a list of assessments' do
       assessments = Controls.assessments
 
-      expect(assessments).to match_assessment_format
+      assessments.each do |assessment|
+        expect(assessment).to match_assessment_format
+      end
     end
   end
 

data/spec/matchers.rb

@@ -4,43 +4,18 @@ require 'rspec/expectations'
 RSpec::Matchers.define :match_assessment_format do
   match do |resource|
     # Reverses the coercion
-    resource.timestamp = resource.timestamp.to_i
     [
       resource.high_risk_asset_count,
       resource.id,
       resource.low_risk_asset_count,
       resource.medium_risk_asset_count,
-      resource.timestamp,
+      resource.timestamp.to_i,
       resource.total_asset_count
     ].each do |attribute|
       expect(attribute.class).to eq(Fixnum)
     end
 
-    expect(resource.assessing.class).to include([TrueClass, FalseClass])
-    expect(resource.overall_risk_score.class).to  include([Float])
+    expect([TrueClass, FalseClass].include?(resource.assessing.class)).to be_true
+    expect([Float].include?(resource.overall_risk_score.class)).to be_true
   end
 end
-
-#RSpec::Matchers.define :match_event_format do
-#  [Fixnum].include? resource.createdAt
-#  [Hash].include? resource.payload
-#  [String].include? resource.type
-#  [String].include? resource.user
-#end
-#
-#RSpec::Matchers.define :match_site_change_event_payload_format do
-#  [TrueClass,FalseClass].include? resource.impactsGrade.class
-#  [String].include? resource.notes.class
-#  [String].include? resource.productVersion.class
-#end
-#
-#RSpec::Matchers.define :match_security_control_change_event_payload_format do
-#  [String,NilClass].include?resource.reason
-#  [String]}]].include?resource.changes:[Array,[Hash,{securityControlName:[String],action
-#end
-#
-#RSpec::Matchers.define :match__change_event_payload_format do
-#  [String,NilClass].include?resource.reason
-#  [Fixnum]}]].include?resource.enabledSites:[Array,[Hash,{name:[String],id
-#  [TrueClass.include?resource.importAllFalseClass]
-#end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: controls
 version: !ruby/object:Gem::Version
-  version: 1.7.0.beta.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Erran Carey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-04 00:00:00.000000000 Z
+date: 2014-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dish
@@ -121,6 +121,7 @@ files:
 - lib/controls/objects/configuration.rb
 - lib/controls/objects/configuration_finding.rb
 - lib/controls/objects/coverage_information.rb
+- lib/controls/objects/error.rb
 - lib/controls/objects/event.rb
 - lib/controls/objects/guidance.rb
 - lib/controls/objects/product_change_event_payload.rb
@@ -135,7 +136,6 @@ files:
 - lib/controls/response.rb
 - lib/controls/version.rb
 - spec/controls/client/assessments_spec.rb
-- spec/controls/client/events_spec.rb
 - spec/matchers.rb
 - spec/spec_helper.rb
 homepage: ''
@@ -153,9 +153,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.0
@@ -164,7 +164,6 @@ specification_version: 4
 summary: This gem interfaces to Rapid7's **controls**insight API.
 test_files:
 - spec/controls/client/assessments_spec.rb
-- spec/controls/client/events_spec.rb
 - spec/matchers.rb
 - spec/spec_helper.rb
 has_rdoc: 

data/spec/controls/client/events_spec.rb

@@ -1,54 +0,0 @@
-#describe '/api/events' do
-#  before do
-#    login_to_environment
-#  end
-#
-#  context 'GET /api/events' do
-#    it 'returns a list of events' do
-#      events = Controls.events
-#
-#      expect(events).to match_format(event_format)
-#    end
-#  end
-#
-#  context 'GET /api/events?filter=ProductChangeEvent' do
-#    it 'returns a list of events' do
-#      events = Controls.events filter: 'ProductChangeEvent'
-#
-#      expect(events).to match_format(event_format)
-#      expect(events.map(&:payload)).to match_format(product_change_format)
-#    end
-#  end
-#
-#  context 'GET /api/events?filter=SecurityControlChangeEvent' do
-#    it 'returns a list of events' do
-#      events = Controls.events filter: 'SecurityControlChangeEvent'
-#      expected_payload_format = security_control_change_format
-#
-#      expect(events).to match_format(event_format)
-#      expect(events.map(&:payload)).to match_format(expected_payload_format)
-#
-#      events.map(&:payload).each do |payload|
-#        payload.keys.map(&:to_sym).each do |key|
-#          expect(payload.send(key)).to match_format(expected_payload_format[key].last)
-#        end
-#      end
-#    end
-#  end
-#
-#  context 'GET /api/events?filter=SiteChangeEvent' do
-#    it 'returns a list of events' do
-#      events = Controls.events filter: 'SiteChangeEvent'
-#      expected_payload_format = site_change_format
-#
-#      expect(events).to match_format(event_format)
-#      expect(events.map(&:payload)).to match_format(expected_payload_format)
-#
-#      events.map(&:payload).each do |payload|
-#        payload.keys.map(&:to_sym).each do |key|
-#          expect(payload.send(key)).to match_format(expected_payload_format[key].last)
-#        end
-#      end
-#    end
-#  end
-#end