Overlay

• Introduction
• JSON Schema
• Usage
• Overlay as a Category Alternative
• Next Steps

Introduction

The Netify Application Overlay enables users and integrators to simplify and customize the presentation layer of application classification. While Netify Agent and by extension, Netify Informatics provides fine-grained visibility for QA, debugging, and analytics, many use cases require higher-level groupings or custom categories for building out intuitive user-facing interfaces.

The overlay feature introduces an overlay mapping layer using JSON that:

• Preserves Netify’s base classification (no interference with Netify Informatics)
• Allows OEMs and integrators to define their own application groupings and labels
• Provides an extensible JSON schema enforced by Netify while allowing vendor-specific attributes
• Supports future features and configurations (e.g., port-based overlays for lightweight deployments)

JSON Schema

It is the responsibility of the integrator to create, maintain and deploy the Netify Application Overlay JSON configuration file. The minimum schema specifications are provided below, but as mentioned above, the end user can customize the document so long as the core schema is preserved.

Version 1.0

{
  "version": "1.0",
  "tags": [
    {
      "tag": "tag",
      "label": "Human-readable name",
      "description": "Tag description",
      "category_id": 1,
      "groups": [
        {
          "group": "group",
          "label": "Group label",
          "description": "Detailed group description",
          "criteria": {
            "applications": [],
            "protocols": [],
            "ip_protocols": [],
            "ports": [],
            "dst_ports": [],
            "src_ports": []
          }
        }
      ]
    }
  ]
}

Tags

A tag represents the highest level classification. In some deployments, it may be used to group common applications togethr (like Google or Meta properties) under a desired label. In an alternative case, it can act as a category.

A tag name must be:

• unique
• case insensitive
• contain only letters, numbers, hyphens or underscores

Label

A short description of the tag.

Description

A longer, more informative description of the tag.

Category ID

The attribute categories_id is optional. It's value will be 0 if not present in the overlay tag definition. The attribute maps to a category as defined in /etc/netifyd/netify-categories.json

Groups

Under each tag, 0 (not useful) or more groups can be defined. Within each group, a criteria attribute (documented below) defines how Netify will assign a flow.

Criteria

When creating a criteria for a group, each attribute accepts an array of Integers or Strings. For example, if the purpose was to bundle all Google and YouTube applications into one entry, it could be defined in a single group:

"applications": [ 123, 124, 126, 10005, 10041, 10205, 10300, 10344, 10705, 10733, 10763, 10909, 10910, 11010, 11239, 11285, 11527, 11807, 11891, 11995, 12025, 12173 ]

netifyd --dump-apps | grep -E "google|youtube"

The implied operators applied to the criteria matching are as follows:

• between criteria attributes, implied AND
• within each attribute, implied OR

Usage

Once the overlay.json file has been defined, it is placed in /etc/netifyd/ with appropriate permissions for the Netify agent to read the file. On reload/restart, new tag>.group attributes will be accessible in flow/aggregate objects.

{
  "flow": {
    ..
    .
    "tags": [
      "google.play"
    ],
    ..
    .
}

Overlay attributes can be referenced in Netify’s Flow Actions PluginFlow Action Plugin criteria. Below are examples of valid criteria syntax.

"criteria": "tag == 'google'"
"criteria": "tag == 'google.gcp'"
"criteria": "tag_category == 'business'"
"criteria": "tag_category_id == 1"
"criteria": "! tag"

This enables simple policy, reporting, or UX filtering on custom overlays without altering the underlying Netify classifications.

Overlay as a Category Alternative

The flexibility of the tagging overlay is further demonstrated by the optional implementation of a custom category alternative to Netify’s Category classification. This sample demonstration is not to be confused with the categories feature (ex. /etc/netifyd/netify-categories.json).

In the sample JSON overlay provided below, we define a tag called “app-category”. Every group defined in this single tag can be considered a category (the prefix). Care should be taken to ensure that regardless of how many groups are defined, an application in the criteria is unique to a group.

{
  "version": "1.0",
  "tags": [
    {
      "tag": "app-category",
      "label": "Top-level application category",
      "description": "Top-level application category system",
      "groups": [
        {
          "group": "social-media",
          "label": "Social Media",
          "description": "Social media blah blah",
          "criteria": {
            "applications": [
              1,
              2,
              3
            ]
          }
        },
        {
          "group": "forums",
          "label": "Forums",
          "description": "Forums blah blah",
          "criteria": {
            "applications": [
              4,
              5,
              6
            ]
          }
        }
        ... snip ...
      ]
    },
    {
      "tag": "tag",
      "label": "Tags group",
      "description": "Blah blah",
    }
}

Next Steps

• Applications
• Protocols