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.