Network Direction

Enrich Elastic Compatible

Synopsis

Determines network traffic direction by analyzing source and destination IP addresses against defined internal networks.

Schema

- network_direction:
    internal_networks: <string[]>
    source_ip: <string>
    destination_ip: <string>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    internal_networks_field: <ident>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>
    target_field: <ident>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
internal_networks	Y*	-	CIDR ranges defining internal networks
source_ip	N	source.ip	Field containing source IP
destination_ip	N	destination.ip	Field containing destination IP
description	N	-	Documentation note
if	N	-	Conditional expression
ignore_failure	N	false	Skip processing errors
ignore_missing	N	true	Skip if fields missing
internal_networks_field	N	-	Field holding the internal networks. Cannot read a JSON array — see Details. Conditionally required if internal_networks is not set
on_failure	N	-	Error handling processors
on_success	N	-	Success handling processors
tag	N	-	Identifier for logging
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration
target_field	N	network.direction	Output field for direction

* = Conditionally required (see configuration details below)

Details

The processor classifies traffic as inbound, outbound, internal, or external based on whether IPs belong to specified internal networks.

note

Both IPv4 and IPv6 addresses in CIDR notation are supported for internal network definitions.

The processor classifies traffic into four categories:

Inbound	Traffic from external to internal networks
Outbound	Traffic from internal to external networks
Internal	Traffic between internal networks
External	Traffic between external networks

The processor is useful for analyzing network traffic patterns and flows to identify potential security threats, to monitor and log access to internal resources, to track and report on network traffic for compliance requirements, and to validate network segmentation policies.

warning

At least one of internal_networks or internal_networks_field must be specified, and the resulting list must be non-empty, or the processor fails with no internal networks specified.

warning

internal_networks_field cannot read a list that arrived in the event. It accepts only a Go []string, and a JSON array parses to a list of untyped values, so a field like "internal_nets": ["192.168.0.0/16"] fails with internal networks field is not a list of strings rather than being used.

Configure the ranges with internal_networks instead. internal_networks_field is usable only where an earlier step produced a genuine string list.

Examples

Basic

Classifying inbound traffic...	{ "source": {"ip": "128.232.110.120"}, "destination": {"ip": "192.168.1.1"} } - network_direction: internal_networks: ["192.168.0.0/16"]
identifies external to internal:	{ "source": {"ip": "128.232.110.120"}, "destination": {"ip": "192.168.1.1"}, "network": { "direction": "inbound" } }

Outbound

Detecting outbound connections...	{ "source": {"ip": "192.168.1.1"}, "destination": {"ip": "128.232.110.120"} } - network_direction: internal_networks: ["192.168.0.0/16"]
identifies internal to external:	{ "source": {"ip": "192.168.1.1"}, "destination": {"ip": "128.232.110.120"}, "network": { "direction": "outbound" } }

Internal

Monitoring internal network traffic...	{ "source": {"ip": "192.168.1.1"}, "destination": {"ip": "192.168.2.1"} } - network_direction: internal_networks: ["192.168.0.0/16"]
identifies internal communication:	{ "source": {"ip": "192.168.1.1"}, "destination": {"ip": "192.168.2.1"}, "network": { "direction": "internal" } }

External

Monitoring external traffic...	{ "source": {"ip": "128.232.110.120"}, "destination": {"ip": "203.0.113.5"} } - network_direction: internal_networks: ["192.168.0.0/16"]
identifies external routing:	{ "source": {"ip": "128.232.110.120"}, "destination": {"ip": "203.0.113.5"}, "network": { "direction": "external" } }

Named Ranges

Listing the ranges on the processor rather than in the event...	{ "source": {"ip": "128.232.110.120"}, "destination": {"ip": "192.168.1.1"} } - network_direction: internal_networks: ["192.168.0.0/16"]
resolves the direction against them:	{ "source": {"ip": "128.232.110.120"}, "destination": {"ip": "192.168.1.1"}, "network": { "direction": "inbound" } }