NAME

File::Util::SecureDir - process-wide, set-once directory security filter.

SYNOPSIS

# In any module with directories to check; no arguments.

use File::Util::SecureDir;

state $secure = File::Util::SecureDir->new;  # the singleton.
my    @clean  = $secure->filter_dirs( @candidates );

say 'filtering with ' . $secure->filter;     # name only, read-only.

# In the #! code, only to pick something other than the default;
# it must come before any module that filters directories.

#!/usr/bin/env perl
use v5.36;

use File::Util::SecureDir qw( filter=same_owner );

# In any module, any time; verbose and debug can be reset.

use File::Util::SecureDir qw( verbose );

DESCRIPTION

The #! code defines the security context. It may select one of the named filters with use File::Util::SecureDir qw( filter=NAME ); the file making the request is checked against $0, so any other caller supplying filter croaks. If the #! code says nothing, the first call to filter_dirs installs the default. Either way the filter is assigned once and cannot be changed or replaced afterwards, so a filter=NAME that arrives after another module has already filtered croaks rather than being silently ignored.

Filters, least to most restrictive:

all             accept everything (testing only).
other_no_write  reject world-writable directories (default).
group_no_write  also reject group-writable directories.
same_owner      also require the owner to be the effective user
                of the process (or root / Administrators).

filter or filter= with no name selects the default explicitly.

verbose[=0|1] reports the selected filter and every rejected directory on STDERR; debug[=0|1] reports every decision. Either can be given by any module, any time, and be reset.

EXAMPLE

A module that builds a search path from directories it did not choose, such as FindBin::libs, uses the filter with no arguments, so a script that only loads that module gets the default level without knowing this module exists:

package FindBin::libs;

use File::Util::SecureDir;      # no arguments: nothing is selected here.

sub import
{
    my    @libz   = ...;        # candidate directories.
    state $secure = File::Util::SecureDir->new;

    # the first call installs the default if the #! code chose none.

    if( my @clean = $secure->filter_dirs( @libz ) )
    {
        # use @clean for @INC, PERL5LIB, LD_LIBRARY_PATH...
    }
}

A script that wants a different level, including all, says so first:

#!/usr/bin/env perl
use v5.36;

use File::Util::SecureDir qw( filter=all );
use FindBin::libs;

If it puts the line after use FindBin::libs, the default has already been installed and the filter=all croaks instead of being ignored.

METHODS

new

Returns the singleton (the package name).

filter

Name of the filter in effect ('' if unset). Read-only.

filter_dirs( @dirs )

Returns the directories that pass, in order. Unreadable directories fail.

verbose, debug

Get or set the flag.

LIMITS

Code in the same interpreter can always redefine subroutines; the guarantee is that the API cannot weaken the filter. The check that filter= comes from the #! code compares the caller's file name to $0: perl -M and PERL5OPT pass it (they report the script, line 0) and a # line directive in a module can spoof it. Whoever controls the command line or environment already controls the process. Only the directory itself is checked: not its parents, and symlinks are followed. A directory can change between the check and its use.

AUTHOR

Steven Lembark <lembark@wrkhors.com>

LICENSE

Same terms as Perl v5.36 or any later version of Perl.