Skip to main content

Function Library — Network

C.Net covers address classification and CIDR arithmetic for JavaScript scripts. Every function operates on the string it is given — none of them resolves a name or opens a connection.

FunctionSignatureReturns
cidrMatch(range, address)true where the address falls inside the CIDR range
isIp(value)true for any valid IPv4 or IPv6 address
isIpV4(value)true for a valid IPv4 address
isIpV6(value)true for a valid IPv6 address
isIPV4Cidr(value)true for a valid IPv4 CIDR range
isIPV6Cidr(value)true for a valid IPv6 CIDR range
isPrivate(address)true for an RFC 1918 address
isIpV4AllInterfaces(value)true for 0.0.0.0
isIpV6AllInterfaces(value)true for the IPv6 unspecified address
ipv6Normalize(address)The canonical short form of an IPv6 address
communityIDv1(sourceIp, destIp, sourcePort, destPort, protocol, seed)A Community ID flow hash
parseAddressOrRangeString(source, mask)An object describing the address
IPv4_CIDR_REGEX—A regular expression matching an IPv4 CIDR range

Details​

Matching and Classification​

cidrMatch() returns false rather than throwing for anything it cannot use — a malformed range, a malformed address, or an address and range from different families. Test the inputs separately where you need to tell "no match" from "not an address".

Tag traffic from a known subnet...

- script:
    lang: js
    source: |
        const ip = __e['source.ip'];
        if (C.Net.isIp(ip)) {
          __e.internal = C.Net.cidrMatch('10.0.0.0/8', ip);
        }

isIpV6() treats IPv4-mapped forms such as ::ffff:1.2.3.4 as IPv6.

warning

isPrivate() covers IPv4 only, and only the three RFC 1918 ranges — 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. It returns false for loopback, link-local, carrier-grade NAT and every IPv6 address, including unique local addresses. Where you need a broader definition, test the ranges you care about with cidrMatch().

Normalization​

ipv6Normalize() returns the RFC 5952 canonical form — lowercase, with the longest run of zero groups collapsed. An address it cannot parse yields an empty string.

C.Net.ipv6Normalize('2001:0db8:0000:0000:0000:0000:0000:0001')   // '2001:db8::1'

Community ID​

communityIDv1() produces the Community ID v1 flow hash, which identifies a network flow identically regardless of which endpoint is treated as the source. Two events describing opposite directions of the same connection therefore receive the same value — the point of using it as a correlation key.

The protocol argument accepts either a number or an IANA keyword (tcp, udp, icmp, icmpv6, gre, esp, sctp and the other standard names). The seed argument is optional and defaults to zero.

ICMP request and reply types are paired, so an echo request and its reply also hash identically.

The function returns null where an address will not parse or the protocol is unrecognized.

Add a flow correlation key...

{
  "source.ip": "1.2.3.4",
  "source.port": 1122,
  "destination.ip": "5.6.7.8",
  "destination.port": 3344,
  "network.transport": "tcp"
}
- script:
    lang: js
    source: |
        __e['network.community_id'] = C.Net.communityIDv1(
          __e['source.ip'], __e['destination.ip'],
          __e['source.port'], __e['destination.port'],
          __e['network.transport']
        );

An event for the reverse direction produces the same value...

{
  "network.community_id": "1:wCb3OG7yAFWelaUydu0D+125CLM="
}

Parsing an Address​

parseAddressOrRangeString() breaks an address, CIDR range or hyphenated range into its parts, returning an object with address, version, subnetMask, cidr and valid keys. It returns null where the address will not parse.

The precedence for the prefix length is worth knowing:

  • A hyphenated range (10.0.0.1-10.0.0.9) uses only the first address, and the mask argument is ignored.
  • A / suffix wins over the mask argument.
  • Otherwise the mask argument applies, given either as a prefix length or, for IPv4, as a dotted-quad netmask.