The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Parse-Netstat-Search-0.2.1
River stage zero No dependents
++
/ Parse::Netstat::Search

NAME

Parse::Netstat::Search - Searches the connection list in the results returned by Parse::Netstat

VERSION

Version 0.2.1

SYNOPSIS

    use Parse::Netstat::Search;
    use Parse::Netstat qw(parse_netstat);

    my $res = parse_netstat(output => join("", `netstat -n`), flavor=>$^O);

    my $search = Parse::Netstat::Search->new();

    $search->set_cidrs( [ '10.0.0.0/24', '192.168.0.0/16' ] );

    my @found=$search->search($res);

Two big things to bet aware of is this module does not currently resulve names and this module does not handle unix sockets. Unix sockets will just be skipped over.

The connection hashes returned differ from Parse::Netstat slightly. Below is what a standard ones for IPv4/6 looks like.

    {
        'foreign_host'=>'10.0.0.1',
        'local_host'=>'10.0.0.2',
        'foreign_port'=>'22222',
        'local_port'=>'22',
        'sendq'=>'0',
        'recvq'=>'0',
        'state' => 'ESTABLISHED',
        'proto' => 'tcp4',
    }

This module has two additional keys, "local_pp" and "foreign_pp". Which contains and data after % in a address. So "fe80::1%lo0" would be split into "fe80::1" and "lo0" as in the example below.

     {
        'state' => '',
        'foreign_host' => '*',
        'local_port' => '123',
        'proto' => 'udp6',
        'foreign_pp' => undef,
        'foreign_port' => '*',
        'local_host' => 'fe80::1',
        'recvq' => '44',
        'local_pp' => 'lo0',
        'sendq' => '33'
    }

methods

new

This initiates it.

No values are taken.

    my $search=Parse::Netstat::Search->new;

get_cidrs

Retrieves the CIDR match list.

The returned value is an array.

    my @CIDRs=$search->get_cidrs;

get_cidrs_invert

Gets the invert status of the CIDRs search.

    if ( $search->get_cidrs_invert ){
        print "The search will be inverted\n";
    }else{
        print "The search will not be inverted";
    }

get_ports

Gets a list of desired ports.

The returned value is a array. Each item is a port number, regardless of if it was set based on number or service name.

    my @ports=$search->get_ports;

get_ports_invert

Gets the invert status of the ports search.

    if ( $search->get_ports_invert ){
        print "The search will be inverted\n";
    }else{
        print "The search will not be inverted";
    }

get_protocols

Gets a list of desired protocols.

The returned value is a array.

Also if you've passed any named ones to it previously, this will not return them, but the port number as that is how they are stored internlly.

    my @protocols=$search->get_protocols;

get_protocols_invert

Gets the invert status of the protocols search.

    if ( $search->get_protocols_invert ){
        print "The search will be inverted\n";
    }else{
        print "The search will not be inverted";
    }

get_states

Get a list of desired sets.

The returned value is a array.

The returned values are all lowercased. Any trailing or proceeding whitespace will also have been removed.

    my @states=$search->get_states;

get_state_invert

Gets the invert status of the states search.

    if ( $search->get_state_invert ){
        print "The search will be inverted\n";
    }else{
        print "The search will not be inverted";
    }

get_ptrs

Gets the list of PTRs to search for.

The returned value is a array. Each item is a PTR.

    my @PTRs=$search->get_ptrs;

get_ptrs_invert

Gets the invert status of the PTRs search.

    if ( $search->get_ptr_invert ){
        print "The search will be inverted\n";
    }else{
        print "The search will not be inverted";
    }

get_ptrs_r

Gets the list of PTR regexps to search for.

The returned value is a array. Each item is a PTR.

    my @regexps=$search->get_ptrs_r;

get_ptrs_invert

Gets the invert status of the PTRs search.

    if ( $search->get_ptr_invert ){
        print "The search will be inverted\n";
    }else{
        print "The search will not be inverted";
    }

This runs the search results.

    my @found=$search->search( $res );

set_cidrs

This sets the list of CIDRs to search for in either the local or remote field.

One value is taken and that is a array ref of CIDRs.

Validating in is done by Net::CIDR::cidrvalidate.

If you are using this, you will want to use -n with netstat as this module currently does not resolve names.

    # set the desired CIDRs to the contents of @CIDRs
    $search->set_cidrs( \@CIDRs );
    if ( $search->error ){
        warn("Improper CIDR");
    }

    # clear any previously set
    $search->set_cidrs;

set_cidrs_invert

This sets if the CIDRs search should be inverted or not.

One value is taken and that is a boolean.

    # if it does not match, hit on it
    $search->set_cidrs_invert(1);

    # only hit on matches, the default
    $search->set_cidrs_invert; # or...
    $search->set_cidrs_invert(0);

set_ports

This sets the ports to search for in either the local or remote field.

One value is taken and that is a array ref of ports.

The ports can be either numeric or by name.

    # Set the desired ports to the contents of @ports.
    $search->set_ports( \@ports );
    if ( $search->error ){
        warn("Bad value in ports array");
    }

    # removes any previous selections
    $search->set_ports;

set_ports_invert

This sets if the ports search should be inverted or not.

One value is taken and that is a boolean.

    # if it does not match, hit on it
    $search->set_port_invert(1);

    # only hit on matches, the default
    $search->set_port_invert; # or...
    $search->set_port_invert(0);

set_protocols

Sets the list of desired protocols to match.

One value is taken and that is a array.

If this is undef, then previous settings will be cleared.

Lacking of exhaustive list of possible values for the OSes supported by Parse::Netstat, no santity checking is done.

Starting and trailing white space is removed.

    # Set the desired ports to the contents of @protocols.
    $search->set_protocols( \@protocols );

    # removes any previous selections
    $search->set_protocols;

set_protocols_invert

This sets if the protocols search should be inverted or not.

One value is taken and that is a boolean.

    # if it does not match, hit on it
    $search->set_port_invert(1);

    # only hit on matches, the default
    $search->set_protocol_invert; # or...
    $search->set_protocol_invert(0);

set_ptrs

This sets a list of PTRs to search for.

One value is taken and that is a array.

If this is undef, then previous settings will be cleared.

White space, [\ \t], at the start or end of each item is removed. It is then converted to lowercase and saved for later lookup.

    # Set the desired PTRs to the contents of @ptrs.
    $search->set_ptrs( \@ptrs );

    # removes any previous selections
    $search->set_ptrs;

set_ptrs_invert

This sets if the PTRs search should be inverted or not.

One value is taken and that is a boolean.

    # if it does not match, hit on it
    $search->set_ptrs_invert(1);

    # only hit on match, the default
    $search->set_ptrs_invert; # or...
    $search->set_ptrs_invert(0);

set_ptrs_r

This sets a list of PTRs to search for via regexp

One value is taken and that is a array.

If this is undef, then previous settings will be cleared.

    # Set the desired PTRs regexps to the contents of @ptrs.
    $search->set_ptrs_r( \@ptrs );

    # removes any previous selections
    $search->set_ptrs;

set_ptrs_invert

This sets if the regexp PTRs search should be inverted or not.

One value is taken and that is a boolean.

    # if it does not match, hit on it
    $search->set_ptrs_r_invert(1);

    # only hit on match, the default
    $search->set_ptrs_r_invert; # or...
    $search->set_ptrs_r_invert(0);

set_states

Sets the list of desired states to match.

One value is taken and that is a array.

If this is undef, then previous settings will be cleared.

Lacking of exhaustive list of possible values for the OSes supported by Parse::Netstat, no santity checking is done.

Starting and trailing white space is removed.

    # Set the desired ports to the contents of @protocols.
    $search->set_protocols( \@protocols );
    if ( $search->error ){
        warn("Bad value in ports array");
    }

    # removes any previous selections
    $search->set_protocols;

set_ptrs_invert

This sets if the state search should be inverted or not.

One value is taken and that is a boolean.

    # if it does not match, hit on it
    $search->set_state_invert(1);

    # only hit on match, the default
    $search->set_state_invert; # or...
    $search->set_state_invert(0);

ERROR CODES / FLAGS

Error handling is provided by Error::Helper.

1 / badCIDR

Invalid CIDR passed.

Validation is done by Net::CIDR::cidrvalidate.

2 / unknownService

Could not look up the port number for the specified service.

3 / badResults

The passed array does not appear to be properly formatted.

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-parse-netstat-search at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Parse-Netstat-Search. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Parse::Netstat::Search

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2019 Zane C. Bowers-Hadley.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.