{"id":13599200,"url":"https://github.com/bytecodealliance/cap-std","last_synced_at":"2025-05-13T20:14:59.283Z","repository":{"id":37192017,"uuid":"275013363","full_name":"bytecodealliance/cap-std","owner":"bytecodealliance","description":"Capability-oriented version of the Rust standard library","archived":false,"fork":false,"pushed_at":"2025-04-21T21:30:08.000Z","size":2571,"stargazers_count":681,"open_issues_count":18,"forks_count":37,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-05-08T00:04:10.693Z","etag":null,"topics":["rust","sandboxing","security"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bytecodealliance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-06-25T20:55:02.000Z","updated_at":"2025-05-02T00:28:39.000Z","dependencies_parsed_at":"2023-02-18T11:48:14.748Z","dependency_job_id":"c78ab2eb-14ec-4722-80c4-3520320a889a","html_url":"https://github.com/bytecodealliance/cap-std","commit_stats":{"total_commits":1357,"total_committers":13,"mean_commits":"104.38461538461539","dds":"0.17612380250552695","last_synced_commit":"79ae7ce65e2f45f7a1156737995b293ed99ced15"},"previous_names":[],"tags_count":701,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fcap-std","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fcap-std/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fcap-std/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fcap-std/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytecodealliance","download_url":"https://codeload.github.com/bytecodealliance/cap-std/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254020638,"owners_count":22000755,"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":["rust","sandboxing","security"],"created_at":"2024-08-01T17:01:00.783Z","updated_at":"2025-05-13T20:14:59.263Z","avatar_url":"https://github.com/bytecodealliance.png","language":"Rust","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e\u003ccode\u003ecap-std\u003c/code\u003e\u003c/h1\u003e\n\n  \u003cp\u003e\n    \u003cstrong\u003eCapability-based version of the Rust standard library\u003c/strong\u003e\n  \u003c/p\u003e\n\n  \u003cstrong\u003eA \u003ca href=\"https://bytecodealliance.org/\"\u003eBytecode Alliance\u003c/a\u003e project\u003c/strong\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/bytecodealliance/cap-std/actions?query=workflow%3ACI\"\u003e\u003cimg src=\"https://github.com/bytecodealliance/cap-std/workflows/CI/badge.svg\" alt=\"Github Actions CI Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://bytecodealliance.zulipchat.com/#narrow/stream/217126-wasmtime\"\u003e\u003cimg src=\"https://img.shields.io/badge/zulip-join_chat-brightgreen.svg\" alt=\"zulip chat\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nThe `cap-std` project is organized around the eponymous [`cap-std`] crate, and\ndevelops libraries to make it easy to write capability-based code, including:\n\n - [`cap-std`] itself, which provides capability-based versions of `std` APIs\n - [`cap-async-std`], which is to [`async-std`] what `cap-std` is to `std`\n - [`cap-directories`] which provides capability-based access to\n   [standard application directories]\n - [`cap-tempfile`], which provides capability-based access to\n   [temporary directories]\n - [`cap-fs-ext`], which provides additional filesystem features beyond\n   what's available in `std`\n - [`cap-time-ext`], which provides additional time features beyond\n   what's available in `std`\n - [`cap-rand`], which provides capability-based access to\n   [random number generators]\n - [`cap-net-ext`], which provides additional network features beyond\n   what's available in `std`\n\nThere is also a [`cap-std-ext`](https://crates.io/crates/cap-std-ext) crate available\nwhich is maintained independently, and includes further extension APIs for\nboth filesystem APIs (including atomic create/replace on Linux specifically)\nand passing file descriptors to child processes.\n\nCap-std features protection against [CWE-22], \"Improper Limitation of a\nPathname to a Restricted Directory ('Path Traversal')\", which is #8 in the\n[2021 CWE Top 25 Most Dangerous Software Weaknesses]. It can also be used to\nprevent untrusted input from inducing programs to open \"/proc/self/mem\" on\nLinux.\n\n[CWE-22]: https://cwe.mitre.org/data/definitions/22.html\n[2021 CWE Top 25 Most Dangerous Software Weaknesses]: https://cwe.mitre.org/top25/archive/2021/2021_cwe_top25.html\n[`cap-std`]: https://github.com/bytecodealliance/cap-std/blob/main/cap-std/README.md\n[`cap-async-std`]: https://github.com/bytecodealliance/cap-std/blob/main/cap-async-std/README.md\n[`cap-directories`]: https://github.com/bytecodealliance/cap-std/blob/main/cap-directories/README.md\n[`cap-tempfile`]: https://github.com/bytecodealliance/cap-std/blob/main/cap-tempfile/README.md\n[`cap-fs-ext`]: https://github.com/bytecodealliance/cap-std/blob/main/cap-fs-ext/README.md\n[`cap-time-ext`]: https://github.com/bytecodealliance/cap-std/blob/main/cap-time-ext/README.md\n[`cap-rand`]: https://github.com/bytecodealliance/cap-std/blob/main/cap-rand/README.md\n[`cap-net-ext`]: https://github.com/bytecodealliance/cap-std/blob/main/cap-net-ext/README.md\n[`cap_std::fs`]: https://docs.rs/cap-std/latest/cap_std/fs/index.html\n[`async-std`]: https://docs.rs/async-std/\n[standard application directories]: https://docs.rs/directories-next/\n[temporary directories]: https://docs.rs/tempfile/\n[random number generators]: https://docs.rs/rand/\n\n## Capability-based security\n\nOperating systems have a concept of resource handles, or file descriptors, which\nare values that can be passed around within and sometimes between programs, and\nwhich represent access to external resources. Programs typically have the\n*ambient authority* to request any file or network handle simply by providing\nits name or address:\n\n```rust\nlet file = File::open(\"/anything/you/want.txt\")?;\n```\n\nThere may be access-control lists, namespaces, firewalls, or virtualization\nmechanisms governing which resources can actually be accessed, but those are\ntypically coarse-grained and configured outside of the application.\n\nCapability-based security seeks to avoid ambient authority, to make sandboxing\nfiner-grained and composable. To open a file, one needs a [`Dir`], representing\nan open directory it's in:\n\n```rust\nlet file = dir.open(\"the/thing.txt\")?;\n```\n\nAttempts to access paths not contained within the directory:\n\n```rust\nlet hidden = dir.open(\"../hidden.txt\")?;\n\ndir.symlink(\"/hidden.txt\", \"misdirection.txt\")?;\nlet secret = dir.open(\"misdirection.txt\")?;\n```\n\nreturn `PermissionDenied` errors.\n\nThis allows application logic to configure its own access, without changing the\nbehavior of the whole host process, setting up a separate host process, or\nrequiring external configuration.\n\n[`Dir`]: https://docs.rs/cap-std/latest/cap_std/fs/struct.Dir.html\n\n## How do I obtain a [`Dir`]?\n\nIf every resource requires some other resource to obtain, how does one obtain\nthe first resource?\n\nThere currently are three main ways:\n - Use the [`cap-directories`] crate to create `Dir`s for config, cache and\n   other data directories.\n - Use the [`cap-tempfile`] crate to create `Dir`s for temporary directories.\n - Use [`Dir::open_ambient_dir`] to open a plain path. This function is not\n   sandboxed, and may open any file the host process has access to.\n\n## Examples\n\nThere are several examples of cap-std in use:\n\n - As a sandbox: For a simple yet complete example of cap-std in action, see\n   [this port of tide], to use cap-std to access static files, where it\n   prevents path resolution from following symlinks outside of the designated\n   root directory. [The diff] shows the kinds of changes needed to use this\n   API.\n\n - As a general-purpose `Dir` type for working with directories: The io-streams\n   crate [uses `cap-tempdir`] to create temporary directories for unit tests.\n   Here, the main benefit of `Dir` is just convenience—`Dir`'s API lets tests\n   just say `dir.open(...)` instead of using `open(path.join(...))` or dealing\n   with `chdir` and global mutable state. The fact that it also sandboxes the\n   unit tests is just a nice side effect.\n\n - As an application data store: See the [`kv-cli` example] for a simple example\n   of a program using `cap-directories` and `cap-std` APIs to store\n   application-specific data.\n\n - And, cap-std is a foundation for the [`WASI`] implementation in [`Wasmtime`],\n   providing sandboxing and support for Linux, macOS, Windows, and more.\n\n[uses `cap-tempdir`]: https://github.com/sunfishcode/io-streams/blob/main/tests/tests.rs#L16\n[this port of tide]: https://github.com/sunfishcode/tide/\n[The diff]: https://github.com/sunfishcode/tide/commit/9b4c5449c6b3d1f0c78d8f6f44669905be5a7c78\n[`Dir::open_ambient_dir`]: https://docs.rs/cap-std/latest/cap_std/fs/struct.Dir.html#method.open_ambient_dir\n[`kv-cli` example]: https://github.com/bytecodealliance/cap-std/blob/main/examples/kv-cli.rs\n[`WASI`]: https://github.com/WebAssembly/WASI/\n[`Wasmtime`]: https://wasmtime.dev/\n\n## What can I use `cap-std` for?\n\n`cap-std` is not a sandbox for untrusted Rust code. Among other things,\nuntrusted Rust code could use `unsafe` or the unsandboxed APIs in `std::fs`.\n\n`cap-std` allows code to declare its intent and to opt in to protection from\nmalicious path names. Code which takes a [`Dir`] from which to open files,\nrather than taking bare filenames, declares its intent to only open files\nunderneath that `Dir`. And, `Dir` automatically protects against paths which\nmight include `..`, symlinks, or absolute paths that might lead outside of that\n`Dir`.\n\n`cap-std` also has another role, within WASI, because `cap-std`'s filesystem\nAPIs closely follow WASI's sandboxing APIs. In WASI, `cap-std` becomes a very\nthin layer, thinner than `libstd`'s filesystem APIs because it doesn't need\nextra code to handle absolute paths.\n\n## How fast is it?\n\nOn Linux 5.6 and newer, `cap-std` uses [`openat2`] to implement `Dir::open`\nwith a single system call in common cases. Several other operations internally\nutilize [`openat2`], [`O_PATH`], and [`/proc/self/fd`] (though only when /proc\nis mounted, it's really `procfs`, and there are no mounts on top of it) for\nfast path resolution as well.\n\nOn FreeBSD 13.0 and newer, `cap-std` uses [`openat(O_RESOLVE_BENEATH)`] to\nimplement `Dir::open` with a single system call in common cases.\nSeveral other operations internally utilize `AT_RESOLVE_BENEATH` and `O_PATH` for\nfast path resolution as well.\n\nOtherwise, `cap-std` opens each component of a path individually, in order to\nspecially handle `..` and symlinks. The algorithm is carefully designed to\nminimize system calls, so opening `red/green/blue` performs just 5 system\ncalls—it opens `red`, `green`, and then `blue`, and closes the handles for `red`\nand `green`.\n\n[`openat2`]: https://lwn.net/Articles/796868/\n[`O_PATH`]: https://man7.org/linux/man-pages/man2/open.2.html\n[`/proc/self/fd`]: https://man7.org/linux/man-pages/man5/proc.5.html\n[`openat(O_RESOLVE_BENEATH)`]: https://man.freebsd.org/cgi/man.cgi?openat\n\n## What about networking?\n\ncap-std also contains a simple capability-based version of `std::net`, with a\n[`Pool`] type that represents a pool of network addresses and ports that can be\naccessed, which serves an analogous role to [`Dir`]. It's usable for basic use\ncases, though it's not yet very sophisticated.\n\n[`Pool`]: https://docs.rs/cap-std/latest/cap_std/net/struct.Pool.html\n\n## What is `cap_std::fs_utf8`?\n\nIt's similar to `cap_std::fs`, but uses [`camino`] for its `Path` types, so\npaths are always valid UTF-8. To use it, opt in by enabling the `fs_utf8`\nfeature and using `std::fs_utf8` in place of `std::fs`.\n\nThere's also an experimental extension to `fs_utf8` which allows losslessly\nencoding arbitrary host byte sequences within UTF-8 strings, using the\n[`arf-strings`] technique. To try this experiment, opt in by enabling the\n`arf_strings` feature.\n\n## Similar crates\n\n`cap-std` provides similar functionality to the [`openat`] crate, with a similar\n`Dir` type with associated functions corresponding to `*at` functions.\n`cap-std`'s `Dir` type performs sandboxing, including for multiple-component\npaths. And `cap-std` supports symlinks as long as they remain within the\nsandbox, while `openat` doesn't support following symlinks.\n\n`cap-std` has some similar functionality to [`pathrs`] in that it also\nexplicitly verifies that `/proc` has actual `procfs` mounted on it and nothing\nmounted on top, and it can also use `openat2`. And it has some similar\nfunctionality to [`unix_fd`]. However, `cap-std` uses `RESOLVE_BENEATH`-style\nresolution where absolute paths are considered errors, while `pathrs` and\n`unix_fd` use `RESOLVE_IN_ROOT`-style resolution, where absolute paths are\ninterpreted as references to the base file descriptor. And overall, `cap-std`\nseeks to provide a portable `std`-like API which supports Windows in addition\nto Unix-like platforms, while `pathrs` provides a lower-level API that exposes\nmore of the underlying `openat2` options and only supports Linux, and `unix_fd`\nis specific to Unix-like platforms.\n\n[`obnth`] is a new crate which appears to be very similar to `cap_std::fs`.\nIt's not mature yet, and it doesn't support Windows. It does support\n`openat2`-like features such as `RESOLVE_NO_XDEV`, `RESOLVE_NO_SYMLINKS`,\nand `RESOLVE_IN_ROOT`, including emulation when `openat2` isn't available.\n\n### Why use `RESOLVE_BENEATH`?\n\nCapability-based security is all about *granularity*. We want to encourage\napplications and users to think about having separate handles for directories\nthey need, so that they're isolated from each other, rather than in terms of\nhaving \"root directories\" containing multiple unrelated resources.\n\nAlso, some applications have \"well known\" absolute path strings present, such\nas \"/etc/resolv.conf\", and could accidentally use them within `Dir` methods.\n`RESOLVE_BENEATH` catches such errors early, rather than taking chances with\nuser content inside the `Dir`.\n\nAnd, `RESOLVE_BENEATH` handles symlinks within a `Dir` consistently. Accessing\na symlink to an absolute path within a `Dir` is always an error. With\n`RESOLVE_IN_ROOT`, a symlink to an absolute path in a `Dir` may succeed, and\npotentially resolve to something different than it would when resolved through\nthe process filesystem namespace.\n\n## Minimum Supported Rust Version (MSRV)\n\nThis crate currently works on Rust 1.63, when default features are enabled.\nSome of the optional features have stricter requirements.\n\n[`arf-strings`]: https://github.com/bytecodealliance/arf-strings/\n[`openat`]: https://crates.io/crates/openat\n[`pathrs`]: https://crates.io/crates/pathrs\n[`obnth`]: https://crates.io/crates/obnth\n[`camino`]: https://crates.io/crates/camino\n[`unix_fd`]: https://crates.io/crates/unix_fd\n","funding_links":[],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytecodealliance%2Fcap-std","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytecodealliance%2Fcap-std","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytecodealliance%2Fcap-std/lists"}