Merge pull request #159 from python-discord/bytes-output

File system and Binary file sending

Author: mbaruh

README.md

@@ -7,6 +7,9 @@
 
 Python sandbox runners for executing code in isolation aka snekbox.
 
+Supports a memory [virtual read/write file system](#virtual-file-system) within the sandbox,
+allowing text or binary files to be sent and returned.
+
 A client sends Python code to a snekbox, the snekbox executes the code, and finally the results of the execution are returned to the client.
 
 ```mermaid
@@ -60,10 +63,26 @@ The main features of the default configuration are:
 * Memory limit
 * Process count limit
 * No networking
-* Restricted, read-only filesystem
+* Restricted, read-only system filesystem
+* Memory-based read-write filesystem mounted as working directory `/home`
 
 NsJail is configured through [`snekbox.cfg`]. It contains the exact values for the items listed above. The configuration format is defined by a [protobuf file][7] which can be referred to for documentation. The command-line options of NsJail can also serve as documentation since they closely follow the config file format.
 
+### Memory File System
+
+On each execution, the host will mount an instance-specific `tmpfs` drive, this is used as a limited read-write folder for the sandboxed code. There is no access to other files or directories on the host container beyond the other read-only mounted system folders. Instance file systems are isolated; it is not possible for sandboxed code to access another instance's writeable directory.
+
+The following options for the memory file system are configurable as options in [gunicorn.conf.py](config/gunicorn.conf.py)
+
+* `memfs_instance_size` Size in bytes for the capacity of each instance file system.
+* `memfs_home` Path to the home directory within the instance file system.
+* `memfs_output` Path to the output directory within the instance file system.
+* `files_limit` Maximum number of valid output files to parse.
+* `files_timeout` Maximum time in seconds for output file parsing and encoding.
+* `files_pattern` Glob pattern to match files within `output`.
+
+The sandboxed code execution will start with a writeable working directory of `home`. By default, the output folder is also `home`. New files, and uploaded files with a newer last modified time, will be uploaded on completion.
+
 ### Gunicorn
 
 [Gunicorn settings] can be found in [`gunicorn.conf.py`]. In the default configuration, the worker count, the bind address, and the WSGI app URI are likely the only things of any interest. Since it uses the default synchronous workers, the [worker count] effectively determines how many concurrent code evaluations can be performed.

config/snekbox.cfg

@@ -3,7 +3,7 @@ description: "Execute Python"
 
 mode: ONCE
 hostname: "snekbox"
-cwd: "/snekbox"
+cwd: "/home"
 
 time_limit: 6
 
@@ -16,10 +16,12 @@ envar: "VECLIB_MAXIMUM_THREADS=5"
 envar: "NUMEXPR_NUM_THREADS=5"
 envar: "PYTHONPATH=/snekbox/user_base/lib/python3.11/site-packages"
 envar: "PYTHONIOENCODING=utf-8:strict"
+envar: "HOME=home"
 
 keep_caps: false
 
 rlimit_as: 700
+rlimit_fsize_type: INF
 
 clone_newnet: true
 clone_newuser: true
@@ -108,12 +110,12 @@ cgroup_mem_max: 52428800
 cgroup_mem_swap_max: 0
 cgroup_mem_mount: "/sys/fs/cgroup/memory"
 
-cgroup_pids_max: 5
+cgroup_pids_max: 6
 cgroup_pids_mount: "/sys/fs/cgroup/pids"
 
 iface_no_lo: true
 
 exec_bin {
     path: "/usr/local/bin/python"
-    arg: "-Squ"
+    arg: "-BSqu"
 }

docker-compose.yml

@@ -8,7 +8,7 @@ services:
     image: ghcr.io/python-discord/snekbox${IMAGE_SUFFIX:--venv:dev}
     pull_policy: never
     ports:
-     - 8060:8060
+     - "8060:8060"
     init: true
     ipc: none
     tty: true

snekbox/__init__.py

@@ -12,7 +12,7 @@
 from snekbox.nsjail import NsJail  # noqa: E402
 from snekbox.utils.logging import init_logger, init_sentry  # noqa: E402
 
-__all__ = ("NsJail", "SnekAPI")
+__all__ = ("NsJail", "SnekAPI", "DEBUG")
 
 init_sentry(__version__)
 init_logger(DEBUG)

snekbox/__main__.py

@@ -37,7 +37,7 @@ def parse_args() -> argparse.Namespace:
 def main() -> None:
     """Evaluate Python code through NsJail."""
     args = parse_args()
-    result = NsJail().python3(args.code, nsjail_args=args.nsjail_args, py_args=args.py_args)
+    result = NsJail().python3(py_args=[*args.py_args, args.code], nsjail_args=args.nsjail_args)
     print(result.stdout)
 
     if result.returncode != 0:

snekbox/api/resources/eval.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import logging
 
 import falcon
@@ -7,6 +9,8 @@
 
 __all__ = ("EvalResource",)
 
+from snekbox.snekio import FileAttachment, ParsingError
+
 log = logging.getLogger(__name__)
 
 
@@ -25,8 +29,26 @@ class EvalResource:
         "properties": {
             "input": {"type": "string"},
             "args": {"type": "array", "items": {"type": "string"}},
+            "files": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            # Disallow starting with / or containing \0 anywhere
+                            "pattern": r"^(?!/)(?!.*\\0).*$",
+                        },
+                        "content": {"type": "string"},
+                    },
+                    "required": ["path"],
+                },
+            },
         },
-        "required": ["input"],
+        "anyOf": [
+            {"required": ["input"]},
+            {"required": ["args"]},
+        ],
     }
 
     def __init__(self, nsjail: NsJail):
@@ -38,8 +60,11 @@ def on_post(self, req: falcon.Request, resp: falcon.Response) -> None:
         Evaluate Python code and return stdout, stderr, and the return code.
 
         A list of arguments for the Python subprocess can be specified as `args`.
-        Otherwise, the default argument "-c" is used to execute the input code.
-        The input code is always passed as the last argument to Python.
+
+        If `input` is specified, it will be appended as the last argument to `args`,
+        and `args` will have a default argument of `"-c"`.
+
+        Either `input` or `args` must be specified.
 
         The return codes mostly resemble those of a Unix shell. Some noteworthy cases:
 
@@ -53,33 +78,64 @@ def on_post(self, req: falcon.Request, resp: falcon.Response) -> None:
         Request body:
 
         >>> {
-        ...     "input": "[i for i in range(1000)]",
-        ...     "args": ["-m", "timeit"] # This is optional
+        ...    "input": "print('Hello')"
+        ... }
+
+        >>> {
+        ...    "args": ["-c", "print('Hello')"]
+        ... }
+
+        >>> {
+        ...    "args": ["main.py"],
+        ...    "files": [
+        ...        {
+        ...            "path": "main.py",
+        ...            "content": "SGVsbG8...="  # Base64
+        ...        }
+        ...    ]
         ... }
 
         Response format:
 
         >>> {
-        ...     "stdout": "10000 loops, best of 5: 23.8 usec per loop\n",
-        ...     "returncode": 0
+        ...     "stdout": "10000 loops, best of 5: 23.8 usec per loop",
+        ...     "returncode": 0,
+        ...     "files": [
+        ...         {
+        ...             "path": "output.png",
+        ...             "size": 57344,
+        ...             "content": "eJzzSM3...="  # Base64
+        ...         }
+        ...     ]
         ... }
 
         Status codes:
 
         - 200
             Successful evaluation; not indicative that the input code itself works
         - 400
-           Input's JSON schema is invalid
+           Input JSON schema is invalid
         - 415
             Unsupported content type; only application/JSON is supported
         """
-        code = req.media["input"]
-        args = req.media.get("args", ("-c",))
-
+        body: dict[str, str | list[str] | list[dict[str, str]]] = req.media
+        # If `input` is supplied, default `args` to `-c`
+        if "input" in body:
+            body.setdefault("args", ["-c"])
+            body["args"].append(body["input"])
         try:
-            result = self.nsjail.python3(code, py_args=args)
+            result = self.nsjail.python3(
+                py_args=body["args"],
+                files=[FileAttachment.from_dict(file) for file in body.get("files", [])],
+            )
+        except ParsingError as e:
+            raise falcon.HTTPBadRequest(title="Request file is invalid", description=str(e))
         except Exception:
             log.exception("An exception occurred while trying to process the request")
             raise falcon.HTTPInternalServerError
 
-        resp.media = {"stdout": result.stdout, "returncode": result.returncode}
+        resp.media = {
+            "stdout": result.stdout,
+            "returncode": result.returncode,
+            "files": [f.as_dict for f in result.files],
+        }

snekbox/filesystem.py

@@ -0,0 +1,88 @@
+"""Mounts and unmounts filesystems."""
+from __future__ import annotations
+
+import ctypes
+import os
+from ctypes.util import find_library
+from enum import IntEnum
+from pathlib import Path
+
+__all__ = ("mount", "unmount", "Size", "UnmountFlags")
+
+libc = ctypes.CDLL(find_library("c"), use_errno=True)
+libc.mount.argtypes = (
+    ctypes.c_char_p,
+    ctypes.c_char_p,
+    ctypes.c_char_p,
+    ctypes.c_ulong,
+    ctypes.c_char_p,
+)
+libc.umount2.argtypes = (ctypes.c_char_p, ctypes.c_int)
+
+
+class Size(IntEnum):
+    """Size multipliers for bytes."""
+
+    KiB = 1024
+    MiB = 1024**2
+    GiB = 1024**3
+    TiB = 1024**4
+
+
+class UnmountFlags(IntEnum):
+    """Flags for umount2."""
+
+    MNT_FORCE = 1
+    MNT_DETACH = 2
+    MNT_EXPIRE = 4
+    UMOUNT_NOFOLLOW = 8
+
+
+def mount(source: Path | str, target: Path | str, fs: str, **options: str | int) -> None:
+    """
+    Mount a filesystem.
+
+    https://man7.org/linux/man-pages/man8/mount.8.html
+
+    Args:
+        source: Source directory or device.
+        target: Target directory.
+        fs: Filesystem type.
+        **options: Mount options.
+
+    Raises:
+        OSError: On any mount error.
+    """
+    if Path(target).is_mount():
+        raise OSError(f"{target} is already a mount point")
+
+    kwargs = " ".join(f"{key}={value}" for key, value in options.items())
+
+    result: int = libc.mount(
+        str(source).encode(), str(target).encode(), fs.encode(), 0, kwargs.encode()
+    )
+    if result < 0:
+        errno = ctypes.get_errno()
+        raise OSError(errno, f"Error mounting {target}: {os.strerror(errno)}")
+
+
+def unmount(target: Path | str, flags: UnmountFlags | int = UnmountFlags.MNT_DETACH) -> None:
+    """
+    Unmount a filesystem.
+
+    https://man7.org/linux/man-pages/man2/umount.2.html
+
+    Args:
+        target: Target directory.
+        flags: Unmount flags.
+
+    Raises:
+        OSError: On any unmount error.
+    """
+    if not Path(target).is_mount():
+        raise OSError(f"{target} is not a mount point")
+
+    result: int = libc.umount2(str(target).encode(), int(flags))
+    if result < 0:
+        errno = ctypes.get_errno()
+        raise OSError(errno, f"Error unmounting {target}: {os.strerror(errno)}")