NAME

       LWPx::ParanoidAgent - subclass of LWP::UserAgent that protects you from harm

SYNOPSIS

        require LWPx::ParanoidAgent;

        my $ua = LWPx::ParanoidAgent->new;

        # this is 10 seconds overall, from start to finish.  not just between
        # socket reads.  and it includes all redirects.  so attackers telling
        # you to download from a malicious tarpit webserver can only stall
        # you for $n seconds

        $ua->timeout(10);

        # setup extra block lists, in addition to the always-enforced blocking
        # of private IP addresses, loopbacks, and multicast addresses

        $ua->blocked_hosts(
           "foo.com",
           qr/\.internal\.company\.com$/i,
           sub { my $host = shift;  return 1 if is_bad($host); },
        );

        $ua->whitelisted_hosts(
           "brad.lj",
           qr/^192\.168\.64\.3?/,
           sub { ... },
        );

        # get/set the DNS resolver object that's used
        my $resolver = $ua->resolver;
        $ua->resolver(Net::DNS::Resolver->new(...));

        # and then just like a normal LWP::UserAgent, because it is one.
        my $response = $ua->get('http://search.cpan.org/');
        ...
        if ($response->is_success) {
            print $response->content;  # or whatever
        }
        else {
            die $response->status_line;
        }

DESCRIPTION

       The "LWPx::ParanoidAgent" is a class subclassing "LWP::UserAgent", but paranoid against
       attackers.  It's to be used when you're fetching a remote resource on behalf of a possibly
       malicious user.

       This class can do whatever "LWP::UserAgent" can (callbacks, uploads from files, etc),
       except proxy support is explicitly removed, because in that case you should do your
       paranoia at your proxy.

       Also, the schemes are limited to http and https, which are mapped to
       "LWPx::Protocol::http_paranoid" and "LWPx::Protocol::https_paranoid", respectively, which
       are forked versions of the same ones without the "_paranoid".  Subclassing them didn't
       look possible, as they were essentially just one huge function.

       This class protects you from connecting to internal IP ranges (unless you whitelist them),
       hostnames/IPs that you blacklist, remote webserver tarpitting your process (the timeout
       parameter is changed to be a global timeout over the entire process), and all combinations
       of redirects and DNS tricks to otherwise tarpit and/or connect to internal resources.

CONSTRUCTOR

       "new"
           my $ua = LWPx::ParanoidAgent->new([ %opts ]);

           In addition to any constructor options from LWP::UserAgent, you may also set
           "blocked_hosts" (to an arrayref), "whitelisted_hosts" (also an arrayref), and
           "resolver", a Net::DNS::Resolver object.

METHODS

       $csr->resolver($net_dns_resolver)
       $csr->resolver
           Get/set the Net::DNS::Resolver object used to lookup hostnames.

       $csr->blocked_hosts(@host_list)
       $csr->blocked_hosts
           Get/set the list of blocked hosts.  The items in @host_list may be compiled regular
           expressions (with qr//), code blocks, or scalar literals.  In any case, the thing that
           is match, passed in, or compared (respectively), is all of the given hostname, given
           IP address, and IP address in canonical a.b.c.d decimal notation.  So if you want to
           block "1.2.3.4" and the user entered it in a mix of network/host form in a mix of
           decimal/octal/hex, you need only block "1.2.3.4" and not worry about the details.

       $csr->whitelisted_hosts(@host_list)
       $csr->whitelisted_hosts
           Like blocked hosts, but matching the hosts/IPs that bypass blocking checks.  The only
           difference is the IP address isn't canonicalized before being whitelisted-matched,
           mostly because it doesn't make sense for somebody to enter in a good address in a
           subversive way.

SEE ALSO

       See LWP::UserAgent to see how to use this class.

       http://contributing.appspot.com/lwpx-paranoidagent
       http://brad.livejournal.com/2409049.html
       https://github.com/collectiveintel/LWPx-ParanoidAgent
       http://search.cpan.org/dist/LWPx-ParanoidAgent

ISSUES

       Report issues: https://github.com/collectiveintel/LWPx-ParanoidAgent/issues

WARRANTY

       This module is supplied "as-is" and comes with no warranty, expressed or implied.  It
       tries to protect you from harm, but maybe it will.  Maybe it will destroy your data and
       your servers.  You'd better audit it and send me bug reports.

BUGS

       Maybe.  See the warranty above.

COPYRIGHT

        Copyright 2005 Brad Fitzpatrick
        Copyright 2013 Wes Young (wesyoung.me)

       Lot of code from the base class, copyright 1995-2004 Gisle Aas.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.