Skip to content

Latest commit

 

History

History
144 lines (128 loc) · 9.51 KB

README.md

File metadata and controls

144 lines (128 loc) · 9.51 KB
Raw

Godbox

Secure sandboxing system for untrusted code execution.

It uses isolate which uses specific functionnalities of the Linux kernel, thus godbox not able to run properly outside of Linux.

Installation

Kubernetes

Helm Chart

helm repo add godbox-charts https://quantumsheep.github.io/godbox-helm/charts
helm install my-godbox godbox-charts/godbox

Docker Compose

version: "3"

services:
  godbox:
    image: quantumsheep/godbox:2
    privileged: true
    ports:
      - 8080:8080

Docker

docker run -it -d --privileged -p 8080:8080 quantumsheep/godbox:2

Environment variables

Name Type Default Description
API_MAX_PAYLOAD_SIZE number 32768 API maximum payload size
ALLOW_PROFILING boolean true Enable or disable profiling
MAX_RUN_TIME_LIMIT number 5 Maximum run time limit
MAX_EXTRA_TIME_LIMIT number 0 Maximum extra time limit
MAX_WALL_TIME_LIMIT number 10 Maximum wall time limit
MAX_STACK_SIZE_LIMIT number 128000 Maximum stack size limit
MAX_PROCESS_COUNT_LIMIT number 120 Maximum process count limit
MAX_MEMORY_LIMIT number 512000 Maximum memory limit
MAX_STORAGE_LIMIT number 10240 Maximum storage limit

Run commands

Send a POST HTTP request to http://localhost:8080/run containing the wanted configuration in JSON. See below for properties.

Properties

Name Type Description
phases* Phase[] Execution phases (check examples bellow)
files* string Base64-encoded zip file containing the files used in the phases
environment Record<string, string> Environment variables used in all phases
sandbox_settings SandboxSettings Override default sandbox limitation settings

Phase

Name Type Default Description
script* string Multi-line bash script that will be executed inside the isolated environment
name string Phase's index Name that will be used in result output
stdin string Content used in stdin
environment Record Environment variables available inside script execution. This will override global environment variables with the same given keys
sandbox_settings SandboxSettings Overrides default sandbox limitation settings. This will override global sandbox settings with the same given keys
profiling boolean false Run a profiler on script. This functionnality is WIP

SandboxSettings

Name Type Default Description
run_time_limit number 5 Limit run time of the whole control group in seconds. Fractional numbers are allowed
extra_time_limit number 0 When a time limit is exceeded, wait for extra time seconds before killing the program. This has the advantage that the real execution time is reported, even though it slightly exceeds the limit. Fractional numbers are again allowed
wall_time_limit number 10 Limit wall-clock time to time seconds. Fractional values are allowed. This clock measures the time from the start of the program to its exit, so it does not stop when the program has lost the CPU or when it is for an external event. It is recommend to use run_time_limit as the main limit, but set wall_time_limit to a much higher value as a precaution against sleeping programs
stack_size_limit number 128000 Limit process stack to size kilobytes. It is subject to memory_limit
process_count_limit number 120 Permit the program to create up to max processes and/or threads
memory_limit number 512000 Limit total memory usage by the whole control group in kilobytes
storage_limit number 10240 Limit size of files created (or modified) by the program in kilobytes

Example

The files should be passed as a base64 zip archive.

The folowing demonstration uses the folowing file architecture:

.
└── src
    └── main.c

Encoded using command zip -q -r - * | base64 (could have been a library, it doesn't matter while it keeps beeing files -> zip -> base64).

{
  "phases": [
    {
      "name": "Compilation",
      "script": "/usr/local/gcc-11.1.0/bin/gcc src/main.c -o out",
      "sandbox_settings": {
        "run_time_limit": 20,
        "wall_time_limit": 40
      }
    },
    {
      "name": "Execution",
      "script": "./out"
    }
  ],
  "environment": {
    "ENABLE_AWESOME_SHEEP": "true"
  },
  "files": "UEsDBAoAAAAAAJe1pVIAAAAAAAAAAAAAAAAEABwAc3JjL1VUCQADvgOTYNQDk2B1eAsAAQT1AQAABBQAAABQSwMEFAAIAAgABbalUgAAAAAAAAAATQAAAAoAHABzcmMvbWFpbi5jVVQJAAOKBJNgjASTYHV4CwABBPUBAAAEFAAAAFPOzEvOKU1JVbApLknJzNfLsOPiyswrUchNzMzT0OSq5lIAgoLSkmINJY/UnJx8HYXw/KKcFEUlTWsusFxRaklpUZ6CgTVXLRcAUEsHCMUkHr9KAAAATQAAAFBLAQIeAwoAAAAAAJe1pVIAAAAAAAAAAAAAAAAEABgAAAAAAAAAEADtQQAAAABzcmMvVVQFAAO+A5NgdXgLAAEE9QEAAAQUAAAAUEsBAh4DFAAIAAgABbalUsUkHr9KAAAATQAAAAoAGAAAAAAAAQAAAKSBPgAAAHNyYy9tYWluLmNVVAUAA4oEk2B1eAsAAQT1AQAABBQAAABQSwUGAAAAAAIAAgCaAAAA3AAAAAAA"
}

Output

{
  "phases": [
    {
      "name": "Compilation",
      "status": 0,
      "stdout": "",
      "stderr": "",
      "time": 0.037,
      "time_wall": 0.043,
      "used_memory": 6640,
      "sandbox_status": null,
      "csw_voluntary": 18,
      "csw_forced": 16
    },
    {
      "name": "Execution",
      "status": 0,
      "stdout": "Hello, World!\n",
      "stderr": "",
      "time": 0.002,
      "time_wall": 0.007,
      "used_memory": 856,
      "sandbox_status": null,
      "csw_voluntary": 7,
      "csw_forced": 0
    }
  ]
}