eggsy

README

eggsy

eggsy's goal is to execute a set of source files in a sandboxed container, i.e. it's job is effectively to

execute_with_gvisor(dockerfile, file set, command, timeout, seccomp, network mode)

The FileSet just has to be a list of paths and their io.ReadCloser's. It is copied into the container along with the provided Dockerfile.

Execute means that after the Dockerfile is run, the provided shell command is executed with a user-defined timeout. The executor also takes in an optional seccomp security profile and flag to configure network access.

The Sandbox is gVisor, a user-space kernel intended to isolate a process in a container from the host's kernel.

Example:

package main

import (
    "context"
    "io/ioutil"
    "log"
    "os"
    "strings"
    "time"

    "github.com/smasher164/eggsy"
)

const dockerfile = `
FROM golang:1.10
COPY somefile.go .
`

const cmd = "go run somefile.go"

const file = `
package main
import (
    "fmt"
    "time"
)
func main() {
    time.Sleep(10 * time.Second)
    fmt.Println("Hello from the container")
}
`

type fslice []eggsy.File

func (f fslice) At(i int) (eggsy.File, error) { return f[i], nil }
func (f fslice) Len() int                     { return len(f) }

func main() {
    files := fslice{eggsy.File{
        Path:       "somefile.go",
        ReadCloser: ioutil.NopCloser(strings.NewReader(file)),
    }}

    e := &eggsy.Executor{
        Dockerfile: dockerfile,
        Files:      files,
        Cmd:        cmd,
        Timeout:    3 * time.Second,
        Seccomp:    eggsy.SEDefault,
        Net:        eggsy.NetBridge,
        Stdout:     os.Stdout,
        Stderr:     os.Stderr,
    }
    err := e.Execute(context.Background())
    if err != nil {
        log.Println(err)
        return
    }
}

which should output a message similar to the following:

2018/08/14 23:42:15 process "go run somefile.go" in container eb06ed18d403e87e28382a8867e44b7a from image 98897596d97f38af229c2847c6287079 has timed out

Documentation

Index

• Constants
• type Executor
  • func (e *Executor) Execute(ctx context.Context) (err error)
• type File
• type FileSet
• type Network
• type TimeoutError
  • func (t TimeoutError) Error() string

Constants

const (
	NoTimeout time.Duration = -1

	SEDefault    = ""
	SEUnconfined = "unconfined"

	// NetBridge is the default network mode. No ports are exposed to the
	// outside world and other containers are only accessible via IP.
	NetBridge Network = 0

	// NetNone disables all network access in the container except to localhost.
	NetNone Network = 1
)

Types

type Executor

type Executor struct {
	// Dockerfile is the Dockerfile used to construct the container.
	Dockerfile string

	// Files holds the set of files to be transferred into the build context.
	Files FileSet

	// Cmd is the shell command to execute inside the container.
	Cmd string

	// Timeout represents the timeout for the container to exit after
	// it has been spawned. A Timeout < 0 means there is no timeout.
	// If the timeout is reached before the container exits on its own,
	// Execute will return a TimeoutError.
	Timeout time.Duration

	// Seccomp is the security profile used to constrain system calls made
	// from the container to the Linux kernel. The default profile is
	// provided by docker.
	Seccomp string

	// Net is the network mode for the container. The default mode
	// is a bridge network.
	Net Network

	// Stdout and Stderr specify the container's standard output and standard error.
	//
	// If either is nil, output will be written to the null device.
	//
	// If Stdout == Stderr, at most one goroutine at a time will call Write.
	Stdout io.Writer
	Stderr io.Writer
	// contains filtered or unexported fields
}

Executor represents a non-reusable sandbox for executing a command.

func (*Executor) Execute

func (e *Executor) Execute(ctx context.Context) (err error)

Execute takes in a context, executes the Executor's command in a container, and waits for the container to exit. The timeout of the provided context is different from the timeout of the container. Execute will return a TimeoutError on a container timeout.

type File

type File struct {
	Path string
	io.ReadCloser
}

File associates a path with readable data, used in a FileSet to create a build context for a container environment.

type FileSet

type FileSet interface {
	At(i int) (File, error)
	Len() int
}

FileSet is a list of files used to create a build context for a container environment.

type Network

type Network int

Network is a network mode for a container. See the constant definitions for descriptions of valid network modes.

type TimeoutError

type TimeoutError string

TimeoutError represents an error with a container finishing its command execution, given its timeout.

func (TimeoutError) Error

func (t TimeoutError) Error() string