xaqt

README

What is it?

xaqt (ɛksəkjuti) is a Docker based sandbox to run untrusted code and return the output to your app. Users can submit their code in any of the supported languages. The system will test the code in an isolated environment. This way you do not have to worry about untrusted code possibly damaging your server intentionally or unintentionally.

How does it work?

A client submits their code and a languageID to the API. The API then creates a new Docker container and runs the code using the compiler/interpreter of that language. The program runs inside a virtual machine with limited resources and has a time-limit for execution (20s by default). Once the output is ready it is returned as a result of the API request. The Docker container is destroyed and all the files are deleted from the server.

No two coders have access to each other’s Docker or files.

Installation Instructions

OS X

If running on OS X, ensure that the command gtimeout is installed, commonly via brew install coreutils.

Building the Docker

1. Install docker as appropriate for your platform.
2. Run docker pull frenata/xaqt-sandbox in project root.

Building the Server

1. Install the Go toolchain as appropriate for your platform.
2. Run go get github.com/frenata/xaqt/...

Running the Server

1. Set the desired port for xaqt via the environment variable XAQT_PORT.
2. From project root, run xaqt.

Usage Instructions

Included with the xaqt library is a simple REST api server. Two endpoints are exposed by the running server:

• GET /languages/ : This will return a JSON list with the available target languages.
• POST /evaluate/ : This evaluates code, encoded in a JSON body of the following form:

{
    "language": "python",
    "stdins": ["1","2"],
    "code": "import sys\nprint(sys.stdin.read())"
}

Returned is a JSON object that reports success or failure of evaluation, and for each element of stdins, what the code has printed to stdout for that element.

Development

Vendoring

we currently use govendor as our vendoring tool for external dependencies.

Documentation

Index

• Constants
• func DataPath() string
• func Image(i string) option
• func Path(p string) option
• func TargetFolder(f string) option
• func Timeout(t time.Duration) option
• type CompilerDetails
• type Compilers
  • func ReadCompilers(filename string) Compilers
• type CompositionDetails
• type Context
  • func NewContext(compilers Compilers, options ...option) (*Context, error)
  • func (c *Context) Evaluate(language, code string, stdins []string) ([]string, Message)
  • func (c *Context) Languages() map[string]CompositionDetails
• type ExecutionDetails
• type Message

Constants

const (
	TmpDirPrefix = "xaqt-"
)

Functions

func DataPath

func DataPath() string

func Image

func Image(i string) option

Image configures which docker image should be used for evaluation.

func Path

func Path(p string) option

Path configures the folder with the execution script and "Payload" dir.

func TargetFolder

func TargetFolder(f string) option

TargetFolder configures where the result directory should be created.

func Timeout

func Timeout(t time.Duration) option

Timeout configures how long evaluation should run before it is killed.

Types

type CompilerDetails

type CompilerDetails struct {
	ExecutionDetails
	CompositionDetails
}

CompilerDetails contains everything XAQT knows about handling a certain language

type Compilers

type Compilers map[string]CompilerDetails

Compilers maps language names to the details of how to execute code in that language.

func ReadCompilers

func ReadCompilers(filename string) Compilers

ReadCompilers reads a compilers map from a file.

type CompositionDetails

type CompositionDetails struct {
	Boilerplate   string `json:"boilerplate"`
	CommentPrefix string `json:"commentPrefix"`
}

CompositionDetails specifies how to write code in a given language

type Context

type Context struct {
	// contains filtered or unexported fields
}

Context creates a execution context for evaluating user code.

func NewContext

func NewContext(compilers Compilers, options ...option) (*Context, error)

NewContext creates a context from a map of compilers and some user provided options.

func (*Context) Evaluate

func (c *Context) Evaluate(language, code string, stdins []string) ([]string, Message)

Evaluate code in a given language and for a set of 'stdin's.

func (*Context) Languages

func (c *Context) Languages() map[string]CompositionDetails

Languages returns a list of available language names.

type ExecutionDetails

type ExecutionDetails struct {
	Compiler           string `json:"compiler"`
	SourceFile         string `json:"sourceFile"`
	OptionalExecutable string `json:"optionalExecutable"`
	CompilerFlags      string `json:"compilerFlags"`
	Disabled           string `json:"disabled"`
}

ExecutionDetails specifies how to execute certain code.

type Message

type Message struct {
	Type string `json:"type"`
	Data string `json:"data"`
}

Message represents details on success or failure of execution.