controls 1.0.0.beta.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fadb777b4fbaf3fdc6b52f08d20b285c8f1904fb
+  data.tar.gz: c7589578857e422ebc60be2dcd6ef9b9e42bcb6e
+SHA512:
+  metadata.gz: ee1c3c4c8a44dd97310f9616752ff416204055d21cf40984605be06534f9fdf853cca8a8374f606322372b408005dd06bbc4c71288cfece0e8667e06a6204b3d
+  data.tar.gz: 15212139246d997a70435bb8d7fd5c8cde611b4bab1c7b778a9971fd899dfb8cac37f1ee69637e9b5c07d2713a98d6eeec7d5b3ad52eba8a2b0f6c03ca087035

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.yardopts

@@ -0,0 +1 @@
+- LICENSE.md

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in controls.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Erran Carey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,78 @@
+# ![controls insight](https://raw.github.com/ipwnstuff/controls.rb/master/docs/images/controlsinsight.png "controlsinsight") client gem
+The **controls**insight (controls) gem interfaces with [Rapid7's **controls**insight API](http://docs.controlsinsight.apiary.io).
+
+## Installation
+Add this line to your application's Gemfile:
+
+    gem 'controls'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install controls
+
+## Documentation
+* [Apiary API documentation](http://docs.controlsinsight.apiary.io)
+* [YARD documentation for the Ruby client](http://www.rubydoc.info/github/ipwnstuff/controls.rb)
+
+## Basic Resources
+### Authentication
+```ruby
+Controls.web_endpoint = 'https://nexpose.local:3780/insight/controls'
+Controls.api_endpoint = "#{Controls.web_endpoint}/api/1.0"
+
+# If your endpoint uses a self-signed cert. turn off SSL cert. verification
+Controls.verify_ssl = false
+
+Controls.login :user => 'admin', :password => 'password'
+
+Controls.client.methods
+```
+
+### Assessments
+```ruby
+# Retrieve all the assessments that have been ran
+Controls.assessments
+# => TODO: Add example output
+
+# Only retrieve a single assessment
+Controls.assessments(1)
+# => TODO: Add example output
+```
+
+
+### Assets
+```ruby
+# Retrieve a list of all the assets that Controls has access to
+Controls.assets
+# => TODO: Add example output
+
+# Only retrieve a single assessment
+Controls.assets('your-asset-uuid-here')
+# => TODO: Add example output
+```
+
+### Guidance
+```ruby
+# Only retrieve a single guidance by name
+Controls.guidance('your-guidance-name-here')
+# => TODO: Add example output
+```
+
+### Threats
+```ruby
+# Retrieve a list of all the threats
+Controls.threats
+# => TODO: Add example output
+
+# Only retrieve a single threat
+Controls.threats('threat-name-here')
+# => TODO: Add example output
+```
+
+
+## License
+This project was created by [Erran Carey (@ipwnstuff)](http://ipwnstuff.github.io) and licensed under [the MIT License](LICENSE.md).

data/Rakefile

@@ -0,0 +1,3 @@
+require 'bundler/gem_tasks'
+
+task :default => :install

data/controls.gemspec

@@ -0,0 +1,30 @@
+# encoding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'controls/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'controls'
+  spec.version       = Controls::VERSION
+  spec.authors       = ['Erran Carey']
+  spec.email         = %w['me@errancarey.com']
+  spec.description   = %q{This gem interfaces to Rapid7's **controls**insight API.}
+  spec.summary       = %q{This gem interfaces to Rapid7's **controls**insight API.}
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = %w[lib]
+
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'faraday'
+  spec.add_dependency 'nokogiri'
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'netrc'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'vcr'
+  spec.add_development_dependency 'yard'
+end

data/lib/controls.rb

@@ -0,0 +1,42 @@
+require 'controls/client'
+require 'controls/default'
+
+# A Ruby client for the **controls**insight API
+module Controls
+  class << self
+    include Controls::Configurable
+
+    # A {Client} object that includes {Configurable}
+    #
+    # @return [Client] the current {Client} object or a newly initialized
+    #   {Client} object
+    def client
+      unless defined?(@client) && @client.same_options?(options)
+        @client = Controls::Client.new(options)
+      end
+
+      @client
+    end
+
+    # @yield [client]
+    def configure
+      yield client
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      client.respond_to?(method_name, include_private)
+    end
+
+    private
+
+    def method_missing(method_name, *args, &block)
+      if client.respond_to?(method_name)
+        client.send(method_name, *args, &block)
+      else
+        super
+      end
+    end
+  end
+end
+
+Controls.setup

data/lib/controls/authentication.rb

@@ -0,0 +1,46 @@
+module Controls
+  # A module that holds authentication methods for {Controls::Client}
+  module Authentication
+    # @return [Boolean] whether the user is authenticated using Basic Auth
+    def basic_authenticated?
+      @username && @password
+    end
+
+    # @note the following aliases should become real methods once new methods
+    #   of authentication become available such as token/OAuth authentication
+    alias_method :authenticated?, :basic_authenticated?
+    alias_method :user_authenticated?, :basic_authenticated?
+
+    # @note this method should be updated if new methods for authentication
+    #   become available.
+    def login(username, password)
+      middleware.basic_auth(username, password)
+    end
+
+    # @return [Boolean] whether the netrc file was successfully loaded, otherwise
+    #   returns false and prints an error to STDERR
+    def login_from_netrc
+      return false unless netrc?
+
+      require 'netrc'
+      host =  URI.parse(api_endpoint).host
+      creds = Netrc.read(File.expand_path(netrc_file))[host]
+
+      if creds
+        self.username = creds.shift
+        self.password = creds.shift
+
+        middleware.basic_auth(username, password)
+      else
+        warn "No credentials found for '#{host}' in '#{netrc_file}'."
+
+        false
+      end
+    rescue LoadError
+      warn 'You must install the netrc gem to login via netrc.',
+           'Retry after running `gem install netrc`.'
+
+      false
+    end
+  end
+end

data/lib/controls/client.rb

@@ -0,0 +1,151 @@
+require 'faraday'
+require 'json'
+require 'nokogiri'
+require 'controls/authentication'
+require 'controls/configurable'
+require 'controls/client/assessments'
+require 'controls/client/assets'
+require 'controls/client/guidance'
+require 'controls/client/security_controls'
+require 'controls/client/threats'
+require 'controls/response'
+
+module Controls
+  # A class that handles interactions with the **controls**insight API
+  class Client
+    include Controls::Authentication
+    include Controls::Configurable
+    include Controls::Client::Assessments
+    include Controls::Client::Assets
+    include Controls::Client::Guidance
+    include Controls::Client::SecurityControls
+    include Controls::Client::Threats
+
+    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
+    #
+    # @param [Hash] options the options to use when adding keys from
+    #   {Controls::Configurable}
+    def initialize(options = {})
+      Controls::Configurable.keys.each do |key|
+        value = options[key].nil? ? Controls.instance_variable_get(:"@#{key}") : options[key]
+        instance_variable_set(:"@#{key}", value)
+      end
+
+      if options[:verify_ssl].nil?
+        middleware.ssl[:verify] = if ENV['CONTROLS_VERIFY_SSL'].nil?
+                                    true
+                                  else
+                                    !(ENV['CONTROLS_VERIFY_SSL'] =~ /false/)
+                                  end
+      else
+        middleware.ssl[:verify] = !!options[:verify_ssl]
+      end
+
+      login_from_netrc unless authenticated?
+
+      if basic_authenticated?
+        middleware.basic_auth(@username, @password)
+      end
+    end
+
+    def verify_ssl
+      middleware.ssl[:verify].nil? || !!middleware.ssl[:verify]
+    end
+
+    def verify_ssl=(verify)
+      middleware.ssl[:verify] = !!verify
+    end
+
+    # Censors the password from the output of {#inspect}
+    #
+    # @return [String] the censored data
+    def inspect
+      raw = super
+      raw.sub!(/(@password=")#{@password}(")/, "\\1*********\\2") if @password
+
+      raw
+    end
+
+    # A wrapper for GET requests
+    #
+    # @return [Array,Hash] an array or hash of parsed JSON data
+    def get(path, params = {}, headers = {})
+      headers = connection_options[:headers].merge(headers)
+      url = URI.escape(File.join(api_endpoint, path))
+      resp = middleware.get(url, params, headers)
+
+      Response.generate_ruby(resp.body)
+    rescue Faraday::Error::ConnectionFailed => e
+      if e.message =~ /^SSL_connect/
+        warn(*SSL_WARNING)
+      else
+        raise e
+      end
+    end
+
+
+    # A wrapper for GET requests
+    #
+    # @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)
+      Response.generate_ruby(resp.body)
+    rescue Faraday::Error::ConnectionFailed => e
+      if e.message =~ /^SSL_connect/
+        warn(*SSL_WARNING)
+      else
+        raise e
+      end
+    end
+
+    def api_methods
+      mods = Controls::Client.included_modules.map do |mod|
+        if mod.to_s =~ /^Controls::Client::/
+          mod
+        end
+      end
+
+      mods.compact.map { |mod| mod.instance_methods(false) }.flatten.sort
+    end
+
+    def references(version = '1.0')
+      version = '1.0' unless version =~ /\d.\d/
+
+       web_get "/api/#{version}"
+
+      @references = Hash[Response.generate_ruby(resp.body).sort]
+    rescue Faraday::Error::ConnectionFailed => e
+      if e.message =~ /^SSL_connect/
+        warn(*SSL_WARNING)
+      else
+        raise e
+      end
+    end
+
+    def same_options?(opts)
+      opts.hash.eql? options.hash
+    end
+
+    %w[assessment asset configuration
+       guidance security_control threat
+       threat_vector].each do |predicate_method|
+      pluralized_method = predicate_method.eql?('guidance') ? 'guidance' : "#{predicate_method}s"
+
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{predicate_method}?(*args)         # def assessment?(*args)
+          send(:#{pluralized_method}, *args)    #   assessments(*args)
+        rescue Controls::NotFound => e          # rescue Controls::NotFound => e
+          false                                 #   false
+        end                                     # end
+      RUBY
+    end
+  end
+end

data/lib/controls/client/assessments.rb

@@ -0,0 +1,17 @@
+module Controls
+  class Client
+    # A module to encapsulate API methods related to assessments
+    # @since API v1.0
+    # @version v1.0.0
+    module Assessments
+      # @return [Array<Hash>] an array of assessment hashes
+      def assessments(assessment_id = nil)
+        if assessment_id
+          get "/assessments/#{assessment_id}"
+        else
+          get '/assessments'
+        end
+      end
+    end
+  end
+end

data/lib/controls/client/assets.rb

@@ -0,0 +1,64 @@
+module Controls
+  class Client
+    # A module to encapsulate API methods related to assets
+    # @since API v1.0
+    # @version v1.0.0
+    # TODO: Update docs
+    module Assets
+      # @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
+      # @return [Hash] a hash representing the matching asset
+      def assets(params = {})
+        if params.is_a? Hash
+          uuid = params.delete(:uuid)
+        else
+          uuid = params
+          params = {}
+        end
+
+        if uuid
+          get "/assets/#{uuid}", params
+        else
+          get '/assets', params
+        end
+      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 = {})
+        get "/guidance/#{guidance}/applicable_assets", params
+      end
+      alias_method :assets_by_guidance, :applicable_assets
+
+      # @param [String] configuration the name of the configuration to search by
+      # @return [Array<Hash>] an array of hashes that represent assets
+      def misconfigured_assets(configuration, params = {})
+        get "/configurations/#{configuration}/uncovered_assets", params
+      end
+      alias_method :assets_by_configuration, :misconfigured_assets
+
+      # @param [String] threat the threat name to search by
+      # @return [Array<Hash>] an array of hashes that represent assets
+      def threat_assets(threat, params = {})
+        get "/threats/#{threat}/assets", params
+      end
+      alias_method :assets_by_threat, :threat_assets
+
+      # @param [String] security_control the name of the security control to
+      #   search by
+      # @return [Array<Hash>] an array of hashes that represent assets
+      def uncovered_assets(security_control, params = {})
+        get "/security_controls/#{security_control}/uncovered_assets", params
+      end
+      alias_method :assets_by_security_control, :uncovered_assets
+
+      # @param [String] threat_vector the threat vectory to search by
+      # @return [Array<Hash>] an array of hashes that represent assets
+      def undefended_assets(threat_vector, params = {})
+        get "/threat_vectors/#{threat_vector}/undefended_assets", params
+      end
+      alias_method :assets_by_threat_vector, :undefended_assets
+    end
+  end
+end