From a3461fbbac897b45ccd418862caa9a9cb5d12180 Mon Sep 17 00:00:00 2001 From: Harry Stern Date: Tue, 16 Apr 2024 00:32:47 -0400 Subject: [PATCH] Minor docs update - Add overview section to user guide - Add an extra link to the user guide at the top of the readme - Enable all features in docs - Update CHANGELOG as well --- CHANGELOG.md | 2 ++ Cargo.toml | 3 +++ README.md | 1 + user-guide.md | 18 +++++++++++++++++- 4 files changed, 23 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cd812a3..66d6f33 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ unreleased ---------- +- Minor docs/user guide update +- Use unix datagram sockets instead of stream in ipc server example and run in CI 0.5.0 ----- diff --git a/Cargo.toml b/Cargo.toml index cfd349b..9f27579 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -9,6 +9,9 @@ license = "MIT" keywords = ["security", "seccomp", "landlock", "syscall"] categories = ["os::linux-apis"] +[package.metadata.docs.rs] +all-features = true + [features] landlock = ["dep:landlock"] isolate = [] diff --git a/README.md b/README.md index f56f852..70b51cc 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ fn main() { eprintln!("and so does stderr!"); } ``` +[**user guide**](https://github.com/boustrophedon/extrasafe/blob/master/user-guide.md) You've used safe and unsafe Rust: now your code can be extrasafe. diff --git a/user-guide.md b/user-guide.md index a0eb136..775f9eb 100644 --- a/user-guide.md +++ b/user-guide.md @@ -1,4 +1,20 @@ -# How to use extrasafe +# extrasafe user guide + +## Overview + +extrasafe currently consists of two main components: [`SafetyContext`](https://docs.rs/extrasafe/latest/extrasafe/struct.SafetyContext.html) and [`Isolate`](https://docs.rs/extrasafe/latest/extrasafe/isolate/struct.Isolate.html) + +`SafetyContext` is used to create [seccomp](https://www.kernel.org/doc/html/v4.19/userspace-api/seccomp_filter.html) and [Landlock](https://landlock.io/) filters, while `Isolate` is used to launch and configure [unprivileged user namespaces](https://man7.org/linux/man-pages/man7/namespaces.7.html) + +`seccomp` is a Linux kernel facility that allows you to voluntarily prohibit your code from calling specified syscalls, but is somewhat course-grained and cannot effectively filter syscalls with complicated arguments. `Landlock` allows for more fine-grained access control over filesystem (and recently network, although this is not available in extrasafe currently) operations. + +Linux `namespaces` operate at a higher level of abstraction than seccomp or landlock, and change how entire Linux subsystems operate. They are the core feature that powers container runtimes, and allow your program to have root-like control over isolated filesystems, networks, process spaces, and users. extrasafe Isolates use namespaces to make your program run in an environment where it doesn't have access to the rest of your regular filesystem, network (optionally), and process tree. Isolates are suitable for running subprocesses and using libraries that may be more likely to have vulnerabilities, like image and video processing code, although that doesn't make them perfectly secure - user namespaces have had vulnerabilities in the past. + +Once applied, all of these security features are enabled permanently for the lifetime of the thread, and all new threads and subprocesses created after they are enabled. Additionally, seccomp allows you to apply its filters to **all** threads at once, even ones that are already running. + +Together, all of these security features allow developers to secure their programs from the inside (as opposed to externally via things like [AppArmor](https://apparmor.net/) and [selinux](https://www.redhat.com/en/topics/linux/what-is-selinux)) and hedge against undiscovered vulnerabilities lurking in your or others' code. + +## Basic `SafetyContext` usage See [the corresponding example in the source code](https://github.com/boustrophedon/extrasafe/blob/master/examples/user-guide.rs) for an executable version of this guide's code.