NAME

Net::Silk::Pmap - SiLK Prefix Map interface

SYNOPSIS

  use Net::Silk::Pmap;
  use Net::Silk::IPSet;

  my $addys  = Net::Silk::IPSet->load("netblocks.set");
  my $labels = Net::Silk::Pmap->load("services.pmap");

  while (my $ip = <$addys>) {
    my $svc = $labels{$ip}; # or $labels->get($ip)
    print "$ip $svc" unless $svc eq 'UNKNOWN';
  }

  while (my $entry = <$labels>) {
    my($range, $label) = @$entry;
    my $block = Net::Silk::IPSet->new($range);
    if ($block && $addys) {
      # intersects
      print "$range $label\n";
    }
  }

  # or build from scratch

  my $pm = Net::Silk::IPSet::IPv4->new(
    name    => "my ipv4",
    default => "external",
  );
  $pm->add("1.2.2.1", "1.2.3.255" => "lab servers");
  $pm->add("5.6.7.8/27" => "wombat enclave");
  $pm->add("10.11.1.1-10.11.1.255" => "front office");
  $pm->save("my_addys.pmap");

DESCRIPTION

Net::Silk::Pmap objects are an interface to SiLK Prefix Maps. Prefix maps are an immutable mapping from IP addresses or protocol/port pairs to labels. Pmap objects are created from SiLK prefix map files which in turn are created by rwpmapbuild(1).

METHODS

new(%parms)

Note that a more typical usage is to invoke new() from the specific class for the pmap type of interest, notably one of Net::Silk::Pmap::IPv4, Net::Silk::Pmap::IPv6, or Net::Silk::Pmap::ProtoPort.

Parameters passed to new() can be any of:

type

Type of pmap to create, one of 'ipv4', 'ipv6', or 'protoport'. See above about using type-specific classes instead. Defaults to 'ipv4'.

name

Optional name of this pmap.

default

Default label for unspecified ranges. Defaults to 'UNKNOWN'.

load($pmap_file)

Returns a new Net::Silk::Pmap::IPv4, Net::Silk::Pmap::IPv6, or Net::Silk::Pmap::ProtoPort object, depending what type of keys the file uses for its pmap.

get_name()

Return the name of this pmap.

get_type()

Return the type of this pmap, one of 'ipv4', 'ipv6', or 'protoport'.

get($proto, $port)
get($ip_or_pp)

Returns the label for the given IP address or protocol/port pair. For the single argument version, the key can be a Net::Silk::IPAddr object or a Net::Silk::ProtoPort object, or a string representation of either.

get_range($key)

Return a Net::Silk::Range object representing the range containing the given key with high and low Net::Silk::IPAddr or Net::Silk::ProtoPort values.

add($range_or_cidr, $label)
add($lo, $hi, $label)

Add a label to a range, specified either as a Net::Silk::CIDR or Net::Silk::Range object, string (IP range or cidr, or port/proto pair) or as the low and hi values. NOTE: Nested ranges are allowed as long as the larger range is added first. The add_all() method will properly sort these for you. Overlapping ranges are not allowed.

add_all(\@ranges)

Add a list of ranges and their associated labels to the pmap, properly sorting them along the way such that larger ranges are added first. Each entry to be added can be one of [$range_or_cidr, $label], [[$hi, $low], $label], or [$hi, $lo, $label].

iter_ranges()
iter()

Returns a sub ref iterator. Each invocation returns Net::Silk::Range key paired with a label. The first/last pairs in the range object are one of Net::Silk::IPAddr or Net::Silk::ProtoPort objects depending on the type of pmap file. Using the IO operator <$pm> on the pmap reference will also iterate over range/label values. See on of the ip-specific classes for cidr_iter(). The iterator will return all values if invoked in list context. Using the pmap as a filehandle with <$pmap> will return the same values.

iter_vals()

Returns a sub ref iterator that returns each label value in the pmap. The iterator returns all values when invoked in list context.

iter_keys()

Returns a sub ref iterator that returns a Net::Silk::Range key for each range present in the pmap. The iterator returns all keys when invoked in list context.

invert()

For an IP address pmap, return a hash that maps labels to Net::Silk::IPSet objects representing the all of the IP ranges for that label. For a protocol/port pmap, return a hash mapping labels to a list of all the proto/port ranges for that label.

IPv4 AND IPv6 METHODS

The Net::Silk::Pmap::IPv4 and Net::Silk::Pmap::IPv6 classes have some additional methods specific to IP addresses:

iter_cidr()

Returns a sub ref that when invoked returns an array ref containing a Net::Silk::CIDR block along with its associated label. The iterator will return all pairs when invoked in list context.

get_cidr($key)

Return a Net::Silk::CIDR object representing the block containing the given IP address.

OPERATORS

The IO operator <> works on Net::Silk::Pmap references, returning the same results as the iterator returned from the iter() method.

TIED HASH

The pmap reference can be treated as a hash reference, so that $pmap->{$key}, keys %$pmap, etc, work as expected.

SEE ALSO

Net::Silk, Net::Silk::RWRec, Net::Silk::IPSet, Net::Silk::Bag, Net::Silk::IPWildcard, Net::Silk::Range, Net::Silk::CIDR, Net::Silk::IPAddr, Net::Silk::TCPFlags, Net::Silk::ProtoPort, Net::Silk::File, Net::Silk::Site, silk(7)

COPYRIGHT & LICENSE

Copyright (C) 2011-2016 by Carnegie Mellon University

Use of the Net-Silk library and related source code is subject to the terms of the following licenses:

GNU General Public License (GPL) Rights pursuant to Version 2, June 1991 Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013

NO WARRANTY

See GPL.txt and LICENSE.txt for more details.