1 #ifndef VSF_PTRACESANDBOX_H 2 #define VSF_PTRACESANDBOX_H 3 4 /* Forward delcarations */ 5 struct pt_sandbox; 6 7 typedef int (*ptrace_sandbox_validator_t)(struct pt_sandbox*, void*); 8 9 /* ptrace_sandbox_alloc() 10 * PURPOSE 11 * Allocates a ptrace sandbox object which is needed for the rest of the API. 12 * RETURNS 13 * NULL on failure, otherwise an opaque handle. 14 * TODO 15 * Only one per process supported at this time. 16 */ 17 struct pt_sandbox* ptrace_sandbox_alloc(); 18 19 /* ptrace_sandbox_free() 20 * PURPOSE 21 * Frees the sandbox object. 22 * PARAMETERS 23 * p_sandbox - the sandbox handle to free 24 */ 25 void ptrace_sandbox_free(struct pt_sandbox* p_sandbox); 26 27 /* ptrace_sandbox_launch_process() 28 * PURPOSE 29 * Launches a new process and attaches the sandbox to it when it stops. 30 * PARAMETERS 31 * p_sandbox - the sandbox handle 32 * p_func - the function to call at the start of the new process 33 * p_arg - an argument to pass to the function 34 * RETURNS 35 * -1 on failure, otherwise an id for the created process. Not necessarily a 36 * "pid", please treat is as opaque! 37 * TODO 38 * Only one call to this per sandbox object is supported at this time. 39 */ 40 int ptrace_sandbox_launch_process(struct pt_sandbox* p_sandbox, 41 void (*p_func)(void*), 42 void* p_arg); 43 44 /* ptrace_sandbox_run_processes() 45 * PURPOSE 46 * Runs sandboxed children until they exit or are killed. 47 * PARAMETERS 48 * p_sandbox - the sandbox handle 49 * RETURNS 50 * 0 on normal exit or death of processes. 51 * -1 if any process breached the policy. 52 */ 53 int ptrace_sandbox_run_processes(struct pt_sandbox* p_sandbox); 54 55 /* ptrace_sandbox_kill_processes() 56 * PURPOSE 57 * Safely kills off all sandboxed processes. 58 * PARAMETERS 59 * p_sandbox - the sandbox handle 60 */ 61 void ptrace_sandbox_kill_processes(struct pt_sandbox* p_sandbox); 62 63 /* ptrace_sandbox_get_arg() 64 * PURPOSE 65 * Gets a syscall argument value for a process stopped in syscall entry. 66 * PARAMETERS 67 * p_sandbox - the sandbox handle 68 * arg - the arg number to get (zero-based) 69 * p_out - the result is written here 70 * RETURNS 71 * 0 on success; otherwise it's a failure. 72 */ 73 int ptrace_sandbox_get_arg(struct pt_sandbox* p_sandbox, 74 int arg, 75 unsigned long* p_out); 76 77 /* ptrace_sandbox_get_socketcall_arg() 78 * PURPOSE 79 * Gets a syscall argument value for a process stopped in syscall entry, where 80 * the system call is a socket-related one. On some architectures (e.g. i386, 81 * socket calls are in fact multiplexed and store the arguments in a struct 82 * in user space, hence the need for abstraction. 83 * PARAMETERS 84 * p_sandbox - the sandbox handle 85 * arg - the arg number to get (zero-based) 86 * p_out - the result is written here 87 * RETURNS 88 * 0 on success; otherwise it's a failure. 89 */ 90 int ptrace_sandbox_get_socketcall_arg(struct pt_sandbox* p_sandbox, 91 int arg, 92 unsigned long* p_out); 93 94 /* ptrace_sandbox_get_long() 95 * PURPOSE 96 * Gets a long from the address space of the process stopped in syscall entry. 97 * PARAMETERS 98 * p_sandbox - the sandbox handle 99 * ptr - the address to read the long from 100 * p_out - the result is written here 101 * RETURNS 102 * 0 on success; otherwise it's a failure. 103 */ 104 int ptrace_sandbox_get_long(struct pt_sandbox* p_sandbox, 105 unsigned long ptr, 106 unsigned long* p_out); 107 108 /* ptrace_sandbox_get_buf() 109 * PURPOSE 110 * Gets a piece of memory from the address space of the process stopped in 111 * syscall entry. 112 * PARAMETERS 113 * p_sandbox - the sandbox handle 114 * ptr - the address to read the buffer from 115 * len - the length of the buffer 116 * p_buf - the result is written here 117 * RETURNS 118 * 0 on success; otherwise it's a failure. 119 */ 120 int ptrace_sandbox_get_buf(struct pt_sandbox* p_sandbox, 121 unsigned long ptr, 122 unsigned long len, 123 void* p_buf); 124 125 /* ptrace_sandbox_attach_point() 126 * PURPOSE 127 * Used by the sandbox child code to stop and indicate it is ready to be 128 * attached to. 129 * NOTES 130 * In the event of error trying to stop, the process is forcibly killed as a 131 * security measure. 132 */ 133 void ptrace_sandbox_attach_point(void); 134 135 /* POLICY EDIT: permits exit() and exit_group() */ 136 void ptrace_sandbox_permit_exit(struct pt_sandbox* p_sandbox); 137 /* POLICY EDIT: permits read() */ 138 void ptrace_sandbox_permit_read(struct pt_sandbox* p_sandbox); 139 /* POLICY EDIT: permits write() */ 140 void ptrace_sandbox_permit_write(struct pt_sandbox* p_sandbox); 141 /* POLICY EDIT: permits sigaction() and rt_sigaction() */ 142 void ptrace_sandbox_permit_sigaction(struct pt_sandbox* p_sandbox); 143 /* POLICY EDIT: permits alarm() */ 144 void ptrace_sandbox_permit_alarm(struct pt_sandbox* p_sandbox); 145 /* POLICY EDIT: permits time() and gettimeofday() */ 146 void ptrace_sandbox_permit_query_time(struct pt_sandbox* p_sandbox); 147 /* POLICY EDIT: permits mmap2() (but not the MAP_SHARED flag) */ 148 void ptrace_sandbox_permit_mmap(struct pt_sandbox* p_sandbox); 149 /* POLICY EDIT: permits mprotect() */ 150 void ptrace_sandbox_permit_mprotect(struct pt_sandbox* p_sandbox); 151 /* POLICY EDIT: permits stat(), stat64(), lstat(), lstat64() */ 152 void ptrace_sandbox_permit_file_stats(struct pt_sandbox* p_sandbox); 153 /* POLICY EDIT: permits fstat(), fstat64() */ 154 void ptrace_sandbox_permit_fd_stats(struct pt_sandbox* p_sandbox); 155 /* POLICY EDIT: permits getcwd() */ 156 void ptrace_sandbox_permit_getcwd(struct pt_sandbox* p_sandbox); 157 /* POLICY EDIT: permits chdir() */ 158 void ptrace_sandbox_permit_chdir(struct pt_sandbox* p_sandbox); 159 /* POLICY EDIT: permits umask() */ 160 void ptrace_sandbox_permit_umask(struct pt_sandbox* p_sandbox); 161 /* POLICY EDIT: permits open(), except O_ASYNC and O_DIRECT. Only O_RDONLY 162 * allowed unless writeable is 1 163 */ 164 void ptrace_sandbox_permit_open(struct pt_sandbox* p_sandbox, int writeable); 165 /* POLICY EDIT: permits close() */ 166 void ptrace_sandbox_permit_close(struct pt_sandbox* p_sandbox); 167 /* POLICY EDIT: permits getdents(), getdents64() */ 168 void ptrace_sandbox_permit_getdents(struct pt_sandbox* p_sandbox); 169 /* POLICY EDIT: permits fcntl(), fcntl64() for file locking, safe F_SETFL flag 170 * setting (no O_ASYNC, O_DIRECT), F_SETOWN for your own pid and F_SETFD. 171 */ 172 void ptrace_sandbox_permit_fcntl(struct pt_sandbox* p_sandbox); 173 /* POLICY EDIT: permits sendfile(), sendfile64() */ 174 void ptrace_sandbox_permit_sendfile(struct pt_sandbox* p_sandbox); 175 /* POLICY EDIT: permits lseek(), llseek() */ 176 void ptrace_sandbox_permit_seek(struct pt_sandbox* p_sandbox); 177 /* POLICY EDIT: permits select(), newselect() */ 178 void ptrace_sandbox_permit_select(struct pt_sandbox* p_sandbox); 179 /* POLICY EDIT: permits unlink() */ 180 void ptrace_sandbox_permit_unlink(struct pt_sandbox* p_sandbox); 181 /* POLICY EDIT: permits mkdir() */ 182 void ptrace_sandbox_permit_mkdir(struct pt_sandbox* p_sandbox); 183 /* POLICY EDIT: permits rmdir() */ 184 void ptrace_sandbox_permit_rmdir(struct pt_sandbox* p_sandbox); 185 /* POLICY EDIT: permits rename() */ 186 void ptrace_sandbox_permit_rename(struct pt_sandbox* p_sandbox); 187 /* POLICY EDIT: permits utime(), utimes() */ 188 void ptrace_sandbox_permit_utime(struct pt_sandbox* p_sandbox); 189 /* POLICY EDIT: permits sigreturn() */ 190 void ptrace_sandbox_permit_sigreturn(struct pt_sandbox* p_sandbox); 191 /* POLICY EDIT: permits recv() */ 192 void ptrace_sandbox_permit_recv(struct pt_sandbox* p_sandbox); 193 /* POLICY EDIT: permits readlink() */ 194 void ptrace_sandbox_permit_readlink(struct pt_sandbox* p_sandbox); 195 /* POLICY EDIT: permits brk() */ 196 void ptrace_sandbox_permit_brk(struct pt_sandbox* p_sandbox); 197 /* POLICY EDIT: permits nanosleep() */ 198 void ptrace_sandbox_permit_sleep(struct pt_sandbox* p_sandbox); 199 /* POLICY EDIT: permits fchmod() */ 200 void ptrace_sandbox_permit_fchmod(struct pt_sandbox* p_sandbox); 201 /* POLICY EDIT: permits chmod() */ 202 void ptrace_sandbox_permit_chmod(struct pt_sandbox* p_sandbox); 203 /* POLICY EDIT: permits fchown(), fchown32() */ 204 void ptrace_sandbox_permit_fchown(struct pt_sandbox* p_sandbox); 205 /* POLICY EDIT: permits mremap() */ 206 void ptrace_sandbox_permit_mremap(struct pt_sandbox* p_sandbox); 207 /* POLICY EDIT: permits ftruncate(), ftruncate64() */ 208 void ptrace_sandbox_permit_ftruncate(struct pt_sandbox* p_sandbox); 209 /* POLICY EDIT: permits socket() */ 210 void ptrace_sandbox_permit_socket(struct pt_sandbox* p_sandbox); 211 /* POLICY EDIT: set validator for socket() */ 212 void ptrace_sandbox_set_socket_validator(struct pt_sandbox* p_sandbox, 213 ptrace_sandbox_validator_t val, 214 void* p_arg); 215 /* POLICY EDIT: permits bind() */ 216 void ptrace_sandbox_permit_bind(struct pt_sandbox* p_sandbox); 217 /* POLICY EDIT: set validator for bind() */ 218 void ptrace_sandbox_set_bind_validator(struct pt_sandbox* p_sandbox, 219 ptrace_sandbox_validator_t val, 220 void* p_arg); 221 /* POLICY EDIT: permits connect() */ 222 void ptrace_sandbox_permit_connect(struct pt_sandbox* p_sandbox); 223 /* POLICY EDIT: set validator for connect() */ 224 void ptrace_sandbox_set_connect_validator(struct pt_sandbox* p_sandbox, 225 ptrace_sandbox_validator_t val, 226 void* p_arg); 227 /* POLICY EDIT: permits listen() */ 228 void ptrace_sandbox_permit_listen(struct pt_sandbox* p_sandbox); 229 /* POLICY EDIT: permits accept() */ 230 void ptrace_sandbox_permit_accept(struct pt_sandbox* p_sandbox); 231 /* POLICY EDIT: permits setsockopt() */ 232 void ptrace_sandbox_permit_setsockopt(struct pt_sandbox* p_sandbox); 233 /* POLICY EDIT: set validator for setsockopt() */ 234 void ptrace_sandbox_set_setsockopt_validator(struct pt_sandbox* p_sandbox, 235 ptrace_sandbox_validator_t val, 236 void* p_arg); 237 /* POLICY EDIT: permits getsockopt() */ 238 void ptrace_sandbox_permit_getsockopt(struct pt_sandbox* p_sandbox); 239 /* POLICY EDIT: set validator for getsockopt() */ 240 void ptrace_sandbox_set_getsockopt_validator(struct pt_sandbox* p_sandbox, 241 ptrace_sandbox_validator_t val, 242 void* p_arg); 243 /* POLICY EDIT: permits shutdown() */ 244 void ptrace_sandbox_permit_shutdown(struct pt_sandbox* p_sandbox); 245 246 /* The traced process is unexpectedly dead; probably an external SIGKILL */ 247 #define PTRACE_SANDBOX_ERR_DEAD -1 248 /* An unexpected error from ptrace() */ 249 #define PTRACE_SANDBOX_ERR_PTRACE -2 250 /* An unexpected error from waitpid() */ 251 #define PTRACE_SANDBOX_ERR_WAITPID -3 252 /* An unexpected waitpid() status was returned */ 253 #define PTRACE_SANDBOX_ERR_WAIT_STATUS -4 254 /* A syscall not in the policy was attempted */ 255 #define PTRACE_SANDBOX_ERR_POLICY_SYSCALL -5 256 /* A "bad" syscall was attemped: out-of-bounds, 64-bit in a 32-bit child etc. */ 257 #define PTRACE_SANDBOX_ERR_BAD_SYSCALL -6 258 /* Bad arguments to a generally accepted syscall */ 259 #define PTRACE_SANDBOX_ERR_POLICY_ARGS -7 260 /* Abuse of our API */ 261 #define PTRACE_SANDBOX_ERR_API_ABUSE_STOPIT -8 262 263 #endif /* VSF_PTRACESANDBOX_H */ 264 265