controls 1.0.0.beta.2

data/lib/controls/client/configurations.rb

@@ -0,0 +1,31 @@
+module Controls
+  class Client
+    # A module to encapsulate API methods related to security controls and
+    # configurations
+    # @since API v1.0
+    # @version v1.0.0
+    module Configurations
+      # @!group Configuration Methods
+
+      # @param [String] configuration the name of the configuration to search
+      #   for
+      # @return [Array<Hash>] a list of hashes representing configurations
+      def configurations(configuration = nil)
+        if configuration
+          get "/configurations/#{configuration}"
+        else
+          get "/configurations"
+        end
+      end
+
+      # @param [String] control the security control look up configurations for
+      # @return [Array<Hash>] a list of hashes representing configurations
+      def security_control_configurations(control)
+        get "/security_controls/#{control}/configurations"
+      end
+      alias_method :configurations_by_security_control, :security_control_configurations
+
+      # @!endgroup
+    end
+  end
+end

data/lib/controls/client/guidance.rb

@@ -0,0 +1,46 @@
+require 'controls/client/prioritized_guidance'
+
+module Controls
+  class Client
+    # A module to encapsulate API methods related to guidance
+    # @since API v1.0
+    # @version v1.0.0
+    module Guidance
+      include PrioritizedGuidance
+
+      # @!group Guidance Methods
+
+      # @param [String] name the name of the guidance to search for
+      # @return [Hash] a hash representing the matching guidance
+      def guidance(name)
+        get "/guidance/#{name}"
+      end
+
+      # @param [String] configuration the configuration name to search by
+      # @return [Array<Hash>] an array of "guidance hashes"
+      def guidance_by_configuration(security_control, configuration)
+        get "/configurations/#{configuration}/guidance"
+      end
+
+      # @param [String] security_control the security control name to search by
+      # @return [Array<Hash>] an array of "guidance hashes"
+      def guidance_by_security_control(security_control)
+        get "/security_controls/#{security_control}/guidance"
+      end
+
+      # @param [String] threat the threat name to search by
+      # @return [Array<Hash>] an array of "guidance hashes"
+      def guidance_by_threat(threat)
+        get "/threats/#{threat}/guidance"
+      end
+
+      # @param [String] threat_vector the threat name to search by
+      # @return [Array<Hash>] an array of "guidance hashes"
+      def guidance_by_threat_vector(threat_vector)
+        get "/threat_vectors/#{threat_vector}/guidance"
+      end
+
+      # @!endgroup
+    end
+  end
+end

data/lib/controls/client/prioritized_guidance.rb

@@ -0,0 +1,34 @@
+module Controls
+  class Client
+    # A module to encapsulate API methods related to guidance
+    # @since API v1.0
+    # @version v1.0.0
+    module PrioritizedGuidance
+      # @!group Prioritized Guidance Methods
+
+      # @param [String] security_control the security control name to search by
+      # @return [Array<Hash>] an array of "guidance hashes"
+      def prioritized_guidance_by_security_control(security_control)
+        get "/security_controls/#{security_control}/prioritized_guidance"
+      end
+
+      # @param [String] configuration the configuration name to search by
+      # @return [Array<Hash>] an array of "guidance hashes"
+      def prioritized_guidance_by_configuration(configuration)
+        get "/configurations/#{configuration}/prioritized_guidance"
+      end
+
+      # @param [String] threat the threat name to search by
+      # @return [Array<Hash>] an array of "guidance hashes"
+      def prioritized_guidance_by_threat(threat)
+        get "/threats/#{threat}/prioritized_guidance"
+      end
+
+      # @param [String] threat_vector the threat name to search by
+      # @return [Array<Hash>] an array of "guidance hashes"
+      def prioritized_guidance_by_threat_vector(threat_vector)
+        get "/threat_vectors/#{threat_vector}/prioritized_guidance"
+      end
+    end
+  end
+end

data/lib/controls/client/security_controls.rb

@@ -0,0 +1,36 @@
+require 'controls/client/configurations'
+
+module Controls
+  class Client
+    # A module to encapsulate API methods related to security controls and
+    # configurations
+    # @since API v1.0
+    # @version v1.0.0
+    module SecurityControls
+      include Configurations
+
+      #!@group Security Control Methods
+
+      # @param [String] control the name of the security control name to
+      #   retrieve
+      # @return [Hash] a hash representing a security control
+      def security_controls(control = nil)
+        if control
+          get "/security_controls/#{control}"
+        else
+          get '/security_controls'
+        end
+      end
+
+      # @param [String] vector the threat vector to search for securuty controls
+      #   by
+      # @return [Array<Hash>] a list of hashes representing threats
+      def threat_vector_security_controls(vector)
+        get "/threat_vectors/#{vector}/security_controls"
+      end
+      alias_method :security_controls_by_threat_vector, :threat_vector_security_controls
+
+      # @!endgroup
+    end
+  end
+end

data/lib/controls/client/threat_vectors.rb

@@ -0,0 +1,29 @@
+module Controls
+  class Client
+    # A module to encapsulate API methods related to threats and threat vectors
+    # @since API v1.0
+    # @version v1.0.0
+    module ThreatVectors
+      # @!group Threat Vector Methods
+
+      # @param [String] vector the threat vector to search for
+      # @return [String] a hash representing the specified threat vector
+      def threat_vectors(vector = nil)
+        if vector
+          get "/threat_vectors/#{vector}"
+        else
+          get '/threat_vectors'
+        end
+      end
+
+      # @param [String] threat the threat to search for threat vectors by
+      # @return [Array<Hash>] a list of hashes representing threats
+      def threat_threat_vectors(threat)
+        get "/threats/#{threat}/threat_vectors"
+      end
+      alias_method :threat_vectors_by_threat, :threat_threat_vectors
+
+      # @!endgroup
+    end
+  end
+end

data/lib/controls/client/threats.rb

@@ -0,0 +1,26 @@
+require 'controls/client/threat_vectors'
+
+module Controls
+  class Client
+    # A module to encapsulate API methods related to threats and threat vectors
+    # @since API v1.0
+    # @version v1.0.0
+    module Threats
+      include ThreatVectors
+
+      # @!group Threat Methods
+
+      # @param [String] threat the threat name to search for
+      # @return [String] a hash representing the specified threat
+      def threats(threat = nil)
+        if threat
+          get "/threats/#{threat}"
+        else
+          get '/threats'
+        end
+      end
+
+      # @!endgroup
+    end
+  end
+end

data/lib/controls/configurable.rb

@@ -0,0 +1,83 @@
+module Controls
+  # A module to hold configurable options to be used by other classes such as
+  # the {Controls} eigenclass or the {Controls::Client} class
+  module Configurable
+    # @!attribute api_endpoint
+    #   @return [String] the endpoint to connect to. default: https://nexpose.local:3780/insight/controls/api/1.0
+    # @!attribute api_endpoint
+    #   @return [String] the endpoint to connect to. default: https://nexpose.local:3780/insight/controls/api/1.0
+    # @!attribute connection_options
+    #   @return [Hash] the current connection options (headers, etc.)
+    # @!attribute default_media_type
+    #   @return [String] the default media type to send with requests. default: application/json
+    # @!attribute middleware
+    #   @return [Faraday::Connection] the middleware used to send requests
+    # @!attribute netrc
+    #   @return [Boolean] whether to use the netrc credentials to authentcicate with the **controls**insight API
+    # @!attribute netrc_file
+    #   @return [String] the path of the .netrc file to look for credentials in. default: ~/.netrc
+    # @!attribute user_agent
+    #   @return [String] the user agent to send with API requests. example: "controls/v1.0.0.beta (ruby; 2.0.0p247; [x86_64-darwin12.4.0]; Faraday v0.8.8)"
+    # @!attribute username
+    #   @return [String] the username to use for authentication
+    # @!attribute web_endpoint
+    #   @return [String] the endpoint to connect to. default: https://nexpose.local:3780/insight/controls
+    attr_accessor :api_endpoint, :api_version, :connection_options,
+                  :default_media_type, :middleware, :netrc, :netrc_file,
+                  :user_agent, :username, :web_endpoint
+
+    # @!attribute [w] password
+    #   @return [String] the password specified on login
+    attr_writer   :password
+
+    class << self
+      # @return [Array<Symbol>] a list of configurable keys
+      def keys
+        @keys ||= [
+          :api_endpoint,
+          :api_version,
+          :connection_options,
+          :default_media_type,
+          :middleware,
+          :netrc,
+          :netrc_file,
+          :password,
+          :user_agent,
+          :username,
+          :web_endpoint
+        ]
+      end
+    end
+
+    # @yield [self]
+    def configure
+      yield self
+    end
+
+    def netrc?
+      !!@netrc
+    end
+
+    # Configures {Controls::Configurable} to use options found in
+    # {Controls::Default}
+    #
+    # @return [self]
+    def setup
+      Controls::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", Controls::Default.options[key])
+      end
+
+      self
+    end
+    # NOTE: This method currently leaves some "updated defaults" intact
+    # alias_method :reset!, :setup
+
+    private
+
+    # @return [Hash] a hash representation of the options mapping key names to
+    #   their instance variable counterpart's value
+    def options
+      Hash[Controls::Configurable.keys.map { |key| [key, instance_variable_get(:"@#{key}")] }]
+    end
+  end
+end

data/lib/controls/default.rb

@@ -0,0 +1,108 @@
+require 'controls/version'
+
+module Controls
+  # Default options merged with environment specific overrides to satisfy the
+  # options specified in the {Controls::Configurable} module
+  module Default
+    # @return [String] the API version to connect to. default: 1.0
+    # @since API v1.0.0
+    API_VERSION = '1.0'.freeze
+
+    # @return [String] the API endpoint to connect to. default: https://nexpose.local:3780/insight/controls/api/1.0
+    # @since API v1.0.0
+    API_ENDPOINT = "https://localhost:3780/insight/controls/api/#{API_VERSION}".freeze
+
+    # @return [String] the default media type to send with requests. default: application/json
+    # @since API v1.0.0
+    MEDIA_TYPE = 'application/json'
+
+    # @return [String] the user agent to send with API requests. example: "controls/v1.0.0.beta (ruby; 2.0.0p247; [x86_64-darwin12.4.0]; Faraday v0.8.8)"
+    USER_AGENT = "controls/v#{Controls::VERSION} (#{(RUBY_DESCRIPTION.split[0..1] + [RUBY_DESCRIPTION.split.last]).join('; ')}; Faraday v#{Faraday::VERSION})".freeze
+
+    # @return [String] the web endpoint to connect to. default: https://nexpose.local:3780/insight/controls
+    WEB_ENDPOINT = 'https://localhost:3780/insight/controls'.freeze
+
+    class << self
+      # @return [Hash] options as a Hash, mapped by keys from {Controls::Configurable}
+      def options
+        Hash[Controls::Configurable.keys.map { |key| [key, send(key)] }]
+      end
+
+      # @return [String] the API endpoint's URI as a URL
+      def api_endpoint
+        endpoint = ENV['CONTROLS_API_ENDPOINT'] || API_ENDPOINT
+        URI.parse(endpoint).to_s
+      end
+
+      # @return [String] the API version to connect to
+      def api_version
+        if ENV['CONTROLS_API_VERSION'].to_s =~ /\d+.\d+/
+          ENV['CONTROLS_API_VERSION']
+        else
+          API_VERSION
+        end
+      end
+
+      # @return [Hash] the current connection options (headers, etc.)
+      def connection_options
+        {
+          headers: {
+            accept: default_media_type,
+            user_agent: user_agent
+          }
+        }
+      end
+
+      # @return [String] the environment specific default media type.
+      #   default: {MEDIA_TYPE}
+      def default_media_type
+        ENV['CONTROLS_MEDIA_TYPE'] || MEDIA_TYPE
+      end
+
+      # REVIEW: Ensure that middleware is unique to the client instance
+      # @return [Faraday::Connection] the middleware used to send requests
+      def middleware
+        @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
+
+      # @return [Boolean] whether to fallback on authentication using the
+      #   specified netrc file
+      def netrc
+        ENV['CONTROLS_NETRC'] || false
+      end
+
+      # @return [String] the netrc file to use for authentication.
+      #   default: ~/.netrc
+      def netrc_file
+        ENV['CONTROLS_NETRC_FILE'] || File.join(Dir.home, '.netrc')
+      end
+
+
+      # @return [String] the password to use for authentication
+      def password
+        ENV['CONTROLS_PASSWORD']
+      end
+
+      # @return [String] the user agent that will be sent along any requests
+      #   sent using {#connection_options}
+      def user_agent
+        ENV['CONTROLS_USER_AGENT'] || USER_AGENT
+      end
+
+      # @return [String] the username to use for authentication
+      def username
+        ENV['CONTROLS_USERNAME']
+      end
+
+      # @return [String] the web endpoint's URI as a URL
+      def web_endpoint
+        endpoint = ENV['CONTROLS_WEB_ENDPOINT'] || WEB_ENDPOINT
+        URI.parse(endpoint).to_s
+      end
+    end
+  end
+end

data/lib/controls/error.rb

@@ -0,0 +1,132 @@
+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