controls 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 55c739a368bec0d5fb73f517d4646f91491f25fc
-  data.tar.gz: c592434a49b7919d222663c9c54c1af04a9bebdb
+  metadata.gz: 8b246a67459339490b8d0afcdf27f033bc458b6e
+  data.tar.gz: ee9b5eab69a2e4add533df170ea443c5f4d314cc
 SHA512:
-  metadata.gz: 68cfed432b398e1f4b2b4e7651ee4ca7f446d3ff8bd7ca185201b2e10267bf0c8612c0033dcf75f0c838a38ac6899f25ad836fb6a7cb5468185e2d7db4f5413d
-  data.tar.gz: 9058fbd27a40f5a5abe79d17fec605bb13b37c7ec57db3d3184d460c42d7c2a3a239850e352f026d439fd42beb7406b458cf22ffee5a2e1525e382264f5c921b
+  metadata.gz: 6f3cca4615165876ece9886fbafb87db819d875e09c62511e0631c66ea643e958b9d353abd90337601ec426ede94d0918095b5edb84046d22c8ef37ef1701df8
+  data.tar.gz: e4267b9510bab07d0214a4879456190be7fb6d3e14b0035dbad50d2f4561153596bc91904d21b7264e271bd853323fbcf54bae8e5bdfb61592a0df845d3de97c

data/LICENSE.md

@@ -1,20 +1,27 @@
-The MIT License (MIT)
+Copyright (c) 2013, Rapid7 Inc.
+All rights reserved.
 
-Copyright (c) 2013 Erran Carey
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-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:
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
 
-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.
+* Neither the name of the Rapid7 Inc. nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -1,5 +1,5 @@
-# ![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).
+# controlsinsight client gem
+The **controls**insight (controls) gem interfaces with [Rapid7's **controls**insight API](http://rapid7.viewdocs.io/controlsinsight.rb).
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -15,8 +15,8 @@ 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)
+* [viewdocs.io API documentation](http://rapid7.viewdocs.io/controlsinsight.rb)
+* [YARD documentation for the Ruby client](http://www.rubydoc.info/github/rapid7/controlsinsight.rb)
 
 ## Basic Resources
 ### Authentication
@@ -60,6 +60,9 @@ Controls.assets('your-asset-uuid-here')
 # Only retrieve a single guidance by name
 Controls.guidance('your-guidance-name-here')
 # => TODO: Add example output
+
+Controls.guidance_by_threat('overall-malware')
+# => TODO: Add example output
 ```
 
 ### Threats
@@ -73,6 +76,29 @@ Controls.threats('threat-name-here')
 # => TODO: Add example output
 ```
 
+### Threat Vectors
+```ruby
+# Retrieve a list of all the threat vectors
+Controls.threat_vectors
+# => TODO: Add example output
+
+# Only retrieve a single threat vector
+Controls.threat_vectors('vector-name-here')
+# => TODO: Add example output
+```
+
+# Trends
+```ruby
+# Retrieve a set of statistics over time
+Controls.threat_trends('threat-name-here')
+# => TODO: Add example output
+
+Controls.threat_vector_trends('vector-name-here')
+# => TODO: Add example output
+
+Controls.configuration_trends('configuration-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/docs/index.md

@@ -0,0 +1,86 @@
+ControlsInsight API v1.0 (beta)
+---
+
+## Overview
+Rapid7's **controlsinsight**, hereafter **controls**insight or simply **controls**,
+
+The **controls**insight API v1.0 allow developers to utilize information about security controls, configurations, threats, and more from **controls**. 
+
+This documentation includes custom Curl examples and Ruby examples using the Ruby API client (ipwnstuff/controls.rb).
+
+Apiary.io also adds example requests in other languages, though they aren't supported tested them.
+
+To see advanced usage in Ruby read the [Ruby client documentation here](http://www.rubydoc.info/github/rapid7/controlsinsight.rb).
+
+## Authentication
+You must authenticate using HTTP Basic Auth when making any of the API requests.
+
+## Curl
+See the cURL man pages on how to authenticate.
+
+```bash
+# Use -k to allow a self-signed certificate
+curl --user admin:password https://nexpose.local:3780/insight/controls/api/1.0
+```
+
+## Ruby
+```ruby
+# Allow connections to Nexpose's self-signed cert
+Controls.middleware.ssl[:verify] = false
+
+Controls.login 'admin', 'password'
+
+# Return the API reference for the current API version
+Controls.get '/'
+```
+
+## Authentication via a `.netrc` file
+### 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
+```
+
+### Ruby
+On the command line run:
+```bash
+gem install netrc
+irb -r controls
+```
+
+Once you open IRB run:
+```ruby
+# Allow connections to Nexpose's self-signed cert
+Controls.middleware.ssl[:verify] = false
+
+client = Controls::Client.new({
+    :api_endpoint => 'https://nexpose.local:3780/insight/controls/api/1.0',
+    :web_endpoint => 'https://nexpose.local:3780/insight/controls',
+    :netrc => true,
+    :netrc_file => '~/.rapid7_netrc'
+})
+```
+
+**NOTE**: The **controls** Ruby client doesn't enable or install netrc support by default. You must follow the preceding instructions to enable it.
+# Status & Error Codes
+## Success
+<table>
+<tr><th>Status Code</th><th>Status</th><th>Description</th></tr>
+<tr><td>200</td><td>OK</td><td>The request was successful (includes a hash/array for the requested resource)</td></tr>
+</table>
+
+## Failure
+<table>
+<tr><th>Status Code</th><th>Status</th><th>Description</th></tr>
+<tr><td>401</td><td>Unauthorized</td><td>The request didn't contain any information for authentication</td></tr>
+<tr><td>403</td><td>Bad Request</td><td>The query parameters you supplied were invalid</td></tr>
+<tr><td>404</td><td>Not Found</td><td>The resource(s) you requested couldn't be found (returns an error message)</td></tr>
+</table>
+
+## Example Error JSON
+```json
+{
+    "status": 404,
+    "messsage": "The resource x could not be found."
+}
+```

data/lib/controls/client.rb

@@ -8,6 +8,7 @@ require 'controls/client/assets'
 require 'controls/client/guidance'
 require 'controls/client/security_controls'
 require 'controls/client/threats'
+require 'controls/client/trends'
 require 'controls/response'
 
 module Controls
@@ -20,6 +21,7 @@ module Controls
     include Controls::Client::Guidance
     include Controls::Client::SecurityControls
     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`.",
@@ -78,7 +80,7 @@ module Controls
       url = URI.escape(File.join(api_endpoint, path))
       resp = middleware.get(url, params, headers)
 
-      Response.generate_ruby(resp.body)
+      Response.parse(resp.body)
     rescue Faraday::Error::ConnectionFailed => e
       if e.message =~ /^SSL_connect/
         warn(*SSL_WARNING)
@@ -96,8 +98,7 @@ module Controls
       url = URI.escape(File.join(web_endpoint, path))
       resp = middleware.get(url, params, headers)
 
-      # Response.parse(resp.body)
-      Response.generate_ruby(resp.body)
+      Response.parse(resp.body)
     rescue Faraday::Error::ConnectionFailed => e
       if e.message =~ /^SSL_connect/
         warn(*SSL_WARNING)

data/lib/controls/client/assessments.rb

@@ -4,6 +4,8 @@ module Controls
     # @since API v1.0
     # @version v1.0.0
     module Assessments
+      # @!group Assessment Methods
+
       # @return [Array<Hash>] an array of assessment hashes
       def assessments(assessment_id = nil)
         if assessment_id
@@ -12,6 +14,8 @@ module Controls
           get '/assessments'
         end
       end
+
+      # @!endgroup
     end
   end
 end

data/lib/controls/client/assets.rb

@@ -3,8 +3,9 @@ module Controls
     # A module to encapsulate API methods related to assets
     # @since API v1.0
     # @version v1.0.0
-    # TODO: Update docs
     module Assets
+      # @!group Asset Methods
+
       # @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
@@ -59,6 +60,8 @@ module Controls
         get "/threat_vectors/#{threat_vector}/undefended_assets", params
       end
       alias_method :assets_by_threat_vector, :undefended_assets
+
+      # @!endgroup
     end
   end
 end

data/lib/controls/client/guidance.rb

@@ -16,30 +16,12 @@ module Controls
         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

data/lib/controls/client/prioritized_guidance.rb

@@ -29,6 +29,8 @@ module Controls
       def prioritized_guidance_by_threat_vector(threat_vector)
         get "/threat_vectors/#{threat_vector}/prioritized_guidance"
       end
+
+      # @!endgroup
     end
   end
 end

data/lib/controls/client/trends.rb

@@ -0,0 +1,39 @@
+module Controls
+  class Client
+    # A module to encapsulate API methods related to trends
+    # @since API v1.0
+    # @version v1.0.1
+    module Trends
+      # @!group Trending Methods
+
+      # @param [String] configuration the name of the configuration for which
+      #   to receive trending for
+      # @return [Array<Hash>] a list of hashes representing trending data over
+      #   time
+      def configuration_trends(configuration)
+        get "/configurations/#{configuration}/trend"
+      end
+      alias_method :trends_by_configuration, :configuration_trends
+
+      # @param [String] threat the name of the threat for which
+      #   to receive trending for
+      # @return [Array<Hash>] a list of hashes representing trending data over
+      #   time
+      def threat_trends(threat)
+        get "/threats/#{threat}/trend"
+      end
+      alias_method :trends_by_threat, :threat_trends
+
+      # @param [String] threat_vector the name of the threat_vector for which
+      #   to receive trending for
+      # @return [Array<Hash>] a list of hashes representing trending data over
+      #   time
+      def threat_vector_trends(threat_vector)
+        get "/threat_vectors/#{threat_vector}/trend"
+      end
+      alias_method :trends_by_threat_vector, :threat_vector_trends
+
+      # @!endgroup
+    end
+  end
+end

data/lib/controls/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: controls
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Erran Carey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-17 00:00:00.000000000 Z
+date: 2013-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -138,6 +138,7 @@ files:
 - controls.gemspec
 - docs/images/controlsinsight+shield.png
 - docs/images/controlsinsight.png
+- docs/index.md
 - lib/controls.rb
 - lib/controls/authentication.rb
 - lib/controls/client.rb
@@ -149,6 +150,7 @@ files:
 - lib/controls/client/security_controls.rb
 - lib/controls/client/threat_vectors.rb
 - lib/controls/client/threats.rb
+- lib/controls/client/trends.rb
 - lib/controls/configurable.rb
 - lib/controls/default.rb
 - lib/controls/error.rb
@@ -177,7 +179,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.9
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: This gem interfaces to Rapid7's **controls**insight API.