controls 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ffc3d3842ad89d5a63367335b5a2f8bda6b72496
-  data.tar.gz: 3d85a25d50b38738c991d10f1ae06732c2c73b99
+  metadata.gz: c4537831e815a135b460f87a742e2a209e07de54
+  data.tar.gz: e4a587053968dfa775c9b3e48a311cf1731fb3af
 SHA512:
-  metadata.gz: 709a94c513400fdb01cd5098ead2ad7a06b1f715a92411c56eccfa2314330f99f6b91e0afab42a1729db7ef2b5f73f73a19110958f98baf106728fbd015d1f68
-  data.tar.gz: 98f40db087370405792c59cfcdba2cd80dccb6988fb0670488170fa046c8f20c8bcf659fe4fd13b7dcc9d8d1a8d55ef5fe702f2864b2f26de2bfd098feeaa44b
+  metadata.gz: 5cb13b0f70613104b6b3984622d57b5f0fbcac877a9e6d1b9f05b30d7724953a79bbc532132711bad8646e2062ce8d54de7fca99b1fc7aa531c3f2f4e9ec259c
+  data.tar.gz: c41b7b8797867824501d6577b213ba9965b8394919fcf1d6f7f071013f579b66138946d61ae7accf9f562e018a6848ced372a785c7f558942e66dd4d10e3c45a

data/README.md

@@ -4,15 +4,19 @@ The **controls**insight (controls) gem interfaces with [Rapid7's **controls**ins
 ## Installation
 Add this line to your application's Gemfile:
 
-    gem 'controls'
+```ruby
+gem 'controls'
+```
 
 And then execute:
-
-    $ bundle
+```bash
+bundle
+```
 
 Or install it yourself as:
-
-    $ gem install controls
+```bash
+gem install controls
+```
 
 ## Documentation
 * [API documentation](http://rapid7.github.io/controlsinsight.rb)
@@ -29,18 +33,21 @@ Controls.verify_ssl = false
 
 Controls.login :user => 'admin', :password => 'password'
 
-Controls.client.methods
+Controls.client.api_methods
+# => [:applicable_assets, :assessments, :asset_search, :assets, :assets_by_configuration, :assets_by_guidance, ..., :uncovered_assets, :undefended_assets, :update_security_controls]
 ```
 
 ### Assessments
 ```ruby
 # Retrieve all the assessments that have been ran
 Controls.assessments
-# => TODO: Add example output
+# => [#<Controls::Assessment: id: 1, timestamp: 2013-12-15 10:07:39 -0600, assessing: false, high_risk_asset_count: 18,
+#     medium_risk_asset_count: 0, low_risk_asset_count: 0, total_asset_count: 18, overall_risk_score: 1.1723226070935302>]
 
 # Only retrieve a single assessment
-Controls.assessments(1)
-# => TODO: Add example output
+Controls.assessments(2)
+# => #<Controls::Assessment: id: 2, timestamp: 2014-02-06 17:35:02 -0600, assessing: false, high_risk_asset_count: 0,
+#    medium_risk_asset_count: 42, low_risk_asset_count: 0, total_asset_count: 42, overall_risk_score: 3.687419753008327>
 ```
 
 
@@ -48,56 +55,125 @@ Controls.assessments(1)
 ```ruby
 # Retrieve a list of all the assets that Controls has access to
 Controls.assets
-# => TODO: Add example output
+# => [
+#      #<Controls::Asset: discovered_at: 2013-12-15 09:55:47 -0600, operating_system: Windows 7 Professional Edition,
+#      operating_system_certainty: 1.0, security_control_findings: [...], risk_level: MEDIUM, risk_score:
+#      5.554266115196547, owner: Administrator, name: 10.4.19.25, host_name: CMMNCTR2K7R2-U, ipaddress: 10.4.19.25,
+#      uuid: db899a57-347c-4df9-9ce2-6932dc4adf38>,
+#      ...
+#    ]
 
 # Only retrieve a single assessment
-Controls.assets('your-asset-uuid-here')
-# => TODO: Add example output
+Controls.assets('335fb288-da73-4d3c-afe9-b6a1506bf907')
+# => #<Controls::Asset: discovered_at: 2013-12-15 09:55:48 -0600, operating_system: Windows 7 Enterprise Edition, 
+#    operating_system_certainty: 1.0, security_control_findings: [...], risk_level: MEDIUM, risk_score: 
+#    4.724118340950002, owner: Administrator, name: 10.4.19.24, host_name: V-OFC-COMPAT-P, ipaddress: 10.4.19.24,
+#    uuid: 335fb288-da73-4d3c-afe9-b6a1506bf907>
+```
+
+### Configuration
+```ruby
+Controls.configurations
+# => [
+#      #<Controls::Configuration: coverage: #<Controls::CoverageItem: total: 42, covered: 1, uncovered: 41, percent_covered: 2.380952380952381>, assessment_timestamp: 2014-02-06 17:58:06 -0600,
+#      name: unique-password, title: unique password>
+#      ...,
+#      #<Controls::Configuration: coverage: #<Controls::CoverageItem: total: 3, covered: 3, uncovered: 0, percent_covered: 100.0>, assessment_timestamp: 2014-02-06 17:58:06 -0600,
+#      name: email-attachment-filtering-enabled, title: E-mail client attachment filtering enabled>
+#    ]
+
+Controls.configurations('antivirus-installed')
+# => #<Controls::Configuration: coverage: #<Dish::Plate:0x007fb052ce9e10>, assessment_timestamp: 2014-02-06 17:58:06 -0600,
+#    name: antivirus-installed, title: antivirus installed>
 ```
 
 ### Guidance
 ```ruby
+# Retreive a list of guidance applicable to a specific threat
+Controls.guidance_by_threat('overall-malware')
+# => [...]
+
 # Only retrieve a single guidance by name
 Controls.guidance('your-guidance-name-here')
-# => TODO: Add example output
+# => #<Dish::Plate: assessment_timestamp: 1391731086251, sans_reference: , dsd_reference: , nist_reference: , 
+#    sections: [...], domain: Desktop, references: [...], target_grade: 3.2759693577089286, improvement_delta: 
+#    0.007545795822296775, improvement_grade: 3.2759693577089286, name: enable-uac, title: Enable User Account Control (UAC)>
 
-Controls.guidance_by_threat('overall-malware')
-# => TODO: Add example output
+Controls.prioritized_guidance_by_security_control('desktops-with-antivirus-deployed').count
+# => 3
+```
+
+### Security Controls
+```ruby
+Controls.security_controls
+# => [
+#      #<Controls::SecurityControl: enabled: true, name: desktops-with-up-to-date-high-risk-applications>,
+#      ...,
+#      #<Controls::SecurityControl: enabled: true, name: desktops-with-email-attachment-filtering-enabled>
+#    ]
+
+Controls.security_controls('code-execution-prevention')
+# => #<Controls::SecurityControl: enabled: true, name: code-execution-prevention>
+```
+
+### Security Control Coverage
+```ruby
+Controls.security_control_coverage
+# => [
+#      #<Controls::SecurityControlCoverage: enabled: true, coverage: #<Controls::CoverageItem: total: 20, covered: 6,
+#      uncovered: 14, percent_covered: 30.0>,
+#      assessment_timestamp: 2014-02-06 17:58:06 -0600, name: desktops-with-up-to-date-high-risk-applications,
+#      title: high-risk applications up to date>,
+#      ...,
+#      #<Controls::SecurityControlCoverage: enabled: true, coverage: #<Controls::CoverageItem: total: 3, covered: 3,
+#      uncovered: 0, percent_covered: 100.0>,
+#      assessment_timestamp: 2014-02-06 17:58:06 -0600, name: desktops-with-email-attachment-filtering-enabled,
+#      title: e-mail client attachment filtering enabled>
+#    ]
+
+Controls.security_controls('code-execution-prevention')
+# => #<Controls::SecurityControlCoverage: enabled: true, coverage: #<Controls::CoverageItem: total: 42, covered: 0, uncovered: 42, percent_covered: 0.0>,
+#    assessment_timestamp: 2014-02-06 17:58:06 -0600, name: code-execution-prevention, title: code execution prevention deployed>
 ```
 
 ### Threats
 ```ruby
 # Retrieve a list of all the threats
 Controls.threats
-# => TODO: Add example output
+# => [#<Controls::Threat: grade: 3, assessment_timestamp: 2014-02-06 17:58:06 -0600, grade_level: POOR, name: overall-malware, title: Overall>]
 
 # Only retrieve a single threat
-Controls.threats('threat-name-here')
-# => TODO: Add example output
+Controls.threats('overall-malware')
+# => #<Controls::Threat: grade: 3, assessment_timestamp: 2014-02-06 17:58:06 -0600, grade_level: POOR, name: overall-malware, title: Overall>
 ```
 
 ### Threat Vectors
 ```ruby
 # Retrieve a list of all the threat vectors
 Controls.threat_vectors
-# => TODO: Add example output
+# => [#<Controls::ThreatVector: grade: 3, assessment_timestamp: 2014-02-06 17:58:06 -0600, grade_level: POOR, name:
+network-borne, title: Network>, ..., #<Controls::ThreatVector: grade: 3, assessment_timestamp: 2014-02-06 17:58:06 -0600, grade_level: POOR, name: email-borne, title: E-mail>]
 
 # Only retrieve a single threat vector
-Controls.threat_vectors('vector-name-here')
-# => TODO: Add example output
+Controls.threat_vectors('network-borne')
+# => #<Controls::ThreatVector: grade: 3, assessment_timestamp: 2014-02-06 17:58:06 -0600, grade_level: POOR, name: network-borne, title: Network>
 ```
 
-# Trends
+### 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
+Controls.threat_trends('overall-malware')
+# => [#<Controls::Trend: grade: 1.1723226070935302, assessment_timestamp: 2013-12-15 10:07:39 -0600, total_assets: 18>,
+#     #<Controls::Trend: grade: 3.2684235618866317, assessment_timestamp: 2014-02-06 17:58:06 -0600, total_assets: 42>]
+
+Controls.threat_vector_trends('network-borne')
+# => [#<Controls::Trend: grade: 1.0187000110028335, assessment_timestamp: 2013-12-15 10:07:39 -0600, total_assets: 18>,
+#     #<Controls::Trend: grade: 3.497538201261831, assessment_timestamp: 2014-02-06 17:58:06 -0600, total_assets: 42>]
+
+Controls.configuration_trends('antivirus-installed')
+# => [#<Controls::Trend: assessment_timestamp: 2013-12-15 10:07:39 -0600, total_assets: 18, covered_assets: 0,
+#     covered_percentage: 0.0>, #<Controls::Trend: assessment_timestamp: 2014-02-06 17:58:06 -0600, total_assets: 42,
+#     covered_assets: 9, covered_percentage: 21.428571428571427>]
 ```
 
 ## License

data/lib/controls/objects/configuration.rb

@@ -1,6 +1,9 @@
+require 'controls/objects/coverage_information'
+
 module Controls
   class Configuration < Dish::Plate
     coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+    coerce :coverage, Controls::CoverageInformation
 
     def to_s
       title

data/lib/controls/objects/coverage_information.rb

@@ -0,0 +1,8 @@
+module Controls
+  class CoverageInformation < Dish::Plate
+    def to_s
+      # [todo] - generate this
+      "#<#{self.class}: total: #{total}, covered: #{covered}, uncovered: #{uncovered}, percent_covered: #{percent_covered}>"
+    end
+  end
+end

data/lib/controls/objects/security_control_coverage.rb

@@ -1,6 +1,9 @@
+require 'controls/objects/coverage_information'
+
 module Controls
   class SecurityControlCoverage < Dish::Plate
     coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
+    coerce :coverage, Controls::CoverageInformation
 
     def to_s
       title

data/lib/controls/response.rb

@@ -16,7 +16,7 @@ module Controls
           Controls::SecurityControlCoverage
         when /(configuration|event|guidance|prioritized_guidance|security_control|threat_vector|trend)s?$/
           Controls.const_get(Regexp.last_match[1].split('_').map(&:capitalize).join)
-        when %r(^(?:/\d.\d)?\/(assessment|configuration|threat|threat_vector)s)
+        when %r(^(?:/\d.\d)?\/(assessment|configuration|security_control|threat|threat_vector)s)
           Controls.const_get(Regexp.last_match[1].split('_').map(&:capitalize).join)
         when /((?:applicable|miconfigured|uncovered|undefended)?_?asset)s$/
           Controls.const_get('AssetCollection')

data/lib/controls/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: controls
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Erran Carey
@@ -181,6 +181,7 @@ files:
 - lib/controls/objects/asset.rb
 - lib/controls/objects/configuration.rb
 - lib/controls/objects/configuration_finding.rb
+- lib/controls/objects/coverage_information.rb
 - lib/controls/objects/guidance.rb
 - lib/controls/objects/security_control.rb
 - lib/controls/objects/security_control_coverage.rb