view release on metacpan or  search on metacpan

lib/Config/IPFilter.pm  view on Meta::CPAN

                sub {
                    $_[0]->lower cmp $_[1]->lower
                        || $_[0]->upper cmp $_[1]->upper;
                }
            )
            )
        {   syswrite $IPFilter, $rule->_as_string . "\n";
        }
        return close $IPFilter;
    }

    sub is_banned {
        my ($s, $ip) = @_;
        return $s->first_rule(
            sub {
                $_->in_range($ip) && $_->access_level < 127;
            }
        ) || ();
    }

    #
    no Moose;
}
1;

=pod

=head1 NAME

Config::IPFilter - Simple, rule-based IP filter

=head1 Synopsis

    use Config::IPFilter;
    my $filter = Config::IPFilter->new;
    my $rule   = $filter->add_rule('89.238.128.0', '89.238.191.255', 127,
                                 'Example range');

    # A list of example IPv4 addresses. IPv6 works too.
    my @ipv4 = qw[89.238.156.165 89.238.156.169 89.238.156.170 89.238.167.84
        89.238.167.86 89.238.167.99];

    # Check a list of ips
    say sprintf '%15s is %sbanned', $_, $filter->is_banned($_) ? '' : 'not '
        for @ipv4;

    # Lower the acces level by one pushes it below our ban threshold
    $rule->decrease_access_level;

    # Check a list of ips
    say sprintf '%15s is %sbanned', $_,
        $filter->is_banned($_) ? 'now ' : 'still not '
        for @ipv4;

You could also load rules directly from an C<ipfilter.dat> file.

=head1 Description

    # Example of a "ipfilter.dat" file
    #
    # All entered IP ranges will be blocked in both directions. Be careful
    # what you enter here. Wrong entries may totally block access to the
    # network.
    #
    # Format:
    # IP-Range , Access Level , Description
    #
    # Access Levels:
    # 127 blocked
    # >=127 permitted

    064.094.089.000 - 064.094.089.255 , 000 , Gator.com

This entry will block the IPs from 064.094.089.000 to 064.094.089.255, i.e.
your code should not connect to any IP in this range.

At the moment only one, read-only access level is implemented; a value at or
below C<127> means that addresses in that range are banned.

=head1 Methods

Here's a list of 'em...

=head2 my $filter = Config::IPFilter->B<new>( )

This builds a new, empty object. There are currently no expected arguments.

=head2 $filter->B<add_rule>( $rule )

This method adds a new L<range|Config::IPFilter::Rule> to the in-memory
ipfilter.

=head2 $filter->B<add_rule>( $lower, $upper, $access_level, $description )

This method coerces the arguments into a new L<rule|Config::IPFilter::Rule>
which is then added to the in-memory ipfilter.

=head2 $filter->B<count_rules>( )

Returns a tally of all loaded L<rule|Config::IPFilter::Rule>s.

=head2 $filter->B<is_empty>( )

Returns a boolean value indicating whether or not there are any
L<rule|Config::IPFilter::Rule>s loaded in the ipfilter.

=head2 $filter->B<clear_rules>( )

Deletes all L<rule|Config::IPFilter::Rule>s from the ipfilter.

=head2 $filter->B<load>( $path )

Slurps an C<ipfilter.dat>-like file and adds the
L<rule|Config::IPFilter::Rule>s found inside to the ipfilter.

=head2 $filter->B<save>( $path )

Stores the in-memory ipfilter to disk.

=head2 $filter->B<is_banned>( $ip )

If C<$ip> is banned, the first L<rule|Config::IPFilter::Rule> in which it was
found below the threshold is returned.

If not, a false value is returned. Currently, rules with an
L<< access_level|Config::IPFilter::Rule/"$filter->B<access_level>( )" >> at or
below C<127> are considered banned.

=head1 IPv6 Support