The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Env-Sanctify-Auto-1.001
River stage zero No dependents
++
/ Env::Sanctify::Auto

NAME

Env::Sanctify::Auto - Perl module that cleans up %ENV

VERSION

Version 1.001 ($Id: Auto.pm 8622 2009-08-18 04:46:41Z FREQUENCY@cpan.org $)

DESCRIPTION

Environment variables such as PATH (command search path) and IFS (input field separator) can have severe security ramifications. Luckily, enabling Perl's taint mode will provide some extra checking whenever there can be potentially unsafe calls to functions like system or open.

However, there has been no simple way to load a module which automatically cleans up your environment. Various methods are used to temporarily clean up the environment for you or forked children, such as:

  local $ENV{PATH} = '/usr/bin:/usr/local/bin';

While this works for most purposes, it has some potential issues such as what to do when the paths are different under different architectures. Obviously such a command is not portable to environments with different path conventions so this would break your program's compatibility with Win32, among others.

This simple module subclasses Env::Sanctify to take care of this for you. Among other things, this means you get the nice bonus of lexically scoped environments (see Env::Sanctify for details).

SYNOPSIS

  my $env = Env::Sanctify::Auto->new();
  # do some stuff, fork some processes, etc.
  $env->restore; # everything is back to normal.

COMPATIBILITY

This module was tested under Perl 5.10.0, using Debian Linux. However, because it's Pure Perl and doesn't do anything too obscure, it should be compatible with any version of Perl that supports its prerequisite modules.

It is untested on Win32 and unlikely to work for the time being.

If you encounter any problems on a different version or architecture, please contact the maintainer.

ENVIRONMENT VARIABLES

This module knows about the following environment variables:

PATH

PATH provides a list of paths to search for executables, which influences which commands are invoked by unqualified calls to system() and others. This variable is particularly dangerous because even if you use a fully qualified call to the executable, like "/usr/bin/echo ..." -- there is still a security hole, since echo could be executing unqualified code itself.

The safest way to handle this, and the strategy used by this module, is to remove everything except /usr/bin and /usr/local/bin (or equivalent, depending on your operating system).

CDPATH

CDPATH provides additional paths for cd to search on the system when it is called. This is dangerous because you could be attempting to change into a known safe directory, but the CDPATH may divert you to another directory. The variable is generally of limited usefulness, and so is removed completely during %ENV scrubbing.

IFS

IFS is the Internal Field Separator, which tells the operating system what characters should be considered whitespace separating command line arguments. Combined with controlling PATH, this exposes a very dangerous vulnerability: if the IFS is set to '/', then system('/bin/more') is essentially the same as system('bin more'). As a result, the 'bin' command is executed instead of '/bin/more' as expected.

ENV and BASH_ENV

ENV and BASH_ENV list files that are executed whenever a new shell is started, which includes whenever a shell script (.sh) is run.

METHODS

Env::Sanctify::Auto->new($opts)

Env::Sanctify::Auto->sanctify($opts)

Creates a new Env::Sanctify::Auto object, scrubbing the environment to remove or pacify potentially dangerous variables. Options may be passed as a hash reference to the constructor.

Code example:

  my $env = Env::Sanctify::Auto->new;

By default, PATH will be set to a sane value, but you can override the behaviour by passing the 'path' option:

  my $env = Env::Sanctify::Auto->new({
    path => '/usr/local/bin:/usr/bin'
  });

AUTHOR

Jonathan Yu <frequency@cpan.org>

CONTRIBUTORS

Your name here ;-)

ACKNOWLEDGEMENTS

  • Thanks to Chris "BinGOs" Williams <chris@bingosnet.co.uk> for making Env::Sanctify, a pretty neat module that inspired this one.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Env::Sanctify::Auto

You can also look for information at:

REPOSITORY

You can access the most recent development version of this module at:

http://svn.ali.as/cpan/trunk/Env-Sanctify-Auto

If you are a CPAN developer and would like to make modifications to the code base, please contact Adam Kennedy <adamk@cpan.org>, the repository administrator. I only ask that you contact me first to discuss the changes you wish to make to the distribution.

FEEDBACK

Please send relevant comments, rotten tomatoes and suggestions directly to the maintainer noted above.

If you have a bug report or feature request, please file them on the CPAN Request Tracker at http://rt.cpan.org. If you are able to submit your bug report in the form of failing unit tests, you are strongly encouraged to do so.

SEE ALSO

Env::Sanctify, the module upon which this one is based.

http://www.perlmonks.org/?node_id=131746, a Perl Monks thread discussing why IFS, CDPATH, ENV and BASH_ENV are considered dangerous

perlsec, a document explaining security considerations for Perl programs.

CAVEATS

KNOWN BUGS

There are no known bugs as of this release.

LIMITATIONS

  • There are lots of variables that can do dangerous things, particularly when executing files via system() or others. This module tries to fix the most common ones, but is by no means a complete way to sanctify your namespace, and is not a substitute for performing your own security audit.

  • I'm not a security expert, so more than likely I've missed something. Please do file bug reports so that I can fix the module.

  • I don't have access to a VMS machine, nor do I know how they work, so there is currently nothing here to deal with that. If you have a OpenVMS machine or know how they work, feel free to send me an e-mail or patch.

QUALITY ASSURANCE METRICS

TEST COVERAGE

  ------------------------- ------ ------ ------ ------ ------ ------
  File                      stmt   bran   cond    sub    pod   total
  ------------------------- ------ ------ ------ ------ ------ ------
  Env/Sanctify/Auto.pm      100.0  100.0  100.0  100.0  100.0  100.0

LICENSE

Copyright (C) 2009 by Jonathan Yu <frequency@cpan.org>

This package is distributed under the same terms as Perl itself. Please see the LICENSE file included in this distribution for full details of these terms.

DISCLAIMER OF WARRANTY

This software is provided by the copyright holders and contributors "AS IS" and ANY EXPRESS OR IMPLIED WARRANTIES, including, but not limited to, the IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.

In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.