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/>.

cpanm CGI::IDS

perl -MCPAN -e shell
install CGI::IDS