{"id":19199576,"url":"https://github.com/subconsciouscompute/seccomp-pledge","last_synced_at":"2025-05-09T01:24:30.065Z","repository":{"id":65319892,"uuid":"585281030","full_name":"SubconsciousCompute/seccomp-pledge","owner":"SubconsciousCompute","description":"seccomp-BPF filtering and pledge/unveil sandboxing for Linux","archived":false,"fork":false,"pushed_at":"2023-02-22T04:19:58.000Z","size":11153,"stargazers_count":7,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T20:12:14.756Z","etag":null,"topics":["linux","pledge","rust","seccomp"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SubconsciousCompute.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":"2023-01-04T19:20:53.000Z","updated_at":"2025-03-25T19:13:36.000Z","dependencies_parsed_at":"2024-11-09T12:28:35.700Z","dependency_job_id":"263a5a27-2988-4daf-b5e0-e19e857d1716","html_url":"https://github.com/SubconsciousCompute/seccomp-pledge","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/SubconsciousCompute%2Fseccomp-pledge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SubconsciousCompute%2Fseccomp-pledge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SubconsciousCompute%2Fseccomp-pledge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SubconsciousCompute%2Fseccomp-pledge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SubconsciousCompute","download_url":"https://codeload.github.com/SubconsciousCompute/seccomp-pledge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253172551,"owners_count":21865536,"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":["linux","pledge","rust","seccomp"],"created_at":"2024-11-09T12:27:53.720Z","updated_at":"2025-05-09T01:24:30.045Z","avatar_url":"https://github.com/SubconsciousCompute.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# seccomp-pledge\r\n\r\n## Introduction\r\n\r\n`seccomp-pledge` is a systems hardening tool for Linux that marries `seccomp-bpf` to `pledge` and `unveil`.\r\n\r\nFor reference, `seccomp-bpf` is a feature in the Linux kernel that allows specifying filters for system calls spawned by processes in the form of Berkeley Packet Filter (BPF) programs. A configurable set of policies (Allow, Errno, Trap, etc.) determines the kind of filtering that will be applied to system calls intercepted by `seccomp`. This minimizes the attack surface of the kernel that is exposed to userland applications.\r\n\r\n`pledge` is a sandboxing mechanism implemented in OpenBSD that restricts the operational capabilities of processes by defining a set of promises that determine the system calls which will be made unavailable to the respective process. It has been ported to Linux as a standalone binary by Justine Tunney. Find more information about `pledge` [here](https://justine.lol/pledge).\r\n\r\n`unveil` is another OpenBSD sandboxing mechanism that is used to provide path permissions to processes. By default, a `pledge` sandbox will restrict access to the entire filesystem. It is possible to allow a process access to some path using `unveil` if required. The type of permissions granted (read-only, read-write, etc.) can also be specified. Justine Tunney's `pledge` port incorporates support for `unveil`.\r\n\r\nThis tool upholds the principle of the least privilege (PoLP) and limits processes to exactly what they are designed for, disallowng any non-essential operations as desired. It will cause core dumps if the user blocks a syscall that is fundamental to the execution of the process, which implies that the `seccomp` filters need to be constructed with care and `pledge` promises must be chosen appropriately.\r\n\r\nA detailed list of syscalls with an explanation of the parameters can be found [here](https://linuxhint.com/list_of_linux_syscalls/).\r\n\r\n## Supported platforms\r\n\r\nSince `seccomp` is Linux-specific, syscall filtering using this feature is supported only on Linux systems. Non-Linux systems will have to proceed without `seccomp-bpf` filters.\r\n\r\n## Features\r\n\r\n- Accept the process to be executed (with optional flags) as an argument\r\n- Perform optional dependency checking\r\n- Display the list of syscalls (name and arguments) spawned by the process using `lurk`\r\n- Use `seccompiler` as a high-level interface for defining `seccomp-bpf` filters\r\n- Serialize the syscall list and filter list into JSON objects using `serde` and save at current path for later reference\r\n- Install user-defined filters as BPF programs for current and child processes\r\n- Support for running in three modes: interactively, non-interactively by directly supplying all necessary arguments during execution and via a Unix IPC socket as an API layer for communication\r\n- Optionally fetch Justine Tunney's Linux port of `pledge` from upstream or use the local version to wrap around command invocations\r\n- Provide intuitive prompts to simplify the process of constructing `seccomp` filters and selecting `pledge` promises and `unveil` path permissions\r\n\r\n## Dependencies\r\n\r\n`seccomp-pledge` has the following dependencies:\r\n\r\n- [seccompiler](https://github.com/rust-vmm/seccompiler) - Provides easy-to-use Linux `seccomp-bpf` jailing\r\n- [lurk](https://github.com/JakWai01/lurk) - A pretty (simple) alternative to `strace`\r\n- [pledge](https://justine.lol/pledge) - Linux port of OpenBSD's `pledge(2)`\r\n- [serde](https://serde.rs) - Framework for (de)serializing data structures in Rust\r\n- [wget](https://www.gnu.org/software/wget/) - Retrieve files from the web using HTTP(S)\r\n- [optional-field](https://github.com/cvpartner/optional-field) - Provides a Rust type for values that can be missing/null\r\n\r\n## Installation\r\n\r\nTo run `seccomp-pledge`, ensure `cargo` is installed on your system and follow these steps:\r\n\r\n```sh\r\ngit clone https://github.com/DeviousCilantro/seccomp-pledge.git\r\ncd seccomp-pledge\r\ncargo build --release\r\n./target/release/seccomp-pledge [FLAGS] [COMMAND]\r\n```\r\n\r\n## Usage\r\nHere is a  quick overview of `seccomp-pledge`:\r\n```sh\r\nUSAGE:\r\n    \u003cpath to seccomp-pledge binary\u003e [--check | --no-check] [--local | --remote] [--api | --no-api] [COMMAND]...\r\n    \r\nARGS:\r\n    \u003ccommand\u003e... Sandbox command\r\n\r\nFLAGS:\r\n    --check\r\n        Proceed with dependency checking\r\n    --no-check\r\n        Continue without dependency checking\r\n    --local\r\n        Use the local pledge binary supplied\r\n    --remote\r\n        Fetch remote pledge binary from upstream using wget\r\n    --api\r\n        Communicate via Unix socket API\r\n    --no-api\r\n        Disable Unix socket API\r\n    -v [PERMS]:PATH\r\n        Unveil path. Defaults to read-only operations\r\n    -p  PROMISES\r\n        Specify the pledge promises to be granted to the process. Defaults to 'stdio rpath'\r\n```\r\n\r\nWhen the `-v` and `-p` flags are supplied, `seccomp-pledge` will run in non-interactive mode, assuming all the necessary arguments have been provided during execution. This skips `seccomp` filtering.\r\n\r\nWhen the `--api` flag is supplied, `seccomp-pledge` will run in API mode, creating a Unix socket at `/tmp/seccomp-pledge.sock` which can then be used for communication using, for instance,  the Linux port of OpenBSD's `netcat` available in most package manager repositories. After installing `netcat`, run the following command to use the socket: `nc -U /tmp/seccomp-pledge.sock`\r\n\r\nOtherwise, `seccomp-pledge` runs in standard interactive mode, guiding the user through the different stages of creating the `seccomp` filtering policy and defining the `pledge` sandbox.\r\n\r\n## Demonstrations\r\n\r\nThis is a series of demonstrations on the three modes of using `seccomp-pledge` for sandboxing, for instance, `ls`. The `pledge` promises supplied are `stdio`, `rpath`, and `tty` and the current directory is unveiled with the default read-only permissions. `seccomp` filtering is disabled for the non-interactive mode.\r\n\r\nNon-interactive mode:\r\n\r\n![seccomp-pledge non-interactive output](_readme/non-interactive.gif)\r\n\r\nInteractive mode:\r\n\r\n![seccomp-pledge interactive output](_readme/interactive.gif)\r\n\r\nAPI mode:\r\n\r\n![seccomp-pledge pledge-error output](_readme/api.gif)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubconsciouscompute%2Fseccomp-pledge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsubconsciouscompute%2Fseccomp-pledge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubconsciouscompute%2Fseccomp-pledge/lists"}