autograder_sandbox module

class AutograderSandbox(name=None, docker_image='jameslp/ag-ubuntu-16:latest', allow_network_access=False, environment_variables=None, container_create_timeout=None, pids_limit=512, memory_limit='4g', min_fallback_timeout=60, debug=False)[source]

This class wraps Docker functionality to provide an interface for running untrusted programs in a secure, isolated environment.

Docker documentation and installation instructions can be found at: https://www.docker.com/

Instances of this class are intended to be used with a context manager. The underlying docker container to be used is created and destroyed when the context manager is entered and exited, respectively.

__init__(name=None, docker_image='jameslp/ag-ubuntu-16:latest', allow_network_access=False, environment_variables=None, container_create_timeout=None, pids_limit=512, memory_limit='4g', min_fallback_timeout=60, debug=False)[source]
Parameters

  • name (Optional[str]) – A human-readable name that can be used to identify this sandbox instance. This value must be unique across all sandbox instances, otherwise starting the sandbox will fail. If no value is specified, a random name will be generated automatically.

  • docker_image (str) –

    The name of the docker image to create the sandbox from. Note that in order to function properly, all custom docker images must extend a supported base image (see README).

    The default value for this parameter can be changed by setting the SANDBOX_DOCKER_IMAGE environment variable.

  • allow_network_access (bool) – When True, programs running inside the sandbox will have unrestricted access to external IP addresses. When False, programs will not be able to contact any external IPs.

  • environment_variables (Optional[Mapping[str, str]]) – A dictionary of (variable_name: value) pairs that should be set as environment variables inside the sandbox.

  • container_create_timeout (Optional[int]) – A time limit to be placed on creating the underlying Docker container for this sandbox. If the time limit is exceeded, subprocess.CalledProcessError will be raised. A value of None indicates no time limit.

  • pids_limit (int) –

    Passed to “docker create” with the –pids-limit flag. This will limit the number of processes that can be created. See https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/pids.html for more information on limiting pids with cgroups.

    We recommend leaving this value set to the default of 512 and using the max_num_processes argument to run_command if you want to impose a strict limit on a particular command.

    The default value for this parameter can be changed by setting the SANDBOX_PIDS_LIMIT environment variable.

  • memory_limit (str) –

    Passed to “docker create” with the –memory, –memory-swap, and –oom-kill-disable arguments. This will limit the amount of memory that processes running in the sandbox can use.

    We choose to disable the OOM killer to prevent the sandbox’s main process from being killed by the OOM killer (which would cause the whole container to exit). This means, however, that a command that hits the memory limit may time out.

    In general we recommend setting this value as high as is safe for your host machine and additionally using the max_virtual_memory argument to run_command to set a tighter limit on the command’s address space size.

    The default value for this parameter can be changed by setting the SANDBOX_MEM_LIMIT environment variable.

    See https://docs.docker.com/config/containers/resource_constraints/

    #limit-a-containers-access-to-memory

    for more information.

  • min_fallback_timeout (int) –

    The timeout argument to run_command is primarily enforced by cmd_runner.py. When that argument is not None, a timeout of either twice the timeout argument to run_command or this value, whichever is larger, will be applied to the subprocess call to cmd_runner.py itself.

    The default value for this parameter can be changed by setting the SANDBOX_MIN_FALLBACK_TIMEOUT environment variable.

  • debug (bool) – Whether to print additional debugging information.

add_and_rename_file(filename, new_filename)[source]

Copies the specified file into the working directory of this sandbox and renames it to new_filename.

Return type

None

add_files(*filenames, owner='autograder', read_only=False)[source]

Copies the specified files into the working directory of this sandbox. The filenames specified can be absolute paths or relative paths to the current working directory.

Parameters

  • owner (str) – The name of a user who should be granted ownership of the newly added files. Must be either autograder_sandbox.SANDBOX_USERNAME or ‘root’, otherwise ValueError will be raised.

  • read_only (bool) – If true, the new files’ permissions will be set to read-only.

Return type

None

property allow_network_access

Whether network access is allowed by this sandbox. If an attempt to set this value is made while the sandbox is running, ValueError will be raised.

Return type

bool

property docker_image

The name of the docker image to create the sandbox from.

Return type

str

property environment_variables

A dictionary of environment variables to be set inside the sandbox (Read only).

Return type

Mapping[str, str]

property name

The name used to identify this sandbox. (Read only)

Return type

str

reset()[source]

Destroys, re-creates, and restarts the sandbox. As a side effect, this will effectively kill any processes running inside the sandbox and reset the sandbox’s filesystem.

Return type

None

restart()[source]

Restarts the sandbox without destroying it.

Return type

None

run_command(args, block_process_spawn=False, max_stack_size=None, max_virtual_memory=None, as_root=False, stdin=None, timeout=None, check=False, truncate_stdout=None, truncate_stderr=None)[source]

Runs a command inside the sandbox and returns the results.

Parameters

  • args (List[str]) – A list of strings that specify which command should be run inside the sandbox.

  • block_process_spawn (bool) – If true, prevent the command from spawning child processes by setting the nproc limit to 0.

  • max_stack_size (Optional[int]) – The maximum stack size, in bytes, allowed for the command.

  • max_virtual_memory (Optional[int]) – The maximum amount of memory, in bytes, allowed for the command.

  • as_root (bool) – Whether to run the command as a root user.

  • stdin (Optional[IO[AnyStr]]) – A file object to be redirected as input to the command’s stdin. If this is None, /dev/null is sent to the command’s stdin.

  • timeout (Optional[int]) – The time limit for the command.

  • check (bool) – Causes CalledProcessError to be raised if the command exits nonzero or times out.

  • truncate_stdout (Optional[int]) – When not None, stdout from the command will be truncated after this many bytes.

  • truncate_stderr (Optional[int]) – When not None, stderr from the command will be truncated after this many bytes.

Return type

CompletedCommand

class CompletedCommand(return_code, stdout, stderr, timed_out, stdout_truncated, stderr_truncated)[source]
__init__(return_code, stdout, stderr, timed_out, stdout_truncated, stderr_truncated)[source]
Parameters

  • return_code (Optional[int]) – The return code of the command, or None if the command timed out.

  • stdout (IO[bytes]) – A file object containing the stdout content of the command.

  • stderr (IO[bytes]) – A file object containing the stderr content of the command.

  • timed_out (bool) – Whether the command exceeded the time limit.

  • stdout_truncated (bool) – Whether stdout was truncated.

  • stderr_truncated (bool) – Whether stderr was truncated.

exception SandboxCommandError[source]

An exception to be raised when a call to AutograderSandbox.run_command doesn’t finish normally.