controls 1.0.2 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e0d929dd3cbd0cdce372929aca69e9a6c7a12212
-  data.tar.gz: 7dde81cc5fce99bb3ad043aa17febca1014ebd68
+  metadata.gz: b4c24961d1145261cb33c03a110b650f41eea255
+  data.tar.gz: 4df1a60e8405bbc41f875b9f6dad838bab803021
 SHA512:
-  metadata.gz: 7560f659c7a00b70923e70242a8d3f5a0fbebe088dc44d334cd36e5b90b486023d9a1fa0ac22a8ad480fd05031c733e94fca437738ac542ecb7c2d8d5b08b01c
-  data.tar.gz: 7d54e6c6c44f93b6b5f261b28cf13a84eb1773dc51bd881a2ca9aa859d6c4473de0c81efd1823abec027486ef30733fdbc53d55e7480193f1331795c8eaa4a8a
+  metadata.gz: 8e9d57de39f63b248311e1642149d05f09884543dcb6953266e1478ab14d01c6293ac32cc3913ecb4c218d8bc987b464bc01a1c970c2b887c0667226a46ac37f
+  data.tar.gz: d873718f6aaab45b0511fd5b658aa3c57827168185112ca89b973b261ac23fd4e4ba1422255a2e011c5f613a3a0539a7c15fa96b2d8945ac93c45349cac19f5c

data/docs/index.md

@@ -38,7 +38,8 @@ Controls.get '/'
 ### Curl
 ```bash
 # Use -k to allow a self-signed certificate
-curl -H 'Accept: application/json' --netrc-file ~/.rapid7_netrc  -ik https://nexpose.local:3780/insight/controls/api/1.0
+curl -H 'Accept: application/json' --netrc-file ~/.rapid7_netrc  -ik \
+https://nexpose.local:3780/insight/controls/api/1.0
 ```
 
 ### Ruby

data/lib/controls/client.rb

@@ -23,9 +23,12 @@ module Controls
     include Controls::Client::Threats
     include Controls::Client::Trends
 
-    SSL_WARNING = ["The API endpoint used a self-signed or invalid SSL certificate.",
-             "To allow this connection temporarily use `Controls.verify_ssl = false`.",
-             "See the Controls.rb wiki on GitHub for more information on SSL verification."]
+    # A few messages to show the user of Controls::Client in the case that a bad certificate is encountered
+    SSL_WARNING = [
+      'The API endpoint used a self-signed or invalid SSL certificate.',
+      'To allow this connection temporarily use `Controls.verify_ssl = false`.',
+      'See the Controls.rb wiki on GitHub for more information on SSL verification.'
+    ]
 
     # Creates a new {Controls::Client} object
     #
@@ -54,10 +57,14 @@ module Controls
       end
     end
 
+    # Whether the middleware is currently set to verify SSL connections
     def verify_ssl
       middleware.ssl[:verify].nil? || !!middleware.ssl[:verify]
     end
 
+    # Sets the middleware to to verify the SSL on true, or disregard it on false
+    #
+    # @param [Boolean] verify whether to verify SSL or not
     def verify_ssl=(verify)
       middleware.ssl[:verify] = !!verify
     end
@@ -89,14 +96,13 @@ module Controls
       end
     end
 
-
-    # A wrapper for GET requests
+    # A wrapper for PUT requests
     #
     # @return [Array,Hash] an array or hash of parsed JSON data
-    def web_get(path, params = {}, headers = {})
+    def put(path, body = {}, headers = {}, &block)
       headers = connection_options[:headers].merge(headers)
-      url = URI.escape(File.join(web_endpoint, path))
-      resp = middleware.get(url, params, headers)
+      url = URI.escape(File.join(api_endpoint, path))
+      resp = middleware.put(url, body, headers, &block)
 
       Response.parse(resp.body)
     rescue Faraday::Error::ConnectionFailed => e
@@ -107,6 +113,10 @@ module Controls
       end
     end
 
+    # A list of methods for API connections available to the {Controls::Client}
+    #
+    # @note Any methods defined in a child module will be returned.
+    # @return [Array<Symbol>] the methods defined in {Controls::Client} that are API related
     def api_methods
       mods = Controls::Client.included_modules.map do |mod|
         if mod.to_s =~ /^Controls::Client::/
@@ -117,12 +127,15 @@ module Controls
       mods.compact.map { |mod| mod.instance_methods(false) }.flatten.sort
     end
 
+    # A set of references from the "documentation" API endpoint /api
+    #
+    # @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}"
 
-       # Use generate_ruby
+       # [review] - Use Response#generate_ruby
       @references = Hash[Response.parse(resp.body).sort]
     rescue Faraday::Error::ConnectionFailed => e
       if e.message =~ /^SSL_connect/
@@ -132,6 +145,10 @@ module Controls
       end
     end
 
+    # Compares {#options} or with the given options hash
+    #
+    # @param [Hash] opts whether the options are the same or different
+    # @return whether the options are the same or different
     def same_options?(opts)
       opts.hash.eql? options.hash
     end
@@ -149,5 +166,22 @@ module Controls
         end                                     # end
       RUBY
     end
+
+    # A wrapper for GET requests to the Controls endpoint root (web endpoint)
+    #
+    # @return [Array,Hash] an array or hash of parsed JSON data
+    def web_get(path, params = {}, headers = {})
+      headers = connection_options[:headers].merge(headers)
+      url = URI.escape(File.join(web_endpoint, path))
+      resp = middleware.get(url, params, headers)
+
+      Response.parse(resp.body)
+    rescue Faraday::Error::ConnectionFailed => e
+      if e.message =~ /^SSL_connect/
+        warn(*SSL_WARNING)
+      else
+        raise e
+      end
+    end
   end
 end

data/lib/controls/client/assets.rb

@@ -6,6 +6,7 @@ module Controls
     module Assets
       # @!group Asset Methods
 
+      # [todo] - use @overload here for assets(params) vs assets(uuid) vs assets({ uuid: 'uuid-string', other: 'param' })
       # @note since the uuid is an optional param it has been added to the
       #   params options hash
       # @raise [Controls::NotFound] if the uuid didn't match any assets
@@ -18,13 +19,22 @@ module Controls
           params = {}
         end
 
-        if uuid
+        if uuid && !uuid.empty?
           get "/assets/#{uuid}", params
         else
           get '/assets', params
         end
       end
 
+      # [todo] - change the name to asset_search/search_assets?
+      # @param [String] query the query to retreive assets for
+      # @param [Hash] params the option hash to be turned into query parameters
+      # @return [Hash] a hash representing the matching assets
+      def assets_search(query, params = {})
+        params[:q] = query
+        get "/assets/search", params
+      end
+
       # @param [String] guidance the guidance name to search by
       # @return [Array<Hash>] an array of hashes that represent assets
       def applicable_assets(guidance, params = {})

data/lib/controls/client/security_controls.rb

@@ -13,6 +13,7 @@ module Controls
 
       # @param [String] control the name of the security control name to
       #   retrieve
+      # @todo warn that this method returns a different object now?
       # @return [Hash] a hash representing a security control
       def security_controls(control = nil)
         if control
@@ -22,6 +23,31 @@ module Controls
         end
       end
 
+      # @param [String] control the name of the security control name to
+      #   retrieve
+      # @todo add a since note? this replaces security_controls and security_controls now returns a new object
+      # @return [Hash] a hash representing a security control coverage
+      def security_controls_coverage(control = nil)
+        if control
+          get "/coverage/security_controls/#{control}"
+        else
+          get '/coverage/security_controls'
+        end
+      end
+
+      # Updates the specified security control(s)
+      #
+      # @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
+        if controls.is_a? Array
+          put '/security_controls', controls.to_json
+        elsif controls.is_a? Hash
+          put "/security_controls/#{control['name']}", control.to_json
+        end
+      end
+
       # @param [String] vector the threat vector to search for securuty controls
       #   by
       # @return [Array<Hash>] a list of hashes representing threats

data/lib/controls/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: controls
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.1
 platform: ruby
 authors:
 - Erran Carey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-22 00:00:00.000000000 Z
+date: 2014-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport