[pkg/ottl] Add "NetworkDirection" converter

[michalpristas]

Description

NetworkDirection function calculates the network direction given a source IP address, destination IP address, and a list of internal networks.
Returned value is one of following strings: internal,external,inbound,outbound.

sourceIP is a getter that returns string, destinationIP is a getter that returns string and internal_networks is an optional array of strings.

The named ranges supported for the internal_networks option are:

• loopback - Matches loopback addresses in the range of 127.0.0.0/8 or ::1/128.
• unicast or global_unicast - Matches global unicast addresses defined in RFC 1122, RFC 4632, and RFC 4291 with the exception of the IPv4 broadcast address (255.255.255.255). This includes private address ranges.
• multicast - Matches multicast addresses.
• interface_local_multicast - Matches IPv6 interface-local multicast addresses.
• link_local_unicast - Matches link-local unicast addresses.
• link_local_multicast - Matches link-local multicast addresses.
• private - Matches private address ranges defined in RFC 1918 (IPv4) and RFC 4193 (IPv6).
• public - Matches addresses that are not loopback, unspecified, IPv4 broadcast, link local unicast, link local multicast, interface local multicast, or private.
• unspecified - Matches unspecified addresses (either the IPv4 address "0.0.0.0" or the IPv6 address

Link to tracking issue

Related: #31930

Testing

Unit tests and e2e test case added

Documentation

Updated pkt/ottl/ottfuncs/README.md with examples

[evan-bradley]

@michalpristas Could you give a bit more context on when users want to determine the network direction? Since this returns an enumerable set of values, ideally we should align this with something in the OTel semantic conventions if possible.

[michalpristas]

@evan-bradley we provide this with elasticsearch and i can imagine use cases in security world / network analysis
simple use case, you want to query all external traffic for a time period you have alert for.

suricata supports filters like this in a funny way: https://docs.suricata.io/en/latest/rules/intro.html#direction
zeek as well: https://docs.zeek.org/en/lts/scripts/base/utils/directions-and-hosts.zeek.html

[evan-bradley]

Really appreciate the details, thank you.

I'm still a little concerned about how this fits in with other OTel data. In particular, the experimental network semantic conventions define a direction attribute that has a different definition than the definition here. Would you be willing to open an issue proposing this network boundary value in the semantic conventions repo to see if we can get some alignment on where this fits and maybe if we should use a different term than "direction"?

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 14 days.