https://github.com/fgasper/p5-filesys-restrict

CPAN’s Filesys::Restrict
https://github.com/fgasper/p5-filesys-restrict

filesystem perl

Last synced: 8 months ago
JSON representation

CPAN’s Filesys::Restrict

• Host: GitHub
• URL: https://github.com/fgasper/p5-filesys-restrict
• Owner: FGasper
• License: other
• Created: 2021-10-08T15:27:37.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2022-12-30T13:35:34.000Z (over 3 years ago)
• Last Synced: 2025-03-28T19:21:25.319Z (about 1 year ago)
• Topics: filesystem, perl
• Language: Perl
• Homepage:
• Size: 119 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: Changes
  • License: LICENSE

Awesome Lists containing this project

README

          
# 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](https://metacpan.org/pod/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](https://metacpan.org/pod/Test%3A%3AMockFile) can achieve a similar effect to this module but

has some compatibility problems with some Perl syntax.

Linux’s [fanotify(7)](http://man.he.net/man7/fanotify) provides a method of real-time access control

via the kernel. See [Linux::Fanotify](https://metacpan.org/pod/Linux%3A%3AFanotify) and [Linux::Perl](https://metacpan.org/pod/Linux%3A%3APerl) 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](https://metacpan.org/pod/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](https://metacpan.org/pod/Filesys%3A%3ARestrict%3A%3AX%3A%3AForbidden)

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](https://metacpan.org/pod/perlartistic).

This library was originally a research project at

[cPanel, L.L.C.](https://cpanel.net).