CGI::IDS::Whitelist - Whitelist Processor for PerlIDS - Perl Website Intrusion Detection System (XSS, CSRF, SQLI, LFI etc.)
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.
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; } }
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.
is_suspicious()
suspicious_keys()
non_suspicious_keys()
reset()
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.
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 );
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"]}');
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();
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();
DESCRIPTION resets the member variables suspicious_keys and non_suspicious_keys to [] INPUT none OUTPUT none SYNOPSIS $whitelist->reset();
DESCRIPTION Performs a basic regexp check for harmless characters INPUT + string OUTPUT BOOLEAN (pattern match return value) SYNOPSIS $whitelist->is_harmless_string( $string );
DESCRIPTION Encodes string to UTF-8 and strips malformed UTF-8 characters INPUT + string OUTPUT UTF-8 string SYNOPSIS $whitelist->make_utf_8( $string );
see "BUGS" in CGI::IDS and "SUPPORT" in CGI::IDS
Hinnerk Altenburg, <hinnerk at cpan.org>
<hinnerk at cpan.org>
CGI::IDS
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/>.
To install CGI::IDS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::IDS
CPAN shell
perl -MCPAN -e shell install CGI::IDS
For more information on module installation, please visit the detailed CPAN module installation guide.