NAME
    Linux::Landlock - A higher level interface to the Linux Landlock API

DESCRIPTION
    Landlock is a sandboxing feature specific to Linux that allows a process
    to restrict its own access to the file system. Once set, restrictions
    cannot be undone and they are inherited by all future child processes.

    Since the restrictions are set at runtime, from within the process
    itself, you can take into account dynamic information from your
    configuration. For example, a server that is supposed to serve files
    from a specific directory can restrict itself to that directory and its
    subdirectories to mitigate any bugs allowing directory traversal
    attacks. This is much less intrusive than chroot and does not require
    root privileges.

    This module provides an object-oriented interface to the Linux Landlock
    API. It uses the lower-level interface provided by
    Linux::Landlock::Direct.

    See <https://docs.kernel.org/userspace-api/landlock.html> for more
    information about Landlock.

METHODS
SYNOPSIS
          use Linux::Landlock;

          my $ruleset = Linux::Landlock->new(); # this can die
          $ruleset->add_path_rule('/etc/fstab', qw(read_file));
          $ruleset->add_net_rule(22222, qw(bind_tcp));
          $ruleset->apply();

          print -r '/etc/fstab' ? "allowed\n" : "not allowed\n"; # allowed ...
          IO::File->new('/etc/fstab', 'r') and print "succeeded: $!\n"; # ... and opening works
          print -r '/etc/passwd' ? "allowed\n" : "not allowed\n"; # allowed ...
          IO::File->new('/etc/passwd', 'r') or print "failed\n"; # ... but opening fails because of Landlock

          system('/usr/bin/cat /etc/fstab') and print "failed: $!\n"; # this fails, because we cannot execute cat

          IO::Socket::INET->new(LocalPort => 33333, Proto => 'tcp') or print "failed: $!\n"; # failed
          IO::Socket::INET->new(LocalPort => 22222, Proto => 'tcp') and print "succeeded\n"; # succeeded

    new([handled_fs_actions => \@fs_actions, handled_net_actions =>
    \@net_actions, die_on_unsupported => 1|0])
     Create a new Linux::Landlock instance.

     "handled_fs_actions" and "handled_net_actions" restrict the set of
     actions that can be used in rules and that will be prevented if not
     allowed by any rule. By default, all actions supported by the kernel
     and known to this module are covered. This should usually not be
     changed.

     If "die_on_unsupported" is set to a true value, the module will die if
     an unsupported access right is requested. Otherwise, access rights will
     be set on a best-effort basis, as intended by the upstream Landlock API
     design. This option should usually not be used.

    apply()
     Apply the ruleset to the current process and all future children. Dies
     on error.

    get_abi_version()
     Int, returns the ABI version of the Landlock kernel module. Can be
     called as a static method. A version < 1 means that Landlock is not
     available.

    add_path_beneath_rule($path, @allowed)
     Add a rule to the ruleset that allows the specified access to the given
     path. $path can be a file or a directory. @allowed is a list of access
     rights to allow.

     Possible access rights are:

         execute
         write_file
         read_file
         read_dir
         remove_dir
         remove_file
         make_char
         make_dir
         make_reg
         make_sock
         make_fifo
         make_block
         make_sym
         refer
         truncate
         ioctl_dev

     See <https://docs.kernel.org/userspace-api/landlock.html> for all
     possible access rights.

     This method dies on error. Errors are: non-existing or non-accessible
     paths and empty rules. If "die_on_unsupported" is used, it will also
     die if the rules are not supported by the current kernel.

     Beware: While the API accepts a path or user space file descriptor, the
     rule is actually checked against the corresponding, kernel internal
     file system object. This means that you will lose access if a path or
     directory you allowed access to is renamed or replaced.

    add_net_port_rule($port, @allowed)
     Add a rule to the ruleset that allows the specified access to the given
     port. $port is allowed port, @allowed is a list of allowed operations.

     Possible operations are:

         bind_tcp
         connect_tcp

    allow_perl_inc_access()
     A convenience method that adds rules to allow reading files and
     directories in all directories in @INC. This will not allow access to
     ".", even if it is in @INC.

LIMITATIONS
    This module requires a Linux system supporting the Landlock
    functionality. As of 2024, this is the case for almost all
    distributions, however, the version of the available Landlock ABI
    varies.

    Notably, the "TRUNCATE" access right is only supported by the kernel
    since ABI version 3 (kernel version 6.2 or newer, unless backported).

    Network functionality is only available since ABI version 4.

    Also keep in mind, that some Perl, or even libc, functions might
    implicitly rely on file system access that could have been restricted by
    Landlock.

AUTHOR
    Marc Ballarin, <ballarin.marc@gmx.de>

COPYRIGHT AND LICENSE
    Copyright (C) 2024 by Marc Ballarin

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.