File::Util::SecureDir
A process-wide, set-once directory security filter.
Modules that build search paths from directories they did not choose
(@INC, PERL5LIB, LD_LIBRARY_PATH) pass the candidates through
filter_dirs and use only what comes back. The #! code defines the
security level once; nothing loaded afterwards can relax it.
Usage
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 );
use FindBin::libs;
If the #! code chooses nothing, the first call to filter_dirs installs
the default. A filter=NAME that arrives after that croaks instead of
being ignored.
verbose[=0|1] and debug[=0|1] can be given by any module at any time
and can be reset. They report on STDERR.
Filters
From least to most restrictive:
| Name | Rejects |
|------------------|------------------------------------------------------------------|
| all | nothing (testing only) |
| other_no_write | world-writable directories (the default) |
| group_no_write | group- or world-writable directories |
| same_owner | the above, plus owners other than the effective user or root |
On Win32 the same levels are evaluated from the directory's security
descriptor; the effective user is the user SID of the process token, with
an automatic, warned fallback to the login-name lookup if the token cannot
be read. On Unix the owner is compared with the effective uid ($>), so
sudo and setuid programs check the user they are actually running as.
Contract
- The filter is assigned once per process and cannot be changed or replaced.
- Only the #! code can choose it; any other caller supplying
filtercroaks. - Errors reading a directory reject it (fail closed).
Limits
- Only the directory itself is checked, not its parents or its contents.
- The check is not atomic with the use of the directory.
- Code in the same interpreter can always redefine subroutines; the guarantee is that the API cannot weaken the filter.
- Unix permission bits only; ACLs on Unix are ignored.
See the POD for details.
Installation
perl Makefile.PL
make
make test
make install
Sources and tests live under version/; Makefile.PL copies the
directory matching the running perl into lib/ and t/. Perl v5.36 or
later is required. On Win32, Win32 and Win32::API are also needed.
Testing
Each test file checks one feature and depends only on features tested
before it. The filter is set once per process, so each file ends in one
filter. Win32-only tests skip elsewhere; two tests in
t/14-same_owner-euid.t need root and are skipped otherwise (run them
with sudo prove t/14-same_owner-euid.t).
Author and license
Steven Lembark lembark@wrkhors.com
Same terms as Perl v5.36 or any later version of Perl.