fix: stop following a link out of the root that a file service serves

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-*
+* A file service can now be told to follow a link that leaves the root it serves - [#126](https://github.com/hivesolutions/netius/issues/126)
 
 ### Changed
 
@@ -19,11 +19,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * A configuration file is now read under Python 3.5, instead of failing on it
 * A header that is set by its position now replaces the one that is there
+* A link that leaves the root of a file service is no longer followed by default - [#126](https://github.com/hivesolutions/netius/issues/126)
 * A string that carries no null byte is now given back whole instead of raising
 * A TFTP file that is served under an absolute name no longer fails to open
 * A TFTP peer can no longer reach a file outside the root that is served
 * An environment value that is unset can now be forced into a file, instead of raising
 * An FTP peer can no longer reach a file outside the root that is served
+* An HTTP file server can no longer reach a directory whose name only starts like the root - [#126](https://github.com/hivesolutions/netius/issues/126)
 * The allowed addresses of a service are now honoured, instead of every peer being refused
 * The asyncio compatibility of the event loop no longer fails under Python 3.6
 * The check for a test run no longer raises when a caller carries no source

doc/configuration.md

@@ -74,6 +74,7 @@
 | **PATH_REGEX**  | `list` | `[]`    | The list of regex to path values (separated by the `:` character) that provide a simple way of URL re-writing like behaviour under the file serving extension (eg: `.*:index.html`). |
 | **LIST_DIRS**   | `bool` | `True`  | If directory listing is enabled (may pose a security issue).                                                                                                                         |
 | **LIST_ENGINE** | `str`  | `base`  | The name of the HTML generation engine to be used while listing files (eg: base, apache, legacy, etc.).                                                                              |
+| **FOLLOW_LINKS** | `bool` | `False` | If a symbolic link under the base path whose target lies outside of it should be followed, by default such a link is refused (may pose a security issue).                            |
 
 #### HTTP
 

src/netius/common/__init__.py

@@ -200,6 +200,7 @@
     random_integer,
     host,
     hostname,
+    is_sub_path,
     size_round_unit,
     verify,
     verify_equal,

src/netius/common/util.py

@@ -38,6 +38,7 @@
 """ The license for the module """
 
 import os
+import stat
 import math
 import socket
 import collections
@@ -66,6 +67,11 @@
 to be used for the string representation in the round
 based conversion of size units to be performed """
 
+FILE_ATTRIBUTE_REPARSE_POINT = 0x400
+""" The attribute that marks a file as a reparse point under
+Windows, the kind of a junction, which the mode of the file does
+not report as a link and yet leads somewhere else in the system """
+
 _HOST = None
 """ The globally cached value for the current hostname,
 this value is used to avoid an excessive blocking in the
@@ -297,6 +303,64 @@ def hostname():
     return socket.gethostname()
 
 
+def is_sub_path(base_path, path, follow_links=False):
+    """
+    Verifies if the provided path is contained by the base path,
+    meaning that it's either the base path itself or that it sits
+    below it, both of the paths are expected to be absolute and
+    normalized (no relative components).
+
+    Unless links are meant to be followed a link that sits below
+    the base path is resolved, so that one whose target lies outside
+    of it is not taken as contained, what sits above the base path
+    is never resolved as it's the same for both of the paths.
+
+    :type base_path: String
+    :param base_path: The path of the root that is expected to
+    contain the path that is going to be verified.
+    :type path: String
+    :param path: The path that is going to be verified for the
+    containment under the base path.
+    :type follow_links: bool
+    :param follow_links: If a link that sits below the base path
+    should be taken by its name rather than by its target.
+    :rtype: bool
+    :return: If the path is contained by the base path.
+    """
+
+    is_sub = path == base_path or path.startswith(os.path.join(base_path, ""))
+    if not is_sub or follow_links:
+        return is_sub
+
+    # walks the components of the path that sit below the base path
+    # looking for a link, in case none is found the path leads to the
+    # same place as the one it names and nothing else is to be verified,
+    # note that a component that is not there (or cannot be read) has
+    # nothing left to be resolved and so the walk ends at it
+    current = base_path
+    for name in path[len(base_path) :].split(os.sep):
+        if not name:
+            continue
+        current = os.path.join(current, name)
+        try:
+            mode = os.lstat(current)
+        except OSError:
+            return True
+        attributes = getattr(mode, "st_file_attributes", 0)
+        is_link = stat.S_ISLNK(mode.st_mode)
+        is_link |= bool(attributes & FILE_ATTRIBUTE_REPARSE_POINT)
+        if is_link:
+            break
+    else:
+        return True
+
+    # a link was found below the base path, so both of the paths are
+    # resolved and the containment is verified against their targets
+    base_path_r = os.path.realpath(base_path)
+    path_r = os.path.realpath(path)
+    return path_r == base_path_r or path_r.startswith(os.path.join(base_path_r, ""))
+
+
 def size_round_unit(
     size_value,
     minimum=DEFAULT_MINIMUM,

src/netius/common/util.pyi

@@ -5,6 +5,7 @@ SIZE_UNITS_LIST_S: tuple[str, ...]
 SIZE_UNIT_COEFFICIENT: int
 DEFAULT_MINIMUM: int
 DEFAULT_PLACES: int
+FILE_ATTRIBUTE_REPARSE_POINT: int
 
 def cstring(value: str) -> str: ...
 def chunks(
@@ -27,6 +28,7 @@ def bytes_to_integer(bytes: bytes) -> int: ...
 def random_integer(number_bits: int) -> int: ...
 def host(default: str = ...) -> str: ...
 def hostname() -> str: ...
+def is_sub_path(base_path: str, path: str, follow_links: bool = ...) -> bool: ...
 def size_round_unit(
     size_value: int | float,
     minimum: int = ...,

src/netius/extra/file.py

@@ -88,6 +88,7 @@ def __init__(
         list_engine="base",
         cors=False,
         cache=0,
+        follow_links=False,
         *args,
         **kwargs
     ):
@@ -100,6 +101,7 @@ def __init__(
         self.list_engine = list_engine
         self.cors = cors
         self.cache = cache
+        self.follow_links = follow_links
 
     @classmethod
     def _sorter_build(cls, name=None):
@@ -497,6 +499,10 @@ def on_serve(self):
             self.cors = self.get_env("CORS", self.cors, cast=bool)
         if self.env:
             self.cache = self.get_env("CACHE", self.cache, cast=int)
+        if self.env:
+            self.follow_links = self.get_env(
+                "FOLLOW_LINKS", self.follow_links, cast=bool
+            )
         self._build_regex()
         self.base_path = os.path.abspath(self.base_path)
         self.cache_d = datetime.timedelta(seconds=self.cache)
@@ -547,7 +553,7 @@ def on_data_http(self, connection, parser):
             # verifies if the provided path starts with the contents of the
             # base path in case it does not it's a security issue and a proper
             # exception must be raised indicating the issue
-            is_sub = path_f.startswith(self.base_path)
+            is_sub = self._is_sub(path_f)
             if not is_sub:
                 raise netius.SecurityError("Invalid path")
 
@@ -595,6 +601,13 @@ def on_dir_file(self, connection, parser, path, style=True):
             index_path = os.path.join(path, index_file)
             if not os.path.exists(index_path):
                 continue
+
+            # verifies that the index file is itself under the base path, as
+            # it's the one that is going to be opened and it may be a link
+            # whose target lies outside of it (security issue)
+            is_sub = self._is_sub(index_path)
+            if not is_sub:
+                raise netius.SecurityError("Invalid path")
             return self.on_normal_file(connection, parser, index_path)
 
         if not self.list_dirs:
@@ -837,6 +850,11 @@ def _resolve_regex(self, path):
             return (value, True)
         return (path, False)
 
+    def _is_sub(self, path):
+        return netius.common.is_sub_path(
+            self.base_path, path, follow_links=self.follow_links
+        )
+
 
 if __name__ == "__main__":
     import logging

src/netius/extra/file.pyi

@@ -19,6 +19,7 @@ class FileServer(HTTP2Server):
     list_engine: str
     cors: bool
     cache: int
+    follow_links: bool
 
     def __init__(
         self,
@@ -30,6 +31,7 @@ class FileServer(HTTP2Server):
         list_engine: str = ...,
         cors: bool = ...,
         cache: int = ...,
+        follow_links: bool = ...,
         *args,
         **kwargs
     ): ...
@@ -106,3 +108,4 @@ class FileServer(HTTP2Server):
     def _resolve(self, path: str) -> str: ...
     def _build_regex(self): ...
     def _resolve_regex(self, path: str) -> tuple[str, bool]: ...
+    def _is_sub(self, path: str) -> bool: ...

src/netius/servers/ftp.py

@@ -96,12 +96,19 @@
 class FTPConnection(netius.Connection):
 
     def __init__(
-        self, base_path="", host="ftp.localhost", mode="ascii", *args, **kwargs
+        self,
+        base_path="",
+        host="ftp.localhost",
+        mode="ascii",
+        follow_links=False,
+        *args,
+        **kwargs
     ):
         netius.Connection.__init__(self, *args, **kwargs)
         self.parser = None
         self.base_path = os.path.abspath(base_path)
         self.host = host
+        self.follow_links = follow_links
         self.mode = mode
         self.data_server = None
         self.remaining = None
@@ -214,16 +221,13 @@ def flush_list(self):
 
     def flush_retr(self):
         self.send_ftp(150, "file sending")
-        full_path = self._get_path(self.file_name)
-        self.bytes_p = os.path.getsize(full_path)
-        self.file = open(full_path, "rb")
+        self.bytes_p = os.path.getsize(self.file_path)
+        self.file = open(self.file_path, "rb")
         self._file_send(self)
 
     def flush_stor(self):
         self.send_ftp(150, "file receiving")
-
-        full_path = self._get_path(self.file_name)
-        self.file = open(full_path, "wb")
+        self.file = open(self.file_path, "wb")
 
     def on_flush_list(self, connection):
         self._data_close()
@@ -258,9 +262,14 @@ def on_line(self, code, message, is_final=True):
 
         # retrieves the reference to the method that is going to be called
         # for the handling of the current line from the current instance and
-        # then calls it with the provided message
+        # then calls it with the provided message, note that a path that is
+        # refused is reported back as a failed command instead of being
+        # raised, as dropping the connection for it would be too much
         method = getattr(self, method_n)
-        method(message)
+        try:
+            method(message)
+        except netius.SecurityError:
+            self.not_ok()
 
     def on_user(self, message):
         self.username = message
@@ -387,13 +396,18 @@ def on_list(self, message):
         self.data_server.flush_ftp()
 
     def on_retr(self, message):
+        # resolves the path of the file at the command itself, so that a
+        # path that is refused is answered as a failed command before the
+        # transfer is announced, note that the flushing of the transfer may
+        # only run once the data connection is accepted, at which point the
+        # refusal would have no command left to be reported against
+        self.file_path = self._get_path(extra=message)
         self.remaining = "retr"
-        self.file_name = message
         self.data_server.flush_ftp()
 
     def on_stor(self, message):
+        self.file_path = self._get_path(extra=message)
         self.remaining = "stor"
-        self.file_name = message
         self.data_server.flush_ftp()
 
     def _file_send(self, connection):
@@ -497,8 +511,8 @@ def _get_path(self, extra=None):
         # verifies if the resolved path starts with the contents of the
         # base path in case it does not it's a security issue and a proper
         # exception must be raised indicating the issue
-        is_sub = relative_path == self.base_path or relative_path.startswith(
-            os.path.join(self.base_path, "")
+        is_sub = netius.common.is_sub_path(
+            self.base_path, relative_path, follow_links=self.follow_links
         )
         if not is_sub:
             raise netius.SecurityError("Invalid path")
@@ -559,10 +573,13 @@ class FTPServer(netius.ContainerServer):
     :see: http://tools.ietf.org/html/rfc959
     """
 
-    def __init__(self, base_path="", auth_s="dummy", *args, **kwargs):
+    def __init__(
+        self, base_path="", auth_s="dummy", follow_links=False, *args, **kwargs
+    ):
         netius.ContainerServer.__init__(self, *args, **kwargs)
         self.base_path = base_path
         self.auth_s = auth_s
+        self.follow_links = follow_links
 
     def serve(self, host="ftp.localhost", port=21, *args, **kwargs):
         netius.ContainerServer.serve(self, port=port, *args, **kwargs)
@@ -584,6 +601,10 @@ def on_serve(self):
             self.host = self.get_env("FTP_HOST", self.host)
         if self.env:
             self.auth_s = self.get_env("FTP_AUTH", self.auth_s)
+        if self.env:
+            self.follow_links = self.get_env(
+                "FOLLOW_LINKS", self.follow_links, cast=bool
+            )
         self.auth = self.get_auth(self.auth_s)
         self.info(
             "Starting FTP server on '%s' using '%s' ..." % (self.host, self.auth_s)
@@ -600,6 +621,7 @@ def build_connection(self, socket, address, ssl=False):
             ssl=ssl,
             base_path=self.base_path,
             host=self.host,
+            follow_links=self.follow_links,
         )
 
     def on_line_ftp(self, connection, code, message):

src/netius/servers/ftp.pyi

@@ -16,14 +16,21 @@ class FTPConnection(Connection):
     base_path: str
     host: str
     mode: str
+    follow_links: bool
     data_server: FTPDataServer | None
     remaining: str | None
     cwd: str
     username: str
     password: str
 
     def __init__(
-        self, base_path: str = ..., host: str = ..., mode: str = ..., *args, **kwargs
+        self,
+        base_path: str = ...,
+        host: str = ...,
+        mode: str = ...,
+        follow_links: bool = ...,
+        *args,
+        **kwargs
     ): ...
     def open(self, *args, **kwargs): ...
     def close(self, *args, **kwargs): ...
@@ -119,8 +126,16 @@ class FTPDataServer(StreamServer):
 class FTPServer(ContainerServer):
     base_path: str
     auth_s: str
+    follow_links: bool
 
-    def __init__(self, base_path: str = ..., auth_s: str = ..., *args, **kwargs): ...
+    def __init__(
+        self,
+        base_path: str = ...,
+        auth_s: str = ...,
+        follow_links: bool = ...,
+        *args,
+        **kwargs
+    ): ...
     def serve(  # type: ignore[override]
         self, host: str = ..., port: int = ..., *args, **kwargs
     ): ...