Skip to content

Commit

Permalink
[7.x] [DOCS] Network direction processor (#67943) (#70413)
Browse files Browse the repository at this point in the history
  • Loading branch information
danhermann authored Mar 15, 2021
1 parent 930f937 commit b0576bd
Show file tree
Hide file tree
Showing 2 changed files with 119 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/reference/ingest/ingest-node.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -895,6 +895,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[]
Expand Down
118 changes: 118 additions & 0 deletions docs/reference/ingest/processors/network-direction.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
[role="xpack"]
[testenv="basic"]
[[network-direction-processor]]
=== Network direction processor
++++
<titleabbrev>Network Direction</titleabbrev>
++++

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": {
...
"_type": "_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

0 comments on commit b0576bd

Please sign in to comment.