Class: Inspec::Resources::FileResource

Inherits:
Object
  • Object
show all
Includes:
FilePermissionsSelector, Utils::LinuxMountParser
Defined in:
lib/inspec/resources/file.rb

Overview

TODO: rename file_resource.rb

Direct Known Subclasses

Bond, Directory

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Utils::LinuxMountParser

#includes_whitespaces?, #parse_mount_options

Methods included from FilePermissionsSelector

#select_file_perms_style

Constructor Details

#initialize(path) ⇒ FileResource

Returns a new instance of FileResource.



39
40
41
42
43
44
 
# File 'lib/inspec/resources/file.rb', line 39

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

Instance Attribute Details

#file ⇒ Object (readonly)

Returns the value of attribute file.



38
39
40
 
# File 'lib/inspec/resources/file.rb', line 38

def file
  @file
end

#mount_options ⇒ Object (readonly)

Returns the value of attribute mount_options.



38
39
40
 
# File 'lib/inspec/resources/file.rb', line 38

def mount_options
  @mount_options
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



38
39
40
 
# File 'lib/inspec/resources/file.rb', line 38

def path
  @path
end

Instance Method Details

#allowed?(permission, opts = {}) ⇒ Boolean

Returns:

  • (Boolean) 


108
109
110
111
112
113
 
# File 'lib/inspec/resources/file.rb', line 108

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

#contain(*_) ⇒ Object 



83
84
85
 
# File 'lib/inspec/resources/file.rb', line 83

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

#content ⇒ Object 



58
59
60
61
62
63
 
# File 'lib/inspec/resources/file.rb', line 58

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

  res.force_encoding("utf-8")
end

#content_as_json ⇒ Object

parse the json file content and returns the content



198
199
200
201
202
203
 
# File 'lib/inspec/resources/file.rb', line 198

def content_as_json
  require "json" unless defined?(JSON)
  JSON.parse(file.content)
rescue => e
  raise Inspec::Exceptions::ResourceFailed, "Unable to parse the given JSON file: #{e.message}"
end

#content_as_yaml ⇒ Object

parse the yaml file content and returns the content



206
207
208
209
210
211
 
# File 'lib/inspec/resources/file.rb', line 206

def content_as_yaml
  require "yaml" unless defined?(YAML)
  YAML.load(file.content)
rescue => e
  raise Inspec::Exceptions::ResourceFailed, "Unable to parse the given YAML file: #{e.message}"
end

#executable?(by_usergroup, by_specific_user) ⇒ Boolean

Returns:

  • (Boolean) 


101
102
103
104
105
106
 
# File 'lib/inspec/resources/file.rb', line 101

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

#immutable? ⇒ Boolean

Returns:

  • (Boolean)

Raises:



185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/inspec/resources/file.rb', line 185

def immutable?
  raise Inspec::Exceptions::ResourceSkipped, "The `be_immutable` matcher is not supported on your OS yet." unless inspec.os.unix?

  if inspec.os.linux?
    file_info = LinuxImmutableFlagCheck.new(inspec, file)
  else
    file_info = UnixImmutableFlagCheck.new(inspec, file)
  end

  file_info.is_immutable?
end

#inherited? ⇒ Boolean

returns true if inheritance is enabled on file or folder

Returns:

  • (Boolean) 


75
76
77
78
79
80
81
 
# File 'lib/inspec/resources/file.rb', line 75

def inherited?
  return false unless exist?

  return skip_resource "`inherited?` is not supported on your OS yet." unless inspec.os.windows?

  @perms_provider.inherited?(file)
end

#more_permissive_than?(max_mode = nil) ⇒ Boolean

Returns:

  • (Boolean)

Raises:

  • (ArgumentError) 


157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/inspec/resources/file.rb', line 157

def more_permissive_than?(max_mode = nil)
  return nil unless exist?
  raise ArgumentError, "You must provide a value for the `maximum allowable permission` for the file." if max_mode.nil?
  raise ArgumentError, "You must provide 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-digit 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

#mounted?(expected_options = nil, identical = false) ⇒ Boolean

Returns:

  • (Boolean) 


115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/inspec/resources/file.rb', line 115

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

#readable?(by_usergroup, by_specific_user) ⇒ Boolean

Returns:

  • (Boolean) 


87
88
89
90
91
92
 
# File 'lib/inspec/resources/file.rb', line 87

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

#resource_id ⇒ Object 



221
222
223
 
# File 'lib/inspec/resources/file.rb', line 221

def resource_id
  path
end

#sgid ⇒ Object Also known as: setgid? 



145
146
147
 
# File 'lib/inspec/resources/file.rb', line 145

def sgid
  (mode & 02000) > 0
end

#sticky ⇒ Object Also known as: sticky? 



151
152
153
 
# File 'lib/inspec/resources/file.rb', line 151

def sticky
  (mode & 01000) > 0
end

#suid ⇒ Object Also known as: setuid? 



139
140
141
 
# File 'lib/inspec/resources/file.rb', line 139

def suid
  (mode & 04000) > 0
end

#to_s ⇒ Object 



213
214
215
216
217
218
219
 
# File 'lib/inspec/resources/file.rb', line 213

def to_s
  if file
    "File #{source_path}"
  else
    "Bad File on %s" % [inspec.backend.class]
  end
end

#user_permissions ⇒ Object

returns hash containing list of users/groups and their file permissions.



66
67
68
69
70
71
72
 
# File 'lib/inspec/resources/file.rb', line 66

def user_permissions
  return {} unless exist?

  return skip_resource "`user_permissions` is not supported on your OS yet." unless inspec.os.windows?

  @perms_provider.user_permissions(file)
end

#writable?(by_usergroup, by_specific_user) ⇒ Boolean

Returns:

  • (Boolean) 


94
95
96
97
98
99
 
# File 'lib/inspec/resources/file.rb', line 94

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