Metadata-Version: 2.0
Name: hlbox
Version: 1.0.2
Summary: HLBox runs untrusted code in secure Docker based sandboxes (forked from [EpicBox](https://github.com/StepicOrg/epicbox))
Home-page: UNKNOWN
Author: Alex Gajewski
Author-email: agajews@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Requires-Dist: docker (>=2)
Requires-Dist: python-dateutil (~=2.4)
Requires-Dist: requests (~=2.14)
Requires-Dist: structlog (>=15.3)

# 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).



