ContainerizationAPI

The general idea of this project is to provide a service similar to the CodeExecutionAPI by The Alcoding Club but to manually implement the containerization using cgroups, namespaces, chroot and a bunch of other unix/linux utility tools. This will help accomplish faster execution times and cut down on sandboxing overhead

Requirements

To use this API, there aren't really any requirements, you just need to be able to send HTTP requests To Host this API, you need to have Linux or WSL (if you're on windows) or MacOS, because this project makes heavy use of unix-specific tools.

Usage

Using this API is designed to be as simple as possible, at it's core, it's just an HTTP request that you send to /v2/execute, or /execute

The following are the routes that this API makes available, click one to see it's documentation

POST Route: /execute

This route is a drop in replacement for CodeExecutionAPI, if you send any request to the API defined in that repository, it's actually going to be handled by this codebase (because it does the same exact thing but faster)

This route takes 4 fields:

Note: the above mentioned default and max values can be modified by editing the environment variables mentioned at the bottom of this README

Request body format (Example 1):

{
    "language": "python",           // this is the language your code is going to be executed in
    "code": "print('Hello World')"  // a string containing the code itself, with lines separated by \n
}

curl --location 'https://codeapi.anga.codes/execute' \
--header 'Content-Type: application/json' \
--data '{
    "language": "python",
    "code": "print('\''Hello World'\'')"
}'

Response body format (Example 1):

{
    "output": "Hello World\n",  // Output of the code
    "error": "",                // If any error occurs during execution
    "memory_used": "13808 KB",  // RAM used (in KB)
    "cpu_time": "9.166097ms"    // as in 9.16 milliseconds
}

Request body format (Example 2):

{
    "language": "python",
    "code": "import time\nprint('Hello World')\ntime.sleep(5)",
    "timeout": 2       // in seconds (defaults to 5, max 60)
}

curl --location 'https://codeapi.anga.codes/execute' \
--header 'Content-Type: application/json' \
--data '{
    "language": "python",
    "code": "import time\nprint('\''Hello World'\'')\ntime.sleep(5)",
    "timeout": 2       
}'

Response body format (Example 2):

{
    "output": "",                   // No output is returned on timeout
    "error": "Execution Timed Out", // Error message in case of timeout
    "memory_used": "15856 KB",      // RAM used (in KB)
    "cpu_time": "2.00014463s"      // Time before code was terminated
}

Request body format (Example 3):

{
    "language": "python",
    "code": "import random;[random.random() for x in range(10**7)]",
    "max_memory": 300000        // in KB (defaults to 32768, max 131072)
}

curl --location 'https://codeapi.anga.codes/execute' \
--header 'Content-Type: application/json' \
--data '{
    "language": "python",
    "code": "import random;[random.random() for x in range(10**7)]",
    "max_memory": 300000
}'

Response body format (Example 3):

{
    "output": "",
    "error": "Memory limit exceeded",   // code is terminated the moment it takes more memory than allocated
    "memory_used": "136636 KB",
    "cpu_time": "115.779962ms"
}

Request body format (Example 4):

{
    "language": "python",
    "code": "a = input()\nprint(f'first value entered is {a}.')\nb=input()\nprint(f'second value entered is {b}.')",
    "inputs": [
        "bob",
        "alice"
    ]
}

curl --location 'https://codeapi.anga.codes/execute' \
--header 'Content-Type: application/json' \
--data '{
    "language": "python",
    "code": "a = input()\nprint(f'\''first value entered is {a}.'\'')\nb=input()\nprint(f'\''second value entered is {b}.'\'')",
    "inputs": [
        "bob",
        "alice"
    ]
}'

Response body format (Example 4):

{
    "output": "first value entered is bob.\nsecond value entered is alice.\n",
    "error": "",
    "memory_used": "24504 KB",
    "cpu_time": "13.625964ms"
}

Note: the route /execute also calls /v2/execute under the hood, its just that the formatting for the input and output are slightly more easy to read and understand.

POST Route: /v2/execute

This route takes 4 fields:

Note: the above mentioned default and max values can be modified by editing the environment variables mentioned at the bottom of this README

Request body format (Example 1):

{
    "language": "python",
    "code": "print('Hello World')"
}

curl --location 'https://codeapi.anga.codes/v2/execute' \
--header 'Content-Type: application/json' \
--data '{
    "language": "python",
    "code": "print('\''Hello World'\'')"
}'

Response body format (Example 1):

{
    "output": "Hello World\n",  // output from STDOUT
    "error": "",                // output from STDERR
    "cpu_time": 10283909,       // run time in nanoseconds (10ms or 0.01 seconds)
    "memory_used": 25116        // RAM used (in KB)
}

Request body format (Example 2):

{
    "language": "python",
    "code": "import time\nprint('Hello World')\ntime.sleep(5)",
    "timeout": 2000000000       // in nanoseconds (defaults to 5000000000, max 60000000000)
}

curl --location 'https://codeapi.anga.codes/v2/execute' \
--header 'Content-Type: application/json' \
--data '{
    "language": "python",
    "code": "import time\nprint('\''Hello World'\'')\ntime.sleep(5)",
    "timeout": 2000000000
}'

Response body format (Example 2):

{
    "output": "",                   // No output is returned on timeout
    "error": "Execution Timed Out", // Error message in case of timeout
    "cpu_time": 2000003280,         // Time (in nanoseconds) before code was terminated
    "memory_used": 15856,           // RAM used (in KB)
}

Request body format (Example 3):

{
    "language": "python",
    "code": "import random;[random.random() for x in range(10**7)]",
    "max_memory": 300000        // in KB (defaults to 32768, max 131072)
}

curl --location 'https://codeapi.anga.codes/v2/execute' \
--header 'Content-Type: application/json' \
--data '{
    "language": "python",
    "code": "import random;[random.random() for x in range(10**7)]",
    "max_memory": 300000
}'

Response body format (Example 3):

{
    "output": "",
    "error": "Memory limit exceeded",   // code is terminated the moment it takes more memory than allocated
    "cpu_time": 116936122,
    "memory_used": 136628
}

Request body format (Example 4):

{
    "language": "python",
    "code": "a = input()\nprint(f'first value entered is {a}.')\nb=input()\nprint(f'second value entered is {b}.')",
    "inputs": "bob\nalice"
}

curl --location 'https://codeapi.anga.codes/v2/execute' \
--header 'Content-Type: application/json' \
--data '{
    "language": "python",
    "code": "a = input()\nprint(f'\''first value entered is {a}.'\'')\nb=input()\nprint(f'\''second value entered is {b}.'\'')",
    "inputs": "bob\nalice"
}'

Response body format (Example 4):

{
    "output": "first value entered is bob.\nsecond value entered is alice.\n",
    "error": "",
    "cpu_time": 9058716,
    "memory_used": 25136
}

GET Route: /debug/config

This route returns the current server configuration, including memory limits and timeout settings. This is a debug route and must be enabled via the ENABLE_DEBUG environment variable.

Request format:

GET /debug/config

curl --location 'https://codeapi.anga.codes/debug/config'

Response body format:

{
    "limits": {
        "max_timeout": 60000000000,
        "max_memory_limit": 131072,
        "default_timeout": 5000000000,
        "default_memory_limit": 32768
    },
    "globals": {
        "ram_limit": 1048576,
        "enable_debug_routes": false
    }
}

I'm making this as part of a bigger project to host my own coding contests on a platform a little better than HackerRank. The Alcoding Club's API is fine but I need one that's more efficient and has less overhead than firejail.

uname -a
test "$(uname -s)" = Linux
test -r /proc/self/status
test -e /sys/fs/cgroup/cgroup.controllers
test -e /proc/self/ns/user
test -e /proc/self/ns/pid
command -v gcc
command -v go
command -v python3

sudo -E go test ./...
sudo -E go test -race ./executor
bash .github/scripts/check_regressions.sh
git diff --check

sudo -E go test -count=3 -run '^TestSecurityBoundaryNamespacesAndInheritedResources$' ./...
sudo -E go test -count=3 -run '^TestSandboxHardeningC$/^hostile boundary attack chain cannot cross sandbox$' ./...

sentinel_dir=$(mktemp -d)
printf '%s\n' 'operator-sentinel-must-not-change' > "$sentinel_dir/sentinel"
sha256sum "$sentinel_dir/sentinel"
sudo -E go test -run '^TestSecurityBoundaryNamespacesAndInheritedResources$' ./...
sha256sum "$sentinel_dir/sentinel"
rm -rf "$sentinel_dir"