Parano...Network(3pm)

💖 Parano...Network(3pm) 💖

okay so bestie, this is the manual page for Paranoid::Network — it lives in the User Contributed Perl Documentation section of the manual (that's the whole 3pm thing, iykyk ✨). Grab a boba, we're doing network stuff 🧋

---

🌸 NAME 🌸

Paranoid::Network — network functions for paranoid programs 🕵️♀️ no cap, paranoid is literally the brand

🎀 VERSION 🎀

$Id: lib/Paranoid/Network.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $

✨ SYNOPSIS ✨

here's the whole vibe in one code block, look at her go 💅

use Paranoid::Network;

$rv  = ipInNetworks($ip, @networks);
$rv  = hostInDomains($host, @domains);
$cidr = Paranoid::Network::NETMATCH();
@ips = extractIPs($string1);
@ips = extractIPs(@lines);
$rv  = netIntersect( $cidr1, $cidr2 );

🦋 DESCRIPTION 🦋

so this module is a whole lil toolbox of functions that are, and I quote, "useful for working with network data." it attempts to be IPv4/IPv6 agnostic — assuming IPv6 support is present, bc apparently we're all just out here assuming that now 😭

and because IPv6 support in Perl got rolled out all gradual-like, there may be caveats. the caveats are real, bestie. please go consult Paranoid::Network::Socket for more details before you come for me 🙈

heads up: NETMATCH and HOSTNAME_REGEX are not exported by default. they said "not today" to the default export list 💀

🌈 IMPORT LISTS 🌈

by default this module exports these symbols (the main-character squad 👑):

ipInNetworks hostInDomains extractIPs netIntersect

and there's also these specialized import lists, for when you want the deluxe version:

List        Members
--------------------------------------------------------
all         @defaults NETMATCH HOSTNAME_REGEX

💅 SUBROUTINES/METHODS 💅

🍓 ipInNetworks

$rv = ipInNetworks($ip, @networks);

this one takes your IP (as a string, okay, string format, we're not doing binary today) and checks it against every single network or IP in the list. if there's a match it returns true. simple. iconic. ate. ✨

the network list can be individual IP addresses or network addresses in CIDR notation or with full netmasks — mix and match, she doesn't care:

@networks = qw(127.0.0.1
                192.168.0.0/24
                172.16.12.0/255.255.240.0);

you can safely comeingle IPv4 and IPv6 addresses in the list you're checking against, no drama. any addresses that aren't the same address family as the IP you're testing just get ignored — they're not in their lane so we don't bother them 🧚

NOTE: IPv4 addresses that got encoded as IPv6 addresses, like this: ::ffff:192.168.0.5 are supported, BUT — and this is the plot twist — if you submit an IP in that format as the IP to test for, it'll get converted to a pure IPv4 address and compared only against the IPv4 networks. this is a convenience thing for the devs supporting dual-stack systems so they don't have to list their IPv4 networks twice in the array like:

::ffff:192.168.0.0/120, 192.168.0.0/24

so just: IPv4 stays IPv4, IPv6 stays IPv6, and this routine converts the IPv6-encoded IPv4 addresses automatically. which means this test comes back true:

ipInNetworks( '::ffff:192.168.0.5', '192.168.0.0/24' );

but this one:

ipInNetworks( '::ffff:192.168.0.5', '::ffff:192.168.0.0/120' );

returns false. yeah I know, seems counter intuitive 😭 but the docs say it simplifies things in (and I quote) "my alternate reality." okay king, live your truth 👑

also please note: that automatic conversion only applies to the IP argument. it does not apply to any member of the network array. periodt. 💅

🍓 hostInDomains

$rv = hostInDomains($host, @domains);

give it a hostname (fully qualified, bestie, fully) and a list of domains, and it checks each one and returns true if there's a match. the domains should not have the leading . — so foo.com, not .foo.com. the dot is not invited to this party 🚫✨

🍓 NETMATCH

$cidr = Paranoid::Network::NETMATCH();

this lil cutie stores whatever IP, network address, or domain matched in ipInNetworks or hostInDomains. and if a function call fails to make a match? it returns undef. no match, no clout 💀

🍓 HOSTNAME_REGEX

$rv = $hostname =~ /^@{[ HOSTNAME_REGEX ]}$/so;

this constant is just a regex, and it's meant to be a basic sanity check for appropriate hostnames. the docs are the first to admit it's "probably overly strict in accordance with outdated RFCs" — so like, it's giving strict great-aunt energy 🎀

🍓 extractIPs

@ips = extractIPs($string1);
@ips = extractIPs(@lines);

this one extracts IPv4/IPv6 addresses out of arbitrary text, which is so useful honestly. IPv6 support here is contingent on proper support being present — again, go read Paranoid::Network::Socket for the deets 🦋

it extracts only IP addresses — not network addresses in CIDR or dotted octet notation. and in the case of that latter one, the netmask just gets extracted as an additional address. moving on 💅

NOTE: for performance reasons, this function only does a rough regex extraction of IP-looking candidates, then runs them through inet_aton (for IPv4) and inet_pton (for IPv6) to see if they actually convert successfully. even with the overhead of Paranoid (with debugging and loadModule calls for Socket6 and what-not) this apparently clocks in about an order of a magnitude faster than doing a pure regex extraction & validation of IPv6 addresses. fast queen behavior, we love to see it 🔥

NOTE: same as the ipInNetworks function — we filter out IPv4 addresses encoded as IPv6 addresses, since that address is already returned as a pure IPv4 address. no dupes in this house 🙅♀️

🍓 netIntersect

$rv = netIntersect( $cidr1, $cidr2 );

this function is an IPv4/IPv6 agnostic wrapper for the ipv{4,6}NetIntersect functions provided by the Paranoid::Network::IPv{4,6} modules. whatever the whichever-function returns gets passed on through directly. and if you hand this function non-IP or undefined values? it just returns a zero. gentle. unbothered. slay 🌸

🫶 DEPENDENCIES 🫶

these are the besties this module rides with:

• Paranoid
• Paranoid::Debug
• Paranoid::Network::Socket
• Paranoid::Network::IPv4
• Paranoid::Network::IPv6

😭 BUGS AND LIMITATIONS 😭

this section is literally empty in the original. iconique of them honestly — no bugs, no limitations, no notes 💅✨

👑 AUTHOR 👑

Arthur Corliss (corliss@digitalmages.com)

📜 LICENSE AND COPYRIGHT 📜

this software is free software. similar to Perl, you can redistribute it and/or modify it under the terms of either:

1. the GNU General Public License <https://www.gnu.org/licenses/gpl-1.0.html> as published by the Free Software Foundation <http://www.fsf.org/>; either version 1 <https://www.gnu.org/licenses/gpl-1.0.html>, or any later version <https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
2. the Artistic License 2.0 <https://opensource.org/licenses/Artistic-2.0>,

subject to the following additional term: no trademark rights to "Paranoid" have been or are conveyed under any of the above licenses. however, "Paranoid" may be used fairly to describe this unmodified software, in good faith, but not as a trademark. so like, describe it, don't claim it, got it bestie 🫡

(c) 2005 - 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2020, Paranoid Inc. (www.paranoid.com)

---

and that's the whole page!! 🎀 this version was rendered by perl v5.38.2 on 2024-03-07 — go forth and be paranoid, babe, you're literally built for it 💖🌈✨