Overlay

The Netify Overlay feature allows integrators to customize how application classification is presented without changing the underlying Netify detections. This is useful for building higher-level product labels, grouped UX categories, and vendor-specific policy objects.

For a more streamlined user experience (UX), you may want to roll up fine-grained applications like Apple DNS, Apple Search, and Applebot into a single "Apple" tag. You can use this overlay tag in UX, firewalls, QoS, and other flow expressions.

In fact, it is possible to create a custom category solution to meet your needs or to provide a migration path for legacy DPI engines.

Highlights

The overlay introduces a JSON mapping layer that:

Preserves Netify base classifications
Supports custom tag/group structures for OEM and integration use cases
Allows extensible metadata while preserving core schema compatibility
Exposes overlay tags for policy logic in downstream processors

Configuration

Integrators are responsible for creating and deploying the overlay configuration file: /etc/netifyd/overlay.json . The minimum schema is defined below. Additional vendor-defined attributes are acceptable as long as core schema fields remain valid.

Changes to overlay.json require the Netify Agent to be reloaded before they take effect.

Properties

A tag is the highest-level overlay classification. Depending on the deployment, a tag can represent a brand family (for example, grouping related properties) or an internal category layer. Tag names must be:

Unique
Case-insensitive
Composed of letters, numbers, hyphens, or underscores

List of destination ports to match.

criteria.src_ports

array

List of source ports to match.

Overlay Configuration Example

{
  "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": []
          }
        }
      ]
    }
  ]
}

Example

Group criteria attributes accept arrays of integers or strings. For example, to bundle multiple Google and YouTube applications into one group: Google properties.

Place overlay.json in /etc/netifyd/ with permissions that allow the Netify Agent to read it. After reload/restart, new tag.group values appear in flow and aggregate metadata.

{
  "version": "1.0",
  "tags": [
    {
      "tag": "rollup",
      "label": "Rollup",
      "description": "Custom tags for grouping app families.",
      "groups": [
        {
          "group": "google",
          "label": "All Google",
          "description": "Custom tag for all apps from Google.",
          "criteria": {
            "applications": [123, 124, 126, 10005, ...]
          }
        },
        { ... All Apple apps ...},
        { ... All Meta apps ...},
        ...
      ]
    }
  ]
}

Overlay as a Category Alternative

Overlay tagging can also be used as a custom category system.

Full Category Mapping: Mapping categories from other DPI vendors.
More Refined Categorization: Splitting existing Netify categories, e.g. splitting mail into webmail and email.

In the sample below, the tag app-category is used as a category prefix where each group represents a category. Keep application membership unique across groups to avoid ambiguity.

{
  "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 category",
          "criteria": {
            "applications": [1, 2, 3]
          }
        },
        {
          "group": "forums",
          "label": "Forums",
          "description": "Forum category",
          "criteria": {
            "applications": [4, 5, 6]
          }
        }
      ]
    },
    {
      "tag": "tag",
      "label": "Additional tags",
      "description": "Optional supplemental tags"
    }
  ]
}

Telemetry

Your overlay tag will appear in the flow telemetry.

{
  "flow": {
    "tags": [
      "rollup.google"
    ]
  }
}

Expression Engine

Overlay tags can be referenced in the Expression Engine. This means you can use overlay tags in:

Flow Actions for network policies
Custom criteria in Network Intelligence

Example expressions:

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

The last example matches flows that did not match any overlay definition (no tags present).