class Asciidoctor::PathResolver
=> start path /etc is outside of jail: /path/to/docs’
end
puts e.message
rescue SecurityError => e
resolver.system_path(‘images’, ‘/etc’, ‘/path/to/docs’, recover: false)
begin
=> ‘/path/to/docs/images’
resolver.system_path(‘/path/to/docs/images’, nil, ‘/path/to/docs’)
=> ‘path ../../../../../../css refers to location outside jail: /path/to/docs (disallowed in safe mode)’
end
puts e.message
rescue SecurityError => e
resolver.system_path(‘../../../css’, ‘../../..’, ‘/path/to/docs’, recover: false)
begin
=> ‘C:/data/docs/css’
resolver.system_path(‘..\..\css’, ‘C:\data\docs\assets’, ‘C:\data\docs’)
=> ‘C:/data/docs’
resolver.system_path(‘..’, ‘C:\data\docs\assets’, ‘C:\data\docs’)
=> ‘/path/to/docs/css’
resolver.system_path(‘../../../css’, ‘../../..’, ‘/path/to/docs’)
=> ‘/path/to/docs/css’
resolver.system_path(‘../../../css’, nil, ‘/path/to/docs’)
=> ‘/path/to/docs’
resolver.system_path(‘..’, nil, ‘/path/to/docs’)
=> ‘/path/to/docs’
resolver.system_path(nil, nil, ‘/path/to/docs’)
=> ‘/etc/images’
resolver.system_path(”, ‘/etc/images’)
=> ‘/etc/images’
resolver.system_path(‘images’, ‘/etc’)
=> ‘/etc/images’
resolver.system_path(‘/etc/images’)
=> ‘/path/to/images’
resolver.system_path(‘../images’)
=> ‘/path/to/docs/images’
resolver.system_path(‘images’)
=> ‘/path/to/docs’
resolver.working_dir
# System Paths
=> ‘../assets/images/tiger.png’
resolver.web_path(‘tiger.png’, ‘../assets/images’)
=> ‘assets/images’
resolver.web_path(‘images’, ‘assets’)
=> ‘/images’
resolver.web_path(‘/../images’)
=> ‘./assets/images’
resolver.web_path(‘./images/../assets/images’)
=> ‘/images’
resolver.web_path(‘/images’)
=> ‘./images’
resolver.web_path(‘./images’)
=> ‘images’
resolver.web_path(‘images’)
# Web Paths
resolver = PathResolver.new
Examples
makes the class both deterministic and easier to test.
and windows paths independent of the operating system on which it runs. This
internalizing these operations is that the class is able to handle both posix
it handles all aspects of path manipulation. The main benefit of
This class makes no use of path utilities from the Ruby libraries. Instead,
handles the task of joining a parent (start) and child (target) path.
Since joining two paths can result in an insecure path, this class also
directories outside of a jail path, if specified.
path name. Secure paths are paths which are restricted from accessing
paths are void of duplicate parent and current directory references in the
The main emphasis of the class is on creating clean and secure paths. Clean
system paths.
This class includes operations for handling both web paths (request URIs) and
Public: Handles all operations for resolving, cleaning and joining paths.
def absolute_path? path
path - the String path to check
backslash. Windows roots can start with a drive letter.
Unix absolute paths start with a slash. UNC paths can start with a slash or
not have to be posixified beforehand. This operation does not handle URIs.
This operation considers both posix paths and Windows paths. The path does
Public: Check whether the specified path is an absolute path.
def absolute_path? path (path.start_with? SLASH) || (@file_separator == BACKSLASH && (WindowsRootRx.match? path)) end
def descends_from? path, base
base - The String base path to check against. Can be relative.
path - The String path to check. Can be relative.
If path equals base, or base is a parent of path, return true.
Public: Determine whether path descends from base.
def descends_from? path, base if base == path 0 elsif base == SLASH (path.start_with? SLASH) && 1 else (path.start_with? base + SLASH) && (base.length + 1) end end
def expand_path path
returns a String path as a posix path with parent references resolved and self references removed.
path - the String path to expand
references (..), and removing self references (.).
Public: Expand the specified path by converting the path to a posix path, resolving parent
def expand_path path path_segments, path_root = partition_path path if path.include? DOT_DOT resolved_segments = [] path_segments.each do |segment| segment == DOT_DOT ? resolved_segments.pop : resolved_segments << segment end join_path resolved_segments, path_root else join_path path_segments, path_root end end
def extract_uri_prefix str
str - the String to check
the prefix is removed.
Uses the Asciidoctor::UriSniffRx regex to match the URI prefix in the specified String (e.g., http://). If present,
Internal: Efficiently extracts the URI prefix from the specified String if the String is a URI
def extract_uri_prefix str if (str.include? ':') && UriSniffRx =~ str [(str.slice $&.length, str.length), $&] else str end end
def initialize file_separator = nil, working_dir = nil
working_dir - the String working directory (optional, default: Dir.pwd)
(optional, default: File::ALT_SEPARATOR or File::SEPARATOR)
file_separator - the String file separator to use for path operations
expanded to an absolute path inside the constructor.
(to override the present working directory). The working directory will be
file separator (to override the system default) and the working directory
Public: Construct a new instance of PathResolver, optionally specifying the
def initialize file_separator = nil, working_dir = nil @file_separator = file_separator || ::File::ALT_SEPARATOR || ::File::SEPARATOR @working_dir = working_dir ? ((root? working_dir) ? (posixify working_dir) : (::File.expand_path working_dir)) : ::Dir.pwd @_partition_path_sys = {} @_partition_path_web = {} end
def join_path segments, root = nil
returns a String path formed by joining the segments using the posix file
root - a String path root (optional, default: nil)
segments - a String Array of path segments
a relative path.
if specified, to construct an absolute path. Otherwise join the segments as
how to work with paths specified this way, regardless of OS). Use the root,
Public: Join the segments using the posix file separator (since Ruby knows
def join_path segments, root = nil root ? %(#{root}#{segments.join SLASH}) : (segments.join SLASH) end
def partition_path path, web = nil
Returns a 2-item Array containing the Array of String path segments and the
as a web path (optional, default: false)
web - a Boolean indicating whether the path should be handled
path - the String path to partition
resolution in a certain context (checking for the breach of a jail, for instance).
Parent references are not resolved by this method since the consumer often needs to handle this
slash, if present. Prior to being partitioned, the path is converted to a posix path.
Public: Partition the path into path segments and remove self references (.) and the trailing
def partition_path path, web = nil if (result = (cache = web ? @_partition_path_web : @_partition_path_sys)[path]) return result end posix_path = posixify path if web # ex. /sample/path if web_root? posix_path root = SLASH # ex. ./sample/path elsif posix_path.start_with? DOT_SLASH root = DOT_SLASH end # otherwise ex. sample/path elsif root? posix_path # ex. //sample/path if unc? posix_path root = DOUBLE_SLASH # ex. /sample/path elsif posix_path.start_with? SLASH root = SLASH # ex. uri:classloader:sample/path (or uri:classloader:/sample/path) elsif posix_path.start_with? URI_CLASSLOADER root = posix_path.slice 0, URI_CLASSLOADER.length # ex. C:/sample/path (or file:///sample/path in browser environment) else root = posix_path.slice 0, (posix_path.index SLASH) + 1 end # ex. ./sample/path elsif posix_path.start_with? DOT_SLASH root = DOT_SLASH end # otherwise ex. sample/path path_segments = (root ? (posix_path.slice root.length, posix_path.length) : posix_path).split SLASH # strip out all dot entries path_segments.delete DOT cache[path] = [path_segments, root] end
def posixify path
path - the String path to normalize
Public: Normalize path by converting any backslashes to forward slashes
def posixify path if path @file_separator == BACKSLASH && (path.include? BACKSLASH) ? (path.tr BACKSLASH, SLASH) : path else '' end end
def relative_path path, base
base - [String] an absolute base directory.
path - [String] an absolute filename.
original path is returned work is done.
within the base directory, or the relative path cannot be computed, the
If neither path or base are absolute paths, the path is not contained
Public: Calculate the relative path to this absolute path from the specified base directory
def relative_path path, base if root? path if (offset = descends_from? path, base) path.slice offset, path.length else begin (Pathname.new path).relative_path_from(Pathname.new base).to_s rescue path end end else path end end
def root? path
def root? path (absolute_path? path) || (path.start_with? 'file://', 'http://', 'https://') end
def root? path
def root? path (absolute_path? path) || (path.start_with? URI_CLASSLOADER) end
def system_path target, start = nil, jail = nil, opts = {}
jail path, if specified. The path is posixified and all parent and self references in the path
Returns an absolute String path relative to the start path, if specified, and confined to the
* :target_name is used in messages to refer to the path being resolved
automatically recover when an illegal path is encountered
* :recover is used to control whether the processor should
opts - an optional Hash of options to control processing (default: {}):
absolute path (default: nil)
jail - the String jail path to which to confine the resolved path, if specified; must be an
specified, or the working directory specified in the constructor (default: nil)
start - the String start path from which to resolve a relative target; falls back to jail, if
target - the String target path
parent and self references in the resolved path.
the target is an absolute path, use it as is (unless it breaches the jail path). Expands all
path. If a jail path is not provided, the resolved path may be any location on the system. If
that order. If a jail path is specified, the resolved path is forced to descend from the jail
relative to the start path, jail path, or working directory (specified in the constructor), in
Resolves the target to an absolute path on the current filesystem. The target is assumed to be
Public: Securely resolve a system path
def system_path target, start = nil, jail = nil, opts = {} if jail raise ::SecurityError, %(Jail is not an absolute path: #{jail}) unless root? jail #raise ::SecurityError, %(Jail is not a canonical path: #{jail}) if jail.include? DOT_DOT jail = posixify jail end if target if root? target target_path = expand_path target if jail && !(descends_from? target_path, jail) if opts.fetch :recover, true logger.warn %(#{opts[:target_name] || 'path'} is outside of jail; recovering automatically) target_segments, = partition_path target_path jail_segments, jail_root = partition_path jail return join_path jail_segments + target_segments, jail_root else raise ::SecurityError, %(#{opts[:target_name] || 'path'} #{target} is outside of jail: #{jail} (disallowed in safe mode)) end end return target_path else target_segments, = partition_path target end else target_segments = [] end if target_segments.empty? if start.nil_or_empty? return jail || @working_dir elsif root? start if jail start = posixify start else return expand_path start end else target_segments, = partition_path start start = jail || @working_dir end elsif start.nil_or_empty? start = jail || @working_dir elsif root? start start = posixify start if jail else #start = system_path start, jail, jail, opts start = %(#{(jail || @working_dir).chomp '/'}/#{start}) end # both jail and start have been posixified at this point if jail is set if jail && (recheck = !(descends_from? start, jail)) && @file_separator == BACKSLASH start_segments, start_root = partition_path start jail_segments, jail_root = partition_path jail if start_root != jail_root if opts.fetch :recover, true logger.warn %(start path for #{opts[:target_name] || 'path'} is outside of jail root; recovering automatically) start_segments = jail_segments recheck = false else raise ::SecurityError, %(start path for #{opts[:target_name] || 'path'} #{start} refers to location outside jail root: #{jail} (disallowed in safe mode)) end end else start_segments, jail_root = partition_path start end if (resolved_segments = start_segments + target_segments).include? DOT_DOT unresolved_segments, resolved_segments = resolved_segments, [] if jail jail_segments, = partition_path jail unless jail_segments warned = false unresolved_segments.each do |segment| if segment == DOT_DOT if resolved_segments.size > jail_segments.size resolved_segments.pop elsif opts.fetch :recover, true unless warned logger.warn %(#{opts[:target_name] || 'path'} has illegal reference to ancestor of jail; recovering automatically) warned = true end else raise ::SecurityError, %(#{opts[:target_name] || 'path'} #{target} refers to location outside jail: #{jail} (disallowed in safe mode)) end else resolved_segments << segment end end else unresolved_segments.each do |segment| segment == DOT_DOT ? resolved_segments.pop : resolved_segments << segment end end end if recheck target_path = join_path resolved_segments, jail_root if descends_from? target_path, jail target_path elsif opts.fetch :recover, true logger.warn %(#{opts[:target_name] || 'path'} is outside of jail; recovering automatically) jail_segments, = partition_path jail unless jail_segments join_path jail_segments + target_segments, jail_root else raise ::SecurityError, %(#{opts[:target_name] || 'path'} #{target} is outside of jail: #{jail} (disallowed in safe mode)) end else join_path resolved_segments, jail_root end end
def unc? path
path - the String path to check
Public: Determine if the path is a UNC (root) path
def unc? path path.start_with? DOUBLE_SLASH end
def web_path target, start = nil
start path with any parent references resolved and self
returns a String path that joins the target path with the
start - the String start (i.e., parent) path
target - the String target path
That check should happen before this method is invoked.
The target is assumed to be a path, not a qualified URI.
references and remove any self references.
The main function of this operation is to resolve any parent
Public: Resolve a web path from the target and start paths.
def web_path target, start = nil target = posixify target start = posixify start unless start.nil_or_empty? || (web_root? target) target, uri_prefix = extract_uri_prefix %(#{start}#{(start.end_with? SLASH) ? '' : SLASH}#{target}) end # use this logic instead if we want to normalize target if it contains a URI #unless web_root? target # target, uri_prefix = extract_uri_prefix target if preserve_uri_target # target, uri_prefix = extract_uri_prefix %(#{start}#{SLASH}#{target}) unless uri_prefix || start.nil_or_empty? #end target_segments, target_root = partition_path target, true resolved_segments = [] target_segments.each do |segment| if segment == DOT_DOT if resolved_segments.empty? resolved_segments << segment unless target_root && target_root != DOT_SLASH elsif resolved_segments[-1] == DOT_DOT resolved_segments << segment else resolved_segments.pop end else resolved_segments << segment # checking for empty would eliminate repeating forward slashes #resolved_segments << segment unless segment.empty? end end if (resolved_path = join_path resolved_segments, target_root).include? ' ' resolved_path = resolved_path.gsub ' ', '%20' end uri_prefix ? %(#{uri_prefix}#{resolved_path}) : resolved_path end
def web_root? path
path - the String path to check
Public: Determine if the path is an absolute (root) web path
def web_root? path path.start_with? SLASH end