controls 1.4.1 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: ffc3d3842ad89d5a63367335b5a2f8bda6b72496
4
- data.tar.gz: 3d85a25d50b38738c991d10f1ae06732c2c73b99
3
+ metadata.gz: c4537831e815a135b460f87a742e2a209e07de54
4
+ data.tar.gz: e4a587053968dfa775c9b3e48a311cf1731fb3af
5
5
  SHA512:
6
- metadata.gz: 709a94c513400fdb01cd5098ead2ad7a06b1f715a92411c56eccfa2314330f99f6b91e0afab42a1729db7ef2b5f73f73a19110958f98baf106728fbd015d1f68
7
- data.tar.gz: 98f40db087370405792c59cfcdba2cd80dccb6988fb0670488170fa046c8f20c8bcf659fe4fd13b7dcc9d8d1a8d55ef5fe702f2864b2f26de2bfd098feeaa44b
6
+ metadata.gz: 5cb13b0f70613104b6b3984622d57b5f0fbcac877a9e6d1b9f05b30d7724953a79bbc532132711bad8646e2062ce8d54de7fca99b1fc7aa531c3f2f4e9ec259c
7
+ data.tar.gz: c41b7b8797867824501d6577b213ba9965b8394919fcf1d6f7f071013f579b66138946d61ae7accf9f562e018a6848ced372a785c7f558942e66dd4d10e3c45a
data/README.md CHANGED
@@ -4,15 +4,19 @@ The **controls**insight (controls) gem interfaces with [Rapid7's **controls**ins
4
4
  ## Installation
5
5
  Add this line to your application's Gemfile:
6
6
 
7
- gem 'controls'
7
+ ```ruby
8
+ gem 'controls'
9
+ ```
8
10
 
9
11
  And then execute:
10
-
11
- $ bundle
12
+ ```bash
13
+ bundle
14
+ ```
12
15
 
13
16
  Or install it yourself as:
14
-
15
- $ gem install controls
17
+ ```bash
18
+ gem install controls
19
+ ```
16
20
 
17
21
  ## Documentation
18
22
  * [API documentation](http://rapid7.github.io/controlsinsight.rb)
@@ -29,18 +33,21 @@ Controls.verify_ssl = false
29
33
 
30
34
  Controls.login :user => 'admin', :password => 'password'
31
35
 
32
- Controls.client.methods
36
+ Controls.client.api_methods
37
+ # => [:applicable_assets, :assessments, :asset_search, :assets, :assets_by_configuration, :assets_by_guidance, ..., :uncovered_assets, :undefended_assets, :update_security_controls]
33
38
  ```
34
39
 
35
40
  ### Assessments
36
41
  ```ruby
37
42
  # Retrieve all the assessments that have been ran
38
43
  Controls.assessments
39
- # => TODO: Add example output
44
+ # => [#<Controls::Assessment: id: 1, timestamp: 2013-12-15 10:07:39 -0600, assessing: false, high_risk_asset_count: 18,
45
+ # medium_risk_asset_count: 0, low_risk_asset_count: 0, total_asset_count: 18, overall_risk_score: 1.1723226070935302>]
40
46
 
41
47
  # Only retrieve a single assessment
42
- Controls.assessments(1)
43
- # => TODO: Add example output
48
+ Controls.assessments(2)
49
+ # => #<Controls::Assessment: id: 2, timestamp: 2014-02-06 17:35:02 -0600, assessing: false, high_risk_asset_count: 0,
50
+ # medium_risk_asset_count: 42, low_risk_asset_count: 0, total_asset_count: 42, overall_risk_score: 3.687419753008327>
44
51
  ```
45
52
 
46
53
 
@@ -48,56 +55,125 @@ Controls.assessments(1)
48
55
  ```ruby
49
56
  # Retrieve a list of all the assets that Controls has access to
50
57
  Controls.assets
51
- # => TODO: Add example output
58
+ # => [
59
+ # #<Controls::Asset: discovered_at: 2013-12-15 09:55:47 -0600, operating_system: Windows 7 Professional Edition,
60
+ # operating_system_certainty: 1.0, security_control_findings: [...], risk_level: MEDIUM, risk_score:
61
+ # 5.554266115196547, owner: Administrator, name: 10.4.19.25, host_name: CMMNCTR2K7R2-U, ipaddress: 10.4.19.25,
62
+ # uuid: db899a57-347c-4df9-9ce2-6932dc4adf38>,
63
+ # ...
64
+ # ]
52
65
 
53
66
  # Only retrieve a single assessment
54
- Controls.assets('your-asset-uuid-here')
55
- # => TODO: Add example output
67
+ Controls.assets('335fb288-da73-4d3c-afe9-b6a1506bf907')
68
+ # => #<Controls::Asset: discovered_at: 2013-12-15 09:55:48 -0600, operating_system: Windows 7 Enterprise Edition,
69
+ # operating_system_certainty: 1.0, security_control_findings: [...], risk_level: MEDIUM, risk_score:
70
+ # 4.724118340950002, owner: Administrator, name: 10.4.19.24, host_name: V-OFC-COMPAT-P, ipaddress: 10.4.19.24,
71
+ # uuid: 335fb288-da73-4d3c-afe9-b6a1506bf907>
72
+ ```
73
+
74
+ ### Configuration
75
+ ```ruby
76
+ Controls.configurations
77
+ # => [
78
+ # #<Controls::Configuration: coverage: #<Controls::CoverageItem: total: 42, covered: 1, uncovered: 41, percent_covered: 2.380952380952381>, assessment_timestamp: 2014-02-06 17:58:06 -0600,
79
+ # name: unique-password, title: unique password>
80
+ # ...,
81
+ # #<Controls::Configuration: coverage: #<Controls::CoverageItem: total: 3, covered: 3, uncovered: 0, percent_covered: 100.0>, assessment_timestamp: 2014-02-06 17:58:06 -0600,
82
+ # name: email-attachment-filtering-enabled, title: E-mail client attachment filtering enabled>
83
+ # ]
84
+
85
+ Controls.configurations('antivirus-installed')
86
+ # => #<Controls::Configuration: coverage: #<Dish::Plate:0x007fb052ce9e10>, assessment_timestamp: 2014-02-06 17:58:06 -0600,
87
+ # name: antivirus-installed, title: antivirus installed>
56
88
  ```
57
89
 
58
90
  ### Guidance
59
91
  ```ruby
92
+ # Retreive a list of guidance applicable to a specific threat
93
+ Controls.guidance_by_threat('overall-malware')
94
+ # => [...]
95
+
60
96
  # Only retrieve a single guidance by name
61
97
  Controls.guidance('your-guidance-name-here')
62
- # => TODO: Add example output
98
+ # => #<Dish::Plate: assessment_timestamp: 1391731086251, sans_reference: , dsd_reference: , nist_reference: ,
99
+ # sections: [...], domain: Desktop, references: [...], target_grade: 3.2759693577089286, improvement_delta:
100
+ # 0.007545795822296775, improvement_grade: 3.2759693577089286, name: enable-uac, title: Enable User Account Control (UAC)>
63
101
 
64
- Controls.guidance_by_threat('overall-malware')
65
- # => TODO: Add example output
102
+ Controls.prioritized_guidance_by_security_control('desktops-with-antivirus-deployed').count
103
+ # => 3
104
+ ```
105
+
106
+ ### Security Controls
107
+ ```ruby
108
+ Controls.security_controls
109
+ # => [
110
+ # #<Controls::SecurityControl: enabled: true, name: desktops-with-up-to-date-high-risk-applications>,
111
+ # ...,
112
+ # #<Controls::SecurityControl: enabled: true, name: desktops-with-email-attachment-filtering-enabled>
113
+ # ]
114
+
115
+ Controls.security_controls('code-execution-prevention')
116
+ # => #<Controls::SecurityControl: enabled: true, name: code-execution-prevention>
117
+ ```
118
+
119
+ ### Security Control Coverage
120
+ ```ruby
121
+ Controls.security_control_coverage
122
+ # => [
123
+ # #<Controls::SecurityControlCoverage: enabled: true, coverage: #<Controls::CoverageItem: total: 20, covered: 6,
124
+ # uncovered: 14, percent_covered: 30.0>,
125
+ # assessment_timestamp: 2014-02-06 17:58:06 -0600, name: desktops-with-up-to-date-high-risk-applications,
126
+ # title: high-risk applications up to date>,
127
+ # ...,
128
+ # #<Controls::SecurityControlCoverage: enabled: true, coverage: #<Controls::CoverageItem: total: 3, covered: 3,
129
+ # uncovered: 0, percent_covered: 100.0>,
130
+ # assessment_timestamp: 2014-02-06 17:58:06 -0600, name: desktops-with-email-attachment-filtering-enabled,
131
+ # title: e-mail client attachment filtering enabled>
132
+ # ]
133
+
134
+ Controls.security_controls('code-execution-prevention')
135
+ # => #<Controls::SecurityControlCoverage: enabled: true, coverage: #<Controls::CoverageItem: total: 42, covered: 0, uncovered: 42, percent_covered: 0.0>,
136
+ # assessment_timestamp: 2014-02-06 17:58:06 -0600, name: code-execution-prevention, title: code execution prevention deployed>
66
137
  ```
67
138
 
68
139
  ### Threats
69
140
  ```ruby
70
141
  # Retrieve a list of all the threats
71
142
  Controls.threats
72
- # => TODO: Add example output
143
+ # => [#<Controls::Threat: grade: 3, assessment_timestamp: 2014-02-06 17:58:06 -0600, grade_level: POOR, name: overall-malware, title: Overall>]
73
144
 
74
145
  # Only retrieve a single threat
75
- Controls.threats('threat-name-here')
76
- # => TODO: Add example output
146
+ Controls.threats('overall-malware')
147
+ # => #<Controls::Threat: grade: 3, assessment_timestamp: 2014-02-06 17:58:06 -0600, grade_level: POOR, name: overall-malware, title: Overall>
77
148
  ```
78
149
 
79
150
  ### Threat Vectors
80
151
  ```ruby
81
152
  # Retrieve a list of all the threat vectors
82
153
  Controls.threat_vectors
83
- # => TODO: Add example output
154
+ # => [#<Controls::ThreatVector: grade: 3, assessment_timestamp: 2014-02-06 17:58:06 -0600, grade_level: POOR, name:
155
+ 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>]
84
156
 
85
157
  # Only retrieve a single threat vector
86
- Controls.threat_vectors('vector-name-here')
87
- # => TODO: Add example output
158
+ Controls.threat_vectors('network-borne')
159
+ # => #<Controls::ThreatVector: grade: 3, assessment_timestamp: 2014-02-06 17:58:06 -0600, grade_level: POOR, name: network-borne, title: Network>
88
160
  ```
89
161
 
90
- # Trends
162
+ ### Trends
91
163
  ```ruby
92
164
  # Retrieve a set of statistics over time
93
- Controls.threat_trends('threat-name-here')
94
- # => TODO: Add example output
95
-
96
- Controls.threat_vector_trends('vector-name-here')
97
- # => TODO: Add example output
98
-
99
- Controls.configuration_trends('configuration-name-here')
100
- # => TODO: Add example output
165
+ Controls.threat_trends('overall-malware')
166
+ # => [#<Controls::Trend: grade: 1.1723226070935302, assessment_timestamp: 2013-12-15 10:07:39 -0600, total_assets: 18>,
167
+ # #<Controls::Trend: grade: 3.2684235618866317, assessment_timestamp: 2014-02-06 17:58:06 -0600, total_assets: 42>]
168
+
169
+ Controls.threat_vector_trends('network-borne')
170
+ # => [#<Controls::Trend: grade: 1.0187000110028335, assessment_timestamp: 2013-12-15 10:07:39 -0600, total_assets: 18>,
171
+ # #<Controls::Trend: grade: 3.497538201261831, assessment_timestamp: 2014-02-06 17:58:06 -0600, total_assets: 42>]
172
+
173
+ Controls.configuration_trends('antivirus-installed')
174
+ # => [#<Controls::Trend: assessment_timestamp: 2013-12-15 10:07:39 -0600, total_assets: 18, covered_assets: 0,
175
+ # covered_percentage: 0.0>, #<Controls::Trend: assessment_timestamp: 2014-02-06 17:58:06 -0600, total_assets: 42,
176
+ # covered_assets: 9, covered_percentage: 21.428571428571427>]
101
177
  ```
102
178
 
103
179
  ## License
@@ -1,6 +1,9 @@
1
+ require 'controls/objects/coverage_information'
2
+
1
3
  module Controls
2
4
  class Configuration < Dish::Plate
3
5
  coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
6
+ coerce :coverage, Controls::CoverageInformation
4
7
 
5
8
  def to_s
6
9
  title
@@ -0,0 +1,8 @@
1
+ module Controls
2
+ class CoverageInformation < Dish::Plate
3
+ def to_s
4
+ # [todo] - generate this
5
+ "#<#{self.class}: total: #{total}, covered: #{covered}, uncovered: #{uncovered}, percent_covered: #{percent_covered}>"
6
+ end
7
+ end
8
+ end
@@ -1,6 +1,9 @@
1
+ require 'controls/objects/coverage_information'
2
+
1
3
  module Controls
2
4
  class SecurityControlCoverage < Dish::Plate
3
5
  coerce :assessmentTimestamp, ->(value) { Time.at(value / 1000) if value }
6
+ coerce :coverage, Controls::CoverageInformation
4
7
 
5
8
  def to_s
6
9
  title
@@ -16,7 +16,7 @@ module Controls
16
16
  Controls::SecurityControlCoverage
17
17
  when /(configuration|event|guidance|prioritized_guidance|security_control|threat_vector|trend)s?$/
18
18
  Controls.const_get(Regexp.last_match[1].split('_').map(&:capitalize).join)
19
- when %r(^(?:/\d.\d)?\/(assessment|configuration|threat|threat_vector)s)
19
+ when %r(^(?:/\d.\d)?\/(assessment|configuration|security_control|threat|threat_vector)s)
20
20
  Controls.const_get(Regexp.last_match[1].split('_').map(&:capitalize).join)
21
21
  when /((?:applicable|miconfigured|uncovered|undefended)?_?asset)s$/
22
22
  Controls.const_get('AssetCollection')
@@ -1,4 +1,4 @@
1
1
  module Controls
2
2
  # The version of the Controls gem
3
- VERSION = '1.4.1'
3
+ VERSION = '1.5.0'
4
4
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: controls
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.4.1
4
+ version: 1.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Erran Carey
@@ -181,6 +181,7 @@ files:
181
181
  - lib/controls/objects/asset.rb
182
182
  - lib/controls/objects/configuration.rb
183
183
  - lib/controls/objects/configuration_finding.rb
184
+ - lib/controls/objects/coverage_information.rb
184
185
  - lib/controls/objects/guidance.rb
185
186
  - lib/controls/objects/security_control.rb
186
187
  - lib/controls/objects/security_control_coverage.rb