Class: SafePath

Inherits:
Object
  • Object
show all
Defined in:
lib/ndr_support/safe_path.rb

Overview

SafePath

SafePath is a class which contains path to a file or directory. It also holds “path space” and permissions. The path space is a directory. Everything in this directory and all the subdirectories can be accessed with the permissions given to the constructor. The instance of the class checks whether the path constructed points to a directory, whcih is in the “path space”. The idea is to limit the access of the program to given directory.

Example of usage is :

sp = SafePath("dbs_inbox")

The root directory of the pathspace is in the file config/filesystem_paths.yml . In this case dbs_inbox has root /mounts/ron/dbs_inbox . Every path which starts with /mount/ron/dbs_inbox is considered as safe. If a path is constructed which is /mounts/ron/dbs_inbox/../../../etc/passwd for example then the class will evaluate the path and it will raise exception SecurityError.

The paths can be constructed by using +, join or join!. Example:

This:
  sp = SafePath("dbs_inbox")
  sp + "/my_dir"
Points to:
  /mounts/ron/dbs_inbox/my_dir

The functions join and join! work in similar way. The difference between join and join! is that join creates new instance of the class SafePath and return it and join! doesn’t create new instance, but works in-place and after that it returns reference to the current instance. The both operators can be used like that:

sp.join("/my_dir")  #this is the same as sp + "my_dir"
sp.join!("/my_dir") #this is NOT the same as sp "my_dir"

Warning the function sp.path = “some_path” will treat some_path as absolute path and if it doesn’t point to the root it will raise exception. The danger is that it returns the argument on the right hand side. So if it is a string the operator will return a string. This is the way ruby works. If it is used properly it shouldn’t be a problem. The best way to use it is:

sp.path = sp.root + "my_dir"

sp.root returns SafePath and after that + is called which also returns SafePath. So the right hand side of the expression is SafePath and the = will return SafePath.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path_space, root_suffix = '') ⇒ SafePath

Takes:

 * path - This is a path to a directory. Usually a string.
 * path_space - This is identifier of the path space in whichi the system should work.
   it is a string. To find list of path spaces with their roots, please
   see config/filesystem_paths.yml

Raises:
  * ArgumentError
  * SecurityError



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/ndr_support/safe_path.rb', line 85

def initialize(path_space, root_suffix = '')
  # The class has to use different path definitions during test

  fs_paths = self.class.fs_paths

  platform = fs_paths.keys.select do |key|
    RUBY_PLATFORM.match key
  end[0]

  root_path_regexp = if platform == /mswin32|mingw32/
                      /\A([A-Z]:[\\\/]|\/\/)/
                     else
                      /\A\//
                     end

  fail ArgumentError, "The space #{path_space} doesn't exist. Please choose one of: #{fs_paths[platform].keys.inspect}" unless fs_paths[platform][path_space]
  fail ArgumentError, "The space #{path_space} is broken. The root path should be absolute path but it was #{fs_paths[platform][path_space]['root']}" unless fs_paths[platform][path_space]['root'].match(root_path_regexp)
  fail ArgumentError, "The space #{path_space} is broken. No permissions specified}" unless fs_paths[platform][path_space]['prms']

  # The function verify uses @root. Therefore first assign the root path
  # specified in the yaml file. After that verify that the root path
  # specified from the contructor is subpath of the path specified in the
  # yaml file. If it is not raise exception before anything else is done.
  #
  # The reason to assign @root 2 times is that it is better to have the
  # logic verifing the path in only one function. This way it is going
  # to be easier to maintain it and keep it secure.
  #

  @root = File.expand_path fs_paths[platform][path_space]['root']
  @root = verify(File.join(fs_paths[platform][path_space]['root'], root_suffix)) unless root_suffix.blank?

  @path_space = path_space
  @maximum_prms = fs_paths[platform][path_space]['prms']

  self.path = @root
end

Class Method Details

.configure!(filepath) ⇒ Object

Takes the path the filesystem_paths.yml file that should be used. Attempting to reconfigure with new settings will raise a security error.



64
65
66
67
68
69
70
71
72
73
 
# File 'lib/ndr_support/safe_path.rb', line 64

def self.configure!(filepath)
  if defined?(@@fs_paths)
    fail SecurityError, 'Attempt to re-assign SafePath config!'
  else
    File.open(filepath, 'r') do |file|
      @@fs_paths = YAML.load(ERB.new(file.read).result)
      @@fs_paths.freeze
    end
  end
end

.fs_paths ⇒ Object

Returns the list of safe ‘root’ filesystem locations, or raises a SecurityError if no configuration has been provided.



53
54
55
56
57
58
59
 
# File 'lib/ndr_support/safe_path.rb', line 53

def self.fs_paths
  if defined?(@@fs_paths)
    @@fs_paths
  else
    fail SecurityError, 'SafePath not configured!'
  end
end

Instance Method Details

#+(path) ⇒ Object

Another name for join



221
222
223
 
# File 'lib/ndr_support/safe_path.rb', line 221

def +(path)
  self.join(path)
end

#==(other) ⇒ Object 



123
124
125
 
# File 'lib/ndr_support/safe_path.rb', line 123

def ==(other)
  other.class == SafePath and other.root.to_s == @root and other.permissions == self.permissions and other.to_s == self.to_s
end

#join(path) ⇒ Object

Used to construct path. It joins the current path with the given one. Takes:

* path - path to be concatenated

Returns:

New instance of SafePath which contains the new path.

Raises:

* SecurityError



235
236
237
238
239
 
# File 'lib/ndr_support/safe_path.rb', line 235

def join(path)
  r = self.clone
  r.path = File.join(@path, path)
  r
end

#join!(path) ⇒ Object

Used to construct path. It joins the current path with the given one. Takes:

* path - path to be concatenated

Returns:

Reference to the current instance. It works in-place

Raises:

* SecurityError



251
252
253
254
 
# File 'lib/ndr_support/safe_path.rb', line 251

def join!(path)
  self.path = File.join(@path, path)
  self
end

#length ⇒ Object 



256
257
258
 
# File 'lib/ndr_support/safe_path.rb', line 256

def length()
  @path.length
end

#path=(path) ⇒ Object

Setter for path.

Takes:

* path - The path.

Returns:

Array - this is the result of the assignment. Note it is the right hand side of the expression

Raises:

* SecurityError

Warning avoid using this in expressions like this (safe_path_new = (safe_path.path = safe_path.root.to_s + “/test”)) + path_from_attacker This is unsafe!



215
216
217
218
 
# File 'lib/ndr_support/safe_path.rb', line 215

def path=(path)
  @path = verify(path)
  self
end

#path_space ⇒ Object

Getter for path space identifier.

Returns:

Array



162
163
164
 
# File 'lib/ndr_support/safe_path.rb', line 162

def path_space
  @path_space
end

#permissions ⇒ Object

Getter for permissions.

Returns:

Array



149
150
151
152
153
154
155
 
# File 'lib/ndr_support/safe_path.rb', line 149

def permissions
  if @prm
    @prm
  else
    @maximum_prms
  end
end

#permissions=(permissions) ⇒ Object

The permissions are specified in the yml file, but this function can select subset of these permissions. It cannot select permission, which is not specified in the yml file.

Takes:

* Array of permission or single permission - If it is array then
  tha array could contain duplicates and it also can be nested.
  All the duplicates will be removed and the array will be flattened

Returns:

Array - this is the reuslt of the assignment. Note it is the right hand side of the expression

Raises:

* ArgumentError



193
194
195
196
197
198
199
 
# File 'lib/ndr_support/safe_path.rb', line 193

def permissions=(permissions)
  err_mess = "permissions has to be one or more of the values: #{@maximum_prms.inspect}\n but it was #{permissions.inspect}"

  @prm = [permissions].flatten.each do |prm|
    fail ArgumentError, err_mess unless @maximum_prms.include?(prm)
  end.uniq
end

#root ⇒ Object

Getter for the root of the path space.

Returns:

SafePath



171
172
173
174
175
176
 
# File 'lib/ndr_support/safe_path.rb', line 171

def root
  r = self.clone
  r.path = @root
  r.permissions = self.permissions
  r
end

#to_s ⇒ Object

WARNING: do not use sp.to_s + from_attacker . This is unsafe!

Returns:

String



132
133
134
 
# File 'lib/ndr_support/safe_path.rb', line 132

def to_s
  @path
end

#to_str ⇒ Object

WARNING: do not use s.to_s + “my_path” . This is unsafe!

Returns:
  String



141
142
143
 
# File 'lib/ndr_support/safe_path.rb', line 141

def to_str
  self.to_s
end