/ 
CGI-IDS-1.0217
River stage zero No dependents
/ CGI::IDS::Whitelist

NAME

CGI::IDS::Whitelist - Whitelist Processor for PerlIDS - Perl Website Intrusion Detection System (XSS, CSRF, SQLI, LFI etc.)

DESCRIPTION

Whitelist Processor for PerlIDS (CGI::IDS). Performs a basic string check and the whitelist check. See section "Whitelist" in CGI::IDS for details on setting up a whitelist file. CGI::IDS::Whitelist may also be used standalone without CGI::IDS to check whether a request has suspicious parameters at all before handing it over to CGI::IDS. This may be the case if you let worker servers do the more expensive CGI::IDS job and only want to send over the requests that have suspicious parameters. See SYNOPSIS for an example.

SYNOPSIS

use CGI;
use CGI::IDS::Whitelist;

$query = new CGI;

my $whitelist = CGI::IDS::Whitelist->new(
  whitelist_file  => '/home/hinnerk/sandbox/ids/cgi-bin/param_whitelist.xml',
);

my @request_keys = keys %$query->Vars;
foreach my $key (@request_keys) {
  if ( $whitelist->is_suspicious(key => $key, request => $query->Vars ) {
    send_to_ids_worker_server( $query->Vars );
    last;
  }
}

METHODS

new()

Constructor. Can optionally take the path to a whitelist file. If whitelist_file is not given, just a basic string check will be performed.

The whitelist will stay loaded during the lifetime of the object. You may call is_suspicious() multiple times, the collecting debug arrays suspicious_keys() and non_suspicious_keys() will only be emptied by an explizit reset() call.

For example, the following are valid constructors:

my $whitelist = CGI::IDS::Whitelist->new(
    whitelist_file  => '/home/hinnerk/sandbox/ids/cgi-bin/param_whitelist.xml',
);

my $whitelist = CGI::IDS::Whitelist->new();

The Constructor dies (croaks) if a whitelist parsing error occurs.

is_suspicious()

DESCRIPTION
  Performs the whitelist check for a given request parameter.
INPUT
  HASHREF
    + key       The key of the request parameter to be checked
    + request   HASHREF to the complete request (for whitelist conditions check)
OUTPUT
  1 if you should check it with the complete filter set,
  0 if harmless or sucessfully whitelisted.
SYNOPSIS
  $whitelist->is_suspicious( key => 'mykey', request => $request );

convert_if_marked_encoded()

DESCRIPTION
  Tries to JSON-decode and flatten a value to a plain string if the key has been marked as JSON in the whitelist.
  Other encodings may follow in future.
INPUT
  HASHREF
    + key
    + value
OUTPUT
  The JSON-decoded and flattened 'value' if key is marked JSON. Plain keys and values, newline separated.
  Untouched 'value' otherwise.
SYNOPSIS
  $whitelist->convert_if_marked_encoded( key => 'data', value => '{"a":"b","c":["123", 111, "456"]}');

suspicious_keys()

DESCRIPTION
  Returns the set of filters that are suspicious
  Keys are listed from the last reset() or Whitelist->new()
INPUT
  none
OUTPUT
  [ { 'value' => , 'reason' => , 'key' =>  }, { ... } ]
SYNOPSIS
  $whitelist->suspicious_keys();

non_suspicious_keys()

DESCRIPTION
  Returns the set of filters that have been checked but are not suspicious
  Keys are listed from the last reset() or Whitelist->new()
INPUT
  none
OUTPUT
  [ { 'value' => , 'reason' => , 'key' =>  }, { ... } ]
SYNOPSIS
  $whitelist->non_suspicious_keys();

reset()

DESCRIPTION
  resets the member variables suspicious_keys and non_suspicious_keys to []
INPUT
  none
OUTPUT
  none
SYNOPSIS
  $whitelist->reset();

is_harmless_string()

DESCRIPTION
  Performs a basic regexp check for harmless characters
INPUT
  + string
OUTPUT
  BOOLEAN (pattern match return value)
SYNOPSIS
  $whitelist->is_harmless_string( $string );

make_utf_8()

DESCRIPTION
  Encodes string to UTF-8 and strips malformed UTF-8 characters
INPUT
  + string
OUTPUT
  UTF-8 string
SYNOPSIS
  $whitelist->make_utf_8( $string );

BUGS & SUPPORT

see "BUGS" in CGI::IDS and "SUPPORT" in CGI::IDS

AUTHOR

Hinnerk Altenburg, <hinnerk at cpan.org>

SEE ALSO

CGI::IDS

COPYRIGHT & LICENSE

Copyright (C) 2014 Hinnerk Altenburg (http://www.hinnerk-altenburg.de/)

This file is part of PerlIDS.

PerlIDS is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

PerlIDS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with PerlIDS. If not, see <http://www.gnu.org/licenses/>.