inspec-resource-lister 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b1f21bd20e07a90956677cdbf5ca5f05dcfb8cf8
+  data.tar.gz: e5352db5025a6f0dd5f149902681a9e4f6354c9e
+SHA512:
+  metadata.gz: 210ffa42125e8bd214f7f0494eeced75c5406d4a62e8156d3b6aa188b83abb20093984373c370081afb9b36fb96e65bd66c617dc3d39b4bc60888401fb6e3f58
+  data.tar.gz: 5cabbadd3c96cb70351d541c34833c29f4e1f9120f9eecef5e9ad46c496f0bc81ff123f1ea7ed05764186fb160afda47ef56dea56443cac2df88d3ba8cd510e2

data/Gemfile

@@ -0,0 +1,12 @@
+# encoding: utf-8
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'bundler'
+  gem 'byebug'
+  gem 'minitest'
+  gem 'rake'
+  gem 'rubocop', '= 0.49.1' # Need to keep in sync with main InSpec project, so config files will work
+end

data/README.md

@@ -0,0 +1,62 @@
+# InSpec Plugin Example - Resource Lister
+
+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.
+
+## To Install this as a User
+
+You will need InSpec v2.3 or later.
+
+If you want to just use this (not learn how to write a plugin), you can do so by simply running:
+
+```
+you@machine $ inspec plugin install inspec-resource-lister
+```
+
+You can then run:
+
+```
+you@machine $ inspec plugin help listresources
+# ... Usage info
+
+you@machine $ inspec plugin listresources core
+aide_conf
+apache
+apache_conf
+... snip ...
+yumrepo
+zfs_dataset
+zfs_pool
+------------------------------
+160 resources total
+```
+
+## Features of This Example Kit
+
+This example plugin is a full-fledged plugin example, with everything a real-world, industrial grade plugin would have, including:
+
+* an implementation of an InSpec CLI Command, using the InSpec PluginV2 API
+* documentation (you are reading it now)
+* tests, at the unit and functional level
+* a .gemspec, for packaging and publishing it as a gem
+* a Gemfile, for managing its dependencies
+* a Rakefile, for running development tasks
+* Rubocop linting support for using the base InSpec project rubocop.yml (See Rakefile)
+
+You are encouraged to use this plugin as a starting point for real plugins.
+
+## Development of a Plugin
+
+[Plugin Development](https://github.com/inspec/inspec/blob/master/docs/dev/plugins.md) is documented on the `inspec` project on GitHub.  Additionally, this example
+plugin has extensive comments explaining what is happening, and why.
+
+### A Tour of the Plugin
+
+One nice circuit of the plugin might be:
+ * look at the gemspec, to see what the plugin thinks it does
+ * look at the functional tests, to see the plugin proving it does what it says
+ * look at the unit tests, to see how the plugin claims it is internally structured
+ * look at the Rakefile, to see how to interact with the project
+ * look at lib/inspec-resource-lister.rb, the entry point which InSpec will always load if the plugin is installed
+ * look at lib/inspec-resource-lister/plugin.rb, the plugin definition which InSpec uses to understand what the plugin _can_ do.
+ * look at lib/inspec-resource-lister/cli_command.rb, the CLI Command implementation itself.
+

data/inspec-resource-lister.gemspec

@@ -0,0 +1,45 @@
+# coding: utf-8
+
+# As plugins are usually packaged and distributed as a RubyGem,
+# we have to provide a .gemspec file, which controls the gembuild
+# and publish process.  This is a fairly generic gemspec.
+
+# It is traditional in a gemspec to dynamically load the current version
+# from a file in the source tree.  The next three lines make that happen.
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'inspec-resource-lister/version'
+
+Gem::Specification.new do |spec|
+  # Importantly, all InSpec plugins must be prefixed with `inspec-` (most
+  # plugins) or `train-` (plugins which add new connectivity features).
+  spec.name          = 'inspec-resource-lister'
+
+  # It is polite to namespace your plugin under InspecPlugins::YourPluginInCamelCase
+  spec.version       = InspecPlugins::ResourceLister::VERSION
+  spec.authors       = ['Clinton Wolfe']
+  spec.email         = ['cwolfe@chef.io']
+  spec.summary       = 'InSpec Plugin example, lists available resources'
+  spec.description   = 'Example for implementing an InSpec Plugin.  This simply lists available resources.'
+  spec.homepage      = 'https://github.com/inspec/inspec/tree/master/examples/plugin'
+  spec.license       = 'Apache-2.0'
+
+  # Though complicated-looking, this is pretty standard for a gemspec.
+  # It just filters what will actually be packaged in the gem (leaving
+  # out tests, etc)
+  spec.files = %w{
+    README.md inspec-resource-lister.gemspec Gemfile
+  } + Dir.glob(
+    'lib/**/*', File::FNM_DOTMATCH
+  ).reject { |f| File.directory?(f) }
+  spec.require_paths = ['lib']
+
+  # If you rely on any other gems, list them here with any constraints.
+  # This is how `inspec plugin install` is able to manage your dependencies.
+  # For example, perhaps you are writing a thing that talks to AWS, and you
+  # want to ensure you have `aws-sdk` in a certain version.
+
+  # All plugins should mention inspec, > 2.2.78
+  # 2.2.78 included the v2 Plugin API
+  spec.add_dependency 'inspec', '>=2.2.78', '<4.0.0'
+end

data/lib/inspec-resource-lister.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+# This file is known as the "entry point."
+# This is the file InSpec will try to load if it
+# thinks your plugin is installed.
+
+# The *only* thing this file should do is setup the
+# load path, then load the plugin definition file.
+
+# Next two lines simply add the path of the gem to the load path.
+# This is not needed when being loaded as a gem; but when doing
+# plugin development, you may need it.  Either way, it's harmless.
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require 'inspec-resource-lister/plugin'

data/lib/inspec-resource-lister/cli_command.rb

@@ -0,0 +1,70 @@
+# encoding: utf-8
+
+require 'inspec/resource'
+
+module InspecPlugins::ResourceLister
+  # This class will provide the actual CLI implementation.
+  # Its superclass is provided by another call to Inspec.plugin,
+  # this time with two args.  The first arg specifies we are requesting
+  # version 2 of the Plugins API.  The second says we are making a CLI
+  # Command plugin component, so please make available any DSL needed
+  # for that.
+  #  In fact, aside from a some housekeeping DSL methods, most of the
+  # DSL provided is that of Thor. Inspec.plugin(2, :cli_command)
+  # promises to return a class that is a subclass of Thor.  So, to add
+  # commands, usage information, and options, use the Thor documentation.
+  class CliCommand < Inspec.plugin(2, :cli_command)
+    # This isn't provided by Thor, but is needed by InSpec so that it can
+    # register the subcommand.  Args are a usage message, and a short decription.
+    # These will appear when someone has installed the plugin, and then they
+    # run `inspec help`.
+    subcommand_desc 'list-resources [COMMAND]', 'List resources that InSpec finds.'
+
+    # The usual rhythm for a Thor CLI file is description, options, command method.
+    # Thor just has you call DSL methods in sequence prior to each command.
+    # Let's make a command, 'core', that lists all of the resources included with InSpec.
+
+    # First, provide a usage / description. This will appear in `inspec help list-resources`.
+    desc 'core [OPTIONS]', 'List resources that are included with InSpec.'
+
+    # Let's include an option, -s, to summarize the list.
+    # Refer to the Thors docs; there is a lot you can do here.
+    option :summary, desc: 'Include a total at the bottom', \
+                     type: :boolean, default: true, aliases: [:s]
+
+    # OK, now the actual method itself.  If you provide params, you're telling Thor that
+    # you accept CLI arguments after all options have been consumed. Let's accept a
+    # pattern, assumed to be a wildcard substring. If we provide a default, the CLI arg becomes optional.
+    def core(pattern = /.+/)
+      # The code here will *only* be executed if someone actually runs
+      # `inspec list-resources core`.  So, we can lazily wait to load
+      # expensive things here. However, InSpec has in fact already
+      # loaded the Resources, so we don't have anything to load.
+
+      # If we were passed a CLI arg, wrap the arg in Regexp matchers so
+      # we will match anywhere in the name.
+      unless pattern == /.+/
+        pattern = Regexp.new('.*' + pattern + '.*')
+      end
+
+      # This gets a bit into InSpec innards; but this is simply a Hash.
+      registry = Inspec::Resource.default_registry
+      resource_names = registry.keys.grep(pattern).sort
+
+      # One day we'll have nice UI support.
+      resource_names.each { |name| puts name }
+
+      if options[:summary]
+        puts '-' * 30
+        puts "#{resource_names.count} resources total"
+      end
+    end
+
+    # A neat idea for future work would be to add another command, perhaps
+    # 'resource-pack', which examines a possibly remote resource pack and
+    # enumerates the resources it defines.
+
+    # Another idea might be to fetch a profile, and list the resources actually
+    # used in the controls of the profile, along with counts.
+  end
+end

data/lib/inspec-resource-lister/plugin.rb

@@ -0,0 +1,55 @@
+# encoding: UTF-8
+
+# Plugin Definition file
+# The purpose of this file is to declare to InSpec what plugin_types (capabilities)
+# are included in this plugin, and provide hooks that will load them as needed.
+
+# It is important that this file load successfully and *quickly*.
+# Your plugin's functionality may never be used on this InSpec run; so we keep things
+# fast and light by only loading heavy things when they are needed.
+
+# Presumably this is light
+require 'inspec-resource-lister/version'
+
+# The InspecPlugins namespace is where all plugins should declare themselves.
+# The 'Inspec' capitalization is used throughout the InSpec source code; yes, it's
+# strange.
+module InspecPlugins
+  # Pick a reasonable namespace here for your plugin.  A reasonable choice
+  # would be the CamelCase version of your plugin gem name.
+  # inspec-resource-lister => ResourceLister
+  module ResourceLister
+    # This simple class handles the plugin definition, so calling it simply Plugin is OK.
+    #   Inspec.plugin returns various Classes, intended to be superclasses for various
+    # plugin components. Here, the one-arg form gives you the Plugin Definition superclass,
+    # which mainly gives you access to the hook / plugin_type DSL.
+    #   The number '2' says you are asking for version 2 of the plugin API. If there are
+    # future versions, InSpec promises plugin API v2 will work for at least two more InSpec
+    # major versions.
+    class Plugin < ::Inspec.plugin(2)
+      # Internal machine name of the plugin. InSpec will use this in errors, etc.
+      plugin_name :'inspec-resource-lister'
+
+      # Define a new CLI subcommand.
+      # The argument here will be used to match against the command line args,
+      # and if the user said `inspec list-resources`, this hook will get called.
+      # Notice that you can define multiple hooks with different names, and they
+      # don't have to match the plugin name.
+
+      # We'd like this to be list-resources, but Thor does not support hyphens
+      # see https://github.com/erikhuda/thor/pull/613
+      cli_command :listresources do
+        # Calling this hook doesn't mean list-resources is being executed - just
+        # that we should be ready to do so. So, load the file that defines the
+        # functionality.
+        # For example, InSpec will activate this hook when `inspec help` is
+        # executed, so that this plugin's usage message will be included in the help.
+        require 'inspec-resource-lister/cli_command'
+
+        # Having loaded our functionality, return a class that will let the
+        # CLI engine tap into it.
+        InspecPlugins::ResourceLister::CliCommand
+      end
+    end
+  end
+end

data/lib/inspec-resource-lister/version.rb

@@ -0,0 +1,10 @@
+# encoding: UTF-8
+
+# This file simply makes it easier for CI engines to update
+# the version stamp, and provide a clean way for the gemspec
+# to learn the current version.
+module InspecPlugins
+  module ResourceLister
+    VERSION = '0.1.0'.freeze
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: inspec-resource-lister
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Clinton Wolfe
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-09-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: inspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.78
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.78
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+description: Example for implementing an InSpec Plugin.  This simply lists available
+  resources.
+email:
+- cwolfe@chef.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- inspec-resource-lister.gemspec
+- lib/inspec-resource-lister.rb
+- lib/inspec-resource-lister/cli_command.rb
+- lib/inspec-resource-lister/plugin.rb
+- lib/inspec-resource-lister/version.rb
+homepage: https://github.com/inspec/inspec/tree/master/examples/plugin
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: InSpec Plugin example, lists available resources
+test_files: []