hlbox 1.0.1.dev4

HLBox runs untrusted code in secure Docker based sandboxes (forked from [EpicBox](https://github.com/StepicOrg/epicbox))

# hlbox

A Python library to run untrusted code in secure, isolated [Docker](https://www.docker.com/)
based sandboxes.

> It allows to spawn a process inside one-time Docker container, send data
> to stdin, and obtain its exit code and stdout/stderr output. It's very similar
> to what the [`subprocess`](https://docs.python.org/3/library/subprocess.html#module-subprocess)
> module does but additionally you can specify a custom environment for the process
> (a Docker [image](https://docs.docker.com/v17.09/engine/userguide/storagedriver/imagesandcontainers/))
> and limit the CPU, memory, disk, and network usage for the running process.

> ## Usage
> Run a simple Python script in a one-time Docker container using the
> [`python:3.6.5-alpine`](https://hub.docker.com/_/python/) image:
> ```python
> import epicbox

> epicbox.configure(
> profiles=[
> epicbox.Profile('python', 'python:3.6.5-alpine')
> ]
> )
> files = [{'name': 'main.py', 'content': b'print(42)'}]
> limits = {'cputime': 1, 'memory': 64}
> result = epicbox.run('python', 'python3 main.py', files=files, limits=limits)

> ```
> The `result` value is:
> ```python
> {'exit_code': 0,
> 'stdout': b'42\n',
> 'stderr': b'',
> 'duration': 0.143358,
> 'timeout': False,
> 'oom_killed': False}
> ```

> ### Advanced usage
> A more advanced usage example of `epicbox` is to compile a C++ program and then
> run it multiple times on different input data. In this example `epicbox` will
> run containers on a dedicated [Docker Swarm](https://docs.docker.com/swarm/overview/)
> cluster instead of locally installed Docker engine:
> ```python
> import epicbox

> PROFILES = {
> 'gcc_compile': {
> 'docker_image': 'stepik/epicbox-gcc:6.3.0',
> 'user': 'root',
> },
> 'gcc_run': {
> 'docker_image': 'stepik/epicbox-gcc:6.3.0',
> # It's safer to run untrusted code as a non-root user (even in a container)
> 'user': 'sandbox',
> 'read_only': True,
> 'network_disabled': False,
> },
> }
> epicbox.configure(profiles=PROFILES, docker_url='tcp://1.2.3.4:2375')

> untrusted_code = b"""
> // C++ program
> #include <iostream>

> int main() {
> int a, b;
> std::cin >> a >> b;
> std::cout << a + b << std::endl;
> }
> """
> # A working directory allows to preserve files created in a one-time container
> # and access them from another one. Internally it is a temporary Docker volume.
> with epicbox.working_directory() as workdir:
> epicbox.run('gcc_compile', 'g++ -pipe -O2 -static -o main main.cpp',
> files=[{'name': 'main.cpp', 'content': untrusted_code}],
> workdir=workdir)
> epicbox.run('gcc_run', './main', stdin='2 2',
> limits={'cputime': 1, 'memory': 64},
> workdir=workdir)
> # {'exit_code': 0, 'stdout': b'4\n', 'stderr': b'', 'duration': 0.095318, 'timeout': False, 'oom_killed': False}
> epicbox.run('gcc_run', './main', stdin='14 5',
> limits={'cputime': 1, 'memory': 64},
> workdir=workdir)
> # {'exit_code': 0, 'stdout': b'19\n', 'stderr': b'', 'duration': 0.10285, 'timeout': False, 'oom_killed': False}
> ```

> ## Installation
> `epicbox` can be installed by running `pip install epicbox`. It's tested on Python 3.4+ and
> Docker 1.12+.

> You can also check the [epicbox-images](https://github.com/StepicOrg/epicbox-images)
> repository that contains Docker images used to automatically grade programming
> assignments on [Stepik.org](https://stepik.org/).

> ## Contributing
> Contributions are welcome, and they are greatly appreciated!
> More details can be found in [CONTRIBUTING](CONTRIBUTING.rst).