Landlock

https://docs.rs/landlock/0.4.3/
Admin
Landlock is a Rust crate providing safe abstractions for the Linux Landlock security feature to...
Tokens:67,568
Snippets:575
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Simple Landlock Ruleset Creation Example

Source: https://docs.rs/landlock/0.4.3/landlock/struct.Ruleset.html

Demonstrates creating a Landlock ruleset to restrict file system access. This example uses a helper function `restrict_fd` which handles Landlock-related errors. Ensure the Landlock ABI is correctly managed.

```rust
use landlock::{
    Access,
    AccessFs,
    PathBeneath,
    PathFd,
    RestrictionStatus,
    Ruleset,
    RulesetAttr,
    RulesetCreatedAttr,
    RulesetError,
    ABI,
};
use std::os::unix::io::AsFd;

fn restrict_fd<T>(hierarchy: T) -> Result<RestrictionStatus, RulesetError>
where
    T: AsFd,
{
    // The Landlock ABI should be incremented (and tested) regularly.
    let abi = ABI::V1;
    let access_all = AccessFs::from_all(abi);
    let access_read = AccessFs::from_read(abi);
    Ok(Ruleset::default()
        .handle_access(access_all)?
        .create()? 
        .add_rule(PathBeneath::new(hierarchy, access_read))?
        .restrict_self()?)
}

let fd = PathFd::new("/home").expect("failed to open /home");
let status = restrict_fd(fd).expect("failed to build the ruleset");

```

--------------------------------

### Create PathBeneath with PathFd

Source: https://docs.rs/landlock/0.4.3/landlock/struct.PathFd.html

Example demonstrating how to create a PathBeneath object using PathFd for a given path and access permissions. This is useful for setting up restricted file system access.

```rust
use landlock::{AccessFs, PathBeneath, PathFd, PathFdError};

fn allowed_root_dir(access: AccessFs) -> Result<PathBeneath<PathFd>, PathFdError> {
    let fd = PathFd::new("/")?;
    Ok(PathBeneath::new(fd, access))
}
```

--------------------------------

### Ruleset Creation with SoftRequirement and Rule

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Tests creating a ruleset with SoftRequirement compatibility, handling execute and refer access, adding a path rule, and verifying the RestrictionStatus. This example is conditional on ABI compatibility.

```rust
if compat::can_emulate(ABI::V1, ABI::V1, Some(ABI::V2)) {
        assert_eq!(
            Ruleset::from(ABI::V1)
                .handle_access(make_bitflags!(AccessFs::{Execute | Refer}))
                .unwrap()
                .create()
                .unwrap()
                // SoftRequirement for RulesetCreated with a rule.
                .set_compatibility(CompatLevel::SoftRequirement)
                .add_rule(PathBeneath::new(PathFd::new("/").unwrap(), AccessFs::Refer))
                .unwrap()
                .restrict_self()
                .unwrap(),
            RestrictionStatus {
                ruleset: RulesetStatus::NotEnforced,
                // With SoftRequirement, no_new_privs is still enabled, even if there is an error
                // (e.g. unsupported access right).
                no_new_privs: true,
            }
        );
    }
```

--------------------------------

### Clone Ruleset and Verify Owned File Descriptors

Source: https://docs.rs/landlock/0.4.3/src/landlock/lib.rs.html

This example demonstrates creating a ruleset, cloning it multiple times, and verifying that each clone results in a distinct owned file descriptor. It checks for file system access and ensures the file descriptors are valid and unique.

```rust
use std::os::unix::io::{AsRawFd, OwnedFd};

let abi = ABI::V1;
check_ruleset_support(
    abi,
    Some(abi),
    move |ruleset: Ruleset| -> _ {
        let ruleset1 = ruleset.handle_access(AccessFs::from_all(abi))?.create()?;
        let ruleset2 = ruleset1.try_clone().unwrap();
        let ruleset3 = ruleset2.try_clone().unwrap();

        let some1: Option<OwnedFd> = ruleset1.into();
        if let Some(fd1) = some1 {
            assert!(fd1.as_raw_fd() >= 0);

            let some2: Option<OwnedFd> = ruleset2.into();
            let fd2 = some2.unwrap();
            assert!(fd2.as_raw_fd() >= 0);

            assert_ne!(fd1.as_raw_fd(), fd2.as_raw_fd());
        }
        Ok(ruleset3.restrict_self()?)
    },
    false,
);
```

--------------------------------

### Handle ABI v2 with ABI v1 Compatibility

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

This example shows how to create a Landlock ruleset with ABI V1 compatibility, handle filesystem access, and add rules for different paths and access types. It demonstrates how ABI V2 rules are ignored when ABI V1 is enforced.

```rust
assert_eq!(
    Ruleset::from(ABI::V1)
        .set_compatibility(CompatLevel::HardRequirement)
        .handle_access(AccessFs::from_all(ABI::V1))
        .unwrap()
        .set_compatibility(CompatLevel::SoftRequirement)
        // Because Ruleset only supports V1, Refer will be ignored.
        .handle_access(AccessFs::Refer)
        .unwrap()
        .create()
        .unwrap()
        .add_rule(PathBeneath::new(
            PathFd::new("/tmp").unwrap(),
            AccessFs::from_all(ABI::V2)
        ))
        .unwrap()
        .add_rule(PathBeneath::new(
            PathFd::new("/usr").unwrap(),
            make_bitflags!(AccessFs::{ReadFile | ReadDir})
        ))
        .unwrap()
        .restrict_self()
        .unwrap(),
    RestrictionStatus {
        ruleset: RulesetStatus::NotEnforced,
        no_new_privs: true,
    }
);
```

--------------------------------

### Creating and Asserting Network Access Rights

Source: https://docs.rs/landlock/0.4.3/landlock/enum.AccessNet.html

Demonstrates how to create a BitFlags set for network access rights and assert equality between different methods of creating these sets. This example requires the landlock crate and its associated types.

```rust
use landlock::{ABI, Access, AccessNet, BitFlags, make_bitflags};

let bind = AccessNet::BindTcp;

let bind_set: BitFlags<AccessNet> = bind.into();

let bind_connect = make_bitflags!(AccessNet::{BindTcp | ConnectTcp});

let net_v4 = AccessNet::from_all(ABI::V4);

assert_eq!(bind_connect, net_v4);

```

--------------------------------

### ABI V2: Execute and Refer access with best-effort compatibility

Source: https://docs.rs/landlock/0.4.3/src/landlock/lib.rs.html

This example demonstrates Landlock ruleset configuration for ABI V2, allowing both Execute and Refer access. It highlights that `AccessFs::Refer` is not supported by ABI V1, hence the best-effort compatibility setting.

```rust
check_ruleset_support(
            ABI::V1,
            Some(ABI::V2),
            move |ruleset: Ruleset| -> _ {
                Ok(ruleset
                    .handle_access(AccessFs::Execute)?
                    // AccessFs::Refer is not supported by ABI::V1 (best-effort).
                    .handle_access(AccessFs::Refer)?
                    .create()? // AccessFs::Refer is not supported by ABI::V1 (best-effort).
                    .restrict_self()?)
            },
            false,
        );
```

--------------------------------

### Compatibility Struct Creation

Source: https://docs.rs/landlock/0.4.3/src/landlock/compat.rs.html

Creates a new `Compatibility` instance using the current ABI. This is a common way to start building compatibility settings.

```rust
pub(crate) fn new() -> Self {
    ABI::new_current().into()
}
```

--------------------------------

### Create Landlock PathBeneath Rule

Source: https://docs.rs/landlock/0.4.3/src/landlock/fs.rs.html

Example demonstrating how to create a `PathBeneath` rule for Landlock, specifying a parent directory and allowed access rights. This rule restricts operations to a specific file hierarchy.

```rust
use landlock::{AccessFs, PathBeneath, PathFd, PathFdError};

fn home_dir() -> Result<PathBeneath<PathFd>, PathFdError> {
    Ok(PathBeneath::new(PathFd::new("/home")?, AccessFs::ReadDir))
}
```

--------------------------------

### Example with SoftRequirement for Renaming Files

Source: https://docs.rs/landlock/0.4.3/landlock/trait.Compatible.html

This snippet demonstrates using `CompatLevel::SoftRequirement` to create a ruleset that either supports file renaming (`AccessFs::Refer`) or silently ignores the sandboxing if the feature is unsupported. It also shows setting `CompatLevel::BestEffort` for subsequent access rights.

```rust
use landlock::*

fn ruleset_handling_renames() -> Result<RulesetCreated, RulesetError> {
    Ok(Ruleset::default()
        // This ruleset must either handle the AccessFs::Refer right,
        // or it must silently ignore the whole sandboxing.
        .set_compatibility(CompatLevel::SoftRequirement)
        .handle_access(AccessFs::Refer)?
        // However, this ruleset may also handle other (future) access rights
        // if they are supported by the running kernel.
        .set_compatibility(CompatLevel::BestEffort)
        .handle_access(AccessFs::from_all(ABI::V6))?
        .create()?)
}
```

--------------------------------

### Handle Unsupported Network Access with EINVAL Error

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

This example shows how to handle unsupported network access with Landlock ABI V3 and verifies that the resulting error is an Errno with the value EINVAL, indicating an invalid argument.

```rust
assert_eq!(
    Errno::from(
        Ruleset::from(ABI::V3)
            .handle_access(AccessNet::from_all(ABI::V3))
            .unwrap_err()
    ),
    Errno::new(libc::EINVAL)
);
```

--------------------------------

### fn from_all(abi: ABI) -> BitFlags<Self>

Source: https://docs.rs/landlock/0.4.3/landlock/trait.Access.html

Gets the access rights defined by a specific ABI. This method is required by the Access trait.

```APIDOC
## fn from_all(abi: ABI) -> BitFlags<Self>

### Description
Gets the access rights defined by a specific `ABI`.

### Parameters
#### Path Parameters
- **abi** (ABI) - Required - The ABI to get access rights from.

### Returns
- **BitFlags<Self>** - The access rights for the given ABI.
```

--------------------------------

### Rust Landlock Ruleset Builder Example

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Demonstrates how to create a Landlock ruleset using the builder pattern. This helper function restricts access to a given file descriptor, allowing all filesystem access initially and then adding a specific rule for read access beneath a path.

```Rust
use landlock::{
    Access, AccessFs, PathBeneath, PathFd, RestrictionStatus, Ruleset,
    RulesetAttr,
    RulesetCreatedAttr,
    RulesetError,
    ABI,
};
use std::os::unix::io::AsFd;

fn restrict_fd<T>(hierarchy: T) -> Result<RestrictionStatus, RulesetError>
where
    T: AsFd,
{
    // The Landlock ABI should be incremented (and tested) regularly.
    let abi = ABI::V1;
    let access_all = AccessFs::from_all(abi);
    let access_read = AccessFs::from_read(abi);
    Ok(Ruleset::default()
        .handle_access(access_all)?
        .create()?
        .add_rule(PathBeneath::new(hierarchy, access_read))?
        .restrict_self()?)
}

let fd = PathFd::new("/home").expect("failed to open /home");
let status = restrict_fd(fd).expect("failed to build the ruleset");

```

--------------------------------

### Example: Restricting Environment Variables with Custom Iterator

Source: https://docs.rs/landlock/0.4.3/landlock/trait.RulesetCreatedAttr.html

Demonstrates how to create a custom iterator to parse paths from an environment variable and add them as rules to a Landlock ruleset. This is useful for restricting executable paths.

```rust
use landlock::{
    Access,
    AccessFs,
    BitFlags,
    PathBeneath,
    PathFd,
    PathFdError,
    RestrictionStatus,
    Ruleset,
    RulesetAttr,
    RulesetCreatedAttr,
    RulesetError,
    ABI,
};
use std::env;
use std::ffi::OsStr;
use std::os::unix::ffi::{OsStrExt, OsStringExt};
use thiserror::Error;

#[derive(Debug, Error)]
enum PathEnvError<'a> {
    #[error(transparent)]
    Ruleset(#[from] RulesetError),
    #[error(transparent)]
    AddRuleIter(#[from] PathFdError),
    #[error("missing environment variable {0}")]
    MissingVar(&'a str),
}

struct PathEnv {
    paths: Vec<u8>,
    access: BitFlags<AccessFs>,
}

impl PathEnv {
    // env_var is the name of an environment variable
    // containing paths requested to be allowed.
    // Paths are separated with ":", e.g. "/bin:/lib:/usr:/proc".
    // In case an empty string is provided,
    // no restrictions are applied.
    // `access` is the set of access rights allowed for each of the parsed paths.
    fn new<'a>(
        env_var: &'a str,
        access: BitFlags<AccessFs>,
    ) -> Result<Self, PathEnvError<'a>> {
        Ok(Self {
            paths: env::var_os(env_var)
                .ok_or(PathEnvError::MissingVar(env_var))? 
                .into_vec(),
            access,
        })
    }

    fn iter(
        &self,
    ) -> impl Iterator<Item = Result<PathBeneath<PathFd>, PathEnvError<'static>>> + '_ {
        let is_empty = self.paths.is_empty();
        self.paths
            .split(|b| *b == b':')
            // Skips the first empty element from of an empty string.
            .skip_while(move |_| is_empty)
            .map(OsStr::from_bytes)
            .map(move |path|
                Ok(PathBeneath::new(PathFd::new(path)?, self.access)))
    }
}

fn restrict_env() -> Result<RestrictionStatus, PathEnvError<'static>> {
    Ok(Ruleset::default()
        .handle_access(AccessFs::from_all(ABI::V1))?
        .create()? 
        // In the shell: export EXECUTABLE_PATH="/usr:/bin:/sbin"
        .add_rules(PathEnv::new("EXECUTABLE_PATH", AccessFs::Execute.into())?.iter())?
        .restrict_self()?)
}
```

--------------------------------

### Example with HardRequirement for Minimum Restrictions

Source: https://docs.rs/landlock/0.4.3/landlock/trait.Compatible.html

This snippet illustrates using `CompatLevel::HardRequirement` to ensure a ruleset supports at least the restrictions from Landlock version 1 (`AccessFs::from_all(ABI::V1)`). If these are not supported, an error is returned. It then sets `CompatLevel::BestEffort` for newer access rights.

```rust
use landlock::*

fn ruleset_fragile() -> Result<RulesetCreated, RulesetError> {
    Ok(Ruleset::default()
        // This ruleset must either handle at least all accesses defined by
        // the first Landlock version (e.g. AccessFs::WriteFile),
        // or the following handle_access() call must return a wrapped
        // AccessError<AccessFs>::Incompatible error.
        .set_compatibility(CompatLevel::HardRequirement)
        .handle_access(AccessFs::from_all(ABI::V1))?
        // However, this ruleset may also handle new access rights
        // (e.g. AccessFs::Refer defined by the second version of Landlock)
        // if they are supported by the running kernel,
        // but without returning any error otherwise.
        .set_compatibility(CompatLevel::BestEffort)
        .handle_access(AccessFs::from_all(ABI::V6))?
        .create()?)
}
```

--------------------------------

### Attempt to grant all access rights to /etc/passwd

Source: https://docs.rs/landlock/0.4.3/src/landlock/lib.rs.html

This example shows an attempt to grant all possible access rights to a specific file ('/etc/passwd'). This is expected to fail if Landlock is configured to prevent such broad permissions. It uses `PathBeneath` and `AccessFs::from_all`.

```rust
check_ruleset_support(
            abi,
            None,
            move |ruleset: Ruleset| -> _ {
                Ok(ruleset
                    .handle_access(AccessFs::from_all(abi))?
                    .create()? // Same code as allow_root_compat() but with /etc/passwd instead of /
                    .add_rule(PathBeneath::new(
                        PathFd::new("/etc/passwd")?,
                        // Tries to allow all access rights on a file.
                        AccessFs::from_all(abi),
                    ))?
                    .restrict_self()?)
            },
            false,
        );
```

--------------------------------

### Enforce hard requirement for execution and best effort for other access

Source: https://docs.rs/landlock/0.4.3/src/landlock/lib.rs.html

This example configures Landlock with a hard requirement for execution access and best-effort for all other access types. It also sets the `no_new_privs` flag and adds a rule for the root directory.

```rust
check_ruleset_support(
            abi,
            Some(abi),
            move |ruleset: Ruleset| -> _ {
                // Sets default support requirement: abort the whole sandboxing for any Landlock error.
                Ok(ruleset
                    // Must have at least the execute check…
                    .set_compatibility(CompatLevel::HardRequirement)
                    .handle_access(AccessFs::Execute)?
                    // …and possibly others.
                    .set_compatibility(CompatLevel::BestEffort)
                    .handle_access(AccessFs::from_all(abi))?
                    .create()? // Sets default support requirement: abort the whole sandboxing for any Landlock error.
                    .set_no_new_privs(true)
                    .add_rule(PathBeneath::new(PathFd::new("/")?, AccessFs::from_all(abi)))?
                    .restrict_self()?)
            },
            true,
        );
```

--------------------------------

### Prepare and Create Ruleset with File Access

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Demonstrates preparing a ruleset by setting compatibility and handling file system access operations like execute and read/write. The ruleset is then created using the prepared configuration.

```rust
let mut ruleset = Ruleset::from(ABI::Unsupported);
let ruleset_ref = &mut ruleset;

// Can pass this reference to prepare the ruleset...
ruleset_ref
    .set_compatibility(CompatLevel::BestEffort)
    .handle_access(AccessFs::Execute)
    .unwrap()
    .handle_access(AccessFs::ReadFile)
    .unwrap();

// ...and finally create the ruleset (thanks to non-lexical lifetimes).
ruleset
    .set_compatibility(CompatLevel::BestEffort)
    .handle_access(AccessFs::Execute)
    .unwrap()
    .handle_access(AccessFs::WriteFile)
    .unwrap()
    .create()
    .unwrap();
```

--------------------------------

### Any Trait - type_id() Method

Source: https://docs.rs/landlock/0.4.3/landlock/enum.CompatError.html

Gets the TypeId of the current type. This is part of the Any trait implementation.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Error Trait - cause() Method (Deprecated)

Source: https://docs.rs/landlock/0.4.3/landlock/enum.CompatError.html

Deprecated method for getting the cause of the error. Replaced by Error::source.

```rust
fn cause(&self) -> Option<&dyn Error>
```

--------------------------------

### Create and Populate Ruleset

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Demonstrates creating a ruleset, setting compatibility, and adding path-based access rules for execution. This is useful for defining granular permissions for specific directories.

```rust
    let mut ruleset_created = Ruleset::new().unwrap().create().unwrap();
    let ruleset_created_ref = &mut ruleset_created;

    ruleset_created_ref
        .set_compatibility(CompatLevel::BestEffort)
        .add_rule(PathBeneath::new(
            PathFd::new("/usr").unwrap(),
            AccessFs::Execute,
        ))
        .unwrap()
        .add_rule(PathBeneath::new(
            PathFd::new("/etc").unwrap(),
            AccessFs::Execute,
        ))
        .unwrap();
```

--------------------------------

### Error Trait - description() Method (Deprecated)

Source: https://docs.rs/landlock/0.4.3/landlock/enum.CompatError.html

Deprecated method for getting a string description of the error. Use the Display implementation or to_string() instead.

```rust
fn description(&self) -> &str
```

--------------------------------

### Get Underlying Bits of BitFlags

Source: https://docs.rs/landlock/0.4.3/landlock/struct.BitFlags.html

Retrieves the raw numeric representation of the set flags. This is useful for debugging or when interacting with systems that expect a raw bitmask.

```rust
#[bitflags]
#[repr(u8)]
#[derive(Clone, Copy)]
enum Flags {
    Foo = 1 << 0,
    Bar = 1 << 1,
}

let both_flags = Flags::Foo | Flags::Bar;
assert_eq!(both_flags.bits(), 0b11);
```

--------------------------------

### Get Errno from Landlock Status

Source: https://docs.rs/landlock/0.4.3/src/landlock/compat.rs.html

Retrieves the OS error number (errno) if the current kernel ABI is `Unsupported`. It specifically returns `ENOSYS` or `EOPNOTSUPP` for unsupported Landlock kernels.

```Rust
#[cfg(test)]
pub(crate) fn get_errno_from_landlock_status() -> Option<i32> {
    use std::io::Error;

    match ABI::new_current() {
        ABI::Unsupported => match Error::last_os_error().raw_os_error() {
            // Returns ENOSYS when the kernel is not built with Landlock support,
            // or EOPNOTSUPP when Landlock is supported but disabled at boot time.
            ret @ Some(libc::ENOSYS | libc::EOPNOTSUPP) => ret,
            // Other values can only come from bogus seccomp filters or debug tampering.
            _ => unreachable!(),
        },
        _ => None,
    }
}
```

--------------------------------

### Ruleset Creation with SoftRequirement and No New Privileges

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Demonstrates creating a ruleset with SoftRequirement compatibility, handling execute access, and verifying the RestrictionStatus, including the no_new_privs flag.

```rust
assert_eq!(
        Ruleset::from(ABI::Unsupported)
            .handle_access(AccessFs::Execute)
            .unwrap()
            .create()
            .unwrap()
            // SoftRequirement for RulesetCreated without any rule.
            .set_compatibility(CompatLevel::SoftRequirement)
            .restrict_self()
            .unwrap(),
        RestrictionStatus {
            ruleset: RulesetStatus::NotEnforced,
            // With SoftRequirement, no_new_privs is untouched if there is no error (e.g. no rule).
            no_new_privs: true,
        }
    );
```

--------------------------------

### Create a NetPort for HTTP Bindings

Source: https://docs.rs/landlock/0.4.3/landlock/struct.NetPort.html

Demonstrates how to create a `NetPort` rule for binding to TCP port 80, commonly used for HTTP. This requires importing `AccessNet` and `NetPort` from the `landlock` crate.

```rust
use landlock::{AccessNet, NetPort};

fn bind_http() -> NetPort {
    NetPort::new(80, AccessNet::BindTcp)
}
```

--------------------------------

### Building a Landlock Ruleset with Path Restrictions

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Demonstrates how to construct a Landlock ruleset that restricts access to specific file system hierarchies. It defines custom error handling for ruleset operations and applies read access to specified paths. Ensure the Landlock ABI is compatible.

```rust
use landlock::{
    Access, AccessFs, PathBeneath, PathFd, PathFdError, RestrictionStatus, Ruleset,
    RulesetAttr, RulesetCreatedAttr, RulesetError, ABI,
};
use thiserror::Error;

#[derive(Debug, Error)]
enum MyRestrictError {
    #[error(transparent)]
    Ruleset(#[from] RulesetError),
    #[error(transparent)]
    AddRule(#[from] PathFdError),
}

fn restrict_paths(hierarchies: &[&str]) -> Result<RestrictionStatus, MyRestrictError> {
    // The Landlock ABI should be incremented (and tested) regularly.
    let abi = ABI::V1;
    let access_all = AccessFs::from_all(abi);
    let access_read = AccessFs::from_read(abi);
    Ok(Ruleset::default()
        .handle_access(access_all)?
        .create()?
        .add_rules(
            hierarchies
                .iter()
                .map::<Result<_, MyRestrictError>, _>(|p| {
                    Ok(PathBeneath::new(PathFd::new(p)?, access_read))
                }),
        )?
        .restrict_self()?)
}

let status = restrict_paths(&["/usr", "/home"]).expect("failed to build the ruleset");

```

--------------------------------

### Creating and Using Landlock Scope Flags

Source: https://docs.rs/landlock/0.4.3/src/landlock/scope.rs.html

Demonstrates how to create a `BitFlags<Scope>` set for signals and abstract Unix sockets, and how to compare it with a set created using `Scope::from_all`.

```rust
use landlock::{ABI, Access, Scope, BitFlags, make_bitflags};

let signal = Scope::Signal;

let signal_set: BitFlags<Scope> = signal.into();

let signal_uds = make_bitflags!(Scope::{Signal | AbstractUnixSocket});

let scope_v6 = Scope::from_all(ABI::V6);

assert_eq!(signal_uds, scope_v6);
```

--------------------------------

### Creating and Using Scope BitFlags

Source: https://docs.rs/landlock/0.4.3/landlock/enum.Scope.html

Demonstrates how to create and manipulate sets of Landlock Scope flags using BitFlags and make_bitflags macro.

```rust
use landlock::{ABI, Access, Scope, BitFlags, make_bitflags};

let signal = Scope::Signal;

let signal_set: BitFlags<Scope> = signal.into();

let signal_uds = make_bitflags!(Scope::{Signal | AbstractUnixSocket});

let scope_v6 = Scope::from_all(ABI::V6);

assert_eq!(signal_uds, scope_v6);

```

--------------------------------

### Create Ruleset with Execute Access and Path Restriction

Source: https://docs.rs/landlock/0.4.3/src/landlock/lib.rs.html

This snippet demonstrates creating a ruleset that allows executing files, with a rule to restrict access to paths beneath the root directory. It also shows how to attempt cloning the ruleset.

```rust
check_ruleset_support(
            ABI::V1,
            Some(ABI::V1),
            move |ruleset: Ruleset| -> _ {
                Ok(ruleset
                    .handle_access(AccessFs::Execute)?
                    .create()? 
                    .add_rule(PathBeneath::new(PathFd::new("/")?, AccessFs::Execute))?
                    .try_clone()? 
                    .restrict_self()?)
            },
            false,
        );
```

--------------------------------

### Creating and Manipulating AccessFs BitFlags

Source: https://docs.rs/landlock/0.4.3/landlock/enum.AccessFs.html

Demonstrates how to create BitFlags sets for AccessFs, combine individual rights, and perform bitwise operations. This is useful for defining specific permission sets for file system access.

```rust
use landlock::{ABI, Access, AccessFs, BitFlags, make_bitflags};

let exec = AccessFs::Execute;

let exec_set: BitFlags<AccessFs> = exec.into();

let file_content = make_bitflags!(AccessFs::{Execute | WriteFile | ReadFile});

let fs_v1 = AccessFs::from_all(ABI::V1);

let without_exec = fs_v1 & !AccessFs::Execute;

assert_eq!(fs_v1 | AccessFs::Refer, AccessFs::from_all(ABI::V2));
```

--------------------------------

### Creating a Landlock Ruleset with Root Path Access

Source: https://docs.rs/landlock/0.4.3/src/landlock/lib.rs.html

Demonstrates how to create a Landlock ruleset with access granted to the root directory and a specific path beneath it. This is useful for restricting file system access to specific locations.

```Rust
let abi = ABI::V1;

check_ruleset_support(
    abi,
    Some(abi),
    move |ruleset: Ruleset| -> _ {
        Ok(ruleset
            .handle_access(AccessFs::from_all(abi))?
            .create()? // Creates a new ruleset
            .add_rule(PathBeneath::new(PathFd::new("/")?, AccessFs::from_all(abi)))? // Adds a rule for the root path

```

--------------------------------

### Using make_bitflags! for Multiple Flags

Source: https://docs.rs/landlock/0.4.3/landlock/macro.make_bitflags.html

Demonstrates how to use the make_bitflags! macro to create a BitFlags instance with multiple flags set. This is useful for setting several permissions or states at once.

```rust
let x = make_bitflags!(Test::{A | C});
assert_eq!(x, Test::A | Test::C);
```

--------------------------------

### PathBeneath try_compat_inner implementation

Source: https://docs.rs/landlock/0.4.3/src/landlock/fs.rs.html

This snippet shows the `try_compat_inner` method for `PathBeneath`, which determines valid accesses based on whether the parent is a file or directory. It returns `CompatResult::Partial` with an error if the allowed access is incompatible.

```rust
fn try_compat_inner(
        &mut self,
        _abi: ABI,
    ) -> Result<CompatResult<AccessFs>, CompatError<AccessFs>> {
        // Gets subset of valid accesses according the FD type.
        let valid_access =
            if is_file(&self.parent_fd).map_err(|e| PathBeneathError::StatCall { source: e })? {
                self.allowed_access & ACCESS_FILE
            } else {
                self.allowed_access
            };

        if self.allowed_access != valid_access {
            let error = PathBeneathError::DirectoryAccess {
                access: self.allowed_access,
                incompatible: self.allowed_access ^ valid_access,
            }
            .into();
            self.allowed_access = valid_access;
            // Linux would return EINVAL.
            Ok(CompatResult::Partial(error))
        } else {
            Ok(CompatResult::Full)
        }
    }
```

--------------------------------

### Compatibility Struct Initialization

Source: https://docs.rs/landlock/0.4.3/src/landlock/compat.rs.html

Shows how to initialize a `Compatibility` struct from an `ABI` value. The `level` is set to its default, and the `state` is initialized to `CompatState::Init`.

```rust
impl From<ABI> for Compatibility {
    fn from(abi: ABI) -> Self {
        Compatibility {
            abi,
            level: Default::default(),
            state: CompatState::Init,
        }
    }
}
```

--------------------------------

### Create Landlock Ruleset with Actual Handled Access

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

This snippet demonstrates the creation of a Landlock ruleset when actual handled filesystem, network, or scoped accesses are present. It prepares the attributes for the `landlock_create_ruleset` system call and handles potential errors.

```rust
let attr = uapi::landlock_ruleset_attr {
    handled_access_fs: self.actual_handled_fs.bits(),
    handled_access_net: self.actual_handled_net.bits(),
    scoped: self.actual_scoped.bits(),
};
match unsafe { uapi::landlock_create_ruleset(&attr, size_of_val(&attr), 0) } {
    fd if fd >= 0 => Ok(RulesetCreated::new(
        self,
        Some(unsafe { OwnedFd::from_raw_fd(fd) }),
    )),
    _ => Err(CreateRulesetError::CreateRulesetCall {
        source: Error::last_os_error(),
    }),
}
```

--------------------------------

### ALL

Source: https://docs.rs/landlock/0.4.3/landlock/struct.BitFlags.html

Represents a `BitFlags` with all flags set in a const context.

```APIDOC
## ALL

### Description
A `BitFlags` with all flags set. Equivalent to `all()`, but works in a const context.

### Constant
`pub const ALL: BitFlags<T>`
```

--------------------------------

### Ruleset Compatibility Handling (Dummy)

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Tests how Landlock rulesets handle compatibility states (Init, No, Dummy) with different compatibility levels when executing actions. This is useful for understanding how Landlock adapts to different kernel versions or configurations.

```rust
    for level in [CompatLevel::BestEffort, CompatLevel::SoftRequirement] {
        println!("level: {:?}", level);

        // ABI:Unsupported does not support AccessFs::Execute.
        let ruleset = Ruleset::from(ABI::Unsupported);
        assert_eq!(ruleset.compat.state, CompatState::Init);

        let ruleset = ruleset.set_compatibility(level);
        assert_eq!(ruleset.compat.state, CompatState::Init);

        let ruleset = ruleset.handle_access(AccessFs::Execute).unwrap();
        assert_eq!(
            ruleset.compat.state,
            match level {
                CompatLevel::BestEffort => CompatState::No,
                CompatLevel::SoftRequirement => CompatState::Dummy,
                _ => unreachable!(),
            }
        );

        let ruleset_created = ruleset.create().unwrap();
        // Because the compatibility state was either No or Dummy, calling create() updates it to
        // Dummy.
        assert_eq!(ruleset_created.compat.state, CompatState::Dummy);

        let ruleset_created = ruleset_created
            .add_rule(PathBeneath::new(
                PathFd::new("/usr").unwrap(),
                AccessFs::Execute,
            ))
            .unwrap();
        assert_eq!(ruleset_created.compat.state, CompatState::Dummy);
    }
```

--------------------------------

### Test PathBeneath compatibility with different files and access levels

Source: https://docs.rs/landlock/0.4.3/src/landlock/fs.rs.html

This test suite checks `PathBeneath::try_compat` for various file paths and access permissions under `ABI::V1`. It asserts expected `CompatError::PathBeneath` or `CompatError::Access` errors based on the provided access flags and compatibility levels.

```rust
#[test]
fn path_beneath_try_compat() {
    use crate::*;

    let abi = ABI::V1;

    for file in &["/etc/passwd", "/dev/null"] {
        let mut compat_state = CompatState::Init;
        let ro_access = AccessFs::ReadFile | AccessFs::ReadDir;
        assert!(matches!(
            PathBeneath::new(PathFd::new(file).unwrap(), ro_access)
                .try_compat(abi, CompatLevel::HardRequirement, &mut compat_state)
                .unwrap_err(),
            CompatError::PathBeneath(PathBeneathError::DirectoryAccess { access, incompatible })
                if access == ro_access && incompatible == AccessFs::ReadDir
        ));

        let mut compat_state = CompatState::Init;
        assert!(matches!(
            PathBeneath::new(PathFd::new(file).unwrap(), BitFlags::EMPTY)
                .try_compat(abi, CompatLevel::BestEffort, &mut compat_state)
                .unwrap_err(),
            CompatError::Access(AccessError::Empty)
        ));
    }

    let full_access = AccessFs::from_all(ABI::V1);
    for compat_level in &[
        CompatLevel::BestEffort,
        CompatLevel::SoftRequirement,
        CompatLevel::HardRequirement,
    ] {
        let mut compat_state = CompatState::Init;
        let mut path_beneath = PathBeneath::new(PathFd::new("/").unwrap(), full_access)
            .try_compat(abi, *compat_level, &mut compat_state)

```

--------------------------------

### Generic Ruleset Creation with Custom Error Handling

Source: https://docs.rs/landlock/0.4.3/landlock/struct.Ruleset.html

Demonstrates creating a Landlock ruleset with broad access permissions and then adding path-based read restrictions. It includes a custom error enum to handle potential errors during ruleset creation and rule addition. Use this for setting up basic file system restrictions.

```rust
use landlock::{
    Access, AccessFs, PathBeneath, PathFd, PathFdError, RestrictionStatus, Ruleset,
    RulesetAttr, RulesetCreatedAttr, RulesetError, ABI,
};
use thiserror::Error;

#[derive(Debug, Error)]
enum MyRestrictError {
    #[error(transparent)]
    Ruleset(#[from] RulesetError),
    #[error(transparent)]
    AddRule(#[from] PathFdError),
}

fn restrict_paths(hierarchies: &[&str]) -> Result<RestrictionStatus, MyRestrictError> {
    // The Landlock ABI should be incremented (and tested) regularly.
    let abi = ABI::V1;
    let access_all = AccessFs::from_all(abi);
    let access_read = AccessFs::from_read(abi);
    Ok(Ruleset::default()
        .handle_access(access_all)?
        .create()?
        .add_rules(
            hierarchies
                .iter()
                .map::<Result<_, MyRestrictError>, _>(|p| {
                    Ok(PathBeneath::new(PathFd::new(p)?, access_read))
                }),
        )?
        .restrict_self()?)
}

let status = restrict_paths(&["/usr", "/home"]).expect("failed to build the ruleset");
```

--------------------------------

### Unsupported Ruleset Handling (BestEffort/SoftRequirement)

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Tests Landlock ruleset behavior with an unsupported ABI, demonstrating how 'BestEffort' and 'SoftRequirement' compatibility levels affect restriction status. This is useful for understanding fallback mechanisms when full Landlock support is unavailable.

```rust
    assert_eq!(
        Ruleset::from(ABI::Unsupported)
            // BestEffort for Ruleset.
            .handle_access(AccessFs::Execute)
            .unwrap()
            .create()
            .unwrap()
            .restrict_self()
            .unwrap(),
        RestrictionStatus {
            ruleset: RulesetStatus::NotEnforced,
            // With BestEffort, no_new_privs is still enabled.
            no_new_privs: true,
        }
    );

    assert_eq!(
        Ruleset::from(ABI::Unsupported)
            // SoftRequirement for Ruleset.
            .set_compatibility(CompatLevel::SoftRequirement)
            .handle_access(AccessFs::Execute)
            .unwrap()
            .create()
            .unwrap()
            .restrict_self()
            .unwrap(),
        RestrictionStatus {
            ruleset: RulesetStatus::NotEnforced,
            // With SoftRequirement, no_new_privs is still enabled.
            no_new_privs: true,
        }
    );
```

--------------------------------

### Ruleset Compatibility Handling (Partial)

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Examines how Landlock rulesets manage partial compatibility states when certain access types are unsupported by the ABI. This demonstrates how Landlock can still enforce some rules while gracefully handling unsupported ones.

```rust
    // CompatLevel::BestEffort
    let ruleset = Ruleset::from(ABI::V1);
    assert_eq!(ruleset.compat.state, CompatState::Init);

    // ABI::V1 does not support AccessFs::Refer.
    let ruleset = ruleset.handle_access(AccessFs::Refer).unwrap();
    assert_eq!(ruleset.compat.state, CompatState::No);

    let ruleset = ruleset.handle_access(AccessFs::Execute).unwrap();
    assert_eq!(ruleset.compat.state, CompatState::Partial);

    // Requesting to handle another unsupported handled access does not change anything.
    let ruleset = ruleset.handle_access(AccessFs::Refer).unwrap();
    assert_eq!(ruleset.compat.state, CompatState::Partial);
```

--------------------------------

### Check Empty Handled Access for Minimal Ruleset

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

Verifies that attempting to handle empty access rights for a minimal ruleset (ABI::V1) results in a HandleAccessError::Compat::Access::Empty error.

```rust
assert!(matches!(
        Ruleset::from(ABI::V1)
            // Empty access-rights
            .handle_access(AccessFs::from_all(ABI::Unsupported))
            .unwrap_err(),
        RulesetError::HandleAccesses(HandleAccessesError::Fs(HandleAccessError::Compat(
            CompatError::Access(AccessError::Empty)
        )))
    ));
```

--------------------------------

### Handle Unsupported Network Access with ABI v3

Source: https://docs.rs/landlock/0.4.3/src/landlock/ruleset.rs.html

This snippet demonstrates handling network access with Landlock ABI V3 and checking for errors related to unsupported or incompatible access types. It expects a specific error indicating an empty access set.

```rust
matches!(
    Ruleset::from(ABI::V3)
        .handle_access(AccessNet::from_all(ABI::V3))
        .unwrap_err(),
    RulesetError::HandleAccesses(HandleAccessesError::Net(HandleAccessError::Compat(
        CompatError::Access(AccessError::Empty)
    )))
);
```

--------------------------------

### CompatState Update Logic

Source: https://docs.rs/landlock/0.4.3/src/landlock/compat.rs.html

Demonstrates the state transitions of `CompatState` when the `update` method is called with different `CompatState` values. This shows how the state evolves based on the compatibility requirements.

```rust
state.update(CompatState::Full);
assert_eq!(state, CompatState::Full);

state.update(CompatState::No);
assert_eq!(state, CompatState::Partial);

state.update(CompatState::Full);
assert_eq!(state, CompatState::Partial);

state.update(CompatState::Full);
assert_eq!(state, CompatState::Partial);

state.update(CompatState::No);
assert_eq!(state, CompatState::Partial);

state.update(CompatState::Dummy);
assert_eq!(state, CompatState::Dummy);

state.update(CompatState::Full);
assert_eq!(state, CompatState::Dummy);
}
```

```rust
let mut state = CompatState::Full;

state.update(CompatState::Full);
assert_eq!(state, CompatState::Full);

state.update(CompatState::No);
assert_eq!(state, CompatState::Partial);

state.update(CompatState::Full);
assert_eq!(state, CompatState::Partial);
}
```

--------------------------------

### Create Ruleset with IoctlDev Access and Path Restriction

Source: https://docs.rs/landlock/0.4.3/src/landlock/lib.rs.html

This snippet shows how to create a ruleset that allows binding TCP sockets and performing device IOCTL operations, with a rule to restrict IOCTL device access to paths beneath the root.

```rust
check_ruleset_support(
            ABI::V4,
            Some(ABI::V5),
            move |ruleset: Ruleset| -> _ {
                Ok(ruleset
                    .handle_access(AccessNet::BindTcp)?
                    .handle_access(AccessFs::IoctlDev)?
                    .create()? 
                    .add_rule(PathBeneath::new(PathFd::new("/")?, AccessFs::IoctlDev))?
                    .restrict_self()?)
            },
            false,
        );
```

--------------------------------

### Using make_bitflags! in Const Context

Source: https://docs.rs/landlock/0.4.3/landlock/macro.make_bitflags.html

Shows how to use the make_bitflags! macro in a const context to initialize a BitFlags instance with a single flag. This is useful for compile-time constant definitions.

```rust
const X: BitFlags<Test> = make_bitflags!(Test::A);
```

--------------------------------

### From<T> for T - from() Method

Source: https://docs.rs/landlock/0.4.3/landlock/enum.CompatError.html

Returns the argument unchanged. This is the implementation of From<T> for T.

```rust
fn from(t: T) -> T
```

--------------------------------

### Iterating over BitFlags

Source: https://docs.rs/landlock/0.4.3/landlock/struct.BitFlags.html

Demonstrates how to iterate over the set flags within a BitFlags instance. Requires the `make_bitflags!` macro for initialization.

```rust
let flags = make_bitflags!(MyFlag::{A | C});

flags.iter()
    .for_each(|flag| println!("{:?}", flag));
```

--------------------------------

### Update Compatibility State

Source: https://docs.rs/landlock/0.4.3/src/landlock/compat.rs.html

Updates the `CompatState` based on a new state. The `Dummy` state is terminal. `Init` takes on the `other` state. Any transition not resulting in `Dummy`, `No`, or `Full` becomes `Partial`.

```Rust
impl CompatState {
    fn update(&mut self, other: Self) {
        *self = match (*self, other) {
            (CompatState::Init, other) => other,
            (CompatState::Dummy, _) => CompatState::Dummy,
            (_, CompatState::Dummy) => CompatState::Dummy,
            (CompatState::No, CompatState::No) => CompatState::No,
            (CompatState::Full, CompatState::Full) => CompatState::Full,
            (_, _) => CompatState::Partial,
        }
    }
}
```

--------------------------------

### NetPort Rule Creation

Source: https://docs.rs/landlock/0.4.3/src/landlock/net.rs.html

Shows how to create a new network port rule for binding to a specific TCP port.

```rust
use landlock::{AccessNet, NetPort};

fn bind_http() -> NetPort {
    NetPort::new(80, AccessNet::BindTcp)
}

```

--------------------------------

### Test PathBeneath compatibility with ABI::V1

Source: https://docs.rs/landlock/0.4.3/src/landlock/fs.rs.html

This test case verifies the error handling of `PathBeneath::add_rule` with `ABI::V1` when `AccessFs::Refer` is used with a file, expecting a `PathBeneathError::DirectoryAccess`.

```rust
#[test]
fn path_beneath_try_compat_children() {
    use crate::*;

    // AccessFs::Refer is not handled by ABI::V1 and only for directories.
    let access_file = AccessFs::ReadFile | AccessFs::Refer;

    // Test error ordering with ABI::V1
    let mut ruleset = Ruleset::from(ABI::V1).handle_access(access_file).unwrap();
    // Do not actually perform any syscall.
    ruleset.compat.state = CompatState::Dummy;
    assert!(matches!(
        RulesetCreated::new(ruleset, None)
            .set_compatibility(CompatLevel::HardRequirement)
            .add_rule(PathBeneath::new(PathFd::new("/dev/null").unwrap(), access_file))
            .unwrap_err(),
        RulesetError::AddRules(AddRulesError::Fs(AddRuleError::Compat(
            CompatError::PathBeneath(PathBeneathError::DirectoryAccess { access, incompatible })
        ))) if access == access_file && incompatible == AccessFs::Refer
    ));

    // Test error ordering with ABI::V2
    let mut ruleset = Ruleset::from(ABI::V2).handle_access(access_file).unwrap();
    // Do not actually perform any syscall.
    ruleset.compat.state = CompatState::Dummy;
    assert!(matches!(
        RulesetCreated::new(ruleset, None)
            .set_compatibility(CompatLevel::HardRequirement)
            .add_rule(PathBeneath::new(PathFd::new("/dev/null").unwrap(), access_file))
            .unwrap_err(),
        RulesetError::AddRules(AddRulesError::Fs(AddRuleError::Compat(
            CompatError::PathBeneath(PathBeneathError::DirectoryAccess { access, incompatible })
        ))) if access == access_file && incompatible == AccessFs::Refer
    ));
}
```

--------------------------------

### Creation from Values

Source: https://docs.rs/landlock/0.4.3/landlock/struct.BitFlags.html

Provides methods for creating BitFlags instances from other types.

```APIDOC
## From Value

### Description
Converts a single flag value into a `BitFlags` instance.

### Method
`from(t: T) -> BitFlags<T>`

### Parameters
- `t`: The flag value to convert.

## From Iterator

### Description
Creates a `BitFlags` instance from an iterator of flag values.

### Method
`from_iter<I>(it: I) -> BitFlags<T>`

### Parameters
- `it`: An iterator yielding items convertible into `BitFlags<T>`.
```

--------------------------------

### Create PathFd and Access File

Source: https://docs.rs/landlock/0.4.3/src/landlock/fs.rs.html

Demonstrates creating a PathFd for a given path and attempting to read from it. This test checks if the file descriptor is opened with O_PATH, which should prevent direct reading.

```rust
use std::fs::File;
use std::io::Read;

PathBeneath::new(PathFd::new("/").unwrap(), AccessFs::Execute);
PathBeneath::new(File::open("/").unwrap(), AccessFs::Execute);

let mut buffer = [0; 1];
// Checks that PathFd really returns an FD opened with O_PATH (Bad file descriptor error).
File::from(PathFd::new("/etc/passwd").unwrap().fd)
    .read(&mut buffer)
    .unwrap_err();
```
Tokens:
Raw