NAME

Log::Scrubber - Perl extension to avoid logging sensitive data

SYNOPSIS

  use Log::Scrubber;             # Override warn() and die() and import scrubber_init()
  use Log::Scrubber qw(:all);    # Override everything this module knows
  use Log::Scrubber qw(:Carp);   # Only override Carp methods
  use Log::Scrubber qw(:Syslog); # Only override syslog()
  use Log::Scrubber qw(scrubber);# scrubber() for use on your own
  use Log::Scrubber qw(+Custom::Method);# Override any perl method

  use Log::Scrubber qw($SCRUBBER :Carp +My::Logs); # Or combine a few

  Example:

    use Log::Scrubber;
    scrubber_init( { '4007000000027' => 'DELETED' } );
    warn "The card number is 4007000000027.\n";

  Output:

    The card number is DELETED.

DESCRIPTION

As required by the PCI Security Standards Council, some data is not acceptable to send to log files. Most notably CVV data. However it is simply a matter of time before a developer accidentally (or on purpose) logs sensitive data to the error_log, or some other inappropriate location.

This module is a solution for this vulnerability. It allows you to create a single location for redaction. What it does is very simple: It replaces occurrences of the your sensitive data in the output of any common logging mechanism such as use warnings, warn, use Carp and die with an acceptable alternative provided by you.

It does so by overriding the functions with a safer alternative so that no code needs to be changed.

Note that in order for this protection to be effective, this module must be used as the last module (ie, after all the modules it can override) in order for proper method replacement to occur.

The protection can also be invoked by the scrubber method, which takes a list of arguments and returns the same list, with all data safely replaced. This method is provided so that you can call it by yourself.

Typically, you will want to issue an use Log::Scrubber qw(:all) after the last module is used in your code, to automatically benefit from the most common level of protection.

Note: If you are using $SIG{__WARN__} and $SIG{__DIE__} then you must call scrubber_init() or set $SCRUBBER=1 afterward to maintain full protection.

METHODS

Additional methods created by this package.

scrubber_init

    Both adds scrubbers to your list, and enables Log::Scrubber

    scrubber_init( { # Initialize the scrubber.
      $ereg1 => $replacementText,
      $ereg2 => $rep2,
      $key1  => sub { my ($key,$val) = @_; $val++; return $val; },
      $key2  => sub { my ($key,$val) = @_; $val =~ s/1/2/; return $val; },
      } )

scrubber_start

    Enables scrubbing by overriding all configured methods/signals.

    scrubber_start();
    # or
    $SCRUBBER = 1;

scrubber_stop

    Disables scrubbing by removing the method/signal overrides.  When disabled your scripts should function exactly as if Log::Scrubber was never installed.

    scrubber_stop();
    # or
    $SCRUBBER = 0;

scrubber_add_scrubber

    Add a new regular expression, or coderef scrubber.  This follows the same format as init_scrubber()

    scrubber_add_scrubber({$ereg=>$replaceTxt});

scrubber_remove_scrubber

    Remove a previously added scrubber.

    scrubber_remove_scrubber({$ereg=>$replaceTxt});

scrubber

    Allows manual use of the scrubber

    @clean = scrubber( @dirty );
    $clean = scrubber $clean;

scrubber_enabled

    if (scrubber_enabled()) { print "Yes it is\n"; }
    # or
    if ($SCRUBBER) { print "Yes it is\n"; }

scrubber_add_signal

scrubber_remove_signal

    scrubber_add_signal('__WARN__');

scrubber_add_method

scrubber_remove_method

    scrubber_add_method('Carp::croak');

scrubber_add_package

scrubber_remove_package

    # Use with caution, it overrides EVERYTHING in the package.  It's usually better to override methods with scrubber_add_method.

    scrubber_add_package('Carp');

LOCAL SCOPING

The scrubber can be locally modified.

  use Log::Scrubber qw($SCRUBBER);
  # setup the scrubber
  {
    local $SCRUBBER;
    # modify scrubber as needed
  }
  # scrubber is now restored back to what it was

EXPORT

Many. The methods are exported or overridden according to this

  $SIG{__WARN__}     - Always overridden
  $SIG{__DIE__}      - Always overridden
  warnings::warn()   - Always overridden
  warnings::warnif() - Always overridden

  Carp::croak()      - Only exported with :Carp or :all
  Carp::carp()       - Only exported with :Carp or :all
  Carp::confess()    - Only exported with :Carp or :all
  Carp::cluck()      - Only exported with :Carp or :all

  main::syslog()     - Only exported with :Syslog or :all

  Custom::method()   - Custom methods can also be overridden.

AUTHOR

Jason Terry <oaxlin@cpan.org>

SEE ALSO

perl(1), Carp(3), warnings(3), Sys::Syslog(3), Unix::Syslog(3)