diff --git a/docs/reference/ingest/ingest-node.asciidoc b/docs/reference/ingest/ingest-node.asciidoc index 2f13d7e7ed1c1..e0dc93aecc2a0 100644 --- a/docs/reference/ingest/ingest-node.asciidoc +++ b/docs/reference/ingest/ingest-node.asciidoc @@ -890,6 +890,7 @@ include::processors/join.asciidoc[] include::processors/json.asciidoc[] include::processors/kv.asciidoc[] include::processors/lowercase.asciidoc[] +include::processors/network-direction.asciidoc[] include::processors/pipeline.asciidoc[] include::processors/remove.asciidoc[] include::processors/rename.asciidoc[] diff --git a/docs/reference/ingest/processors/network-direction.asciidoc b/docs/reference/ingest/processors/network-direction.asciidoc new file mode 100644 index 0000000000000..21e91cf3e41f9 --- /dev/null +++ b/docs/reference/ingest/processors/network-direction.asciidoc @@ -0,0 +1,117 @@ +[role="xpack"] +[testenv="basic"] +[[network-direction-processor]] +=== Network direction processor +++++ +Network Direction +++++ + +Calculates the network direction given a source IP address, destination IP +address, and a list of internal networks. + +The network direction processor reads IP addresses from +{ecs-ref}[Elastic Common Schema (ECS)] fields by default. If you use the ECS, +only the `internal_networks` option must be specified. + +[[network-direction-options]] +.Network Direction Options +[options="header"] +|====== +| Name | Required | Default | Description +| `source_ip` | no | `source.ip` | Field containing the source IP address. +| `destination_ip` | no | `destination.ip` | Field containing the destination IP address. +| `target_field` | no | `network.direction` | Output field for the network direction. +| `internal_networks`| yes | | List of internal networks. Supports IPv4 and +IPv6 addresses and ranges in CIDR notation. Also supports the named ranges listed below. +| `ignore_missing` | no | `true` | If `true` and any required fields are missing, +the processor quietly exits without modifying the document. + + +include::common-options.asciidoc[] +|====== + +[float] +[[supported-named-network-ranges]] +===== Supported named network ranges + +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 "::"). + + +[discrete] +[[network-direction-processor-ex]] +===== Examples + +The following example illustrates the use of the network direction processor: + +[source,console] +---- +POST _ingest/pipeline/_simulate +{ + "pipeline": { + "processors": [ + { + "network_direction": { + "internal_networks": ["private"] + } + } + ] + }, + "docs": [ + { + "_source": { + "source": { + "ip": "128.232.110.120" + }, + "destination": { + "ip": "192.168.1.1" + } + } + } + ] +} +---- + +Which produces the following result: + +[source,console-result] +---- +{ + "docs": [ + { + "doc": { + ... + "_source": { + "destination": { + "ip": "192.168.1.1" + }, + "source": { + "ip": "128.232.110.120" + }, + "network": { + "direction": "inbound" + } + } + } + } + ] +} +---- +// TESTRESPONSE[s/\.\.\./"_index":"_index","_id":"_id","_ingest":{"timestamp":$body.docs.0.doc._ingest.timestamp},/] +// NOTCONSOLE