# Licensed to Elasticsearch B.V. under one or more contributor
# license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright
# ownership. Elasticsearch B.V. licenses this file to you under
# the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# 	http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
---
- name: network
  title: Network
  group: 2
  short: Fields describing the communication path over which the event happened.
  description: >
    The network is defined as the communication path over which a host or network event happens.

    The network.* fields should be populated with details about the network activity associated with an event.
  type: group
  fields:

    - name: name
      level: extended
      type: keyword
      description: >
        Name given by operators to sections of their network.
      example: Guest Wifi

    - name: type
      level: core
      type: keyword
      short: In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc
      description: >
        In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc

        The field value must be normalized to lowercase for querying.
      example: ipv4

    - name: iana_number
      level: extended
      type: keyword
      short: IANA Protocol Number.
      description: >
          IANA Protocol Number (https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml).
          Standardized list of protocols. This aligns well with NetFlow and
          sFlow related logs which use the IANA Protocol Number.
      example: 6

    - name: transport
      level: core
      type: keyword
      short: Protocol Name corresponding to the field `iana_number`.
      description: >
        Same as network.iana_number, but instead using the Keyword name of the
        transport layer (udp, tcp, ipv6-icmp, etc.)

        The field value must be normalized to lowercase for querying.
      example: tcp

    - name: application
      level: extended
      type: keyword
      short: >
        Application level protocol name.
      description: >
        When a specific application or service is identified from network
        connection details (source/dest IPs, ports, certificates, or
        wire format), this field captures the application's or service's name.

        For example, the original event identifies the network connection being
        from a specific web service in a `https` network connection, like
        `facebook` or `twitter`.

        The field value must be normalized to lowercase for querying.
      example: aim

    - name: protocol
      level: core
      type: keyword
      short: Application protocol name.
      description: >
        In the OSI Model this would be the Application Layer protocol. For
        example, `http`, `dns`, or `ssh`.

        The field value must be normalized to lowercase for querying.
      example: http

    - name: direction
      level: core
      type: keyword
      short: Direction of the network traffic.
      description: >
        Direction of the network traffic.

        When mapping events from a host-based monitoring context, populate this
        field from the host's point of view, using the values "ingress" or "egress".

        When mapping events from a network or perimeter-based monitoring context,
        populate this field from the point of view of the network perimeter,
        using the values "inbound", "outbound", "internal" or "external".

        Note that "internal" is not crossing perimeter boundaries, and is meant
        to describe communication between two hosts within the perimeter. Note also
        that "external" is meant to describe traffic between two hosts that are
        external to the perimeter. This could for example be useful for ISPs or
        VPN service providers.
      expected_values:
        - ingress
        - egress
        - inbound
        - outbound
        - internal
        - external
        - unknown
      example: inbound

    - name: forwarded_ip
      level: core
      type: ip
      description: >
        Host IP address when the source IP address is the proxy.
      example: 192.1.1.2

    - name: community_id
      level: extended
      type: keyword
      short: A hash of source and destination IPs and ports.
      description: >
        A hash of source and destination IPs and ports, as well as the protocol
        used in a communication. This is a tool-agnostic standard to identify
        flows.

        Learn more at https://github.com/corelight/community-id-spec.
      example: '1:hO+sN4H+MG5MY/8hIrXPqc4ZQz0='

    # Metrics
    - name: bytes
      level: core
      type: long
      format: bytes
      short: Total bytes transferred in both directions.
      description: >
        Total bytes transferred in both directions.

        If `source.bytes` and `destination.bytes` are known, `network.bytes` is their sum.
      example: 368

    - name: packets
      level: core
      type: long
      short: Total packets transferred in both directions.
      description: >
        Total packets transferred in both directions.

        If `source.packets` and `destination.packets` are known, `network.packets` is their sum.
      example: 24

    # q-in-q vlan fields for identifying 802.1q nested vlans
    - name: inner
      level: extended
      type: object
      short: Inner VLAN tag information
      description: >
        Network.inner fields are added in addition to network.vlan fields to describe
        the innermost VLAN when q-in-q VLAN tagging is present. Allowed fields include
        vlan.id and vlan.name. Inner vlan fields are typically used when sending traffic
        with multiple 802.1q encapsulations to a network sensor (e.g. Zeek, Wireshark.)