Crate landlock

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

BitFlags

Represents a set of flags of some type T. T must have the #[bitflags] attribute applied.

NetPort

Landlock rule for a network port.

PathBeneath

Landlock rule for a file hierarchy.

PathFd

Simple helper to open a file or a directory with the O_PATH flag.

RestrictionStatus

Status of a RulesetCreated after calling restrict_self().

Ruleset

Landlock ruleset builder.

RulesetCreated

Ruleset created with Ruleset::create().

Enums

ABI

Version of the Landlock ABI.

AccessError

AccessFs

File system access right.

AccessNet

Network access right.

AddRuleError

Identifies errors when adding a rule to a ruleset.

AddRulesError

Identifies errors when adding rules to a ruleset thanks to an iterator returning Result<Rule, E> items.

CompatError

CompatLevel

See the Compatible documentation.

CreateRulesetError

Identifies errors when creating a ruleset.

HandleAccessError

Identifies errors when updating the ruleset’s handled access-rights.

HandleAccessesError

PathBeneathError

PathFdError

RestrictSelfError

RulesetError

Maps to all errors that can be returned by a ruleset action.

RulesetStatus

Enforcement status of a ruleset.

Traits

Access

Compatible

Properly handles runtime unsupported features.

Rule

RulesetAttr

RulesetCreatedAttr

Functions

path_beneath_rules

Helper to quickly create an iterator of PathBeneath rules.