inspec-resource-lister 0.1.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/Gemfile +12 -0
- data/README.md +62 -0
- data/inspec-resource-lister.gemspec +45 -0
- data/lib/inspec-resource-lister.rb +16 -0
- data/lib/inspec-resource-lister/cli_command.rb +70 -0
- data/lib/inspec-resource-lister/plugin.rb +55 -0
- data/lib/inspec-resource-lister/version.rb +10 -0
- metadata +72 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: b1f21bd20e07a90956677cdbf5ca5f05dcfb8cf8
|
4
|
+
data.tar.gz: e5352db5025a6f0dd5f149902681a9e4f6354c9e
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 210ffa42125e8bd214f7f0494eeced75c5406d4a62e8156d3b6aa188b83abb20093984373c370081afb9b36fb96e65bd66c617dc3d39b4bc60888401fb6e3f58
|
7
|
+
data.tar.gz: 5cabbadd3c96cb70351d541c34833c29f4e1f9120f9eecef5e9ad46c496f0bc81ff123f1ea7ed05764186fb160afda47ef56dea56443cac2df88d3ba8cd510e2
|
data/Gemfile
ADDED
@@ -0,0 +1,12 @@
|
|
1
|
+
# encoding: utf-8
|
2
|
+
source 'https://rubygems.org'
|
3
|
+
|
4
|
+
gemspec
|
5
|
+
|
6
|
+
group :development do
|
7
|
+
gem 'bundler'
|
8
|
+
gem 'byebug'
|
9
|
+
gem 'minitest'
|
10
|
+
gem 'rake'
|
11
|
+
gem 'rubocop', '= 0.49.1' # Need to keep in sync with main InSpec project, so config files will work
|
12
|
+
end
|
data/README.md
ADDED
@@ -0,0 +1,62 @@
|
|
1
|
+
# InSpec Plugin Example - Resource Lister
|
2
|
+
|
3
|
+
This plugin provides an example of building a plugin for use with [InSpec](https://inspec.io). Its functionality is simple, but useful: list resources included with InSpec.
|
4
|
+
|
5
|
+
## To Install this as a User
|
6
|
+
|
7
|
+
You will need InSpec v2.3 or later.
|
8
|
+
|
9
|
+
If you want to just use this (not learn how to write a plugin), you can do so by simply running:
|
10
|
+
|
11
|
+
```
|
12
|
+
you@machine $ inspec plugin install inspec-resource-lister
|
13
|
+
```
|
14
|
+
|
15
|
+
You can then run:
|
16
|
+
|
17
|
+
```
|
18
|
+
you@machine $ inspec plugin help listresources
|
19
|
+
# ... Usage info
|
20
|
+
|
21
|
+
you@machine $ inspec plugin listresources core
|
22
|
+
aide_conf
|
23
|
+
apache
|
24
|
+
apache_conf
|
25
|
+
... snip ...
|
26
|
+
yumrepo
|
27
|
+
zfs_dataset
|
28
|
+
zfs_pool
|
29
|
+
------------------------------
|
30
|
+
160 resources total
|
31
|
+
```
|
32
|
+
|
33
|
+
## Features of This Example Kit
|
34
|
+
|
35
|
+
This example plugin is a full-fledged plugin example, with everything a real-world, industrial grade plugin would have, including:
|
36
|
+
|
37
|
+
* an implementation of an InSpec CLI Command, using the InSpec PluginV2 API
|
38
|
+
* documentation (you are reading it now)
|
39
|
+
* tests, at the unit and functional level
|
40
|
+
* a .gemspec, for packaging and publishing it as a gem
|
41
|
+
* a Gemfile, for managing its dependencies
|
42
|
+
* a Rakefile, for running development tasks
|
43
|
+
* Rubocop linting support for using the base InSpec project rubocop.yml (See Rakefile)
|
44
|
+
|
45
|
+
You are encouraged to use this plugin as a starting point for real plugins.
|
46
|
+
|
47
|
+
## Development of a Plugin
|
48
|
+
|
49
|
+
[Plugin Development](https://github.com/inspec/inspec/blob/master/docs/dev/plugins.md) is documented on the `inspec` project on GitHub. Additionally, this example
|
50
|
+
plugin has extensive comments explaining what is happening, and why.
|
51
|
+
|
52
|
+
### A Tour of the Plugin
|
53
|
+
|
54
|
+
One nice circuit of the plugin might be:
|
55
|
+
* look at the gemspec, to see what the plugin thinks it does
|
56
|
+
* look at the functional tests, to see the plugin proving it does what it says
|
57
|
+
* look at the unit tests, to see how the plugin claims it is internally structured
|
58
|
+
* look at the Rakefile, to see how to interact with the project
|
59
|
+
* look at lib/inspec-resource-lister.rb, the entry point which InSpec will always load if the plugin is installed
|
60
|
+
* look at lib/inspec-resource-lister/plugin.rb, the plugin definition which InSpec uses to understand what the plugin _can_ do.
|
61
|
+
* look at lib/inspec-resource-lister/cli_command.rb, the CLI Command implementation itself.
|
62
|
+
|
@@ -0,0 +1,45 @@
|
|
1
|
+
# coding: utf-8
|
2
|
+
|
3
|
+
# As plugins are usually packaged and distributed as a RubyGem,
|
4
|
+
# we have to provide a .gemspec file, which controls the gembuild
|
5
|
+
# and publish process. This is a fairly generic gemspec.
|
6
|
+
|
7
|
+
# It is traditional in a gemspec to dynamically load the current version
|
8
|
+
# from a file in the source tree. The next three lines make that happen.
|
9
|
+
lib = File.expand_path('../lib', __FILE__)
|
10
|
+
$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
|
11
|
+
require 'inspec-resource-lister/version'
|
12
|
+
|
13
|
+
Gem::Specification.new do |spec|
|
14
|
+
# Importantly, all InSpec plugins must be prefixed with `inspec-` (most
|
15
|
+
# plugins) or `train-` (plugins which add new connectivity features).
|
16
|
+
spec.name = 'inspec-resource-lister'
|
17
|
+
|
18
|
+
# It is polite to namespace your plugin under InspecPlugins::YourPluginInCamelCase
|
19
|
+
spec.version = InspecPlugins::ResourceLister::VERSION
|
20
|
+
spec.authors = ['Clinton Wolfe']
|
21
|
+
spec.email = ['cwolfe@chef.io']
|
22
|
+
spec.summary = 'InSpec Plugin example, lists available resources'
|
23
|
+
spec.description = 'Example for implementing an InSpec Plugin. This simply lists available resources.'
|
24
|
+
spec.homepage = 'https://github.com/inspec/inspec/tree/master/examples/plugin'
|
25
|
+
spec.license = 'Apache-2.0'
|
26
|
+
|
27
|
+
# Though complicated-looking, this is pretty standard for a gemspec.
|
28
|
+
# It just filters what will actually be packaged in the gem (leaving
|
29
|
+
# out tests, etc)
|
30
|
+
spec.files = %w{
|
31
|
+
README.md inspec-resource-lister.gemspec Gemfile
|
32
|
+
} + Dir.glob(
|
33
|
+
'lib/**/*', File::FNM_DOTMATCH
|
34
|
+
).reject { |f| File.directory?(f) }
|
35
|
+
spec.require_paths = ['lib']
|
36
|
+
|
37
|
+
# If you rely on any other gems, list them here with any constraints.
|
38
|
+
# This is how `inspec plugin install` is able to manage your dependencies.
|
39
|
+
# For example, perhaps you are writing a thing that talks to AWS, and you
|
40
|
+
# want to ensure you have `aws-sdk` in a certain version.
|
41
|
+
|
42
|
+
# All plugins should mention inspec, > 2.2.78
|
43
|
+
# 2.2.78 included the v2 Plugin API
|
44
|
+
spec.add_dependency 'inspec', '>=2.2.78', '<4.0.0'
|
45
|
+
end
|
@@ -0,0 +1,16 @@
|
|
1
|
+
# encoding: utf-8
|
2
|
+
|
3
|
+
# This file is known as the "entry point."
|
4
|
+
# This is the file InSpec will try to load if it
|
5
|
+
# thinks your plugin is installed.
|
6
|
+
|
7
|
+
# The *only* thing this file should do is setup the
|
8
|
+
# load path, then load the plugin definition file.
|
9
|
+
|
10
|
+
# Next two lines simply add the path of the gem to the load path.
|
11
|
+
# This is not needed when being loaded as a gem; but when doing
|
12
|
+
# plugin development, you may need it. Either way, it's harmless.
|
13
|
+
libdir = File.dirname(__FILE__)
|
14
|
+
$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
|
15
|
+
|
16
|
+
require 'inspec-resource-lister/plugin'
|
@@ -0,0 +1,70 @@
|
|
1
|
+
# encoding: utf-8
|
2
|
+
|
3
|
+
require 'inspec/resource'
|
4
|
+
|
5
|
+
module InspecPlugins::ResourceLister
|
6
|
+
# This class will provide the actual CLI implementation.
|
7
|
+
# Its superclass is provided by another call to Inspec.plugin,
|
8
|
+
# this time with two args. The first arg specifies we are requesting
|
9
|
+
# version 2 of the Plugins API. The second says we are making a CLI
|
10
|
+
# Command plugin component, so please make available any DSL needed
|
11
|
+
# for that.
|
12
|
+
# In fact, aside from a some housekeeping DSL methods, most of the
|
13
|
+
# DSL provided is that of Thor. Inspec.plugin(2, :cli_command)
|
14
|
+
# promises to return a class that is a subclass of Thor. So, to add
|
15
|
+
# commands, usage information, and options, use the Thor documentation.
|
16
|
+
class CliCommand < Inspec.plugin(2, :cli_command)
|
17
|
+
# This isn't provided by Thor, but is needed by InSpec so that it can
|
18
|
+
# register the subcommand. Args are a usage message, and a short decription.
|
19
|
+
# These will appear when someone has installed the plugin, and then they
|
20
|
+
# run `inspec help`.
|
21
|
+
subcommand_desc 'list-resources [COMMAND]', 'List resources that InSpec finds.'
|
22
|
+
|
23
|
+
# The usual rhythm for a Thor CLI file is description, options, command method.
|
24
|
+
# Thor just has you call DSL methods in sequence prior to each command.
|
25
|
+
# Let's make a command, 'core', that lists all of the resources included with InSpec.
|
26
|
+
|
27
|
+
# First, provide a usage / description. This will appear in `inspec help list-resources`.
|
28
|
+
desc 'core [OPTIONS]', 'List resources that are included with InSpec.'
|
29
|
+
|
30
|
+
# Let's include an option, -s, to summarize the list.
|
31
|
+
# Refer to the Thors docs; there is a lot you can do here.
|
32
|
+
option :summary, desc: 'Include a total at the bottom', \
|
33
|
+
type: :boolean, default: true, aliases: [:s]
|
34
|
+
|
35
|
+
# OK, now the actual method itself. If you provide params, you're telling Thor that
|
36
|
+
# you accept CLI arguments after all options have been consumed. Let's accept a
|
37
|
+
# pattern, assumed to be a wildcard substring. If we provide a default, the CLI arg becomes optional.
|
38
|
+
def core(pattern = /.+/)
|
39
|
+
# The code here will *only* be executed if someone actually runs
|
40
|
+
# `inspec list-resources core`. So, we can lazily wait to load
|
41
|
+
# expensive things here. However, InSpec has in fact already
|
42
|
+
# loaded the Resources, so we don't have anything to load.
|
43
|
+
|
44
|
+
# If we were passed a CLI arg, wrap the arg in Regexp matchers so
|
45
|
+
# we will match anywhere in the name.
|
46
|
+
unless pattern == /.+/
|
47
|
+
pattern = Regexp.new('.*' + pattern + '.*')
|
48
|
+
end
|
49
|
+
|
50
|
+
# This gets a bit into InSpec innards; but this is simply a Hash.
|
51
|
+
registry = Inspec::Resource.default_registry
|
52
|
+
resource_names = registry.keys.grep(pattern).sort
|
53
|
+
|
54
|
+
# One day we'll have nice UI support.
|
55
|
+
resource_names.each { |name| puts name }
|
56
|
+
|
57
|
+
if options[:summary]
|
58
|
+
puts '-' * 30
|
59
|
+
puts "#{resource_names.count} resources total"
|
60
|
+
end
|
61
|
+
end
|
62
|
+
|
63
|
+
# A neat idea for future work would be to add another command, perhaps
|
64
|
+
# 'resource-pack', which examines a possibly remote resource pack and
|
65
|
+
# enumerates the resources it defines.
|
66
|
+
|
67
|
+
# Another idea might be to fetch a profile, and list the resources actually
|
68
|
+
# used in the controls of the profile, along with counts.
|
69
|
+
end
|
70
|
+
end
|
@@ -0,0 +1,55 @@
|
|
1
|
+
# encoding: UTF-8
|
2
|
+
|
3
|
+
# Plugin Definition file
|
4
|
+
# The purpose of this file is to declare to InSpec what plugin_types (capabilities)
|
5
|
+
# are included in this plugin, and provide hooks that will load them as needed.
|
6
|
+
|
7
|
+
# It is important that this file load successfully and *quickly*.
|
8
|
+
# Your plugin's functionality may never be used on this InSpec run; so we keep things
|
9
|
+
# fast and light by only loading heavy things when they are needed.
|
10
|
+
|
11
|
+
# Presumably this is light
|
12
|
+
require 'inspec-resource-lister/version'
|
13
|
+
|
14
|
+
# The InspecPlugins namespace is where all plugins should declare themselves.
|
15
|
+
# The 'Inspec' capitalization is used throughout the InSpec source code; yes, it's
|
16
|
+
# strange.
|
17
|
+
module InspecPlugins
|
18
|
+
# Pick a reasonable namespace here for your plugin. A reasonable choice
|
19
|
+
# would be the CamelCase version of your plugin gem name.
|
20
|
+
# inspec-resource-lister => ResourceLister
|
21
|
+
module ResourceLister
|
22
|
+
# This simple class handles the plugin definition, so calling it simply Plugin is OK.
|
23
|
+
# Inspec.plugin returns various Classes, intended to be superclasses for various
|
24
|
+
# plugin components. Here, the one-arg form gives you the Plugin Definition superclass,
|
25
|
+
# which mainly gives you access to the hook / plugin_type DSL.
|
26
|
+
# The number '2' says you are asking for version 2 of the plugin API. If there are
|
27
|
+
# future versions, InSpec promises plugin API v2 will work for at least two more InSpec
|
28
|
+
# major versions.
|
29
|
+
class Plugin < ::Inspec.plugin(2)
|
30
|
+
# Internal machine name of the plugin. InSpec will use this in errors, etc.
|
31
|
+
plugin_name :'inspec-resource-lister'
|
32
|
+
|
33
|
+
# Define a new CLI subcommand.
|
34
|
+
# The argument here will be used to match against the command line args,
|
35
|
+
# and if the user said `inspec list-resources`, this hook will get called.
|
36
|
+
# Notice that you can define multiple hooks with different names, and they
|
37
|
+
# don't have to match the plugin name.
|
38
|
+
|
39
|
+
# We'd like this to be list-resources, but Thor does not support hyphens
|
40
|
+
# see https://github.com/erikhuda/thor/pull/613
|
41
|
+
cli_command :listresources do
|
42
|
+
# Calling this hook doesn't mean list-resources is being executed - just
|
43
|
+
# that we should be ready to do so. So, load the file that defines the
|
44
|
+
# functionality.
|
45
|
+
# For example, InSpec will activate this hook when `inspec help` is
|
46
|
+
# executed, so that this plugin's usage message will be included in the help.
|
47
|
+
require 'inspec-resource-lister/cli_command'
|
48
|
+
|
49
|
+
# Having loaded our functionality, return a class that will let the
|
50
|
+
# CLI engine tap into it.
|
51
|
+
InspecPlugins::ResourceLister::CliCommand
|
52
|
+
end
|
53
|
+
end
|
54
|
+
end
|
55
|
+
end
|
@@ -0,0 +1,10 @@
|
|
1
|
+
# encoding: UTF-8
|
2
|
+
|
3
|
+
# This file simply makes it easier for CI engines to update
|
4
|
+
# the version stamp, and provide a clean way for the gemspec
|
5
|
+
# to learn the current version.
|
6
|
+
module InspecPlugins
|
7
|
+
module ResourceLister
|
8
|
+
VERSION = '0.1.0'.freeze
|
9
|
+
end
|
10
|
+
end
|
metadata
ADDED
@@ -0,0 +1,72 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: inspec-resource-lister
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
version: 0.1.0
|
5
|
+
platform: ruby
|
6
|
+
authors:
|
7
|
+
- Clinton Wolfe
|
8
|
+
autorequire:
|
9
|
+
bindir: bin
|
10
|
+
cert_chain: []
|
11
|
+
date: 2018-09-28 00:00:00.000000000 Z
|
12
|
+
dependencies:
|
13
|
+
- !ruby/object:Gem::Dependency
|
14
|
+
name: inspec
|
15
|
+
requirement: !ruby/object:Gem::Requirement
|
16
|
+
requirements:
|
17
|
+
- - ">="
|
18
|
+
- !ruby/object:Gem::Version
|
19
|
+
version: 2.2.78
|
20
|
+
- - "<"
|
21
|
+
- !ruby/object:Gem::Version
|
22
|
+
version: 4.0.0
|
23
|
+
type: :runtime
|
24
|
+
prerelease: false
|
25
|
+
version_requirements: !ruby/object:Gem::Requirement
|
26
|
+
requirements:
|
27
|
+
- - ">="
|
28
|
+
- !ruby/object:Gem::Version
|
29
|
+
version: 2.2.78
|
30
|
+
- - "<"
|
31
|
+
- !ruby/object:Gem::Version
|
32
|
+
version: 4.0.0
|
33
|
+
description: Example for implementing an InSpec Plugin. This simply lists available
|
34
|
+
resources.
|
35
|
+
email:
|
36
|
+
- cwolfe@chef.io
|
37
|
+
executables: []
|
38
|
+
extensions: []
|
39
|
+
extra_rdoc_files: []
|
40
|
+
files:
|
41
|
+
- Gemfile
|
42
|
+
- README.md
|
43
|
+
- inspec-resource-lister.gemspec
|
44
|
+
- lib/inspec-resource-lister.rb
|
45
|
+
- lib/inspec-resource-lister/cli_command.rb
|
46
|
+
- lib/inspec-resource-lister/plugin.rb
|
47
|
+
- lib/inspec-resource-lister/version.rb
|
48
|
+
homepage: https://github.com/inspec/inspec/tree/master/examples/plugin
|
49
|
+
licenses:
|
50
|
+
- Apache-2.0
|
51
|
+
metadata: {}
|
52
|
+
post_install_message:
|
53
|
+
rdoc_options: []
|
54
|
+
require_paths:
|
55
|
+
- lib
|
56
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
57
|
+
requirements:
|
58
|
+
- - ">="
|
59
|
+
- !ruby/object:Gem::Version
|
60
|
+
version: '0'
|
61
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
62
|
+
requirements:
|
63
|
+
- - ">="
|
64
|
+
- !ruby/object:Gem::Version
|
65
|
+
version: '0'
|
66
|
+
requirements: []
|
67
|
+
rubyforge_project:
|
68
|
+
rubygems_version: 2.6.13
|
69
|
+
signing_key:
|
70
|
+
specification_version: 4
|
71
|
+
summary: InSpec Plugin example, lists available resources
|
72
|
+
test_files: []
|