{"id":15715417,"url":"https://github.com/cloudflare/sandbox","last_synced_at":"2025-04-09T05:11:06.010Z","repository":{"id":53821230,"uuid":"269329704","full_name":"cloudflare/sandbox","owner":"cloudflare","description":"Simple Linux seccomp rules without writing any code","archived":false,"fork":false,"pushed_at":"2024-09-26T15:07:47.000Z","size":28,"stargazers_count":474,"open_issues_count":11,"forks_count":27,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-02T04:04:07.968Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-04T10:29:41.000Z","updated_at":"2025-03-29T15:41:24.000Z","dependencies_parsed_at":"2024-12-08T01:04:51.830Z","dependency_job_id":"eb10b7c4-7517-4b86-916b-18fb65f6d276","html_url":"https://github.com/cloudflare/sandbox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fsandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fsandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fsandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fsandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/sandbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980837,"owners_count":21027808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T21:41:30.726Z","updated_at":"2025-04-09T05:11:05.994Z","avatar_url":"https://github.com/cloudflare.png","language":"C","funding_links":[],"categories":["Security \u0026 Privacy"],"sub_categories":["Security Tools"],"readme":"# sandbox\n\n## Linux seccomp made easy\n\nThis package provides a simple way to enable basic `seccomp` [system call filtering][1] in any application (even proprietary one) via environment variables. It is very similar to `SystemCallFilter=` [functionality in systemd][2], but with some advantages:\n\n  * it doesn't have some of `systemd` limitations:\n    \u003e the execve, exit, exit_group, getrlimit, rt_sigreturn, sigreturn system calls and the system calls for querying time and sleeping are implicitly whitelisted...\n  * it can provide tighter filtering for dynamically linked binaries\n\n### Building\n\nThe build system expects a recent version of [libseccomp][5] to be available as a static library. It is recommended to build it from upstream source rather than rely on the version from a particular distribution.\n\nThe `Makefile` will look for a valid [libseccomp][5] tree and the build in the `libseccomp` directory, so the easiest way to satisfy the dependency is to do the following in the project directory:\n\n```bash\nuser@dev:~/sandbox$ curl -L -O https://github.com/seccomp/libseccomp/releases/download/v2.4.3/libseccomp-2.4.3.tar.gz\nuser@dev:~/sandbox$ tar xf libseccomp-2.4.3.tar.gz \u0026\u0026 mv libseccomp-2.4.3 libseccomp\nuser@dev:~/sandbox$ cd libseccomp \u0026\u0026 ./configure --enable-shared=no \u0026\u0026 make\n```\n\nThen build `sandbox` with `make` from the project directory:\n\n```bash\nuser@dev:~/sandbox$ make\ncc -c -fPIC -Ilibseccomp/include -o sandbox.o sandbox.c\ncc -c -fPIC -Ilibseccomp/include -o preload.o preload.c\ncc -shared -Wl,--version-script=libsandbox.version -o libsandbox.so sandbox.o preload.o libseccomp/src/.libs/libseccomp.a\ncc -c -fPIC -Ilibseccomp/include -o sandboxify.o sandboxify.c\ncc -o sandboxify sandboxify.o sandbox.o libseccomp/src/.libs/libseccomp.a\n```\n\n### Usage\n\nThe package provides a dynamically linked library `libsandbox.so` for dynamically linked executables and a command line utility `sandboxify` for statically linked executables. The system call filter can be defined with the following environment variables:\n\n  * if `SECCOMP_SYSCALL_ALLOW` is defined, all system calls listed in the list will be allowed; if the process will attempt to call any system call not from the list, it will be killed by the operating system\n    * example: `SECCOMP_SYSCALL_ALLOW=\"open:write\"`\n  * otherwise, if `SECCOMP_SYSCALL_DENY` is defined, all system calls listed in the list attempted to be used by the process, will cause the process to be killed; all other system calls are allowed\n    * example: `SECCOMP_SYSCALL_DENY=\"execve:mprotect\"`\n\n#### Dynamically linked executables\n\nFor dynamically linked executables the sandboxing code is injected using the `LD_PRELOAD` [dynamic linker option][3].\n\nNo sandboxing:\n\n```bash\n$ ./helloworld\nHello, world!\n```\n\nWith sandboxing:\n\n```bash\n$ LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libsandbox.so SECCOMP_SYSCALL_ALLOW=\"fstat:write:exit_group\" ./helloworld\nadding fstat to the process seccomp filter\nadding write to the process seccomp filter\nadding exit_group to the process seccomp filter\nHello, world!\n```\n\nIf the process uses a system call, which was not explicitly listed:\n\n```bash\n$ LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libsandbox.so SECCOMP_SYSCALL_ALLOW=\"fstat:exit_group\" ./helloworld\nadding fstat to the process seccomp filter\nadding exit_group to the process seccomp filter\nBad system call\n```\n\nand a audit event is generated:\n\n```\n[Mon Apr  6 11:27:30 2020] audit: type=1326 audit(1586168850.755:5): auid=1000 uid=1000 gid=1000 ses=2 subj=kernel pid=3148 comm=\"helloworld\" exe=\"/home/ignat/git/sandbox/helloworld\" sig=31 arch=c000003e syscall=1 compat=0 ip=0x7f6c3650e504 code=0x80000000\n```\n\n##### Make it permanent\n\nIt is possible to permanently link the executable to `libsandbox.so` without recompiling the code and avoid defining `LD_PRELOAD` environment variable. For example:\n\nBefore:\n\n```bash\n$ ldd ./helloworld\n\tlinux-vdso.so.1 (0x00007ffd2018e000)\n\tlibc.so.6 =\u003e /lib/x86_64-linux-gnu/libc.so.6 (0x00007f8392ee9000)\n\t/lib64/ld-linux-x86-64.so.2 (0x00007f83930bd000)\n```\n\nAdding `libsandbox.so` as a runtime dependency:\n\n```bash\n$ patchelf --add-needed /usr/lib/x86_64-linux-gnu/libsandbox.so ./helloworld\n$ ldd ./helloworld\n\tlinux-vdso.so.1 (0x00007fffb74cf000)\n\t/usr/lib/x86_64-linux-gnu/libsandbox.so (0x00007f3706499000)\n\tlibc.so.6 =\u003e /lib/x86_64-linux-gnu/libc.so.6 (0x00007f37062cc000)\n\t/lib64/ld-linux-x86-64.so.2 (0x00007f37064ee000)\n$ SECCOMP_SYSCALL_ALLOW=\"fstat:write:exit_group\" ./helloworld\nadding fstat to the process seccomp filter\nadding write to the process seccomp filter\nadding exit_group to the process seccomp filter\nHello, world!\n```\n\n#### Statically linked executables\n\nFor statically linked executables the sandboxing code is injected by launching the application with `sandboxify` command line utility.\n\n```bash\n$ SECCOMP_SYSCALL_ALLOW=\"brk:arch_prctl:uname:readlink:fstat:write:exit_group\" sandboxify ./helloworld\nadding brk to the process seccomp filter\nadding arch_prctl to the process seccomp filter\nadding uname to the process seccomp filter\nadding readlink to the process seccomp filter\nadding fstat to the process seccomp filter\nadding write to the process seccomp filter\nadding exit_group to the process seccomp filter\nHello, world!\n```\n\nUnder the hood `sandboxify` uses [`PTRACE_O_SUSPEND_SECCOMP` ptrace option][7], therefore requires `CAP_SYS_ADMIN` capability to operate properly. Depending on the target system [Yama LSM][8] configuration `sandboxify` might also require `CAP_SYS_PTRACE` capability.\n\n#### permissive (log) mode\n\nWhen sandboxing new applications it is usually not very clear what system calls it uses to define the proper seccomp filter, so on initial stages it is possible to configure the sandbox to log filter violations instead of immediately killing the process via `SECCOMP_DEFAULT_ACTION=log` environment variable.\n\n```bash\n$ LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libsandbox.so SECCOMP_SYSCALL_ALLOW=\"\" SECCOMP_DEFAULT_ACTION=log ./helloworld\nHello, world!\n```\n\nAbove filter does not allow any system call for the `helloworld` application, but logs the violations instead of killing the process. The violations can be monitored via `dmesg` or auditd (if running on the system):\n\n```\n[Mon Apr  6 12:04:02 2020] audit: type=1326 audit(1586171042.680:138): auid=1000 uid=1000 gid=1000 ses=2 subj=kernel pid=3284 comm=\"helloworld\" exe=\"/home/ignat/git/sandbox/helloworld\" sig=0 arch=c000003e syscall=5 compat=0 ip=0x7f21a2d42af3 code=0x7ffc0000\n[Mon Apr  6 12:04:02 2020] audit: type=1326 audit(1586171042.680:139): auid=1000 uid=1000 gid=1000 ses=2 subj=kernel pid=3284 comm=\"helloworld\" exe=\"/home/ignat/git/sandbox/helloworld\" sig=0 arch=c000003e syscall=1 compat=0 ip=0x7f21a2d43504 code=0x7ffc0000\n[Mon Apr  6 12:04:02 2020] audit: type=1326 audit(1586171042.680:140): auid=1000 uid=1000 gid=1000 ses=2 subj=kernel pid=3284 comm=\"helloworld\" exe=\"/home/ignat/git/sandbox/helloworld\" sig=0 arch=c000003e syscall=231 compat=0 ip=0x7f21a2d1f9d6 code=0x7ffc0000\n```\n\nThe example above shows `helloworld` binary tried to use system calls `5`, `1` and `231`. By searching online, for example [here][4]: it is possible to translate the numbers into system call names: `fstat`, `write` and `exit_group` respectively.\n\n#### sandboxify vs libsandbox.so\n\nWhile it is possible to use `sandboxify` utility for dynamically linked executables as well, `libsandbox.so` has the advantage of being executed later in the process startup, usually after all runtime framework initialisation has been completed. This results in a much tighter seccomp filter, as explicitly allowing system calls, which are used only during process startup, is not required.\n\nFor example, if we attempt to use `sandboxify` to secure dynamically linked `helloworld` application from above, instead of `SECCOMP_SYSCALL_ALLOW=\"fstat:write:exit_group\"` we would need `SECCOMP_SYSCALL_ALLOW=\"brk:access:openat:fstat:mmap:close:read:mprotect:munmap:arch_prctl:write:exit_group\"` to allow all the system calls the dynamic linker and the C-runtime need to setup the process.\n\n#### Check the status\n\nIt is possible to use [`/proc/[pid]/status`][6] to verify the target process has a seccomp policy applied by checking the `Seccomp` field in the output (it has to be set to `2`):\n\n```bash\n$ grep Seccomp /proc/self/status\nSeccomp:\t0\n$ LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libsandbox.so SECCOMP_SYSCALL_ALLOW=\"brk:close:exit_group:fstat:futex:mmap:openat:read:rt_sigaction:sigaltstack:stat:write\" SECCOMP_DEFAULT_ACTION=log grep Seccomp /proc/self/status\nadding brk to the process seccomp filter\nadding close to the process seccomp filter\nadding exit_group to the process seccomp filter\nadding fstat to the process seccomp filter\nadding futex to the process seccomp filter\nadding mmap to the process seccomp filter\nadding openat to the process seccomp filter\nadding read to the process seccomp filter\nadding rt_sigaction to the process seccomp filter\nadding sigaltstack to the process seccomp filter\nadding stat to the process seccomp filter\nadding write to the process seccomp filter\nSeccomp:\t2\n```\n\nUnfortunately, the field only indicates that some policy was applied, but provides no further details.\n\n### Currently not supported\n\n  * filters based on specific system call arguments\n  * custom return error codes\n\n[1]: http://man7.org/linux/man-pages/man2/seccomp.2.html\n[2]: https://www.freedesktop.org/software/systemd/man/systemd.exec.html#SystemCallFilter=\n[3]: http://man7.org/linux/man-pages/man8/ld.so.8.html\n[4]: https://filippo.io/linux-syscall-table/\n[5]: https://github.com/seccomp/libseccomp\n[6]: https://man7.org/linux/man-pages/man5/proc.5.html\n[7]: https://man7.org/linux/man-pages/man2/ptrace.2.html\n[8]: https://www.kernel.org/doc/html/latest/admin-guide/LSM/Yama.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fsandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fsandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fsandbox/lists"}