Documentation for --allow-paths and changelog entry for fixes

Author: cameel

Changelog.md

@@ -16,6 +16,7 @@ Bugfixes:
  * Code Generator: Fix internal compiler error when calling functions bound to calldata structs and arrays.
  * Code Generator: Fix internal compiler error when passing a 32-byte hex literal or a zero literal to ``bytes.concat()`` by disallowing such literals.
  * Commandline Interface: Fix crash when a directory path is passed to ``--standard-json``.
+ * Commandline Interface: Fix resolution of paths whitelisted with ``--allowed-paths`` or implicitly due to base path, remappings and files being compiled. Correctly handle paths that do not match imports exactly due to being relative, non-normalized or empty.
  * Commandline Interface: Read JSON from standard input when ``--standard-json`` gets ``-`` as a file name.
  * Standard JSON: Include source location for errors in files with empty name.
  * Type Checker: Fix internal error and prevent static calls to unimplemented modifiers.

docs/path-resolution.rst

@@ -297,7 +297,7 @@ Here are some examples of what you can expect if they are not:
     The same effect can be achieved in a more reliable way by using direct imports with
     :ref:`base path <base-path>` and :ref:`import remapping <import-remapping>`.
 
-.. index:: ! base path, --base-path
+.. index:: ! base path, ! --base-path
 .. _base-path:
 
 Base Path
@@ -355,6 +355,66 @@ If the base path is empty (e.g. if it is not explicitly provided), it is treated
 to the path to the current working directory with all symbolic links resolved.
 The result becomes the source unit name.
 
+.. index:: ! allowed paths, ! --allow-paths, remapping; target
+.. _allowed-paths:
+
+Allowed Paths
+=============
+
+As a security measure, the Host Filesystem Loader will refuse to load files from outside of a few
+locations that are considered safe by default:
+
+- Outside of Standard JSON mode:
+
+  - The directories containing input files listed on the command line.
+  - The directories used as :ref:`remapping <import-remapping>` targets.
+    If the target is not a directory (i.e does not end with ``/``, ``/.`` or ``/..``) the directory
+    containing the target is used instead.
+  - Base path.
+
+- In Standard JSON mode:
+
+  - Base path.
+
+Additional directories can be whitelisted using the ``--allow-paths`` option.
+The option accepts a comma-separated list of paths:
+
+.. code-block:: bash
+
+    cd /home/user/project/
+    solc token/contract.sol \
+        lib/util.sol=libs/util.sol \
+        --base-path=token/ \
+        --allow-paths=../utils/,/usr/libraries
+
+When the compiler is invoked with the command shown above, the Host Filesystem Loader will allow
+importing files from the following directories:
+
+- ``/home/user/project/token/`` (because ``token/`` contains the input file and also because it is
+  the base path),
+- ``/home/user/project/libs/`` (because ``libs/`` is a directory containing a remapping target),
+- ``/home/user/utils/`` (because of ``../utils/`` passed to ``--allow-paths``),
+- ``/usr/libraries`` (because of ``/usr/libraries`` passed to ``--allow-paths``),
+
+.. note::
+
+    The working directory of the compiler is not one of the allowed paths by default unless it
+    happens to be the base path (or the base path is not specified or has an empty value).
+
+.. note::
+
+    The compiler does not check if allowed paths actually exist and whether they are directories.
+    Non-existent or empty paths are simply ignored.
+    If an allowed path matches a file rather than a directory, the file is considered whitelisted too.
+
+.. warning::
+
+    Files and directories only reachable through symbolic links from allowed directories are not
+    automatically whitelisted.
+    For example if ``token/contract.sol`` in the example above was actually a symlink pointing at
+    ``/etc/passwd`` the compiler would refuse to load it unless ``/etc/`` was one of the allowed
+    paths too.
+
 .. index:: ! remapping; import, ! import; remapping, ! remapping; context, ! remapping; prefix, ! remapping; target
 .. _import-remapping:
 

docs/using-the-compiler.rst

@@ -47,16 +47,13 @@ it is also possible to provide :ref:`path redirects <import-remapping>` using ``
 
 This essentially instructs the compiler to search for anything starting with
 ``github.com/ethereum/dapp-bin/`` under ``/usr/local/lib/dapp-bin``.
-``solc`` will not read files from the filesystem that lie outside of
-the remapping targets and outside of the directories where explicitly specified source
-files reside, so things like ``import "/etc/passwd";`` only work if you add ``/=/`` as a remapping.
 
 When accessing the filesystem to search for imports, :ref:`paths that do not start with ./
-or ../ <relative-imports>` are treated as relative to the directory specified using
+or ../ <direct-imports>` are treated as relative to the directory specified using
 ``--base-path`` option (or the current working directory if base path is not specified).
 Furthermore, the part added via ``--base-path`` will not appear in the contract metadata.
 
-For security reasons the compiler has restrictions on what directories it can access.
+For security reasons the compiler has :ref:`restrictions on what directories it can access <allowed-paths>`.
 Directories of source files specified on the command line and target paths of
 remappings are automatically allowed to be accessed by the file reader, but everything
 else is rejected by default.