controls 1.0.0 → 1.0.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/LICENSE.md +23 -16
- data/README.md +30 -4
- data/docs/index.md +86 -0
- data/lib/controls/client.rb +4 -3
- data/lib/controls/client/assessments.rb +4 -0
- data/lib/controls/client/assets.rb +4 -1
- data/lib/controls/client/guidance.rb +0 -18
- data/lib/controls/client/prioritized_guidance.rb +2 -0
- data/lib/controls/client/trends.rb +39 -0
- data/lib/controls/version.rb +1 -1
- metadata +5 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 8b246a67459339490b8d0afcdf27f033bc458b6e
|
4
|
+
data.tar.gz: ee9b5eab69a2e4add533df170ea443c5f4d314cc
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 6f3cca4615165876ece9886fbafb87db819d875e09c62511e0631c66ea643e958b9d353abd90337601ec426ede94d0918095b5edb84046d22c8ef37ef1701df8
|
7
|
+
data.tar.gz: e4267b9510bab07d0214a4879456190be7fb6d3e14b0035dbad50d2f4561153596bc91904d21b7264e271bd853323fbcf54bae8e5bdfb61592a0df845d3de97c
|
data/LICENSE.md
CHANGED
@@ -1,20 +1,27 @@
|
|
1
|
-
|
1
|
+
Copyright (c) 2013, Rapid7 Inc.
|
2
|
+
All rights reserved.
|
2
3
|
|
3
|
-
|
4
|
+
Redistribution and use in source and binary forms, with or without
|
5
|
+
modification, are permitted provided that the following conditions are met:
|
4
6
|
|
5
|
-
|
6
|
-
|
7
|
-
the Software without restriction, including without limitation the rights to
|
8
|
-
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
9
|
-
the Software, and to permit persons to whom the Software is furnished to do so,
|
10
|
-
subject to the following conditions:
|
7
|
+
* Redistributions of source code must retain the above copyright notice, this
|
8
|
+
list of conditions and the following disclaimer.
|
11
9
|
|
12
|
-
|
13
|
-
|
10
|
+
* Redistributions in binary form must reproduce the above copyright notice,
|
11
|
+
this list of conditions and the following disclaimer in the documentation
|
12
|
+
and/or other materials provided with the distribution.
|
14
13
|
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
14
|
+
* Neither the name of the Rapid7 Inc. nor the names of its
|
15
|
+
contributors may be used to endorse or promote products derived from
|
16
|
+
this software without specific prior written permission.
|
17
|
+
|
18
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
19
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
20
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
21
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
22
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
23
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
24
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
25
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
26
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
27
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
data/README.md
CHANGED
@@ -1,5 +1,5 @@
|
|
1
|
-
#
|
2
|
-
The **controls**insight (controls) gem interfaces with [Rapid7's **controls**insight API](http://
|
1
|
+
# controlsinsight client gem
|
2
|
+
The **controls**insight (controls) gem interfaces with [Rapid7's **controls**insight API](http://rapid7.viewdocs.io/controlsinsight.rb).
|
3
3
|
|
4
4
|
## Installation
|
5
5
|
Add this line to your application's Gemfile:
|
@@ -15,8 +15,8 @@ Or install it yourself as:
|
|
15
15
|
$ gem install controls
|
16
16
|
|
17
17
|
## Documentation
|
18
|
-
* [
|
19
|
-
* [YARD documentation for the Ruby client](http://www.rubydoc.info/github/
|
18
|
+
* [viewdocs.io API documentation](http://rapid7.viewdocs.io/controlsinsight.rb)
|
19
|
+
* [YARD documentation for the Ruby client](http://www.rubydoc.info/github/rapid7/controlsinsight.rb)
|
20
20
|
|
21
21
|
## Basic Resources
|
22
22
|
### Authentication
|
@@ -60,6 +60,9 @@ Controls.assets('your-asset-uuid-here')
|
|
60
60
|
# Only retrieve a single guidance by name
|
61
61
|
Controls.guidance('your-guidance-name-here')
|
62
62
|
# => TODO: Add example output
|
63
|
+
|
64
|
+
Controls.guidance_by_threat('overall-malware')
|
65
|
+
# => TODO: Add example output
|
63
66
|
```
|
64
67
|
|
65
68
|
### Threats
|
@@ -73,6 +76,29 @@ Controls.threats('threat-name-here')
|
|
73
76
|
# => TODO: Add example output
|
74
77
|
```
|
75
78
|
|
79
|
+
### Threat Vectors
|
80
|
+
```ruby
|
81
|
+
# Retrieve a list of all the threat vectors
|
82
|
+
Controls.threat_vectors
|
83
|
+
# => TODO: Add example output
|
84
|
+
|
85
|
+
# Only retrieve a single threat vector
|
86
|
+
Controls.threat_vectors('vector-name-here')
|
87
|
+
# => TODO: Add example output
|
88
|
+
```
|
89
|
+
|
90
|
+
# Trends
|
91
|
+
```ruby
|
92
|
+
# 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
|
101
|
+
```
|
76
102
|
|
77
103
|
## License
|
78
104
|
This project was created by [Erran Carey (@ipwnstuff)](http://ipwnstuff.github.io) and licensed under [the MIT License](LICENSE.md).
|
data/docs/index.md
ADDED
@@ -0,0 +1,86 @@
|
|
1
|
+
ControlsInsight API v1.0 (beta)
|
2
|
+
---
|
3
|
+
|
4
|
+
## Overview
|
5
|
+
Rapid7's **controlsinsight**, hereafter **controls**insight or simply **controls**,
|
6
|
+
|
7
|
+
The **controls**insight API v1.0 allow developers to utilize information about security controls, configurations, threats, and more from **controls**.
|
8
|
+
|
9
|
+
This documentation includes custom Curl examples and Ruby examples using the Ruby API client (ipwnstuff/controls.rb).
|
10
|
+
|
11
|
+
Apiary.io also adds example requests in other languages, though they aren't supported tested them.
|
12
|
+
|
13
|
+
To see advanced usage in Ruby read the [Ruby client documentation here](http://www.rubydoc.info/github/rapid7/controlsinsight.rb).
|
14
|
+
|
15
|
+
## Authentication
|
16
|
+
You must authenticate using HTTP Basic Auth when making any of the API requests.
|
17
|
+
|
18
|
+
## Curl
|
19
|
+
See the cURL man pages on how to authenticate.
|
20
|
+
|
21
|
+
```bash
|
22
|
+
# Use -k to allow a self-signed certificate
|
23
|
+
curl --user admin:password https://nexpose.local:3780/insight/controls/api/1.0
|
24
|
+
```
|
25
|
+
|
26
|
+
## Ruby
|
27
|
+
```ruby
|
28
|
+
# Allow connections to Nexpose's self-signed cert
|
29
|
+
Controls.middleware.ssl[:verify] = false
|
30
|
+
|
31
|
+
Controls.login 'admin', 'password'
|
32
|
+
|
33
|
+
# Return the API reference for the current API version
|
34
|
+
Controls.get '/'
|
35
|
+
```
|
36
|
+
|
37
|
+
## Authentication via a `.netrc` file
|
38
|
+
### Curl
|
39
|
+
```bash
|
40
|
+
# Use -k to allow a self-signed certificate
|
41
|
+
curl -H 'Accept: application/json' --netrc-file ~/.rapid7_netrc -ik https://nexpose.local:3780/insight/controls/api/1.0
|
42
|
+
```
|
43
|
+
|
44
|
+
### Ruby
|
45
|
+
On the command line run:
|
46
|
+
```bash
|
47
|
+
gem install netrc
|
48
|
+
irb -r controls
|
49
|
+
```
|
50
|
+
|
51
|
+
Once you open IRB run:
|
52
|
+
```ruby
|
53
|
+
# Allow connections to Nexpose's self-signed cert
|
54
|
+
Controls.middleware.ssl[:verify] = false
|
55
|
+
|
56
|
+
client = Controls::Client.new({
|
57
|
+
:api_endpoint => 'https://nexpose.local:3780/insight/controls/api/1.0',
|
58
|
+
:web_endpoint => 'https://nexpose.local:3780/insight/controls',
|
59
|
+
:netrc => true,
|
60
|
+
:netrc_file => '~/.rapid7_netrc'
|
61
|
+
})
|
62
|
+
```
|
63
|
+
|
64
|
+
**NOTE**: The **controls** Ruby client doesn't enable or install netrc support by default. You must follow the preceding instructions to enable it.
|
65
|
+
# Status & Error Codes
|
66
|
+
## Success
|
67
|
+
<table>
|
68
|
+
<tr><th>Status Code</th><th>Status</th><th>Description</th></tr>
|
69
|
+
<tr><td>200</td><td>OK</td><td>The request was successful (includes a hash/array for the requested resource)</td></tr>
|
70
|
+
</table>
|
71
|
+
|
72
|
+
## Failure
|
73
|
+
<table>
|
74
|
+
<tr><th>Status Code</th><th>Status</th><th>Description</th></tr>
|
75
|
+
<tr><td>401</td><td>Unauthorized</td><td>The request didn't contain any information for authentication</td></tr>
|
76
|
+
<tr><td>403</td><td>Bad Request</td><td>The query parameters you supplied were invalid</td></tr>
|
77
|
+
<tr><td>404</td><td>Not Found</td><td>The resource(s) you requested couldn't be found (returns an error message)</td></tr>
|
78
|
+
</table>
|
79
|
+
|
80
|
+
## Example Error JSON
|
81
|
+
```json
|
82
|
+
{
|
83
|
+
"status": 404,
|
84
|
+
"messsage": "The resource x could not be found."
|
85
|
+
}
|
86
|
+
```
|
data/lib/controls/client.rb
CHANGED
@@ -8,6 +8,7 @@ require 'controls/client/assets'
|
|
8
8
|
require 'controls/client/guidance'
|
9
9
|
require 'controls/client/security_controls'
|
10
10
|
require 'controls/client/threats'
|
11
|
+
require 'controls/client/trends'
|
11
12
|
require 'controls/response'
|
12
13
|
|
13
14
|
module Controls
|
@@ -20,6 +21,7 @@ module Controls
|
|
20
21
|
include Controls::Client::Guidance
|
21
22
|
include Controls::Client::SecurityControls
|
22
23
|
include Controls::Client::Threats
|
24
|
+
include Controls::Client::Trends
|
23
25
|
|
24
26
|
SSL_WARNING = ["The API endpoint used a self-signed or invalid SSL certificate.",
|
25
27
|
"To allow this connection temporarily use `Controls.verify_ssl = false`.",
|
@@ -78,7 +80,7 @@ module Controls
|
|
78
80
|
url = URI.escape(File.join(api_endpoint, path))
|
79
81
|
resp = middleware.get(url, params, headers)
|
80
82
|
|
81
|
-
Response.
|
83
|
+
Response.parse(resp.body)
|
82
84
|
rescue Faraday::Error::ConnectionFailed => e
|
83
85
|
if e.message =~ /^SSL_connect/
|
84
86
|
warn(*SSL_WARNING)
|
@@ -96,8 +98,7 @@ module Controls
|
|
96
98
|
url = URI.escape(File.join(web_endpoint, path))
|
97
99
|
resp = middleware.get(url, params, headers)
|
98
100
|
|
99
|
-
|
100
|
-
Response.generate_ruby(resp.body)
|
101
|
+
Response.parse(resp.body)
|
101
102
|
rescue Faraday::Error::ConnectionFailed => e
|
102
103
|
if e.message =~ /^SSL_connect/
|
103
104
|
warn(*SSL_WARNING)
|
@@ -4,6 +4,8 @@ module Controls
|
|
4
4
|
# @since API v1.0
|
5
5
|
# @version v1.0.0
|
6
6
|
module Assessments
|
7
|
+
# @!group Assessment Methods
|
8
|
+
|
7
9
|
# @return [Array<Hash>] an array of assessment hashes
|
8
10
|
def assessments(assessment_id = nil)
|
9
11
|
if assessment_id
|
@@ -12,6 +14,8 @@ module Controls
|
|
12
14
|
get '/assessments'
|
13
15
|
end
|
14
16
|
end
|
17
|
+
|
18
|
+
# @!endgroup
|
15
19
|
end
|
16
20
|
end
|
17
21
|
end
|
@@ -3,8 +3,9 @@ module Controls
|
|
3
3
|
# A module to encapsulate API methods related to assets
|
4
4
|
# @since API v1.0
|
5
5
|
# @version v1.0.0
|
6
|
-
# TODO: Update docs
|
7
6
|
module Assets
|
7
|
+
# @!group Asset Methods
|
8
|
+
|
8
9
|
# @note since the uuid is an optional param it has been added to the
|
9
10
|
# params options hash
|
10
11
|
# @raise [Controls::NotFound] if the uuid didn't match any assets
|
@@ -59,6 +60,8 @@ module Controls
|
|
59
60
|
get "/threat_vectors/#{threat_vector}/undefended_assets", params
|
60
61
|
end
|
61
62
|
alias_method :assets_by_threat_vector, :undefended_assets
|
63
|
+
|
64
|
+
# @!endgroup
|
62
65
|
end
|
63
66
|
end
|
64
67
|
end
|
@@ -16,30 +16,12 @@ module Controls
|
|
16
16
|
get "/guidance/#{name}"
|
17
17
|
end
|
18
18
|
|
19
|
-
# @param [String] configuration the configuration name to search by
|
20
|
-
# @return [Array<Hash>] an array of "guidance hashes"
|
21
|
-
def guidance_by_configuration(security_control, configuration)
|
22
|
-
get "/configurations/#{configuration}/guidance"
|
23
|
-
end
|
24
|
-
|
25
|
-
# @param [String] security_control the security control name to search by
|
26
|
-
# @return [Array<Hash>] an array of "guidance hashes"
|
27
|
-
def guidance_by_security_control(security_control)
|
28
|
-
get "/security_controls/#{security_control}/guidance"
|
29
|
-
end
|
30
|
-
|
31
19
|
# @param [String] threat the threat name to search by
|
32
20
|
# @return [Array<Hash>] an array of "guidance hashes"
|
33
21
|
def guidance_by_threat(threat)
|
34
22
|
get "/threats/#{threat}/guidance"
|
35
23
|
end
|
36
24
|
|
37
|
-
# @param [String] threat_vector the threat name to search by
|
38
|
-
# @return [Array<Hash>] an array of "guidance hashes"
|
39
|
-
def guidance_by_threat_vector(threat_vector)
|
40
|
-
get "/threat_vectors/#{threat_vector}/guidance"
|
41
|
-
end
|
42
|
-
|
43
25
|
# @!endgroup
|
44
26
|
end
|
45
27
|
end
|
@@ -0,0 +1,39 @@
|
|
1
|
+
module Controls
|
2
|
+
class Client
|
3
|
+
# A module to encapsulate API methods related to trends
|
4
|
+
# @since API v1.0
|
5
|
+
# @version v1.0.1
|
6
|
+
module Trends
|
7
|
+
# @!group Trending Methods
|
8
|
+
|
9
|
+
# @param [String] configuration the name of the configuration for which
|
10
|
+
# to receive trending for
|
11
|
+
# @return [Array<Hash>] a list of hashes representing trending data over
|
12
|
+
# time
|
13
|
+
def configuration_trends(configuration)
|
14
|
+
get "/configurations/#{configuration}/trend"
|
15
|
+
end
|
16
|
+
alias_method :trends_by_configuration, :configuration_trends
|
17
|
+
|
18
|
+
# @param [String] threat the name of the threat for which
|
19
|
+
# to receive trending for
|
20
|
+
# @return [Array<Hash>] a list of hashes representing trending data over
|
21
|
+
# time
|
22
|
+
def threat_trends(threat)
|
23
|
+
get "/threats/#{threat}/trend"
|
24
|
+
end
|
25
|
+
alias_method :trends_by_threat, :threat_trends
|
26
|
+
|
27
|
+
# @param [String] threat_vector the name of the threat_vector for which
|
28
|
+
# to receive trending for
|
29
|
+
# @return [Array<Hash>] a list of hashes representing trending data over
|
30
|
+
# time
|
31
|
+
def threat_vector_trends(threat_vector)
|
32
|
+
get "/threat_vectors/#{threat_vector}/trend"
|
33
|
+
end
|
34
|
+
alias_method :trends_by_threat_vector, :threat_vector_trends
|
35
|
+
|
36
|
+
# @!endgroup
|
37
|
+
end
|
38
|
+
end
|
39
|
+
end
|
data/lib/controls/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: controls
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.0.
|
4
|
+
version: 1.0.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Erran Carey
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2013-
|
11
|
+
date: 2013-11-22 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: activesupport
|
@@ -138,6 +138,7 @@ files:
|
|
138
138
|
- controls.gemspec
|
139
139
|
- docs/images/controlsinsight+shield.png
|
140
140
|
- docs/images/controlsinsight.png
|
141
|
+
- docs/index.md
|
141
142
|
- lib/controls.rb
|
142
143
|
- lib/controls/authentication.rb
|
143
144
|
- lib/controls/client.rb
|
@@ -149,6 +150,7 @@ files:
|
|
149
150
|
- lib/controls/client/security_controls.rb
|
150
151
|
- lib/controls/client/threat_vectors.rb
|
151
152
|
- lib/controls/client/threats.rb
|
153
|
+
- lib/controls/client/trends.rb
|
152
154
|
- lib/controls/configurable.rb
|
153
155
|
- lib/controls/default.rb
|
154
156
|
- lib/controls/error.rb
|
@@ -177,7 +179,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
177
179
|
version: '0'
|
178
180
|
requirements: []
|
179
181
|
rubyforge_project:
|
180
|
-
rubygems_version: 2.
|
182
|
+
rubygems_version: 2.0.3
|
181
183
|
signing_key:
|
182
184
|
specification_version: 4
|
183
185
|
summary: This gem interfaces to Rapid7's **controls**insight API.
|