NAME

Filesys::Restrict - Restrict filesystem access

SYNOPSIS

    {
        my $check = Filesys::Restrict::create(
            sub {
                my ($op, $path) = @_;

                return 1 if $path =~ m<^/safe/place/>;

                # Deny access to anything else:
                return 0;
            },
        );

        # In this block, most Perl code will throw if it tries
        # to access anything outside of /safe/place.
    }

    # No more filesystem checks here.

DESCRIPTION

This module is a reasonable-best-effort at preventing Perl code from accessing files you don’t want to allow. One potential application of this is to restrict filesystem access to /tmp in tests.

THIS IS NOT A SECURITY TOOL!

This module cannot prevent all unintended filesystem access. The following are some known ways to circumvent it:

• Use XS modules (e.g., POSIX).

• Use one of open()’s more esoteric forms. This module tries to parse typical open() arguments but doesn’t “bend over backward”. The 2- and 3-argument forms are assumed to be valid if there’s an unrecognized format, and we ignore the 1-argument form entirely.

• Call system(), do(), or require().

  We could actually restrict do() and require(). These, though, are a bit different from other built-ins because they don’t facilitate reading arbitrary data off the filesystem; rather, they’re narrowly-scoped to bringing in additional Perl code.

  If you have a use case where it’s useful to restrict these, file a feature request.

SEE ALSO

Test::MockFile can achieve a similar effect to this module but has some compatibility problems with some Perl syntax.

Linux’s fanotify(7) provides a method of real-time access control via the kernel. See Linux::Fanotify and Linux::Perl for Perl implementations.

FUNCTIONS

$obj = create( sub { .. } )

Creates an opaque object that installs an access-control callback. Any existing access-control callback is saved and restored whenever $obj is DESTROYed.

The access-control callback is called with two arguments:

• The name of the Perl op that requests filesystem access. The names come from PL_op_desc in Perl’s opcode.h header file; they should correlate to the actual built-in called.

• The filesystem path in question.

The callback can end in one of three ways:

• Return truthy to confirm access to the path.

• Return falsy to cause a Filesys::Restrict::X::Forbidden instance to be thrown.

• Throw a custom exception.

LICENSE & COPYRIGHT

Copyright 2022 Gasper Software Consulting. All rights reserved.

This library is licensed under the same terms as Perl itself. See perlartistic.

This library was originally a research project at cPanel, L.L.C..