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

Limits

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.