# 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: ```perl 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: ```perl #!/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 `filter` croaks. - 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 Same terms as Perl v5.36 or any later version of Perl.