playground

Sandbox, container or whatever utilities for linux.
git clone https://pi.duncano.de/git/playground.git

README (2660B)


      1 playground
      2 ==========
      3 
      4 Sandbox, container or (whatever you want to call it) utilities for linux.
      5 
      6 There is still a lot to do, `pledge` should already work, but it might be
      7 renamed later to be not confused with a similar api for a different OS.
      8 At the moment `newns` is just an idea with some very basic code that does
      9 not even compile and some docs on how or what it should do.
     10 
     11 Usage
     12 -----
     13 
     14 To just restrict the allowed systemcalls:
     15 
     16 	$ pledge -p "proc rpath" sh
     17 
     18 To create a new "container" (unshare all possible namespaces) and share the
     19 base filesystem (/{bin,sbin,lib,var,usr,etc}) with it:
     20 
     21 	$ newns -f "base container" sh
     22 
     23 Or both together:
     24 
     25 	$ newns -f "base container" pledge -p "proc rpath" sh
     26 
     27 
     28 Install
     29 -------
     30 
     31 	$ make
     32 	# make install
     33 
     34 
     35 libpledge
     36 ---------
     37 
     38 The main API is the `pledge(2)` function, the other functions are just a bonus
     39 that might be useful but aren't in most cases, its suggested to only use this
     40 function.
     41 
     42 `pledge(2)` makes use of seccomp layering, the first `pledge(2)` call creates
     43 a whitelist with allowed systemcalls and if necessary a second layer with
     44 filters that look at arguments of systemcalls. Subsequent `pledge(2)` calls
     45 blacklist systemcalls that are not part of the new promises and adds the
     46 filter layer if necessary. The BPF filters are as small as possible and
     47 never blacklist systemcalls twice and never blacklists systemcalls that
     48 were not initially whitelisted.
     49 
     50 There are some differences to the OpenBSD `pledge(2)` systemcall.
     51 The OpenBSD implementation drops filters if `execve(2)` is called,
     52 this is not possible at this time with `seccomp(2)`.
     53 Furthermore in OpenBSDs implementation it is possible to use systemcalls
     54 that operate in specific paths like `/tmp` without priviously promising it.
     55 The `paths` argument for `pledge(2)` from OpenBSDs pledge is deprecated
     56 and `pledge(2)` returns `EINVAL` if its not `NULL` this API does the same.
     57 
     58 
     59 `int pledge(const char *, const char *[]);`
     60 
     61 	Restrict systemcalls based on the supplied `promises` string.
     62 	Subsequent calls reduce the systemcalls further.
     63 
     64 
     65 `uint64_t pledge_flags(const char *);`
     66 
     67 	Converts a list of space separated `promises` to flags.
     68 
     69 
     70 `struct sock_fprog *pledge_whitelist(uint64_t flags);`
     71 
     72 	Creates a `seccomp(2)` `BPF(2)` filter program that whitelists systemcalls.
     73 
     74 
     75 `struct sock_fprog *pledge_blacklist(uint64_t flags, uint64_t oldflags);`
     76 
     77 	Creates a `seccomp(2)` `BPF(2)` filter program to blacklists previously
     78 	whitelisted systemcalls.
     79 
     80 
     81 `struct sock_fprog *pledge_filter(uint64_t flags, uint64_t oldflags);`
     82 
     83 	Creates a `seccomp` `BPF(2)` filter program that filters previously
     84 	whitelisted systemcalls based on its arguments.