{"id":13683386,"url":"https://github.com/proot-me/proot-rs","last_synced_at":"2025-04-15T14:58:36.521Z","repository":{"id":45665014,"uuid":"81742782","full_name":"proot-me/proot-rs","owner":"proot-me","description":"Rust implementation of PRoot, a ptrace-based sandbox","archived":false,"fork":false,"pushed_at":"2023-01-27T14:42:33.000Z","size":512,"stargazers_count":139,"open_issues_count":12,"forks_count":20,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-15T14:58:23.195Z","etag":null,"topics":["bind","bindings","binfmt","container","hacktoberfest","linux","mount","non-root","proot","proot-rs","ptrace","rootless-containers","rust","sandbox","seccomp","userspace"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/proot-me.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-12T17:18:15.000Z","updated_at":"2025-04-04T03:24:57.000Z","dependencies_parsed_at":"2023-02-15T10:15:40.501Z","dependency_job_id":null,"html_url":"https://github.com/proot-me/proot-rs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proot-me%2Fproot-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proot-me%2Fproot-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proot-me%2Fproot-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proot-me%2Fproot-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/proot-me","download_url":"https://codeload.github.com/proot-me/proot-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249094939,"owners_count":21211836,"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":["bind","bindings","binfmt","container","hacktoberfest","linux","mount","non-root","proot","proot-rs","ptrace","rootless-containers","rust","sandbox","seccomp","userspace"],"created_at":"2024-08-02T13:02:09.332Z","updated_at":"2025-04-15T14:58:36.498Z","avatar_url":"https://github.com/proot-me.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# proot-rs\n\n**Please take the PRoot Usage Survey for 2023!** [![Survey](https://img.shields.io/badge/survey-2023-green?style=flat-square)](https://www.surveymonkey.com/r/7GVXS7W)\n\n--\n\n[![Tests](https://img.shields.io/github/actions/workflow/status/proot-me/proot-rs/tests.yml?style=flat-square)](https://github.com/proot-me/proot-rs/actions/workflows/tests.yml)\n[![Releases](https://img.shields.io/github/v/release/proot-me/proot-rs?sort=semver\u0026style=flat-square)](https://github.com/proot-me/proot-rs/releases)\n\n\n_Rust implementation of PRoot, a ptrace-based sandbox._\n\n`proot-rs` works by intercepting all Linux system calls that use paths (`execve`, `mkdir`, `ls`, ...)\nand translating these with the specified path bindings, in order to simulate `chroot`,\nand all this without requiring admin rights (`ptrace` do not require any special rights).\n\nSo for instance, this command:\n\n```\nproot-rs -R /home/user/ mkdir /myfolder\n```\n\n(`-R` defines a new root and adds usual bindings like `/bin`)\n\nwill be equivalent to:\n\n```\nmkdir /home/user/myfolder/\n```\n\nHence, you can apply `proot-rs` to a whole program in order to sandbox it.\nMore concretely, you can for instance download a docker image, extract it,\nand run it, without needing docker:\n\n```\nproot-rs -R ./my-docker-image /bin/sh\n```\n\n## Usage\n\n```\nproot-rs 0.1.0\nchroot, mount --bind, and binfmt_misc without privilege/setup.\n\nUSAGE:\n    proot-rs [OPTIONS] [--] [command]...\n\nFLAGS:\n    -h, --help       Prints help information\n    -V, --version    Prints version information\n\nOPTIONS:\n    -b, --bind \u003cbind\u003e...     Make the content of *host_path* accessible in the guest rootfs. Format:\n                             host_path:guest_path\n    -w, --cwd \u003ccwd\u003e          Set the initial working directory to *path*. [default: /]\n    -r, --rootfs \u003crootfs\u003e    Use *path* as the new guest root file-system. [default: /]\n\nARGS:\n    \u003ccommand\u003e...  \n```\n\n## Requirements\n\n### Cargo\n\nWe use _rustup/cargo_ to develop proot-rs, which is a common approach in Rust development. You can install them as shown [here](https://www.rust-lang.org/tools/install).\n\n### cargo-make\n\nWe also use [`cargo-make`](https://github.com/sagiegurari/cargo-make) as build tool, which can help you launch complex compilation steps. It works a bit like `make`, and you can install it like this:\n\n\u003e Note: We recommend using the stable toolchain to install `cargo-make` in order to avoid installation failures\n\n```shell\n# Install stable rust toolchain\nrustup toolchain install stable\n# Install cargo-make\ncargo +stable install --force cargo-make\n```\n\n## Build\n\nThe recommended way is to use `cargo-make`:\n\n```shell\ncargo make build\n```\nThe command basically consists of the following steps:\n- Run `cargo build` on `loader-shim` package to compile the loader executable.\n- Copy the loader executable `loader-shim` to `proot-rs/src/kernel/execve/loader-shim`\n- Run `cargo build` on `proot-rs` package to  build the final executable.\n\nIf the compilation is successful, it should also print out the path to the `proot-rs` executable file.\n\n### Build Release Version\n\nTo generate the release binary (it takes longer, but the binary generated is quicker), you can specify `--profile=production`:\n\n```shell\ncargo make build --profile=production\n```\n\n\u003e Note: This [`--profile` option](https://github.com/sagiegurari/cargo-make#usage-profiles) comes from `cargo-make`, which has a different meaning than [the `profile` in cargo](https://doc.rust-lang.org/cargo/reference/profiles.html). And it is processed by `cargo-make` and will not be passed to `cargo`. \n\n### Cross Compilation\n\nCurrently `proot-rs` supports multiple platforms. You can change the compilation target by setting the environment variable `CARGO_BUILD_TARGET`.\n\n#### With [`cross`](https://github.com/rust-embedded/cross) (Recommended)\n\nThe `cross` is a “zero setup” cross compilation and “cross testing” tool, which uses docker to provide an out-of-the-box cross-compilation environment which contains a ready-to-use cross-compilation toolchain. So we don't need to prepare it ourselves.\n\n\u003e Note that `cross` depends on docker, so you need to install docker and start it.\n\n- To use cross, you may need to install it first:\n\n    ```shell\n    cargo install cross\n    ```\n\n- Run with `USE_CROSS=true`\n\n  Our `Makefile.toml` script contains the integration with `cross`.\n\n  For example, to compile to the `arm-linux-androideabi` target, you can simply run:\n  ```shell\n  USE_CROSS=true CARGO_BUILD_TARGET=arm-linux-androideabi cargo make build\n  ```\n  \u003e The `USE_CROSS=true` will indicate the build script to use the `cross` tool to compile.\n\n#### With `cargo` (Native Approach)\n\nYou can also use the rust native approach to cross-compile proot-rs.\n\nFor example, to compile to the `arm-linux-androideabi` target\n- Install this target first:\n  ```shell\n  rustup target add arm-linux-androideabi\n  ```\n- Cross compile with `cargo`\n  ```shell\n  CARGO_BUILD_TARGET=arm-linux-androideabi cargo make build\n  ```\n  \u003e Note: This command may fail for compiling to some targets because the linker reports some error. In this case, You may need to install an additional gcc/clang toolchain on your computer, and specify the appropriate linker path in the `.cargo/config.toml` file\n\n\u003c!-- TODO: Try to compile and test multiple targets in CI, and crate a table here. --\u003e\n\n## Run\n\nBuild and run `proot-rs`:\n\n```shell\ncargo make run -- \"\u003cargs-of-proot-rs\u003e\"\n```\n\nBuild and run release version of `proot-rs`:\n\n```shell\ncargo make run --profile=production -- \"\u003cargs-of-proot-rs\u003e\"\n```\n\n## Tests\n\n### Setup new rootfs for testing\n\nTypically, we need to specify a new rootfs path for testing proot-rs.\n\nThis script provided below can be used to create one:\n\n```shell\n# This will create a busybox-based temporary rootfs at ./rootfs/\nbash scripts/mkrootfs.sh\n```\n### Unit testing\n\nStart running unit tests:\n\n```shell\nexport PROOT_TEST_ROOTFS=\"`realpath ./rootfs/`\"\ncargo test --package=proot-rs -- --test-threads=1\n```\n\n\u003e Note:\n\u003e - Since our testing will spawn multiple processes, we need `--test-threads=1` to avoid deadlock caused by `fork()`. The option `--nocapture` may also be needed to show the original panic reason printed out by the child process.\n\u003e - Add the option `--profile=production` if you want to test a release build of proot-rs\n\n### Integration testing\n\nFor the section on running integration tests, please read the [Integration Testing documentation](./tests/README.md)\n\n## Contributing\n\nWe use git hooks to check files staged for commit to ensure the consistency of Rust code style.\n\nBefore you start, please run the following command to setup git hooks:\n\n```shell\ngit config core.hooksPath .githooks\n```\n\nTo format code manually:\n\n```shell\ncargo fmt\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproot-me%2Fproot-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproot-me%2Fproot-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproot-me%2Fproot-rs/lists"}