inspec 2.2.112 → 2.3.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (66) hide show
  1. checksums.yaml +4 -4
  2. data/.rubocop.yml +8 -2
  3. data/CHANGELOG.md +42 -19
  4. data/README.md +1 -1
  5. data/Rakefile +16 -3
  6. data/docs/dev/integration-testing.md +31 -0
  7. data/docs/dev/plugins.md +4 -2
  8. data/docs/dsl_inspec.md +104 -4
  9. data/docs/plugins.md +57 -0
  10. data/docs/resources/aws_ebs_volume.md.erb +76 -0
  11. data/docs/resources/aws_ebs_volumes.md.erb +86 -0
  12. data/docs/style.md +178 -0
  13. data/examples/plugins/inspec-resource-lister/Gemfile +12 -0
  14. data/examples/plugins/inspec-resource-lister/LICENSE +13 -0
  15. data/examples/plugins/inspec-resource-lister/README.md +62 -0
  16. data/examples/plugins/inspec-resource-lister/Rakefile +40 -0
  17. data/examples/plugins/inspec-resource-lister/inspec-resource-lister.gemspec +45 -0
  18. data/examples/plugins/inspec-resource-lister/lib/inspec-resource-lister.rb +16 -0
  19. data/examples/plugins/inspec-resource-lister/lib/inspec-resource-lister/cli_command.rb +70 -0
  20. data/examples/plugins/inspec-resource-lister/lib/inspec-resource-lister/plugin.rb +55 -0
  21. data/examples/plugins/inspec-resource-lister/lib/inspec-resource-lister/version.rb +10 -0
  22. data/examples/plugins/inspec-resource-lister/test/fixtures/README.md +24 -0
  23. data/examples/plugins/inspec-resource-lister/test/functional/README.md +18 -0
  24. data/examples/plugins/inspec-resource-lister/test/functional/inspec_resource_lister_test.rb +110 -0
  25. data/examples/plugins/inspec-resource-lister/test/helper.rb +26 -0
  26. data/examples/plugins/inspec-resource-lister/test/unit/README.md +17 -0
  27. data/examples/plugins/inspec-resource-lister/test/unit/cli_args_test.rb +64 -0
  28. data/examples/plugins/inspec-resource-lister/test/unit/plugin_def_test.rb +51 -0
  29. data/examples/profile/controls/example.rb +9 -8
  30. data/inspec.gemspec +2 -1
  31. data/lib/inspec/attribute_registry.rb +1 -1
  32. data/lib/inspec/globals.rb +4 -0
  33. data/lib/inspec/objects/control.rb +18 -3
  34. data/lib/inspec/plugin/v2.rb +14 -3
  35. data/lib/inspec/plugin/v2/activator.rb +7 -2
  36. data/lib/inspec/plugin/v2/installer.rb +426 -0
  37. data/lib/inspec/plugin/v2/loader.rb +137 -30
  38. data/lib/inspec/plugin/v2/registry.rb +13 -4
  39. data/lib/inspec/profile.rb +2 -1
  40. data/lib/inspec/reporters/json.rb +11 -1
  41. data/lib/inspec/resource.rb +6 -15
  42. data/lib/inspec/rule.rb +18 -9
  43. data/lib/inspec/runner_rspec.rb +1 -1
  44. data/lib/inspec/schema.rb +1 -0
  45. data/lib/inspec/version.rb +1 -1
  46. data/lib/plugins/inspec-plugin-manager-cli/README.md +6 -0
  47. data/lib/plugins/inspec-plugin-manager-cli/lib/inspec-plugin-manager-cli.rb +18 -0
  48. data/lib/plugins/inspec-plugin-manager-cli/lib/inspec-plugin-manager-cli/cli_command.rb +420 -0
  49. data/lib/plugins/inspec-plugin-manager-cli/lib/inspec-plugin-manager-cli/plugin.rb +12 -0
  50. data/lib/plugins/inspec-plugin-manager-cli/test/fixtures/config_dirs/empty/.gitkeep +0 -0
  51. data/lib/plugins/inspec-plugin-manager-cli/test/fixtures/plugins/inspec-egg-white-omelette/lib/inspec-egg-white-omelette.rb +2 -0
  52. data/lib/plugins/inspec-plugin-manager-cli/test/fixtures/plugins/inspec-egg-white-omelette/lib/inspec-egg-white-omelette/.gitkeep +0 -0
  53. data/lib/plugins/inspec-plugin-manager-cli/test/fixtures/plugins/inspec-wrong-structure/.gitkeep +0 -0
  54. data/lib/plugins/inspec-plugin-manager-cli/test/fixtures/plugins/wrong-name/lib/wrong-name.rb +1 -0
  55. data/lib/plugins/inspec-plugin-manager-cli/test/fixtures/plugins/wrong-name/lib/wrong-name/.gitkeep +0 -0
  56. data/lib/plugins/inspec-plugin-manager-cli/test/functional/inspec-plugin_test.rb +651 -0
  57. data/lib/plugins/inspec-plugin-manager-cli/test/unit/cli_args_test.rb +71 -0
  58. data/lib/plugins/inspec-plugin-manager-cli/test/unit/plugin_def_test.rb +20 -0
  59. data/lib/plugins/shared/core_plugin_test_helper.rb +101 -2
  60. data/lib/plugins/things-for-train-integration.rb +14 -0
  61. data/lib/resource_support/aws.rb +2 -0
  62. data/lib/resources/aws/aws_ebs_volume.rb +122 -0
  63. data/lib/resources/aws/aws_ebs_volumes.rb +63 -0
  64. data/lib/resources/port.rb +10 -6
  65. metadata +56 -11
  66. data/docs/ruby_usage.md +0 -204
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ed479c2bc17fad9ab4aefa69f119d6448332b4e2f5befac16f427fa589a8cef8
4
- data.tar.gz: 6e055c297017f08684d15780060e2a9bf528f1f1579e0f8224a35202aad73c66
3
+ metadata.gz: 1e9a4bdc61290bace400878278ede4c09824a0edc8c14c2f3f9b6d2737f46058
4
+ data.tar.gz: 0ee613addabeb1b49e304e4d35fb87a5134f9e66ccfec913f188d987444516f5
5
5
  SHA512:
6
- metadata.gz: b3be7a2eb3219f1ceabad6ce163ae24f644475a67a3825f9163c7a572be3a54db5dad11dc5765d28f5330fa5fea5ce7b535e887e56aa86749dcf3c6453c8b9e2
7
- data.tar.gz: bab90ce890a5973fc24d8d02be94c88673553a0164dd0d6f5675247223244d232fd6f6a253ff0d3141549fb0f5f4857bdd984ab60ab03d2a5620f5325927f818
6
+ metadata.gz: 9869319175d8a4769cbf7a540e4c4d2c383e87ea8ed1c06656e933473e8e50224bcc321be65e0bf8dd6a45eadd1700826bef341dad4de6f9cf834d2c35688251
7
+ data.tar.gz: 486383709c684ee46d1b7ad16e7475fe0cd286a13ea6738554a5d05ea3db08b725a1f663d2b6a4532262521729797a1146ec6d24748df0f100c32daa47b7b8fa
data/.rubocop.yml CHANGED
@@ -5,9 +5,15 @@ AllCops:
5
5
  - Gemfile
6
6
  - Rakefile
7
7
  - 'test/**/*'
8
- - 'examples/**/*'
8
+ - 'lib/plugins/*/test/**/*'
9
+ # This is delicate; we want to include examples/plugins/*/lib
10
+ # but not anything else.
11
+ - 'examples/*profile*/**/*'
12
+ - 'examples/kitchen*/**/*'
13
+ - 'examples/inheritance/**/*'
14
+ - 'examples/custom-resource/**/*'
15
+ - 'examples/plugins/*/test/**/*'
9
16
  - 'vendor/**/*'
10
- - 'lib/plugins/inspec-*/test/**/*'
11
17
  - 'lib/bundles/inspec-init/templates/**/*'
12
18
  - 'www/demo/**/*'
13
19
  AlignParameters:
data/CHANGELOG.md CHANGED
@@ -1,38 +1,61 @@
1
1
  # Change Log
2
2
  <!-- usage documentation: http://expeditor-docs.es.chef.io/configuration/changelog/ -->
3
- <!-- latest_release 2.2.112 -->
4
- ## [v2.2.112](https://github.com/inspec/inspec/tree/v2.2.112) (2018-09-19)
3
+ <!-- latest_release 2.3.4 -->
4
+ ## [v2.3.4](https://github.com/inspec/inspec/tree/v2.3.4) (2018-09-27)
5
5
 
6
- #### Merged Pull Requests
7
- - Move artifact to v2 plugin [#3406](https://github.com/inspec/inspec/pull/3406) ([jquick](https://github.com/jquick))
6
+ #### New Features
7
+ - Plugins: Support for Train Plugins in InSpec [#3444](https://github.com/inspec/inspec/pull/3444) ([clintoncwolfe](https://github.com/clintoncwolfe))
8
8
  <!-- latest_release -->
9
9
 
10
- <!-- release_rollup since=2.2.102 -->
11
- ### Changes since 2.2.102 release
10
+ <!-- release_rollup since=2.2.112 -->
11
+ ### Changes since 2.2.112 release
12
12
 
13
13
  #### Enhancements
14
- - adding `versions` to the `gem` resource [#3398](https://github.com/inspec/inspec/pull/3398) ([majormoses](https://github.com/majormoses)) <!-- 2.2.107 -->
15
- - Plugins: Add support for &#39;bundles&#39; migration [#3384](https://github.com/inspec/inspec/pull/3384) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.2.105 -->
16
-
17
- #### New Features
18
- - Update AWS Security Group to work with IPV6 rules. [#3394](https://github.com/inspec/inspec/pull/3394) ([MartinLogan](https://github.com/MartinLogan)) <!-- 2.2.111 -->
19
- - Added db_name flag [#3383](https://github.com/inspec/inspec/pull/3383) ([kdoores](https://github.com/kdoores)) <!-- 2.2.104 -->
14
+ - Support the Busybox variant of netstat in the port resource [#3425](https://github.com/inspec/inspec/pull/3425) ([RoboticCheese](https://github.com/RoboticCheese)) <!-- 2.2.119 -->
20
15
 
21
16
  #### Merged Pull Requests
22
- - Move artifact to v2 plugin [#3406](https://github.com/inspec/inspec/pull/3406) ([jquick](https://github.com/jquick)) <!-- 2.2.112 -->
23
- - Move inspec init to v2 plugins [#3407](https://github.com/inspec/inspec/pull/3407) ([jquick](https://github.com/jquick)) <!-- 2.2.110 -->
24
- - Fix gem tests from recent merge [#3409](https://github.com/inspec/inspec/pull/3409) ([jquick](https://github.com/jquick)) <!-- 2.2.109 -->
25
- - Fix json automate tests and render call [#3408](https://github.com/inspec/inspec/pull/3408) ([jquick](https://github.com/jquick)) <!-- 2.2.108 -->
26
- - Move habitat to v2 plugin [#3404](https://github.com/inspec/inspec/pull/3404) ([jquick](https://github.com/jquick)) <!-- 2.2.106 -->
27
- - Fix rendering of profiles docs [#3393](https://github.com/inspec/inspec/pull/3393) ([jquick](https://github.com/jquick)) <!-- 2.2.103 -->
17
+ - Plugins: Example CLI Plugin, a Resource Lister [#3421](https://github.com/inspec/inspec/pull/3421) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.3.3 -->
18
+ - Pin postgresql to a lower cookbook version [#3449](https://github.com/inspec/inspec/pull/3449) ([jquick](https://github.com/jquick)) <!-- 2.3.2 -->
19
+ - RFC inspec style guide [#3356](https://github.com/inspec/inspec/pull/3356) ([arlimus](https://github.com/arlimus)) <!-- 2.3.1 -->
20
+ - Bump minor version [#3448](https://github.com/inspec/inspec/pull/3448) ([jquick](https://github.com/jquick)) <!-- 2.3.0 -->
21
+ - Add support for multiple descriptions for controls [#3424](https://github.com/inspec/inspec/pull/3424) ([jerryaldrichiii](https://github.com/jerryaldrichiii)) <!-- 2.2.120 -->
22
+ - Plugins: Load all CLI commands on usage on empty invocation [#3428](https://github.com/inspec/inspec/pull/3428) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.2.118 -->
23
+ - Fix v2 loader appveyor issue [#3434](https://github.com/inspec/inspec/pull/3434) ([jquick](https://github.com/jquick)) <!-- 2.2.116 -->
24
+ - Add new resource: aws_ebs_volume [#3381](https://github.com/inspec/inspec/pull/3381) ([jmassardo](https://github.com/jmassardo)) <!-- 2.2.115 -->
25
+
26
+ #### Bug Fixes
27
+ - Grammar correction in error message: use &quot;an&quot; with attribute and unknown [#3439](https://github.com/inspec/inspec/pull/3439) ([alexpop](https://github.com/alexpop)) <!-- 2.2.117 -->
28
+ - Remove load locks for cloud resources [#3420](https://github.com/inspec/inspec/pull/3420) ([jquick](https://github.com/jquick)) <!-- 2.2.114 -->
29
+
30
+ #### New Features
31
+ - Plugins: Support for Train Plugins in InSpec [#3444](https://github.com/inspec/inspec/pull/3444) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.3.4 -->
32
+ - Plugins Installer API [#3352](https://github.com/inspec/inspec/pull/3352) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.2.113 -->
28
33
  <!-- release_rollup -->
29
34
 
30
35
  <!-- latest_stable_release -->
36
+ ## [v2.2.112](https://github.com/inspec/inspec/tree/v2.2.112) (2018-09-19)
37
+
38
+ #### New Features
39
+ - Added db_name flag [#3383](https://github.com/inspec/inspec/pull/3383) ([kdoores](https://github.com/kdoores))
40
+ - Update AWS Security Group to work with IPV6 rules. [#3394](https://github.com/inspec/inspec/pull/3394) ([MartinLogan](https://github.com/MartinLogan))
41
+
42
+ #### Enhancements
43
+ - Plugins: Add support for &#39;bundles&#39; migration [#3384](https://github.com/inspec/inspec/pull/3384) ([clintoncwolfe](https://github.com/clintoncwolfe))
44
+ - adding `versions` to the `gem` resource [#3398](https://github.com/inspec/inspec/pull/3398) ([majormoses](https://github.com/majormoses))
45
+
46
+ #### Merged Pull Requests
47
+ - Fix rendering of profiles docs [#3393](https://github.com/inspec/inspec/pull/3393) ([jquick](https://github.com/jquick))
48
+ - Move habitat to v2 plugin [#3404](https://github.com/inspec/inspec/pull/3404) ([jquick](https://github.com/jquick))
49
+ - Fix json automate tests and render call [#3408](https://github.com/inspec/inspec/pull/3408) ([jquick](https://github.com/jquick))
50
+ - Fix gem tests from recent merge [#3409](https://github.com/inspec/inspec/pull/3409) ([jquick](https://github.com/jquick))
51
+ - Move inspec init to v2 plugins [#3407](https://github.com/inspec/inspec/pull/3407) ([jquick](https://github.com/jquick))
52
+ - Move artifact to v2 plugin [#3406](https://github.com/inspec/inspec/pull/3406) ([jquick](https://github.com/jquick))
53
+ <!-- latest_stable_release -->
54
+
31
55
  ## [v2.2.102](https://github.com/inspec/inspec/tree/v2.2.102) (2018-09-17)
32
56
 
33
57
  #### Merged Pull Requests
34
58
  - Add json-automate to the report method [#3401](https://github.com/inspec/inspec/pull/3401) ([jquick](https://github.com/jquick))
35
- <!-- latest_stable_release -->
36
59
 
37
60
  ## [v2.2.101](https://github.com/inspec/inspec/tree/v2.2.101) (2018-09-14)
38
61
 
data/README.md CHANGED
@@ -452,4 +452,4 @@ Unless required by applicable law or agreed to in writing, software
452
452
  distributed under the License is distributed on an "AS IS" BASIS,
453
453
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
454
454
  See the License for the specific language governing permissions and
455
- limitations under the License.
455
+ limitations under the License.
data/Rakefile CHANGED
@@ -106,10 +106,23 @@ namespace :test do
106
106
  sh(Gem.ruby, 'test/docker_test.rb', *tests)
107
107
  end
108
108
 
109
- task :integration do
109
+ task :integration, [:os] do |task, args|
110
110
  concurrency = ENV['CONCURRENCY'] || 1
111
- os = ENV['OS'] || ''
112
- sh("bundle exec kitchen test -c #{concurrency} #{os}")
111
+ os = args[:os] || ENV['OS'] || ''
112
+ ENV['DOCKER'] = 'true' if ENV['docker'].nil?
113
+ puts "Building current InSpec gem for audit cookbook testing..."
114
+ output = %x[gem build inspec-core.gemspec]
115
+ puts output
116
+ gem_name = output.split("\n")[-1].split(':')[1].strip
117
+ path = File.dirname(__FILE__)
118
+ File.rename(File.join(path, gem_name), File.join(path, 'inspec-core-local.gem'))
119
+ destination = File.join(path, 'test', 'cookbooks', 'os_prepare', 'files', 'inspec-core-local.gem')
120
+ begin
121
+ FileUtils.cp(File.join(path, 'inspec-core-local.gem'), destination)
122
+ sh("bundle exec kitchen test -c #{concurrency} #{os}")
123
+ ensure
124
+ FileUtils.rm(destination)
125
+ end
113
126
  end
114
127
 
115
128
  task :ssh, [:target] do |_t, args|
@@ -0,0 +1,31 @@
1
+ # Integration Testing with InSpec
2
+
3
+ ## Introduction
4
+
5
+ Inspec uses Test Kitchen for its integration testing. Our current testing uses Docker as our backend. You should install and have Docker running befor you run any tests.
6
+
7
+ ### How to run specific integrations
8
+
9
+ To run a specific integration test use the following:
10
+
11
+ ```bash
12
+ bundle exec rake test:integration[OS_NAME]
13
+ ```
14
+
15
+ Example:
16
+ ```bash
17
+ bundle exec rake test:integration[default-ubuntu-1604]
18
+ ```
19
+
20
+ # Inspec Integrations
21
+
22
+ ### Test Kitchen
23
+
24
+ We run the test/integration/default profile at the end of each integration test in the verify stage. This confirms that our current code is compatible with test kitchen.
25
+
26
+ ### Audit Testing
27
+
28
+ For Audit cookbook testing InSpec sets up some special hooks. The integration rake command will bundle up the current checkout into a gem which is passed along to test kitchen in the os_prepare cookbook. When this cookbook is ran it will install the local inspec gem. Audit will then use this gem accordingly when running in the post chef-client validators. The .kitchen.yml is setup to export the audit report to a json file which we look for and confirm the structure in the test/integration/default/controls/audit_spec.rb file.
29
+
30
+ In the validation file we confirm that the file was created from audit and that the structure looks correct. We also validate that the inspec ran with audit is the same that the current branch is using. This validates that audit did not use a older version for some reason.
31
+
data/docs/dev/plugins.md CHANGED
@@ -26,9 +26,11 @@ The software design of the InSpec Plugin v2 API is deeply inspired by the Vagran
26
26
 
27
27
  The normal distribution and installation method is via gems, handled by the `inspec plugin` command.
28
28
 
29
- TODO: give basic overview of `inspec plugin` and link to docs
29
+ `inspec plugin install inspec-myplugin` will fetch `inspec-myplugin` from rubygems.org, and install it and its gemspec dependencies under the user's `.inspec` directory. You may also provide a local gemfile. For local development, however, path-to-source is usually most convenient.
30
30
 
31
- ### Plugins may also be found by path
31
+ For more on the `plugin` CLI command, run `inspec plugin help`.
32
+
33
+ ### Plugins may also be found by path to a source tree
32
34
 
33
35
  For local development or site-specific installations, you can also 'install' a plugin by path using `inspec plugin`, or edit `~/.inspec/plugins.json` directly to add a plugin.
34
36
 
data/docs/dsl_inspec.md CHANGED
@@ -26,10 +26,8 @@ In various use cases like implementing IT compliance across different department
26
26
  control 'sshd-8' do
27
27
  impact 0.6
28
28
  title 'Server: Configure the service port'
29
- desc '
30
- Always specify which port the SSH server should listen to.
31
- Prevent unexpected settings.
32
- '
29
+ desc 'Always specify which port the SSH server should listen.'
30
+ desc 'rationale', 'This ensures that there are no unexpected settings'
33
31
  tag 'ssh','sshd','openssh-server'
34
32
  tag cce: 'CCE-27072-8'
35
33
  ref 'NSA-RH6-STIG - Section 3.5.2.1', url: 'https://www.nsa.gov/ia/_files/os/redhat/rhel5-guide-i731.pdf'
@@ -44,6 +42,7 @@ where
44
42
 
45
43
  * `'sshd-8'` is the name of the control
46
44
  * `impact`, `title`, and `desc` define metadata that fully describes the importance of the control, its purpose, with a succinct and complete description
45
+ * `desc` when given only one argument it sets the default description. When given 2 arguments (see: `'rationale'`) it will use the first argument as a header when rendering in Automate
47
46
  * `impact` is an float that measures the importance of the compliance results and must be a value between `0.0` and `1.0`. The value ranges are:
48
47
  * `0.0 to <0.4` these are controls with minor criticality
49
48
  * `0.4 to <0.7` these are controls with major criticality
@@ -252,3 +251,104 @@ control 'ssh-1' do
252
251
  end
253
252
  end
254
253
  ```
254
+
255
+ # Using Ruby in InSpec
256
+
257
+ The InSpec DSL is a Ruby based language. This allows you to be flexible with
258
+ Ruby code in controls:
259
+
260
+ ```ruby
261
+ json_obj = json('/file.json')
262
+ json_obj['keys'].each do |value|
263
+ ..
264
+ end
265
+ ```
266
+
267
+ Ruby allows a lot of freedoms, but should be limited in controls so that they
268
+ remain portable and easy to understand. Please see our [profile style guide](./style).
269
+
270
+ Core and custom resources are written as regular Ruby classes which inherit from
271
+ `Inspec.resource`.
272
+
273
+
274
+ ## Interactive Debugging with Pry
275
+
276
+ Here's a sample InSpec control that users Ruby variables to instantiate
277
+ an InSpec resource once and use the content in multiple tests.
278
+
279
+ ```ruby
280
+ control 'check-perl' do
281
+ impact 0.3
282
+ title 'Check perl compiled options and permissions'
283
+ perl_out = command('perl -V')
284
+ #require 'pry'; binding.pry;
285
+ describe perl_out do
286
+ its('exit_status') { should eq 0 }
287
+ its('stdout') { should match /USE_64_BIT_ALL/ }
288
+ its('stdout') { should match /useposix=true/ }
289
+ its('stdout') { should match /-fstack-protector/ }
290
+ end
291
+
292
+ # extract an array of include directories
293
+ perl_inc = perl_out.stdout.partition('@INC:').last.strip.split("\n")
294
+ # ensure include directories are only writable by 'owner'
295
+ perl_inc.each do |path|
296
+ describe directory(path.strip) do
297
+ it { should_not be_writable.by 'group' }
298
+ it { should_not be_writable.by 'other' }
299
+ end
300
+ end
301
+ end
302
+ ```
303
+
304
+ An **advanced** but very useful Ruby tip. In the previous example, I
305
+ commented out the `require 'pry'; binding.pry;` line. If you remove the
306
+ `#` prefix and run the control, the execution will stop at that line and
307
+ give you a `pry` shell. Use that to troubleshoot, print variables, see
308
+ methods available, etc. For the above example:
309
+
310
+ ```ruby
311
+ [1] pry> perl_out.exit_status
312
+ => 0
313
+ [2] pry> perl_out.stderr
314
+ => ""
315
+ [3] pry> ls perl_out
316
+ Inspec::Plugins::Resource#methods: inspect
317
+ Inspec::Resources::Cmd#methods: command exist? exit_status result stderr stdout to_s
318
+ Inspec::Resource::Registry::Command#methods: inspec
319
+ instance variables: @__backend_runner__ @__resource_name__ @command @result
320
+ [4] pry> perl_out.stdout.partition('@INC:').last.strip.split("\n")
321
+ => ["/Library/Perl/5.18/darwin-thread-multi-2level",
322
+ " /Library/Perl/5.18",
323
+ ...REDACTED...
324
+ [5] pry> exit # or abort
325
+ ```
326
+
327
+ You can use `pry` inside both the controls DSL and resources. Similarly,
328
+ for dev and test, you can use `inspec shell` which is based on `pry`,
329
+ for example:
330
+
331
+ ```ruby
332
+ $ inspec shell
333
+ Welcome to the interactive InSpec Shell
334
+ To find out how to use it, type: help
335
+
336
+ inspec> command('ls /home/gordon/git/inspec/docs').stdout
337
+ => "ctl_inspec.rst\ndsl_inspec.rst\ndsl_resource.rst\n"
338
+ inspec> command('ls').stdout.split("\n")
339
+ => ["ctl_inspec.rst", "dsl_inspec.rst", "dsl_resource.rst"]
340
+
341
+ inspec> help command
342
+ Name: command
343
+
344
+ Description:
345
+ Use the command InSpec audit resource to test an arbitrary command that is run on the system.
346
+
347
+ Example:
348
+ describe command('ls -al /') do
349
+ it { should exist }
350
+ its('stdout') { should match /bin/ }
351
+ its('stderr') { should eq '' }
352
+ its('exit_status') { should eq 0 }
353
+ end
354
+ ```
data/docs/plugins.md ADDED
@@ -0,0 +1,57 @@
1
+ ---
2
+ title: About InSpec and Train Plugins
3
+ ---
4
+
5
+ # InSpec and Train Plugins
6
+
7
+ ## What are InSpec Plugins?
8
+
9
+ InSpec Plugins are optional software components that extend the capabilities of InSpec. For example, [`inspec-iggy`](https://github.com/inspec/inspec-iggy) is a Plugin project that aims to generate InSpec controls from infrastructure-as-code files. Plugins are distributed as RubyGems, and InSpec manages their installation. InSpec Plugins always begin with the prefix 'inspec-'.
10
+
11
+ ## What are Train Plugins?
12
+
13
+ Train Plugins allow InSpec to speak to new kinds of targets (typically new remote targets or APIs, but you could treat the local system in a new way if you wished to). For example, if you wanted to audit a Kubernetes cluster, you might want a transport that can talk to the supervisor API. You'd develop a Train Plugin for that, and install it using the InSpec command line. Train Plugins always begin with the prefix 'train-'.
14
+
15
+ ## What can plugins do?
16
+
17
+ Currently, each plugin can offer one or more of these capabilities:
18
+
19
+ * define a new command-line-interface (CLI) command suite
20
+ * connectivity to new types of hosts or cloud providers (`train` plugins)
21
+
22
+ Future work might include new capability types, such as:
23
+
24
+ * reporters (output generators)
25
+ * DSL extensions at the file, control, or test level
26
+ * attribute fetchers to allow reading InSpec attributes from new sources (for example, a remote, encrypted key-value store)
27
+
28
+ ## How do I find out which plugins are available?
29
+
30
+ The InSpec CLI can tell you which plugins are available:
31
+
32
+ ```bash
33
+ $ inspec plugin search
34
+ ```
35
+
36
+ ## How do I install and manage plugins?
37
+
38
+ The InSpec command line now offers a new subcommand just for managing plugins.
39
+
40
+ You can install a plugin by running:
41
+
42
+ ```bash
43
+ $ inspec plugin install inspec-some-plugin
44
+ $ inspec plugin install train-some-plugin
45
+ ```
46
+
47
+ For more details on what the `plugin` command can do, see the [online help](https://www.inspec.io/docs/reference/cli/#plugin), or run `inspec plugin help`.
48
+
49
+ ## How do I write a plugin?
50
+
51
+ ### InSpec Plugins
52
+
53
+ For details on how to author an InSpec Plugin, see the [developer documentation](https://github.com/inspec/inspec/blob/master/docs/dev/plugins.md)
54
+
55
+ ### Train Plugins
56
+
57
+ For details on how to author a Train Plugin, see the [developer documentation](https://github.com/inspec/train/blob/master/docs/dev/plugins.md)
@@ -0,0 +1,76 @@
1
+ ---
2
+ title: About the aws_ebs_volume Resource
3
+ platform: aws
4
+ ---
5
+
6
+ # aws\_ebs\_volume
7
+
8
+ Use the `aws_ebs_volume` InSpec audit resource to test properties of a single AWS EBS volume.
9
+
10
+ <br>
11
+
12
+ ## Availability
13
+
14
+ ### Installation
15
+
16
+ This resource is distributed along with InSpec itself. You can use it automatically.
17
+
18
+ ## Syntax
19
+
20
+ An `aws_ebs_volume` resource block declares the tests for a single AWS EBS volume by either name or id.
21
+
22
+ describe aws_ebs_volume('vol-01a2349e94458a507') do
23
+ it { should exist }
24
+ end
25
+
26
+ describe aws_ebs_volume(name: 'data-vol') do
27
+ it { should be_encrypted }
28
+ end
29
+
30
+ <br>
31
+
32
+ ## Examples
33
+
34
+ The following examples show how to use this InSpec audit resource.
35
+
36
+ ### Test that an EBS Volume does not exist
37
+
38
+ describe aws_ebs_volume(name: 'data_vol') do
39
+ it { should_not exist }
40
+ end
41
+
42
+ ### Test that an EBS Volume is encrypted
43
+
44
+ describe aws_ebs_volume(name: 'secure_data_vol') do
45
+ it { should be_encrypted }
46
+ end
47
+
48
+ ### Test that an EBS Volume the correct size
49
+
50
+ describe aws_ebs_volume(name: 'data_vol') do
51
+ its('size') { should cmp 32 }
52
+ end
53
+
54
+ <br>
55
+
56
+ ## Properties
57
+
58
+ * `availability_zone`, `encrypted`, `iops`, `kms_key_id`, `size`, `snapshot_id`, `state`, `volume_type`
59
+
60
+ <br>
61
+
62
+ ## Matchers
63
+
64
+ This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
65
+
66
+ ### be\_encrypted
67
+
68
+ The `be_encrypted` matcher tests if the described EBS Volume is encrypted.
69
+
70
+ it { should be_encrypted }
71
+
72
+ ## AWS Permissions
73
+
74
+ Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeVolumes`, and `iam:GetInstanceProfile` actions set to allow.
75
+
76
+ You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonec2.html), and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).