train-kubernetes-docs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1193da3e4b88cdff83a82226a1a842cefa49b690
+  data.tar.gz: c359a0ff97031ffb4b27d5d8345cb8c27063be02
+SHA512:
+  metadata.gz: feac8aa75a0d79b1e6f1e29ee426acf7d8c0b8b8c35832275d496801b09450dc234a9c7c527720fbbf0cc9b6e16ace526889abec644145861bca2ae16c09f3a6
+  data.tar.gz: f10a3f01aeaf43f59023d0b46fb1ade9f48bc385e0c134745760752f2f043be24d60f43ceb0d600fd47ab406c4e77ec782badc84b6671008861cdfe31d342e49

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+gemspec
+
+# Remaining group is only used for development.
+group :development do
+  gem 'bundler'
+  gem 'byebug'
+  gem 'inspec', '>= 3.7.11' # We need InSpec for the test harness while developing.
+  gem 'minitest'
+  gem 'rake'
+  gem 'rubocop', '~> 0.59'
+end

data/README.md

@@ -0,0 +1,107 @@
+# Kubernetes transport plugin for Chef Inspec Train
+
+This plugin allows applications that rely on Train to communicate with the Kubernetes API.  For example, InSpec uses this to perform compliance checks against any resource in the Kubernetes API. Train plugins are managed by InSpec CLI.
+
+## Usage
+
+When used in combination with the [InSpec Kubernetes Resource Pack](https://github.com/inspec/inspec-k8s) you can validate the spec of any Kubernetes resource you have access to:
+
+```ruby
+describe k8sobjects(api: 'v1', type: 'pods', namespace: 'default', labelSelector: 'run=nginx') do
+  it { should exist }
+  ...
+end
+```
+
+```ruby
+describe k8sobjects(api: 'v1', type: 'namespaces', labelSelector: 'myns=prod') do
+  it { should exist }
+  ...
+end
+```
+
+```ruby
+describe k8sobject(api: 'v1', type: 'pod', namespace: 'default', name: 'my-pod') do
+  it { should exist }
+  its('name') { should eq 'my-pod' }
+  ...
+end
+```
+
+## File resource
+```ruby
+inspec.backend.file('PATH', pod: 'POD', container: 'CONTAINER', namespace: 'NAMESPACE')
+```
+Currently it supports only Linux based containers
+
+
+## Preconditions
+
+- InSpec 3.7+ or 4.x+
+- Ruby 2.4+
+- You have set the env var KUBECONFIG or have a valid ~/.kube/config
+
+## Installation
+
+**_NOTE:_** **_The train-kubernetes-docs plugin now comes included with InSpec 5.22.0 and later, and does not require installation separately._**
+
+Train plugins are distributed as gems.  You may choose to manage the gem yourself, but if you are an InSpec user, InSPec can handle it for you.
+
+First, run:
+
+```
+gem install train-kubernetes-docs
+```
+
+Next, run:
+
+```
+inspec plugin install train-kubernetes-docs
+```
+
+Next, view the `plugins.json`:
+
+```
+vi ~/.inspec/plugins.json
+```
+
+If it has the version set to `"= 0.1.3"`, modify it to `"0.1.3"` and save the file.
+
+Verify the plugin:
+
+```
+inspec plugin list
+```
+
+```
+inspec detect -t k8s://
+
+== Platform Details
+
+Name:      k8s
+Families:  cloud, api
+Release:   0.1.3
+```
+
+## Troubleshooting (Only applicable for InSpec version 5.21.* and earlier)
+
+If you run into issues installing via `inspec plugin install train-kubernetes-docs`, try:
+
+* Try running `gem install train-kubernetes-docs` before `inspec plugin install train-kubernetes-docs`.
+* Ensure the `~/.inspec/plugins.json` has `"0.1.3"` and not `"= 0.1.3"` for the `version` value.  Modify it by hand if needed.
+* Ensure you can cleanly install the `k8s-ruby` gem version `0.10.4` or greater.  e.g. `gem install k8s-ruby -v 0.10.4`
+* Ensure that only one version of the `excon` gem is installed.  e.g. `gem list | grep excon`.  If you see two versions, `gem uninstall excon` and remove the older version.
+
+## Reporting Issues
+
+Bugs, typos, limitations, and frustrations are welcome to be reported through the [GitHub issues page for the train-kubernetes-docs project](https://github.com/inspec/train-kubernetes-docs/issues).
+
+You may also ask questions in the #inspec channel of the Chef Community Slack team.  However, for an issue to get traction, please report it as a github issue.
+
+### Development Process
+
+If you wish to contribute to this plugin, please use the usual fork-branch-push-PR cycle.  All functional changes need new tests, and bugfixes are expected to include a new test that demonstrates the bug.
+
+### Reference Information
+
+[Plugin Development](https://github.com/inspec/train/blob/master/docs/dev/plugins.md) is documented on the `train` project on GitHub.

data/lib/train-kubernetes-docs/connection.rb

@@ -0,0 +1,58 @@
+require 'train'
+require 'k8s-ruby'
+require 'train-kubernetes-docs/platform'
+require 'train-kubernetes-docs/kubectl_client'
+
+module TrainPlugins
+  module TrainKubernetes
+    class Connection < Train::Plugins::Transport::BaseConnection
+      include TrainPlugins::TrainKubernetes::Platform
+
+      def initialize(options)
+        super(options)
+        @pod = options[:pod] || options[:path]&.gsub('/', '')
+        @container = options[:container]
+        @namespace = options[:namespace] || options[:host]
+        parse_kubeconfig
+        connect
+      end
+
+      attr_accessor :client
+
+      def connect
+        @client.apis(prefetch_resources: true)
+      rescue Excon::Error::Socket => e
+        logger.error e.message
+        exit
+      end
+
+      def uri
+        "kubernetes://#{unique_identifier}"
+      end
+
+      def unique_identifier
+        @client.transport.server.gsub(%r{(http|https)\:\/\/}, '') || 'default'
+      end
+
+      def parse_kubeconfig
+        kubeconfig_file = @options[:kubeconfig] if @options[:kubeconfig]
+        @client = K8s::Client.config(K8s::Config.load_file(::File.expand_path(kubeconfig_file)))
+      end
+
+      private
+
+      attr_reader :pod, :container, :namespace
+
+      def run_command_via_connection(cmd, opts = {}, &_data_handler)
+        KubectlClient.new(pod: opts[:pod] || pod,
+                          container: opts[:container] || container,
+                          namespace: opts[:namespace] || namespace)
+                     .execute(cmd)
+      end
+
+      def file_via_connection(path, **args)
+        TrainPlugins::TrainKubernetes::File::Linux.new(self, path, pod: args[:pod], container: args[:container], namespace: args[:namespace])
+      end
+    end
+  end
+end

data/lib/train-kubernetes-docs/file/linux.rb

@@ -0,0 +1,149 @@
+require 'train/file/remote/linux'
+require 'train/extras/stat'
+
+module TrainPlugins
+  module TrainKubernetes
+    module File
+      class Linux < ::Train::File::Remote::Linux
+        def initialize(backend, path, follow_symlink = true, pod:, **args)
+          @backend = backend
+          @path = path || ''
+          @follow_symlink = follow_symlink
+          @pod = pod
+          @container = args[:container]
+          @namespace = args[:namespace]
+
+          sanitize_filename(path)
+          super(backend, path, follow_symlink)
+        end
+
+        def content
+          return @content if defined?(@content)
+
+          @content = @backend.run_command("cat #{@spath} || echo -n",
+                                          { pod: pod, namespace: namespace, container: container })
+                             .stdout
+          return @content unless @content.empty?
+
+          @content = nil if directory? || size.nil? || (size > 0)
+          @content
+        end
+
+        def content=(new_content)
+          execute_result = @backend.run_command('base64 --help', { pod: pod, namespace: namespace, container: container })
+          if execute_result.exit_status != 0
+            raise TransportError, "#{self.class} found no base64 binary for file writes"
+          end
+
+          unix_cmd = format("echo '%<base64>s' | base64 --decode > %<file>s",
+                            base64: Base64.strict_encode64(new_content),
+                            file: @spath)
+
+          @backend.run_command(unix_cmd, { pod: pod, namespace: namespace, container: container })
+
+          @content = new_content
+        end
+
+        def exist?
+          @exist ||= begin
+            f = @follow_symlink ? '' : " || test -L #{@spath}"
+            @backend.run_command("test -e #{@spath}" + f,
+                                 { pod: pod, namespace: namespace, container: container })
+                    .exit_status == 0
+          end
+        end
+
+        def mounted
+          @mounted ||=
+            @backend.run_command("mount | grep -- ' on #{@path} '",
+                                 { pod: pod, namespace: namespace, container: container })
+        end
+
+        def path
+          return @path unless @follow_symlink && symlink?
+
+          @link_path ||= read_target_path
+        end
+
+        def shallow_link_path
+          return nil unless symlink?
+
+          @shallow_link_path ||=
+            @backend.run_command("readlink #{@spath}", { pod: pod, namespace: namespace, container: container })
+                    .stdout
+                    .chomp
+        end
+
+        def stat
+          @stat ||= begin
+            shell_escaped_path = @spath
+            backend = @backend
+            follow_symlink = @follow_symlink
+            lstat = follow_symlink ? ' -L' : ''
+            format = '--printf'
+            res = backend.run_command("stat#{lstat} #{shell_escaped_path} 2>/dev/null #{format} '%s\n%f\n%U\n%u\n%G\n%g\n%X\n%Y\n%C'",
+                                      { pod: pod, namespace: namespace, container: container })
+            # ignore the exit_code: it is != 0 if selinux labels are not supported
+            # on the system.
+
+            fields = res.stdout.split("\n")
+            return {} if fields.length != 9
+
+            tmask = fields[1].to_i(16)
+            selinux = fields[8]
+            ## selinux security context string not available on esxi
+            selinux = nil if (selinux == '?') || (selinux == '(null)') || (selinux == 'C')
+            {
+              type: Train::Extras::Stat.find_type(tmask),
+              mode: tmask & 07777,
+              owner: fields[2],
+              uid: fields[3].to_i,
+              group: fields[4],
+              gid: fields[5].to_i,
+              mtime: fields[7].to_i,
+              size: fields[0].to_i,
+              selinux_label: selinux
+            }
+          end
+        end
+
+        def source
+          if @follow_symlink
+            self.class.new(@backend, @path, false, pod: pod, container: container, namespace: namespace)
+          else
+            self
+          end
+        end
+
+        def user_permissions
+          return {} unless exist?
+
+          skip_reource '`user_permissions` is not supported on your Linux Containers yet.'
+        end
+
+        def inherited?
+          return false unless exist?
+
+          skip_resource '`inherited?` is not supported on your Linux Containers yet.'
+        end
+
+        private
+
+        # Returns full path of a symlink target(real dest) or '' on symlink loop
+        def read_target_path
+          full_path = @backend.run_command("readlink -n #{@spath} -f",
+                                           { pod: pod, namespace: namespace, container: container })
+                              .stdout
+          # Needed for some OSes like OSX that returns relative path
+          # when the link and target are in the same directory
+          if !full_path.start_with?('/') && full_path != ''
+            full_path = ::File.expand_path("../#{full_path}", @spath)
+          end
+          full_path
+        end
+
+        attr_reader :pod, :container, :namespace
+      end
+    end
+  end
+end

data/lib/train-kubernetes-docs/file/linux_immutable_file_check.rb

@@ -0,0 +1,50 @@
+require 'inspec/resources/file'
+require 'inspec/exceptions'
+
+module TrainPlugins
+  module TrainKubernetes
+    module File
+      class LinuxImmutableFileCheck < Inspec::Resources::LinuxImmutableFlagCheck
+        def initialize(inspec, file, pod:, container: nil, namespace: nil)
+          @pod = pod
+          @container = container
+          @namespace = namespace
+          super(inspec, file)
+        end
+
+        def find_utility_or_error(utility_name)
+          %W(/usr/sbin/#{utility_name} /sbin/#{utility_name} /usr/bin/#{utility_name} /bin/#{utility_name} #{utility_name}).each do |cmd|
+            if inspec.backend
+                     .run_command("sh -c 'type \"#{cmd}\"'", { pod: pod, container: container, namespace: namespace })
+                     .exit_status.to_i == 0
+              return cmd
+            end
+          end
+
+          raise Inspec::Exceptions::ResourceFailed, "Could not find `#{utility_name}`"
+        end
+
+        def is_immutable?
+          # Check if lsattr is available. In general, all linux system has lsattr & chattr
+          # This logic check is valid for immutable flag set with chattr
+          utility = find_utility_or_error('lsattr')
+
+          utility_cmd = inspec.backend.run_command("#{utility} #{file_path}",
+                                                   { pod: pod, container: container, namespace: namespace })
+
+          raise Inspec::Exceptions::ResourceFailed, "Executing #{utility} #{file_path} failed: #{utility_cmd.stderr}" if utility_cmd.exit_status.to_i != 0
+
+          # General output for lsattr file_name is:
+          # ----i---------e----- file_name
+          # The fifth char resembles the immutable flag. Total 20 flags are allowed.
+          lsattr_info = utility_cmd.stdout.strip.squeeze(' ')
+          lsattr_info =~ /^.{4}i.{15} .*/
+        end
+
+        private
+
+        attr_reader :pod, :container, :namespace
+      end
+    end
+  end
+end

data/lib/train-kubernetes-docs/file/linux_permissions.rb

@@ -0,0 +1,25 @@
+module TrainPlugins
+  module TrainKubernetes
+    module File
+      class LinuxPermissions < Inspec::Resources::UnixFilePermissions
+        def initialize(inspec, pod:, namespace: nil, container: nil)
+          @pod = pod
+          @namespace = namespace
+          @container = container
+          super(inspec)
+        end
+
+        def check_file_permission_by_user(access_type, user, path)
+          flag = permission_flag(access_type)
+          perm_cmd = "su -s /bin/sh -c \"test -#{flag} #{path}\" #{user}"
+          cmd = inspec.backend.run_command(perm_cmd, { pod: pod, namespace: namespace, container: container })
+          cmd.exit_status == 0
+        end
+
+        private
+
+        attr_reader :pod, :container, :namespace
+      end
+    end
+  end
+end

data/lib/train-kubernetes-docs/kubectl_client.rb

@@ -0,0 +1,44 @@
+require 'mixlib/shellout'
+require 'train/extras'
+
+module TrainPlugins
+  module TrainKubernetes
+    class KubectlClient
+      attr_reader :pod, :container, :namespace
+
+      DEFAULT_NAMESPACE = 'default'.freeze
+
+      def initialize(pod:, namespace: nil, container: nil)
+        @pod = pod
+        @container = container
+        @namespace = namespace || DEFAULT_NAMESPACE
+      end
+
+      def execute(command, stdin: true, tty: true)
+        instruction = build_instruction(command, stdin, tty)
+        shell = Mixlib::ShellOut.new(instruction)
+        res = shell.run_command
+        Train::Extras::CommandResult.new(res.stdout, res.stderr, res.exitstatus)
+      rescue Errno::ENOENT => _e
+        Train::Extras::CommandResult.new('', '', 1)
+      end
+
+      private
+
+      def shell
+        @shell ||= Mixlib::ShellOut.new(instruction)
+      end
+
+      def build_instruction(command, stdin, _tty)
+        ['kubectl exec'].tap do |arr|
+          arr << '--stdin' if stdin
+          arr << pod if pod
+          arr << '-n'
+          arr << namespace
+          arr << '--'
+          arr << command
+        end.join("\s")
+      end
+    end
+  end
+end

data/lib/train-kubernetes-docs/platform.rb

@@ -0,0 +1,10 @@
+module TrainPlugins
+  module TrainKubernetes
+    module Platform
+      def platform
+        Train::Platforms.name('k8s').in_family('cloud')
+        force_platform!('k8s', release: TrainPlugins::TrainKubernetes::VERSION)
+      end
+    end
+  end
+end

data/lib/train-kubernetes-docs/transport.rb

@@ -0,0 +1,16 @@
+require 'train-kubernetes-docs/connection'
+
+module TrainPlugins
+  module TrainKubernetes
+    class Transport < Train.plugin(1)
+      name 'k8s'
+      option :kubeconfig, default: ENV['KUBECONFIG'] || '~/.kube/config'
+      option :pod, default: nil
+      option :container, default: nil
+      option :namespace, default: nil
+      def connection(_instance_opts = nil)
+        @connection ||= TrainPlugins::TrainKubernetes::Connection.new(@options)
+      end
+    end
+  end
+end

data/lib/train-kubernetes-docs/version.rb

@@ -0,0 +1,10 @@
+# This file exists simply to record the version number of the plugin.
+# It is kept in a separate file, so that your gemspec can load it and
+# learn the current version without loading the whole plugin.  Also,
+# many CI servers can update this file when "version bumping".
+
+module TrainPlugins
+  module TrainKubernetes
+    VERSION = '0.1.0'.freeze
+  end
+end

data/lib/train-kubernetes-docs.rb

@@ -0,0 +1,21 @@
+# This file is known as the "entry point."
+# This is the file Train will try to load if it
+# thinks your plugin is needed.
+
+# The *only* thing this file should do is setup the
+# load path, then load plugin files.
+
+# 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)
+
+# It's traditional to keep your gem version in a separate file, so CI can find it easier.
+require 'train-kubernetes-docs/version'
+
+# A train plugin has three components: Transport, Connection, and Platform.
+# Transport acts as the glue.
+require 'train-kubernetes-docs/transport'
+require 'train-kubernetes-docs/platform'
+require 'train-kubernetes-docs/file/linux'

data/train-kubernetes-docs.gemspec

@@ -0,0 +1,50 @@
+# 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__)
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'train-kubernetes-docs/version'
+
+Gem::Specification.new do |spec|
+  # Importantly, all Train plugins must be prefixed with `train-`
+  spec.name          = 'train-kubernetes-docs'
+
+  # It is polite to namespace your plugin under TrainPlugins::YourPluginInCamelCase
+  spec.version       = TrainPlugins::TrainKubernetes::VERSION
+  spec.authors       = ['Brad Geesaman']
+  spec.email         = ['bradgeesaman@gmail.com']
+  spec.summary       = 'DOCS Train Kubernetes'
+  spec.description   = 'A Train "transport" plugin for Chef Inspec that allows testing of all Kubernetes API resources'
+  spec.homepage      = 'https://github.com/inspec/train-kubernetes-docs'
+  spec.license       = 'Apache-2.0'
+
+  spec.required_ruby_version = '>= 2.4'
+
+  # 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 train-kubernetes-docs.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.
+
+  # If you only need certain gems during development or testing, list
+  # them in Gemfile, not here.
+  # Do not list inspec as a dependency of the train plugin.
+
+  # All plugins should mention train, > 1.4
+  # pinning k8s-ruby to 0.10.5 to avoid broken dry-type gem upgrades from k8s-ruby
+  spec.add_dependency 'k8s-ruby', '~> 0.14.0'
+  spec.add_dependency 'train', '~> 3.0'
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: train-kubernetes-docs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brad Geesaman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: k8s-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+- !ruby/object:Gem::Dependency
+  name: train
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Train "transport" plugin for Chef Inspec that allows testing of all
+  Kubernetes API resources
+email:
+- bradgeesaman@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- train-kubernetes-docs.gemspec
+- Gemfile
+- lib/train-kubernetes-docs/connection.rb
+- lib/train-kubernetes-docs/file/linux.rb
+- lib/train-kubernetes-docs/file/linux_immutable_file_check.rb
+- lib/train-kubernetes-docs/file/linux_permissions.rb
+- lib/train-kubernetes-docs/kubectl_client.rb
+- lib/train-kubernetes-docs/platform.rb
+- lib/train-kubernetes-docs/transport.rb
+- lib/train-kubernetes-docs/version.rb
+- lib/train-kubernetes-docs.rb
+homepage: https://github.com/inspec/train-kubernetes-docs
+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: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14.1
+signing_key: 
+specification_version: 4
+summary: DOCS Train Kubernetes
+test_files: []