Semantic Metadata Annotation for Network Anomaly Detection

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 8 January 2025.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

[I-D.netana-nmop-network-anomaly-architecture] provides an overall introduction into how anomaly detection is being applied into the IP network domain and which operational data is needed. It approaches the problem space by automating what a Network Engineer would normally do when verifying a network connectivity service. Monitor from different network plane perspectives to understand wherever one network plane affects another negatively.¶

In order to fine tune outlier detection as described in [I-D.netana-nmop-network-anomaly-lifecycle], the results provided as analytical data need to be reviewed by a Network Engineer. Keeping the human out of the monitoring but still involving him in the alert verification loop.¶

This document describes what information is needed to understand the output of the outlier detection for a Network Engineer, but also at the same time is semantically structured that it can be used for outlier detection testing by comparing the results systematically and set a baseline for supervised machine learning which requires labeled operational data.¶

2. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3. Observed Symptoms

In this section observed network symptoms are specified and categorized according to the following scheme:¶

Action:

Which action the network node performed for a packet in the Forwarding Plane, a path or adjacency in the Control Plane or state or statistical changes in the Management Plane. For Forwarding Plane we distinguish between missing, where the drop occurred outside the measured network node, drop and on-path delay, which was measured on the network node. For Control Plane we distinguish between reachability, which refers to a change in the routing or forwarding information base (RIB/FIB) and adjacency which refers to a change in peering or link-layer resolution. For Management Plane we refer to state or statistical changes on interfaces.¶

Reason:

For each action, one or more reasons describe why this action was used. For Drops in Forwarding Plane we distinguish between Unreachable because network layer reachability information was missing, Administered because an administrator configured a rule preventing the forwarding for this packet and Corrupt where the network node was unable to determine where to forward to due to packet, software or hardware error. For on-path delay we distinguish between Minimum, Average and Maximum Delay for a given flow. For Control Plane wherever a the reachability was updated or withdrawn or the adjacency was established or teared down. For Management Plane we distinguish between interfaces states up and down, and statistical errors, discards or unknown protocol counters.¶

Cause:

For each reason one or more cause describe the cause why the network node has chosen that action.¶

Table 1 consolidates for the forwarding plane a list of common symptoms with their Actions, Reasons and Causes.¶

Table 2 consolidates for the control plane a list of common symptoms with their actions, reasons and causess.¶

Table 3 consolidates for the management plane a list of common symptoms with their Actions, Reasons and Causes.¶

4. Semantic Metadata

Metadata adds additional context to data. For instance, in networks the software version of a network node where Management Plane metrics are obtained from as described in[I-D.claise-opsawg-collected-data-manifest]. Where in Semantic Metadata the meaning or ontology of the annotated data is being described. In this section a YANG model is defined in order to provide a structure for the metadata related to anomalies happening in the network. The module is intended to describe the metadata used to "annotate" the operational data collected from the network nodes, which can include time series data and logs, as well as other forms of data that is "time-bounded". The aspects discussed so far in this document are grouped under the concept of "anomaly" which represents a collection of symptoms. The anomaly overall has a set of parameters that describe the overall behavior of the network in a given time-window including all the spotted symptoms (network anomalies).¶

<CODE BEGINS> file "ietf-interfaces-with-symptoms@2024-06-29.yang"

module ietf-interfaces-with-symptoms {
    yang-version 1.1;
    namespace "http://example.org/example-ietf-interfaces-with-symptoms";
    prefix "ifws";

    import ietf-symptom-semantic-metadata {
        prefix "sm";
    }
    import ietf-interfaces {
        prefix "if";
    }

    revision 2024-06-29 {
        description
          "Initial version";
        reference
          "Example: Symptoms Annotated IETF Interface";
    }

    augment "/if:interfaces/if:interface" {
        description
        "Augment interfaces with symptoms";
        uses sm:symptom-group;
    }
    augment "/if:interfaces-state/if:interface" {
        description
         "Augment interfaces with symptoms";
        uses sm:symptom-group;
  }
}

<CODE ENDS>

module: ietf-interfaces
  +--rw interfaces
  |  +--rw interface* [name]
  |     +--rw name                        string
  |     +--rw description?                string
  |     +--rw type                        identityref
  |     +--rw enabled?                    boolean
  |     +--rw link-up-down-trap-enable?   enumeration {if-mib}?
  |     +--ro admin-status                enumeration {if-mib}?
  |     +--ro oper-status                 enumeration
  |     +--ro last-change?                yang:date-and-time
  |     +--ro if-index                    int32 {if-mib}?
  |     +--ro phys-address?               yang:phys-address
  |     +--ro higher-layer-if*            interface-ref
  |     +--ro lower-layer-if*             interface-ref
  |     +--ro speed?                      yang:gauge64
  |     +--ro statistics
  |     |  +--ro discontinuity-time    yang:date-and-time
  |     |  +--ro in-octets?            yang:counter64
  |     |  +--ro in-unicast-pkts?      yang:counter64
  |     |  +--ro in-broadcast-pkts?    yang:counter64
  |     |  +--ro in-multicast-pkts?    yang:counter64
  |     |  +--ro in-discards?          yang:counter32
  |     |  +--ro in-errors?            yang:counter32
  |     |  +--ro in-unknown-protos?    yang:counter32
  |     |  +--ro out-octets?           yang:counter64
  |     |  +--ro out-unicast-pkts?     yang:counter64
  |     |  +--ro out-broadcast-pkts?   yang:counter64
  |     |  +--ro out-multicast-pkts?   yang:counter64
  |     |  +--ro out-discards?         yang:counter32
  |     |  +--ro out-errors?           yang:counter32
  |     +--rw ifws:symptom
  |        +--rw ifws:id?                        yang:uuid
  |        +--rw ifws:event-id?                  yang:uuid
  |        +--rw ifws:description?               string
  |        +--rw ifws:start-time?                yang:date-and-time
  |        +--rw ifws:end-time?                  yang:date-and-time
  |        +--rw ifws:confidence-score?          score
  |        +--rw ifws:concern-score?             score
  |        +--rw ifws:tags* [key]
  |        |  +--rw ifws:key      string
  |        |  +--rw ifws:value    string
  |        +--rw (ifws:pattern)?
  |        |  +--:(ifws:drop)
  |        |  |  +--rw ifws:drop                 empty
  |        |  +--:(ifws:spike)
  |        |  |  +--rw ifws:spike                empty
  |        |  +--:(ifws:mean-shift)
  |        |  |  +--rw ifws:mean-shift           empty
  |        |  +--:(ifws:seasonality-shift)
  |        |  |  +--rw ifws:seasonality-shift    empty
  |        |  +--:(ifws:trend)
  |        |  |  +--rw ifws:trend                empty
  |        |  +--:(ifws:other)
  |        |     +--rw ifws:other                string
  |        +--rw ifws:annotator
  |           +--rw (ifws:annotator-type)
  |           |  +--:(ifws:human)
  |           |  |  +--rw ifws:human        empty
  |           |  +--:(ifws:algorithm)
  |           |     +--rw ifws:algorithm    empty
  |           +--rw ifws:name?              string
  x--ro interfaces-state
     x--ro interface* [name]
        x--ro name               string
        x--ro type               identityref
        x--ro admin-status       enumeration {if-mib}?
        x--ro oper-status        enumeration
        x--ro last-change?       yang:date-and-time
        x--ro if-index           int32 {if-mib}?
        x--ro phys-address?      yang:phys-address
        x--ro higher-layer-if*   interface-state-ref
        x--ro lower-layer-if*    interface-state-ref
        x--ro speed?             yang:gauge64
        x--ro statistics
        |  x--ro discontinuity-time    yang:date-and-time
        |  x--ro in-octets?            yang:counter64
        |  x--ro in-unicast-pkts?      yang:counter64
        |  x--ro in-broadcast-pkts?    yang:counter64
        |  x--ro in-multicast-pkts?    yang:counter64
        |  x--ro in-discards?          yang:counter32
        |  x--ro in-errors?            yang:counter32
        |  x--ro in-unknown-protos?    yang:counter32
        |  x--ro out-octets?           yang:counter64
        |  x--ro out-unicast-pkts?     yang:counter64
        |  x--ro out-broadcast-pkts?   yang:counter64
        |  x--ro out-multicast-pkts?   yang:counter64
        |  x--ro out-discards?         yang:counter32
        |  x--ro out-errors?           yang:counter32
        +--ro ifws:symptom
           +--ro ifws:id?                        yang:uuid
           +--ro ifws:event-id?                  yang:uuid
           +--ro ifws:description?               string
           +--ro ifws:start-time?                yang:date-and-time
           +--ro ifws:end-time?                  yang:date-and-time
           +--ro ifws:confidence-score?          score
           +--ro ifws:concern-score?             score
           +--ro ifws:tags* [key]
           |  +--ro ifws:key      string
           |  +--ro ifws:value    string
           +--ro (ifws:pattern)?
           |  +--:(ifws:drop)
           |  |  +--ro ifws:drop                 empty
           |  +--:(ifws:spike)
           |  |  +--ro ifws:spike                empty
           |  +--:(ifws:mean-shift)
           |  |  +--ro ifws:mean-shift           empty
           |  +--:(ifws:seasonality-shift)
           |  |  +--ro ifws:seasonality-shift    empty
           |  +--:(ifws:trend)
           |  |  +--ro ifws:trend                empty
           |  +--:(ifws:other)
           |     +--ro ifws:other                string
           +--ro ifws:annotator
              +--ro (ifws:annotator-type)
              |  +--:(ifws:human)
              |  |  +--ro ifws:human        empty
              |  +--:(ifws:algorithm)
              |     +--ro ifws:algorithm    empty
              +--ro ifws:name?              string

<CODE BEGINS> file "ietf-symptom-semantic-metadata@2024-06-29.yang"

module ietf-symptom-semantic-metadata {
    yang-version 1.1;
    namespace "urn:ietf:params:xml:ns:yang:ietf-symptom-semantic-metadata";
    prefix sm;

    import ietf-yang-types {
        prefix yang;
        reference
          "RFC 6991: Common YANG Data Types";
    }

  organization "IETF NMOP (Network Management Operations) Working Group";
  contact
    "WG Web:   <http:/tools.ietf.org/wg/netconf/>
     WG List:  <mailto:nmop@ietf.org>

     Authors:  Thomas Graf
               <mailto:thomas.graf@swisscom.com>
               Wanting Du
               <mailto:wanting.du@swisscom.com>
               Alex Huang Feng
               <mailto:alex.huang-feng@insa-lyon.fr>
               Vincenzo Riccobene
               <mailto:vincenzo.riccobene@huawei-partners.com>
               Antonio Roberto
               <mailto:antonio.roberto@huawei.com>";
    description
        "This module defines symptom objects to be used by a network
         anomaly detection system. The defined objects can be used to
         augment operational network collected observability data and
         analytical problem data equally. Describing the observed
         symptoms, confidence and concern scores and outlier patterns.

         Copyright (c) 2023 IETF Trust and the persons identified as
         authors of the code.  All rights reserved.

         Redistribution and use in source and binary forms, with or
         without modification, is permitted pursuant to, and subject
         to the license terms contained in, the Revised BSD License
         set forth in Section 4.c of the IETF Trust's Legal Provisions
         Relating to IETF Documents
         (https://trustee.ietf.org/license-info).

         This version of this YANG module is part of RFC XXXX; see the RFC
         itself for full legal notices.";

    revision 2024-06-29 {
        description
          "Initial version";
        reference
          "RFC XXX: Semantic Metadata Annotation for Network Anomaly Detection";
    }

    typedef score {
      type uint8 {
        range "0 .. 1";
      }
    }

    grouping symptom-group {
        container symptom {
            leaf id {
                type yang:uuid;
                description
                    "Unique ID of the symptom type";
            }
            leaf event-id {
                type yang:uuid;
                description "Reference to the network event this symptom is part of";
            }
            leaf description {
                type string;
                description
                    "Textual description of the symptom";
            }
            leaf start-time {
                type yang:date-and-time;
                description
                    "Date and time indicating the beginning of the symptom";
            }
            leaf end-time {
                type yang:date-and-time;
                description
                    "Date and time indicating the end of the symptom";
            }
            leaf confidence-score {
                type score;
            }
            leaf concern-score {
                type score;
            }
            list tags {
                key "key";
                leaf key {
                    type "string";
                    mandatory "true";
                }
                leaf value {
                    type "string";
                    mandatory "true";
                }
            }
            choice pattern {
                mandatory "false";
                description
                    "Network Plane affected by the symptom";
                case drop {
                    leaf drop {
                        mandatory "true";
                        type empty;
                    }
                }
                case spike {
                    leaf spike {
                        mandatory "true";
                        type empty;
                    }
                }
                case mean-shift {
                    leaf mean-shift {
                        mandatory "true";
                        type empty;
                    }
                }
                case seasonality-shift {
                    leaf seasonality-shift {
                        mandatory "true";
                        type empty;
                    }
                }
                case trend {
                    leaf trend {
                        mandatory "true";
                        type empty;
                    }
                }
                case other {
                    leaf other {
                        type string;
                        mandatory "true";
                        description "specify the type";
                    }
                }
            }
            container annotator {
                choice annotator-type {
                    mandatory "true";
                    case human {
                        leaf human {
                            mandatory "true";
                            type empty;
                        }
                    }
                    case algorithm {
                        leaf algorithm {
                            mandatory "true";
                            type empty;
                        }
                    }
                }
                leaf name {
                    mandatory "false";
                    type string;
                }
            }
        }
    }
}

<CODE ENDS>

5. Security Considerations

The security considerations.¶

6. Implementation status

This section provides pointers to existing open source implementations of this draft. Note to the RFC-editor: Please remove this before publishing.¶

7. Acknowledgements

The authors would like to thank xxx for their review and valuable comments.¶

Authors' Addresses