Appendix B - More Resource Examples

11.1. File

# copyright: 2015, Vulcano Security GmbH

require "shellwords"
require "inspec/utils/parser"

module Inspec::Resources
  module FilePermissionsSelector
    def select_file_perms_style(os)
      if os.unix?
        UnixFilePermissions.new(inspec)
      elsif os.windows?
        WindowsFilePermissions.new(inspec)
      end
    end
  end

  # TODO: rename file_resource.rb
  class FileResource < Inspec.resource(1)
    include FilePermissionsSelector
    include LinuxMountParser

    name "file"
    supports platform: "unix"
    supports platform: "windows"
    desc "Use the file InSpec audit resource to test all system file types, including files, directories, symbolic links, named pipes, sockets, character devices, block devices, and doors."
    example <<~EXAMPLE
      describe file('path') do
        it { should exist }
        it { should be_file }
        it { should be_readable }
        it { should be_writable }
        it { should be_executable.by_user('root') }
        it { should be_owned_by 'root' }
        its('mode') { should cmp '0644' }
      end
    EXAMPLE

    attr_reader :file, :mount_options
    def initialize(path)
      # select permissions style
      @perms_provider = select_file_perms_style(inspec.os)
      @file = inspec.backend.file(path)
    end

    %w{
      type exist? file? block_device? character_device? socket? directory?
      symlink? pipe? mode mode? owner owned_by? group grouped_into?
      link_path shallow_link_path linked_to? mtime size selinux_label immutable?
      product_version file_version version? md5sum sha256sum
      path basename source source_path uid gid
    }.each do |m|
      define_method m do |*args|
        file.send(m, *args)
      end
    end

    def content
      res = file.content
      return nil if res.nil?

      res.force_encoding("utf-8")
    end

    def contain(*_)
      raise "Contain is not supported. Please use standard RSpec matchers."
    end

    def readable?(by_usergroup, by_specific_user)
      return false unless exist?
      return skip_resource "`readable?` is not supported on your OS yet." if @perms_provider.nil?

      file_permission_granted?("read", by_usergroup, by_specific_user)
    end

    def writable?(by_usergroup, by_specific_user)
      return false unless exist?
      return skip_resource "`writable?` is not supported on your OS yet." if @perms_provider.nil?

      file_permission_granted?("write", by_usergroup, by_specific_user)
    end

    def executable?(by_usergroup, by_specific_user)
      return false unless exist?
      return skip_resource "`executable?` is not supported on your OS yet." if @perms_provider.nil?

      file_permission_granted?("execute", by_usergroup, by_specific_user)
    end

    def allowed?(permission, opts = {})
      return false unless exist?
      return skip_resource "`allowed?` is not supported on your OS yet." if @perms_provider.nil?

      file_permission_granted?(permission, opts[:by], opts[:by_user])
    end

    def mounted?(expected_options = nil, identical = false)
      mounted = file.mounted

      # return if no additional parameters have been provided
      return file.mounted? if expected_options.nil?

      # deprecation warning, this functionality will be removed in future version
      Inspec.deprecate(:file_resource_be_mounted_matchers, "The file resource `be_mounted.with` and `be_mounted.only_with` matchers are deprecated. Please use the `mount` resource instead")

      # we cannot read mount data on non-Linux systems
      return nil unless inspec.os.linux?

      # parse content if we are on linux
      @mount_options ||= parse_mount_options(mounted.stdout, true)

      if identical
        # check if the options should be identical
        @mount_options == expected_options
      else
        # otherwise compare the selected values
        @mount_options.contains(expected_options)
      end
    end

    def suid
      (mode & 04000) > 0
    end

    alias setuid? suid

    def sgid
      (mode & 02000) > 0
    end

    alias setgid? sgid

    def sticky
      (mode & 01000) > 0
    end

    alias sticky? sticky

    def more_permissive_than?(max_mode = nil)
      raise Inspec::Exceptions::ResourceFailed, "The file" + file.path + "doesn't seem to exist" unless exist?
      raise ArgumentError, "You must proivde a value for the `maximum allowable permission` for the file." if max_mode.nil?
      raise ArgumentError, "You must proivde the `maximum permission target` as a `String`, you provided: " + max_mode.class.to_s unless max_mode.is_a?(String)
      raise ArgumentError, "The value of the `maximum permission target` should be a valid file mode in 4-ditgit octal format: for example, `0644` or `0777`" unless /(0)?([0-7])([0-7])([0-7])/.match?(max_mode)

      # Using the files mode and a few bit-wise calculations we can ensure a
      # file is no more permisive than desired.
      #
      # 1. Calculate the inverse of the desired mode (e.g., 0644) by XOR it with
      # 0777 (all 1s). We are interested in the bits that are currently 0 since
      # it indicates that the actual mode is more permissive than the desired mode.
      # Conversely, we dont care about the bits that are currently 1 because they
      # cannot be any more permissive and we can safely ignore them.
      #
      # 2. Calculate the above result of ANDing the actual mode and the inverse
      # mode. This will determine if any of the bits that would indicate a more
      # permissive mode are set in the actual mode.
      #
      # 3. If the result is 0000, the files mode is equal
      # to or less permissive than the desired mode (PASS). Otherwise, the files
      # mode is more permissive than the desired mode (FAIL).

      max_mode = max_mode.to_i(8)
      inv_mode = 0777 ^ max_mode

      inv_mode & file.mode != 0
    end

    def to_s
      "File #{source_path}"
    end

    private

    def file_permission_granted?(access_type, by_usergroup, by_specific_user)
      raise "`file_permission_granted?` is not supported on your OS" if @perms_provider.nil?

      if by_specific_user.nil? || by_specific_user.empty?
        @perms_provider.check_file_permission_by_mask(file, access_type, by_usergroup, by_specific_user)
      else
        @perms_provider.check_file_permission_by_user(access_type, by_specific_user, source_path)
      end
    end
  end

  class FilePermissions
    attr_reader :inspec
    def initialize(inspec)
      @inspec = inspec
    end
  end

  class UnixFilePermissions < FilePermissions
    def permission_flag(access_type)
      case access_type
      when "read"
        "r"
      when "write"
        "w"
      when "execute"
        "x"
      else
        raise "Invalid access_type provided"
      end
    end

    def usergroup_for(usergroup, specific_user)
      if usergroup == "others"
        "other"
      elsif (usergroup.nil? || usergroup.empty?) && specific_user.nil?
        "all"
      else
        usergroup
      end
    end

    def check_file_permission_by_mask(file, access_type, usergroup, specific_user)
      usergroup = usergroup_for(usergroup, specific_user)
      flag = permission_flag(access_type)
      mask = file.unix_mode_mask(usergroup, flag)
      raise "Invalid usergroup/owner provided" if mask.nil?

      (file.mode & mask) != 0
    end

    def check_file_permission_by_user(access_type, user, path)
      flag = permission_flag(access_type)
      if inspec.os.linux?
        perm_cmd = "su -s /bin/sh -c \"test -#{flag} #{path}\" #{user}"
      elsif inspec.os.bsd? || inspec.os.solaris?
        perm_cmd = "sudo -u #{user} test -#{flag} #{path}"
      elsif inspec.os.aix?
        perm_cmd = "su #{user} -c test -#{flag} #{path}"
      elsif inspec.os.hpux?
        perm_cmd = "su #{user} -c \"test -#{flag} #{path}\""
      else
        return skip_resource "The `file` resource does not support `by_user` on your OS."
      end

      cmd = inspec.command(perm_cmd)
      cmd.exit_status == 0 ? true : false
    end
  end

  class WindowsFilePermissions < FilePermissions
    def check_file_permission_by_mask(_file, _access_type, _usergroup, _specific_user)
      raise "`check_file_permission_by_mask` is not supported on Windows"
    end

    def more_permissive_than?(*)
      raise Inspec::Exceptions::ResourceSkipped, "The `more_permissive_than?` matcher is not supported on your OS yet."
    end

    def check_file_permission_by_user(access_type, user, path)
      access_rule = translate_perm_names(access_type)
      access_rule = convert_to_powershell_array(access_rule)

      cmd = inspec.command("@(@((Get-Acl '#{path}').access | Where-Object {$_.AccessControlType -eq 'Allow' -and $_.IdentityReference -eq '#{user}' }) | Where-Object {($_.FileSystemRights.ToString().Split(',') | % {$_.trim()} | ? {#{access_rule} -contains $_}) -ne $null}) | measure | % { $_.Count }")
      cmd.stdout.chomp == "0" ? false : true
    end

    private

    def convert_to_powershell_array(arr)
      if arr.empty?
        "@()"
      else
        %{@('#{arr.join("', '")}')}
      end
    end

    # Translates a developer-friendly string into a list of acceptable
    # FileSystemRights that match it, because Windows has a fun heirarchy
    # of permissions that are able to be noted in multiple ways.
    #
    # See also: https://www.codeproject.com/Reference/871338/AccessControl-FileSystemRights-Permissions-Table
    def translate_perm_names(access_type)
      names = translate_common_perms(access_type)
      names ||= translate_granular_perms(access_type)
      names ||= translate_uncommon_perms(access_type)
      raise "Invalid access_type provided" unless names

      names
    end

    def translate_common_perms(access_type)
      case access_type
      when "full-control"
        %w{FullControl}
      when "modify"
        translate_perm_names("full-control") + %w{Modify}
      when "read"
        translate_perm_names("modify") + %w{ReadAndExecute Read}
      when "write"
        translate_perm_names("modify") + %w{Write}
      when "execute"
        translate_perm_names("modify") + %w{ReadAndExecute ExecuteFile Traverse}
      when "delete"
        translate_perm_names("modify") + %w{Delete}
      end
    end

    def translate_uncommon_perms(access_type)
      case access_type
      when "delete-subdirectories-and-files"
        translate_perm_names("full-control") + %w{DeleteSubdirectoriesAndFiles}
      when "change-permissions"
        translate_perm_names("full-control") + %w{ChangePermissions}
      when "take-ownership"
        translate_perm_names("full-control") + %w{TakeOwnership}
      when "synchronize"
        translate_perm_names("full-control") + %w{Synchronize}
      end
    end

    def translate_granular_perms(access_type)
      case access_type
      when "write-data", "create-files"
        translate_perm_names("write") + %w{WriteData CreateFiles}
      when "append-data", "create-directories"
        translate_perm_names("write") + %w{CreateDirectories AppendData}
      when "write-extended-attributes"
        translate_perm_names("write") + %w{WriteExtendedAttributes}
      when "write-attributes"
        translate_perm_names("write") + %w{WriteAttributes}
      when "read-data", "list-directory"
        translate_perm_names("read") + %w{ReadData ListDirectory}
      when "read-attributes"
        translate_perm_names("read") + %w{ReadAttributes}
      when "read-extended-attributes"
        translate_perm_names("read") + %w{ReadExtendedAttributes}
      when "read-permissions"
        translate_perm_names("read") + %w{ReadPermissions}
      end
    end
  end
end

11.2. Directory

require "inspec/resources/file"

module Inspec::Resources
  class Directory < FileResource
    name "directory"
    supports platform: "unix"
    supports platform: "windows"
    desc "Use the directory InSpec audit resource to test if the file type is a directory. This is equivalent to using the file InSpec audit resource and the be_directory matcher, but provides a simpler and more direct way to test directories. All of the matchers available to file may be used with directory."
    example <<~EXAMPLE
      describe directory('path') do
        it { should be_directory }
      end
    EXAMPLE

    def exist?
      file.exist? && file.directory?
    end

    def to_s
      "Directory #{source_path}"
    end
  end
end

11.3. etc_hosts

require "inspec/utils/parser"
require "inspec/utils/file_reader"

class EtcHosts < Inspec.resource(1)
  name "etc_hosts"
  supports platform: "linux"
  supports platform: "bsd"
  supports platform: "windows"
  desc 'Use the etc_hosts InSpec audit resource to find an
    ip_address and its associated hosts'
  example <<~EXAMPLE
    describe etc_hosts.where { ip_address == '127.0.0.1' } do
      its('ip_address') { should cmp '127.0.0.1' }
      its('primary_name') { should cmp 'localhost' }
      its('all_host_names') { should eq [['localhost', 'localhost.localdomain', 'localhost4', 'localhost4.localdomain4']] }
    end
  EXAMPLE

  attr_reader :params

  include CommentParser
  include FileReader

  DEFAULT_UNIX_PATH    = "/etc/hosts".freeze
  DEFAULT_WINDOWS_PATH = 'C:\windows\system32\drivers\etc\hosts'.freeze

  def initialize(hosts_path = nil)
    content = read_file_content(hosts_path || default_hosts_file_path)

    @params = parse_conf(content.lines)
  end

  FilterTable.create
    .register_column(:ip_address,     field: "ip_address")
    .register_column(:primary_name,   field: "primary_name")
    .register_column(:all_host_names, field: "all_host_names")
    .install_filter_methods_on_resource(self, :params)

  private

  def default_hosts_file_path
    inspec.os.windows? ? DEFAULT_WINDOWS_PATH : DEFAULT_UNIX_PATH
  end

  def parse_conf(lines)
    lines.reject(&:empty?).reject(&comment?).map(&parse_data).map(&format_data)
  end

  def comment?
    parse_options = { comment_char: "#", standalone_comments: false }

    ->(data) { parse_comment_line(data, parse_options).first.empty? }
  end

  def parse_data
    ->(data) { [data.split[0], data.split[1], data.split[1..-1]] }
  end

  def format_data
    ->(data) { %w{ip_address primary_name all_host_names}.zip(data).to_h }
  end
end