#ifndef VSF_PTRACESANDBOX_H
#define VSF_PTRACESANDBOX_H
/* Forward delcarations */
struct pt_sandbox;
typedef int (*ptrace_sandbox_validator_t)(struct pt_sandbox*, void*);
/* ptrace_sandbox_alloc()
* PURPOSE
* Allocates a ptrace sandbox object which is needed for the rest of the API.
* RETURNS
* NULL on failure, otherwise an opaque handle.
* TODO
* Only one per process supported at this time.
*/
struct pt_sandbox* ptrace_sandbox_alloc();
/* ptrace_sandbox_free()
* PURPOSE
* Frees the sandbox object.
* PARAMETERS
* p_sandbox - the sandbox handle to free
*/
void ptrace_sandbox_free(struct pt_sandbox* p_sandbox);
/* ptrace_sandbox_launch_process()
* PURPOSE
* Launches a new process and attaches the sandbox to it when it stops.
* PARAMETERS
* p_sandbox - the sandbox handle
* p_func - the function to call at the start of the new process
* p_arg - an argument to pass to the function
* RETURNS
* -1 on failure, otherwise an id for the created process. Not necessarily a
* "pid", please treat is as opaque!
* TODO
* Only one call to this per sandbox object is supported at this time.
*/
int ptrace_sandbox_launch_process(struct pt_sandbox* p_sandbox,
void (*p_func)(void*),
void* p_arg);
/* ptrace_sandbox_run_processes()
* PURPOSE
* Runs sandboxed children until they exit or are killed.
* PARAMETERS
* p_sandbox - the sandbox handle
* RETURNS
* 0 on normal exit or death of processes.
* -1 if any process breached the policy.
*/
int ptrace_sandbox_run_processes(struct pt_sandbox* p_sandbox);
/* ptrace_sandbox_kill_processes()
* PURPOSE
* Safely kills off all sandboxed processes.
* PARAMETERS
* p_sandbox - the sandbox handle
*/
void ptrace_sandbox_kill_processes(struct pt_sandbox* p_sandbox);
/* ptrace_sandbox_get_arg()
* PURPOSE
* Gets a syscall argument value for a process stopped in syscall entry.
* PARAMETERS
* p_sandbox - the sandbox handle
* arg - the arg number to get (zero-based)
* p_out - the result is written here
* RETURNS
* 0 on success; otherwise it's a failure.
*/
int ptrace_sandbox_get_arg(struct pt_sandbox* p_sandbox,
int arg,
unsigned long* p_out);
/* ptrace_sandbox_get_socketcall_arg()
* PURPOSE
* Gets a syscall argument value for a process stopped in syscall entry, where
* the system call is a socket-related one. On some architectures (e.g. i386,
* socket calls are in fact multiplexed and store the arguments in a struct
* in user space, hence the need for abstraction.
* PARAMETERS
* p_sandbox - the sandbox handle
* arg - the arg number to get (zero-based)
* p_out - the result is written here
* RETURNS
* 0 on success; otherwise it's a failure.
*/
int ptrace_sandbox_get_socketcall_arg(struct pt_sandbox* p_sandbox,
int arg,
unsigned long* p_out);
/* ptrace_sandbox_get_long()
* PURPOSE
* Gets a long from the address space of the process stopped in syscall entry.
* PARAMETERS
* p_sandbox - the sandbox handle
* ptr - the address to read the long from
* p_out - the result is written here
* RETURNS
* 0 on success; otherwise it's a failure.
*/
int ptrace_sandbox_get_long(struct pt_sandbox* p_sandbox,
unsigned long ptr,
unsigned long* p_out);
/* ptrace_sandbox_get_buf()
* PURPOSE
* Gets a piece of memory from the address space of the process stopped in
* syscall entry.
* PARAMETERS
* p_sandbox - the sandbox handle
* ptr - the address to read the buffer from
* len - the length of the buffer
* p_buf - the result is written here
* RETURNS
* 0 on success; otherwise it's a failure.
*/
int ptrace_sandbox_get_buf(struct pt_sandbox* p_sandbox,
unsigned long ptr,
unsigned long len,
void* p_buf);
/* ptrace_sandbox_attach_point()
* PURPOSE
* Used by the sandbox child code to stop and indicate it is ready to be
* attached to.
* NOTES
* In the event of error trying to stop, the process is forcibly killed as a
* security measure.
*/
void ptrace_sandbox_attach_point(void);
/* POLICY EDIT: permits exit() and exit_group() */
void ptrace_sandbox_permit_exit(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits read() */
void ptrace_sandbox_permit_read(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits write() */
void ptrace_sandbox_permit_write(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits sigaction() and rt_sigaction() */
void ptrace_sandbox_permit_sigaction(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits alarm() */
void ptrace_sandbox_permit_alarm(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits time() and gettimeofday() */
void ptrace_sandbox_permit_query_time(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits mmap2() (but not the MAP_SHARED flag) */
void ptrace_sandbox_permit_mmap(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits mprotect() */
void ptrace_sandbox_permit_mprotect(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits stat(), stat64(), lstat(), lstat64() */
void ptrace_sandbox_permit_file_stats(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits fstat(), fstat64() */
void ptrace_sandbox_permit_fd_stats(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits getcwd() */
void ptrace_sandbox_permit_getcwd(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits chdir() */
void ptrace_sandbox_permit_chdir(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits umask() */
void ptrace_sandbox_permit_umask(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits open(), except O_ASYNC and O_DIRECT. Only O_RDONLY
* allowed unless writeable is 1
*/
void ptrace_sandbox_permit_open(struct pt_sandbox* p_sandbox, int writeable);
/* POLICY EDIT: permits close() */
void ptrace_sandbox_permit_close(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits getdents(), getdents64() */
void ptrace_sandbox_permit_getdents(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits fcntl(), fcntl64() for file locking, safe F_SETFL flag
* setting (no O_ASYNC, O_DIRECT), F_SETOWN for your own pid and F_SETFD.
*/
void ptrace_sandbox_permit_fcntl(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits sendfile(), sendfile64() */
void ptrace_sandbox_permit_sendfile(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits lseek(), llseek() */
void ptrace_sandbox_permit_seek(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits select(), newselect() */
void ptrace_sandbox_permit_select(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits unlink() */
void ptrace_sandbox_permit_unlink(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits mkdir() */
void ptrace_sandbox_permit_mkdir(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits rmdir() */
void ptrace_sandbox_permit_rmdir(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits rename() */
void ptrace_sandbox_permit_rename(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits utime(), utimes() */
void ptrace_sandbox_permit_utime(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits sigreturn() */
void ptrace_sandbox_permit_sigreturn(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits recv() */
void ptrace_sandbox_permit_recv(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits readlink() */
void ptrace_sandbox_permit_readlink(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits brk() */
void ptrace_sandbox_permit_brk(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits nanosleep() */
void ptrace_sandbox_permit_sleep(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits fchmod() */
void ptrace_sandbox_permit_fchmod(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits chmod() */
void ptrace_sandbox_permit_chmod(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits fchown(), fchown32() */
void ptrace_sandbox_permit_fchown(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits mremap() */
void ptrace_sandbox_permit_mremap(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits ftruncate(), ftruncate64() */
void ptrace_sandbox_permit_ftruncate(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits socket() */
void ptrace_sandbox_permit_socket(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: set validator for socket() */
void ptrace_sandbox_set_socket_validator(struct pt_sandbox* p_sandbox,
ptrace_sandbox_validator_t val,
void* p_arg);
/* POLICY EDIT: permits bind() */
void ptrace_sandbox_permit_bind(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: set validator for bind() */
void ptrace_sandbox_set_bind_validator(struct pt_sandbox* p_sandbox,
ptrace_sandbox_validator_t val,
void* p_arg);
/* POLICY EDIT: permits connect() */
void ptrace_sandbox_permit_connect(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: set validator for connect() */
void ptrace_sandbox_set_connect_validator(struct pt_sandbox* p_sandbox,
ptrace_sandbox_validator_t val,
void* p_arg);
/* POLICY EDIT: permits listen() */
void ptrace_sandbox_permit_listen(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits accept() */
void ptrace_sandbox_permit_accept(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: permits setsockopt() */
void ptrace_sandbox_permit_setsockopt(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: set validator for setsockopt() */
void ptrace_sandbox_set_setsockopt_validator(struct pt_sandbox* p_sandbox,
ptrace_sandbox_validator_t val,
void* p_arg);
/* POLICY EDIT: permits getsockopt() */
void ptrace_sandbox_permit_getsockopt(struct pt_sandbox* p_sandbox);
/* POLICY EDIT: set validator for getsockopt() */
void ptrace_sandbox_set_getsockopt_validator(struct pt_sandbox* p_sandbox,
ptrace_sandbox_validator_t val,
void* p_arg);
/* POLICY EDIT: permits shutdown() */
void ptrace_sandbox_permit_shutdown(struct pt_sandbox* p_sandbox);
/* The traced process is unexpectedly dead; probably an external SIGKILL */
#define PTRACE_SANDBOX_ERR_DEAD -1
/* An unexpected error from ptrace() */
#define PTRACE_SANDBOX_ERR_PTRACE -2
/* An unexpected error from waitpid() */
#define PTRACE_SANDBOX_ERR_WAITPID -3
/* An unexpected waitpid() status was returned */
#define PTRACE_SANDBOX_ERR_WAIT_STATUS -4
/* A syscall not in the policy was attempted */
#define PTRACE_SANDBOX_ERR_POLICY_SYSCALL -5
/* A "bad" syscall was attemped: out-of-bounds, 64-bit in a 32-bit child etc. */
#define PTRACE_SANDBOX_ERR_BAD_SYSCALL -6
/* Bad arguments to a generally accepted syscall */
#define PTRACE_SANDBOX_ERR_POLICY_ARGS -7
/* Abuse of our API */
#define PTRACE_SANDBOX_ERR_API_ABUSE_STOPIT -8
#endif /* VSF_PTRACESANDBOX_H */