From 17ef6f657ea2ae36f60a6a85028204a21baf543c Mon Sep 17 00:00:00 2001 From: Tim McCormack Date: Thu, 15 May 2025 22:57:20 -0400 Subject: [PATCH] docs: General doc updates - Remove descriptions of `SAND_PACK`, `UNTRUSTED_PACK`, and `OSPACK`, as these were not referenced anywhere else. Replace with a description of the virtualenv and the file structure of the ephemeral sandbox that jail_code creates. - Clarify Python version app/jail distinction. - Add recommendation for runtime self-tests. - Minor formatting and fixes. --- README.rst | 45 +++++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/README.rst b/README.rst index 6a6fe362..8bf174f6 100644 --- a/README.rst +++ b/README.rst @@ -22,31 +22,26 @@ machines. A CodeJail sandbox consists of several pieces: #) Sandbox environment. For a Python setup, this would be Python and - associated core packages. This is denoted throughout this document - as ****. This is read-only. - -#) Sandbox packages. These are additional packages needed for a given - run. For example, this might be a grader written by an instructor - to run over a student's code, or data that a student's code might - need to access. This is denoted throughout this document as - ****. This is read-only. - -#) Untrusted packages. This is typically the code submitted by the - student to be tested on the server, as well as any data the code - may need to modify. This is denoted throughout this document as - ****. This is currently read-only, but may need to - be read-write for some applications. - -#) OS packages. These are standard system libraries needed to run - Python (e.g. things in /lib). This is denoted throughout this - document as ****. This is read-only, and is specified by - Ubuntu's AppArmor profile. + associated core packages as a virtualenv. This is denoted throughout this document + as ****. This is read-only, and shared across sandbox instantiations. + + Sandboxed code also has access to OS libraries to the extent that the + AppArmor profile permits it. + +#) Sandbox execution directory. This is an ephemeral read-only directory named + like ``/tmp/codejail-XXXXXXXX`` containing the submitted code + (``./jailed_code``), optional additional files, and a writable temporary + directory (``./tmp``) that the submitted code can use as a scratch space. + + The submitted code is typically the code submitted by the student to be + tested on the server, and the additional files are typically a + ``python_lib.zip`` containing grading or utility libraries. To run, CodeJail requires two user accounts. One account is the main account under which the code runs, which has access to create sandboxes. This will be referred to as ****. The second account is the account under which the sandbox runs. This is -typically the account 'sandbox.' +typically the account ``sandbox``. Supported Versions ------------------ @@ -62,6 +57,9 @@ Ubuntu: * 22.04 * 24.04 +(Note that the Python version used inside the sandbox may be different from the +version used for the library itself.) + Installation ------------ @@ -247,12 +245,12 @@ execute the provided Python program with that executable, and AppArmor will automatically limit the resources it can access. CodeJail also uses setrlimit to limit the amount of CPU time and/or memory available to the process. -``CodeJail.jail_code`` takes a program to run, files to copy into its +``codejail.jail_code`` takes a program to run, files to copy into its environment, command-line arguments, and a stdin stream. It creates a temporary directory, creates or copies the needed files, spawns a subprocess to run the code, and returns the output and exit status of the process. -``CodeJail.safe_exec`` emulates Python's exec statement. It takes a chunk of +``codejail.safe_exec`` emulates Python's exec statement. It takes a chunk of Python code, and runs it using jail_code, modifying the globals dictionary as a side-effect. safe_exec does this by serializing the globals into and out of the subprocess as JSON. @@ -262,6 +260,9 @@ Limitations * If codejail or AppArmor is not configured properly, codejail will default to running code insecurely (no sandboxing). It is not secure by default. + Projects integrating codejail should consider including a runtime test suite + that checks for proper confinement at startup before untrusted inputs are + accepted. * Sandbox isolation is achieved via AppArmor confinement. Codejail facilitates this, but cannot isolate execution without the use of AppArmor. * Resource limits can only be constrained using the mechanisms that Linux's