Core module

struct ev_data

Public Members

int epfd
struct epoll_event evts[EVPOOL_SIZE]
struct ev_pollpair polls[EVPOOL_SIZE]
struct ev_header

Public Members

int fd
void (*handler)(struct ev_header *evhdr, uint32_t events)
struct ev_pollpair

Public Members

int fd
uint32_t events
struct fdmap

Public Members

unsigned int num
fdpair *map
struct fdpair

File descriptor mapping.

Public Members

int host
int guest
struct gidpair

Public Members

gid_t host
gid_t guest
struct idmap

Public Members

unsigned int uid_num
unsigned int gid_num
uidpair *uid_map
gidpair *gid_map
class Sandbox : public std::enable_shared_from_this<Sandbox>
#include <sandbox.h>

Sandbox class.

Public Functions

Sandbox(const std::string &_exe_path, const std::vector<std::string> &_argv, const std::vector<std::string> &_envp, const SandboxConfig &_config)

Constructor. Initialize sandbox enviroments and configuration.

Parameters

  • _exe_path: Executable file path in the sandbox.

  • _argv: Arguments.

  • _envp: Environment variables.

  • _config: Sandbox configuration.

~Sandbox()

Destructor. Clean the sandbox.

Sandbox(const Sandbox &other)
Sandbox(Sandbox &&other)
Sandbox &operator=(const Sandbox &other)
Sandbox &operator=(Sandbox &&other)
void start(func_sandbox_stop_callback _stop_callback)

Run the process in the sandbox.

Parameters

  • _stop_callback: Sandbox stop callback.

void terminate()

Terminate the process.

Public Members

uint64_t id

Sandbox ID.

SandboxStat stat

Sandbox statistic.

Public Static Functions

void update_sandboxes(siginfo_t *siginfo)

Update corresponding sandbox states.

Parameters

  • siginfo: The signal detail.

Private Types

enum [anonymous]

Values:

SANDBOX_STATE_INIT

Initialized.

SANDBOX_STATE_PRERUN

Wait for the process to be started.

SANDBOX_STATE_RUNNING

The process is running.

SANDBOX_STATE_STOP

The process is stopped.

Private Functions

int install_limit() const

Install rlimit and user time limit.

int install_filter() const

Install seccomp filter.

int read_stat(uint64_t *utime, uint64_t *stime, uint64_t *peakmem)

Get the process statistic.

Parameters

  • utime: The pointer for storing user time (msec).

  • stime: The pointer for storing system time (msec).

  • peakmem: The pointer for storing maximum usage of memory (bytes).

void update_state(siginfo_t *siginfo)

Update the sandbox state.

Parameters

  • siginfo: The signal detail.

void stop(bool exit_error)

Called after the process is terminated. Call stop callback to report the process statistic.

Parameters

  • exit_error: Whether the process is killed or exited with errors.

Private Members

Sandbox::[anonymous] state

Process state.

pid_t child_pid

PID.

func_sandbox_stop_callback stop_callback

Sandbox stop callback.

std::string exe_path

Executable file path in the sandbox.

std::vector<std::string> argv

Arguments.

std::vector<std::string> envp

Environment variables.

SandboxConfig config

Sandbox configuration.

cgroup *cg

Cgroup.

cgroup_controller *memcg

Cgroup memory controller.

sandbox_evpair *memevt_poll

OOM event pair.

sandbox_evpair *forcetime_poll

Force timeout event pair.

int suspend_fd

Event file descriptor for process synchronization.

int execve_count

Times of execve being called.

Private Static Functions

void memevt_handler(ev_header *hdr, uint32_t events)

OOM event handler.

Parameters

void forcetime_handler(ev_header *hdr, uint32_t events)

Force timeout event handler.

Parameters

int sandbox_entry(void *data)

The sandboxed process entry.

Parameters

Private Static Attributes

uint64_t last_sandbox_id = 0

Last used Sandbox ID.

std::unordered_map<pid_t, std::shared_ptr<Sandbox>> sandbox_map

Live sandboxes map.

std::unordered_map<int, uint64_t> run_map

Prerun and running sandboxes map.

struct sandbox_evpair
#include <sandbox.h>

Event pair for sandbox.

Public Members

ev_header hdr

Event ev_header.

uint64_t id

Sandbox ID.

class SandboxConfig
#include <sandbox.h>

Sandbox configuration.

Public Members

std::string work_path

Working directory in the sanbox.

std::string root_path

Root directory for chroot.

uid_t uid

UID.

gid_t gid

GID.

std::vector<std::pair<uid_t, uid_t>> uid_map

UID mapping.

std::vector<std::pair<gid_t, gid_t>> gid_map

GID mapping.

std::vector<std::pair<int, int>> fd_map

File descriptor mapping.

uint64_t timelimit

Timelimit.

uint64_t memlimit

Memlimit.

sandbox_restrict_level restrict_level

Restriction level.

class SandboxException : public exception
#include <sandbox.h>

Sandbox exception.

Public Functions

SandboxException(const std::string &_what_arg)
virtual const char *what() const

Private Members

std::string what_arg
class SandboxStat
#include <sandbox.h>

Sandbox statistic.

Public Types

enum [anonymous]

Values:

SANDBOX_STAT_NONE = 0

No error.

SANDBOX_STAT_OOM = 1

Memory limit exceed.

SANDBOX_STAT_TIMEOUT = 2

Time limit exceed.

SANDBOX_STAT_FORCETIMEOUT = 3

Force time limit exceed.

SANDBOX_STAT_EXITERR = 4

Runtime error.

SANDBOX_STAT_INTERNALERR = 5

Internal error.

Public Functions

SandboxStat()

Public Members

uint64_t utime

User time (msec).

uint64_t stime

System time (msec).

uint64_t peakmem

Maximum usage of memory (bytes).

SandboxStat::[anonymous] detect_error

Detected error.

class Task
#include <core.h>

Task class. Used to maintain the task and its corresponding sandbox.

Public Functions

Task(const std::shared_ptr<Sandbox> &_sdbx, func_core_task_callback _callback, void *_data)

Constructor.

Parameters

  • _sdbx: Sandbox shared pointer.

  • _callback: Task stop callback.

  • _data: Private data.

Public Members

uint64_t id

Task ID.

std::shared_ptr<Sandbox> sdbx

The sandbox shared pointer.

func_core_task_callback callback

Task stop callback.

void *data

Private data of the task stop callback.

struct taskstat

Task statistic for CFFI interface.

Public Members

uint64_t utime
uint64_t stime
uint64_t peakmem
int detect_error
struct uidpair

UID/GID mapping.

Public Members

uid_t host
uid_t guest
file core.h

Typedefs

typedef void (*func_core_task_callback)(uint64_t id, const SandboxStat &stat, void *data)

Prototype of task callback function.

Functions

int core_init()

Initialize event loop, sandbox environment, and global variables.

Return

0 if success.

void core_destroy()

Destroy event loop.

uint64_t core_create_task(const std::string &exe_path, const std::vector<std::string> &argv, const std::vector<std::string> &envp, const SandboxConfig &config)

Create a task, and store the task into task_map. It won’t start the task.

Return

Task ID, -1 if failed.

Parameters

  • exe_path: Executable file path in the sandbox.

  • argv: Arguments.

  • envp: Environment variables.

  • config: Sandbox configuration.

int core_start_task(uint64_t id, func_core_task_callback callback, void *data)

Start the task.

Return

0 if success.

Parameters

  • id: Task ID.

  • callback: Task stop callback.

  • data: Private data.

Variables

ev_data *core_evdata

Public ev_data of event loop.

file ev.h

Functions

int ev_init(struct ev_data *evdata)
int ev_add(struct ev_data *evdata, struct ev_header *evhdr, uint32_t events)
int ev_del(struct ev_data *evdata, struct ev_header *evhdr)
int ev_mod(struct ev_data *evdata, struct ev_header *evhdr, uint32_t events)
int ev_poll(struct ev_data *evdata, int timeout)
int ev_close(struct ev_data *evdata)
int ev_register(struct ev_header *evhdr, uint32_t events)
int ev_unregister(struct ev_header *evhdr)
int ev_modify(struct ev_header *evhdr, uint32_t events)
file sandbox.h

Typedefs

typedef void (*func_sandbox_stop_callback)(uint64_t id)

Prototype of sandbox stop callback function.

Enums

enum sandbox_restrict_level

Values:

SANDBOX_RESTRICT_LOW = 0

Low restriction level.

Only isolate environment, prevent resource exhausted.

SANDBOX_RESTRICT_HIGH = 1

High restriction level.

Isolate environment, prevent resource exhausted. Enable user time limit, seccomp filter, strict file descriptor limit.

Functions

void sandbox_init()

Initialize signal file descriptor, libcgroup, and signal mask.

file utils.h

Functions

void internal_err(const char *prefix, const char *fmt, ...)

Show the critical error message and hang the program.

Parameters

  • prefix: LOG_PREFIX.

  • fmt: Format string.

  • ...: Arguments.

void internal_info(const char *prefix, const char *fmt, ...)

Show the information message.

Parameters

  • prefix: LOG_PREFIX.

  • fmt: Format string.

  • ...: Arguments.

void internal_dbg(const char *prefix, const char *fmt, ...)

Show the debug message.

Parameters

  • prefix: LOG_PREFIX.

  • fmt: Format string.

  • ...: Arguments.

file core.cpp

Functions

int core_init()

Initialize event loop, sandbox environment, and global variables.

Return

0 if success.

void core_destroy()

Destroy event loop.

static void sandbox_stop_callback(uint64_t id)

Handle sandbox stop event. It will call the corresponding task stop callback, and remove the task from task_map.

Parameters

uint64_t core_create_task(const std::string &exe_path, const std::vector<std::string> &argv, const std::vector<std::string> &envp, const SandboxConfig &config)

Create a task, and store the task into task_map. It won’t start the task.

Return

Task ID, -1 if failed.

Parameters

  • exe_path: Executable file path in the sandbox.

  • argv: Arguments.

  • envp: Environment variables.

  • config: Sandbox configuration.

int core_start_task(uint64_t id, func_core_task_callback callback, void *data)

Start the task.

Return

0 if success.

Parameters

  • id: Task ID.

  • callback: Task stop callback.

  • data: Private data.

Variables

ev_data *core_evdata

Public ev_data of event loop.

std::unordered_map<uint64_t, Task> task_map

Live tasks map.

file ev.cpp

Functions

int ev_add(struct ev_data *evdata, struct ev_header *evhdr, uint32_t events)
int ev_del(struct ev_data *evdata, struct ev_header *evhdr)
int ev_mod(struct ev_data *evdata, struct ev_header *evhdr, uint32_t events)
int ev_register(struct ev_header *evhdr, uint32_t events)
int ev_unregister(struct ev_header *evhdr)
int ev_modify(struct ev_header *evhdr, uint32_t events)
int ev_init(struct ev_data *evdata)
int ev_poll(struct ev_data *evdata, int timeout)
int ev_close(struct ev_data *evdata)

Variables

struct ev_data *curr_evdata
std::unordered_map<ev_header *, bool> unregister_ptr
file pyext.cpp

Typedefs

typedef void (*func_pyext_stop_callback)(uint64_t id, taskstat stat)

Prototype of stop callback for CFFI interface.

Functions

static void enter_pyext()

Escalate privilege while entering the extension.

static void leave_pyext()

Recover privilege while leaving the extension.

DLL_EXPORT int init()

Initialize the extension.

DLL_EXPORT void destroy()

Destroy the extension.

DLL_EXPORT int ext_register(int fd, int events)

Register a event.

Return

0 if success

Parameters

  • fd: File descriptor.

  • events: Event flags.

DLL_EXPORT int ext_unregister(int fd)

Unregister the event.

Return

0 if success

Parameters

  • fd: File descriptor.

DLL_EXPORT int ext_modify(int fd, int events)

Modify the event.

Return

0 if success

Parameters

  • fd: File descriptor.

  • events: Event flags.

DLL_EXPORT int ext_poll(ev_pollpair pollpairs[], int timeout)

Poll events.

Return

Number of events polled.

Parameters

  • pollpairs: An array for storing event pairs.

  • timeout: Timeout.

DLL_EXPORT uint64_t create_task(const char * exe_path, const char * argv[], const char * envp[], const char * work_path, const char * root_path, uid_t uid, gid_t gid, idmap * id_map, fdmap * fd_map, uint64_t timelimit, uint64_t memlimit, int restrict_level)

Create a task.

Return

Task ID, -1 if failed.

Parameters

  • exe_path: Executable file path in the sandbox.

  • argv: List of arguments.

  • envp: List of environment variables.

  • stdin_fd: Standard input file descriptor.

  • stdout_fd: Standard output file descriptor.

  • stderr_fd: Standard error file descriptor.

  • work_path: Working directory in the sandbox.

  • root_path: Root directory.

  • uid: UID.

  • gid: GID.

  • timelimit: Timelimit.

  • memlimit: Memlimit.

  • restrict_level: Restriction level.

static void stop_task_callback(uint64_t id, const SandboxStat &stat, void *data)

Stop task callback.

Parameters

  • id: Task ID.

  • stat: Sandbox statistic.

  • data: Stop callback of CFFI.

DLL_EXPORT int start_task(uint64_t id, func_pyext_stop_callback callback)

Start the task.

Return

0 if success.

Parameters

  • id: Task ID.

  • callback: Stop callback of CFFI.

Variables

uid_t old_euid = 0

Old EUID before escalation.

gid_t old_egid = 0

Old EGID before escalation.

std::unordered_map<int, ev_header *> poll_map

Poll event map.

file sandbox.cpp

Functions

static void sigchld_callback(struct ev_header *evhdr, uint32_t events)

Handle SIGCHLD signal.

Parameters

  • evhdr: Event ev_header.

  • events: Event flags.

void sandbox_init()

Initialize signal file descriptor, libcgroup, and signal mask.

Variables

int sigchld_sigfd

Signal file desceiptor of SIGCHLD.

ev_header sigchld_evhdr

The ev_header of SIGCHLD;.

file utils.cpp

Functions

void internal_err(const char *prefix, const char *fmt, ...)

Show the critical error message and hang the program.

Parameters

  • prefix: LOG_PREFIX.

  • fmt: Format string.

  • ...: Arguments.

void internal_info(const char *prefix, const char *fmt, ...)

Show the information message.

Parameters

  • prefix: LOG_PREFIX.

  • fmt: Format string.

  • ...: Arguments.

void internal_dbg(const char *prefix, const char *fmt, ...)

Show the debug message.

Parameters

  • prefix: LOG_PREFIX.

  • fmt: Format string.

  • ...: Arguments.

dir inc
dir src