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:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: c4537831e815a135b460f87a742e2a209e07de54
|
4
|
+
data.tar.gz: e4a587053968dfa775c9b3e48a311cf1731fb3af
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
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
|
-
|
7
|
+
```ruby
|
8
|
+
gem 'controls'
|
9
|
+
```
|
8
10
|
|
9
11
|
And then execute:
|
10
|
-
|
11
|
-
|
12
|
+
```bash
|
13
|
+
bundle
|
14
|
+
```
|
12
15
|
|
13
16
|
Or install it yourself as:
|
14
|
-
|
15
|
-
|
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.
|
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
|
-
# =>
|
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(
|
43
|
-
# =>
|
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
|
-
# =>
|
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('
|
55
|
-
# =>
|
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
|
-
# =>
|
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.
|
65
|
-
# =>
|
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
|
-
# =>
|
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('
|
76
|
-
# =>
|
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
|
-
# =>
|
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('
|
87
|
-
# =>
|
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
|
-
|
162
|
+
### Trends
|
91
163
|
```ruby
|
92
164
|
# Retrieve a set of statistics over time
|
93
|
-
Controls.threat_trends('
|
94
|
-
# =>
|
95
|
-
|
96
|
-
|
97
|
-
|
98
|
-
|
99
|
-
Controls.
|
100
|
-
|
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
|
data/lib/controls/response.rb
CHANGED
@@ -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')
|
data/lib/controls/version.rb
CHANGED
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
|
+
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
|