Crate landlock

source ·
Expand description

Landlock is a security feature available since Linux 5.13. The goal is to enable to restrict ambient rights (e.g., global filesystem access) for a set of processes by creating safe security sandboxes as new security layers in addition to the existing system-wide access-controls. This kind of sandbox is expected to help mitigate the security impact of bugs, unexpected or malicious behaviors in applications. Landlock empowers any process, including unprivileged ones, to securely restrict themselves. More information about Landlock can be found in the official website.

This crate provides a safe abstraction for the Landlock system calls, along with some helpers.

Minimum Supported Rust Version (MSRV): 1.63

§Use cases

This crate is especially useful to protect users’ data by sandboxing:

  • trusted applications dealing with potentially malicious data (e.g., complex file format, network request) that could exploit security vulnerabilities;
  • sandbox managers, container runtimes or shells launching untrusted applications.

§Examples

A simple example can be found with the path_beneath_rules() helper. More complex examples can be found with the Ruleset documentation and the sandboxer example.

§Current limitations

This crate exposes the Landlock features available as of Linux 5.19 and then inherits some kernel limitations that will be addressed with future kernel releases (e.g., arbitrary mounts are always denied).

§Compatibility

Types defined in this crate are designed to enable the strictest Landlock configuration for the given kernel on which the program runs. In the default best-effort mode, Ruleset will determine compatibility with the intersection of the currently running kernel’s features and those required by the caller. This way, callers can distinguish between Landlock compatibility issues inherent to the current system (e.g., file names that don’t exist) and misconfiguration that should be fixed in the program (e.g., empty or inconsistent access rights). RulesetError identifies such kind of errors.

With set_compatibility(CompatLevel::BestEffort), users of the crate may mark Landlock features that are deemed required and other features that may be downgraded to use lower security on systems where they can’t be enforced. It is discouraged to compare the system’s provided Landlock ABI version directly, as it is difficult to track detailed ABI differences which are handled thanks to the Compatible trait.

To make it easier to migrate to a new version of this library, we use the builder pattern and designed objects to require the minimal set of method arguments. Most enum are marked as non_exhaustive to enable backward-compatible evolutions.

§Test strategy

Developers should test their sandboxed applications with a kernel that supports all requested Landlock features and check that RulesetCreated::restrict_self() returns a status matching Ok(RestrictionStatus { ruleset: RulesetStatus::FullyEnforced, no_new_privs: true, }) to make sure everything works as expected in an enforced sandbox. Alternatively, using set_compatibility(CompatLevel::HardRequirement) will immediately inform about unsupported Landlock features. These configurations should only depend on the test environment (e.g. by checking an environment variable). However, applications should only check that no error is returned (i.e. Ok(_)) and optionally log and inform users that the application is not fully sandboxed because of missing features from the running kernel.

Macros§

  • make_bitflags
    make_bitflags! provides a succint syntax for creating instances of BitFlags<T>. Instead of repeating the name of your type for each flag you want to add, try make_bitflags!(Flags::{Foo | Bar}).

Structs§

Enums§

Traits§

Functions§