{"id":13621635,"url":"https://github.com/StepicOrg/epicbox","last_synced_at":"2025-04-15T01:33:31.179Z","repository":{"id":27488203,"uuid":"30968242","full_name":"StepicOrg/epicbox","owner":"StepicOrg","description":"Run untrusted code in secure Docker based sandboxes","archived":false,"fork":false,"pushed_at":"2024-01-28T18:16:18.000Z","size":98,"stargazers_count":148,"open_issues_count":8,"forks_count":39,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-04-26T17:09:01.793Z","etag":null,"topics":["docker","python","sandbox"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StepicOrg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-18T14:14:52.000Z","updated_at":"2024-06-12T07:22:40.615Z","dependencies_parsed_at":"2022-09-19T06:00:59.994Z","dependency_job_id":"b16136b4-b3eb-459a-976f-ffae6434b56e","html_url":"https://github.com/StepicOrg/epicbox","commit_stats":{"total_commits":82,"total_committers":4,"mean_commits":20.5,"dds":0.1707317073170732,"last_synced_commit":"3673448da65c87430e243c39f166c7186b635190"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StepicOrg%2Fepicbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StepicOrg%2Fepicbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StepicOrg%2Fepicbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StepicOrg%2Fepicbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StepicOrg","download_url":"https://codeload.github.com/StepicOrg/epicbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223654847,"owners_count":17180601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","python","sandbox"],"created_at":"2024-08-01T21:01:08.897Z","updated_at":"2024-11-08T08:31:22.882Z","avatar_url":"https://github.com/StepicOrg.png","language":"Python","readme":"# epicbox\n[![Build Status](https://travis-ci.org/StepicOrg/epicbox.svg?branch=master)](https://travis-ci.org/StepicOrg/epicbox)\n\nA Python library to run untrusted code in secure, isolated [Docker](https://www.docker.com/)\nbased sandboxes. It is used to automatically grade programming assignments\non [Stepik.org](https://stepik.org/).\n\nIt allows to spawn a process inside one-time Docker container, send data\nto stdin, and obtain its exit code and stdout/stderr output.  It's very similar\nto what the [`subprocess`](https://docs.python.org/3/library/subprocess.html#module-subprocess)\nmodule does but additionally you can specify a custom environment for the process\n(a Docker [image](https://docs.docker.com/v17.09/engine/userguide/storagedriver/imagesandcontainers/))\nand limit the CPU, memory, disk, and network usage for the running process.\n\n## Usage\nRun a simple Python script in a one-time Docker container using the\n[`python:3.6.5-alpine`](https://hub.docker.com/_/python/) image:\n```python\nimport epicbox\n\nepicbox.configure(\n    profiles=[\n        epicbox.Profile('python', 'python:3.6.5-alpine')\n    ]\n)\nfiles = [{'name': 'main.py', 'content': b'print(42)'}]\nlimits = {'cputime': 1, 'memory': 64}\nresult = epicbox.run('python', 'python3 main.py', files=files, limits=limits)\n\n```\nThe `result` value is:\n```python\n{'exit_code': 0,\n 'stdout': b'42\\n',\n 'stderr': b'',\n 'duration': 0.143358,\n 'timeout': False,\n 'oom_killed': False}\n```\n\n### Available Limit Options\n\nThe available limit options and default values:\n\n```\nDEFAULT_LIMITS = {\n    # CPU time in seconds, None for unlimited\n    'cputime': 1,\n    # Real time in seconds, None for unlimited\n    'realtime': 5,\n    # Memory in megabytes, None for unlimited\n    'memory': 64,\n\n    # limit the max processes the sandbox can have\n    # -1 or None for unlimited(default)\n    'processes': -1,\n}\n```\n\n### Advanced usage\nA more advanced usage example of `epicbox` is to compile a C++ program and then\nrun it multiple times on different input data.  In this example `epicbox` will\nrun containers on a dedicated [Docker Swarm](https://docs.docker.com/swarm/overview/)\ncluster instead of locally installed Docker engine:\n```python\nimport epicbox\n\nPROFILES = {\n    'gcc_compile': {\n        'docker_image': 'stepik/epicbox-gcc:6.3.0',\n        'user': 'root',\n    },\n    'gcc_run': {\n        'docker_image': 'stepik/epicbox-gcc:6.3.0',\n        # It's safer to run untrusted code as a non-root user (even in a container)\n        'user': 'sandbox',\n        'read_only': True,\n        'network_disabled': False,\n    },\n}\nepicbox.configure(profiles=PROFILES, docker_url='tcp://1.2.3.4:2375')\n\nuntrusted_code = b\"\"\"\n// C++ program\n#include \u003ciostream\u003e\n\nint main() {\n    int a, b;\n    std::cin \u003e\u003e a \u003e\u003e b;\n    std::cout \u003c\u003c a + b \u003c\u003c std::endl;\n}\n\"\"\"\n# A working directory allows to preserve files created in a one-time container\n# and access them from another one. Internally it is a temporary Docker volume.\nwith epicbox.working_directory() as workdir:\n    epicbox.run('gcc_compile', 'g++ -pipe -O2 -static -o main main.cpp',\n                files=[{'name': 'main.cpp', 'content': untrusted_code}],\n                workdir=workdir)\n    epicbox.run('gcc_run', './main', stdin='2 2',\n                limits={'cputime': 1, 'memory': 64},\n                workdir=workdir)\n    # {'exit_code': 0, 'stdout': b'4\\n', 'stderr': b'', 'duration': 0.095318, 'timeout': False, 'oom_killed': False}\n    epicbox.run('gcc_run', './main', stdin='14 5',\n                limits={'cputime': 1, 'memory': 64},\n                workdir=workdir)\n    # {'exit_code': 0, 'stdout': b'19\\n', 'stderr': b'', 'duration': 0.10285, 'timeout': False, 'oom_killed': False}\n```\n\n## Installation\n`epicbox` can be installed by running `pip install epicbox`. It's tested on Python 3.4+ and\nDocker 1.12+.\n\nYou can also check the [epicbox-images](https://github.com/StepicOrg/epicbox-images)\nrepository that contains Docker images used to automatically grade programming\nassignments on [Stepik.org](https://stepik.org/).\n\n## Contributing\nContributions are welcome, and they are greatly appreciated!\nMore details can be found in [CONTRIBUTING](CONTRIBUTING.rst).\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStepicOrg%2Fepicbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStepicOrg%2Fepicbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStepicOrg%2Fepicbox/lists"}