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

Changelog.md

@@ -21,6 +21,7 @@ Bugfixes:
  * Code Generator: Fix ICE on assigning to calldata structs and statically-sized calldata arrays in inline assembly.
  * Code Generator: Use stable source order for ABI functions.
  * Commandline Interface: Disallow the ``--experimental-via-ir`` option in Standard JSON, Assembler and Linker modes.
+ * 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: Report optimizer options as invalid in Standard JSON and linker modes instead of ignoring them.
  * Name Resolver: Fix that when importing an aliased symbol using ``import {AliasedName} from "a.sol"`` it would use the original name of the symbol and not the aliased one.
  * Opcode Optimizer: Prevent the optimizer from running multiple times to avoid potential bytecode differences for referenced code.

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
@@ -373,6 +373,72 @@ The resulting file path becomes the source unit name.
     When working with older versions of the compiler it is recommended to invoke the compiler from
     the base path and to only use relative paths on the command line.
 
+.. 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/,/tmp/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``),
+- ``/tmp/libraries/`` (because of ``/tmp/libraries`` passed to ``--allow-paths``),
+
+.. note::
+
+    The working directory of the compiler is one of the paths allowed by default only if 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.
+
+.. note::
+
+    Allowed paths are case-sensitive even if the filesystem is not.
+    The case must exactly match the one used in your imports.
+    For example ``--allow-paths tokens`` will not match ``import "Tokens/IERC20.sol"``.
+
+.. 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.