# Netify Agent v5 Full Documentation

This document contains the complete reference, guides, and JSON schemas for the Netify Agent v5.

---

# Integration API

## Netify Integration API

### Integration API: OpenAPI Specification
```yaml
openapi: 3.1.0
info:
  title: Netify Integration API
  description: |
    The Netify integration APIs provide programmatic access to the data used by the Netify Agent: applications,
    protocols, intelligence, signatures, and licensing objects. These endpoints supply catalogs, category mappings,
    changelogs, and brand assets that are commonly used by UIs and orchestration systems.
  version: 2.0.0
servers:
  - url: https://agents.netify.ai/api/v2/integrator
    description: Agents integration server
tags:
  - name: Applications
    description: Application catalog, categories, and changelogs.
  - name: Protocols
    description: Protocol catalog, categories, and release logs.
  - name: Intelligence
    description: Intelligence drivers, categories, and release logs.
  - name: Licenses
    description: License lifecycle management and provisioning.
  - name: Signatures
    description: Direct access to signature and category data files.

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

  schemas:
    StatusResponse:
      type: object
      required:
        - status_code
        - status_message
      properties:
        status_code:
          oneOf:
            - type: integer
            - type: string
          description: A numeric status code (0 for success) or a padded string for extended error codes.
        status_message:
          type: string
          description: A human-readable status message.
      example:
        status_code: 0
        status_message: Success.

    ErrorResponse:
      type: object
      required:
        - status_code
        - status_message
      properties:
        status_code:
          oneOf:
            - type: integer
            - type: string
          description: A numeric error code or a padded string for extended error codes.
        status_message:
          type: string
          description: A human-readable error message.
      example:
        status_code: "403.000"
        status_message: Forbidden.

    ApplicationChangelogEntry:
      type: object
      required:
        - application
        - type
        - signature_updated
        - date
      properties:
        application:
          $ref: '#/components/schemas/Application'
        type:
          type: string
          description: The type of change.
          enum:
            - added
            - updated
            - deleted
        signature_updated:
          type: boolean
          description: Indicates if the application signatures were updated.
        date:
          type: string
          description: The change release date.
          format: date

    HomePage:
      type: object
      required:
        - url
        - text
      properties:
        url:
          type: string
          description: URL for the home page.
        text:
          type: string
          description: Anchor text for the home page.

    Application:
      type: object
      required:
        - id
        - tag
        - label
        - description
        - home_page
        - category
        - active
        - favicon
        - icon
        - logo
        - favicon_source
        - icon_source
        - logo_source
      properties:
        id:
          type: integer
          description: The ID number associated with the application.
        tag:
          type: string
          description: The tag associated with the application (for example, netify.whatsapp).
        label:
          type: string
          description: The name an end user would typically use to identify the application.
        full_label:
          type: string
          description: A more formal full name of the application, if available.
        description:
          type: string
          description: A brief summary of the application.
        home_page:
          $ref: '#/components/schemas/HomePage'
          description: A small object that defines both the url and associated text for the application home page.
        category:
          $ref: '#/components/schemas/Category'
          description: A small object that defines the id, tag and label for the application category.
        active:
          type: boolean
          description: Indicates whether the application is currently supported.
        favicon:
          type: string
          description: The URL for the favicon.
        icon:
          type: string
          description: The URL for the icon.
        logo:
          type: string
          description: The URL for the logo.
        favicon_source:
          type: string
          description: The data source used for the favicon.
        icon_source:
          type: string
          description: The data source used for the icon.
        logo_source:
          type: string
          description: The data source used for the logo.
      example:
        id: 156
        tag: netify.spotify
        label: Spotify
        description: Spotify is a popular music streaming service available on mobile, tablets, game consoles and more. The company has a large reach with over 100 million users and more than 20 million songs.
        home_page:
          url: https://www.spotify.com
          text: Spotify
        category:
          id: 29
          tag: streaming-media
          label: Streaming Media
        active: true
        favicon: https://static.netify.ai/logos/s/p/o/fcbgvsl/favicon.png?v=4
        icon: https://static.netify.ai/logos/s/p/o/fcbgvsl/icon.png?v=4
        logo: https://static.netify.ai/logos/s/p/o/fcbgvsl/logo.png?v=4
        favicon_source: app
        icon_source: app
        logo_source: app

    Category:
      type: object
      required:
        - id
        - tag
        - label
      properties:
        id:
          type: integer
          description: The category ID.
        tag:
          type: string
          description: The category tag.
        label:
          type: string
          description: The category label.

    ProtocolReleaseLogEntry:
      type: object
      required:
        - protocol
        - type
        - version
      properties:
        protocol:
          $ref: '#/components/schemas/Protocol'
        type:
          type: string
          description: The type of change.
          enum:
            - added
            - updated
            - deleted
        version:
          type: string
          description: The Netify Agent release version.

    Protocol:
      type: object
      required:
        - id
        - tag
        - label
        - description
        - home_page
        - category
        - introduced
        - deprecated
      properties:
        id:
          type: integer
          description: The ID number associated with the protocol.
        tag:
          type: string
          description: The tag associated with the protocol. The tag is only intended for user interfaces (UIs) and internal use -- it is not used in the Netify Agent.
        label:
          type: string
          description: The name an end user would typically use to identify the protocol.
        full_label:
          type: string
          description: A more formal full name of the protocol. This field is only included if a formal name exists.
        abbreviation:
          type: string
          description: The protocol abbreviation. This field is only included if an abbreviation is in wide use.
        description:
          type: string
          description: A one or two-sentence description of the protocol.
        home_page:
          $ref: '#/components/schemas/HomePage'
          description: A small object that defines both the url and associated text for the protocol home page.
        category:
          $ref: '#/components/schemas/Category'
          description: A small object that defines the id, tag and label for the protocol category.
        introduced:
          type: string
          description: The Netify Agent version where the protocol was introduced.
        deprecated:
          type: string
          description: The Netify Agent version where the protocol was deprecated.
      example:
        id: 206
        tag: wireguard
        label: WireGuard
        full_label: WireGuard
        description: WireGuard is a simple, fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec and OpenVPN.
        home_page:
          url: https://www.wireguard.com/
          text: WireGuard
        category:
          id: 21
          tag: vpn
          label: VPN
        introduced: "3.00"
        deprecated: ""

    IntelligenceReleaseLogEntry:
      type: object
      required:
        - intelligence
        - type
        - version
      properties:
        intelligence:
          $ref: '#/components/schemas/Intelligence'
        type:
          type: string
          description: The type of change.
          enum:
            - added
            - updated
            - deleted
        version:
          type: string
          description: The Netify Intelligence plugin release version.

    Intelligence:
      type: object
      required:
        - id
        - tag
        - label
        - description
        - category
        - supported
        - deprecated
      properties:
        id:
          type: integer
          description: The ID number associated with the intelligence driver.
        tag:
          type: string
          description: The tag associated with the intelligence driver.
        label:
          type: string
          description: The name an end user would typically use to identify the intelligence driver.
        description:
          type: string
          description: A one or two-sentence description of the intelligence driver.
        category:
          $ref: '#/components/schemas/Category'
          description: A small object that defines the id, tag and label for the intelligence category.
        score:
          type: integer
          description: The score associated with the intelligence driver.
        supported:
          type: string
          description: The Netify plugin version where the intelligence driver was introduced.
        deprecated:
          type: string
          description: The Netify plugin version where the intelligence driver was deprecated.
      example:
        id: 21
        tag: doh_scanner
        label: DoH Scanner
        description: Connection with detected DoH server.
        score: 30
        category:
          id: 4
          tag: encrypted_dns_detection
          label: Encrypted DNS Detection
        supported: 1.2.1
        deprecated: ""

    LicenseCreateRequest:
      type: object
      required:
        - issued_to
        - entitlements
      properties:
        issued_to:
          type: string
          description: The name of the individual or organization the license is being issued to.
        entitlements:
          type: array
          description: The list of active entitlements.
          items:
            type: string
        expire_at:
          type: string
          format: date
          description: Requested expiry date formatted as YYYY-MM-DD.
        duration_days:
          type: integer
          description: Alternative to expire_at; requests an expiry date duration_days from the current date.
        duid:
          type: string
          description: Unique device identifier used to restrict the license to a specific hardware endpoint.
        description:
          type: string
          description: Optional description to add to the generated license.
        notes:
          type: string
          description: Optional note to add to the generated license.
        renewable:
          type: boolean
          description: Allows or denies future renewal. Requires API key entitlement. Default is entitlement-dependent.
        transferable:
          type: boolean
          description: Requests omission of the standard non-transferable legal clause. Requires API key entitlement.

    LicenseObject:
      type: object
      description: The license object representation used in lifecycle management operations.
      required:
        - version
        - serial
        - issued_to
        - renewable
        - transferable
        - signature
        - entitlements
        - expire_at
        - created_at
      properties:
        version:
          type: string
          description: The license version format.
        serial:
          type: string
          description: The serial number of the license.
        issued_to:
          type: string
          description: The name of the individual or organization the license is being issued to.
        renewable:
          type: boolean
          description: License renewable flag.
        transferable:
          type: boolean
          description: License transferable flag.
        signature:
          type: string
          description: The cryptographic signature of the license.
        entitlements:
          type: array
          description: The list of active entitlements.
          items:
            type: string
        expire_at:
          type: object
          required:
            - unix_time
            - date
          properties:
            unix_time:
              type: integer
              description: The time the license expires in Unix time.
            date:
              type: string
              description: "The expiration date and time in YYYY-MM-DD HH:MM:SS format"
              pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
        created_at:
          type: object
          required:
            - unix_time
            - date
          properties:
            unix_time:
              type: integer
              description: The time the license was created in Unix time.
            date:
              type: string
              description: "The creation date and time in YYYY-MM-DD HH:MM:SS format"
              pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
      example:
        version: "1.0"
        serial: "2026-3638-61333041"
        issued_to: "Toronto Office"
        renewable: true
        transferable: false
        signature: "LHhbWkp+32qvi4E6bTx..."
        entitlements:
          - "application-signatures"
          - "netify-proc-aggregator"
          - "netify-proc-dev-discovery"
          - "netify-proc-flow-actions"
          - "netify-sink-mqtt"
          - "netify-proc-intel"
        expire_at:
          unix_time: 1780012800
          date: "2026-05-29 00:00:00"
        created_at:
          unix_time: 1774830914
          date: "2026-03-30 00:35:14"

    LicenseNetifyd:
      type: object
      description: The license object representation used for Netify Agent deployments.
      required:
        - created_at
        - expire_at
        - issued_to
        - issuer
        - serial
        - signature
        - terms_of_service
        - transfer_notice
        - version
      properties:
        created_at:
          type: object
          required:
            - date
            - unix
          properties:
            date:
              type: string
              description: "The creation date and time in YYYY-MM-DD HH:MM:SS format"
              pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            unix:
              type: integer
              description: The time the license was created in Unix time.
        expire_at:
          type: object
          required:
            - date
            - unix
          properties:
            date:
              type: string
              description: "The expiration date and time in YYYY-MM-DD HH:MM:SS format"
              pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
            unix:
              type: integer
              description: The time the license expires in Unix time.
        issued_to:
          type: string
          description: The name of the individual or organization the license is being issued to.
        issuer:
          type: object
          description: Information about the issuer.
          required:
            - email
            - name
          properties:
            email:
              type: string
              description: Email of the issuer.
            name:
              type: string
              description: Name of the issuer.
        serial:
          type: string
          description: The serial number of the license.
        signature:
          type: string
          description: The cryptographic signature of the license.
        terms_of_service:
          type: string
          description: Terms of service clause with link.
        transfer_notice:
          type: string
          description: The transferability clause.
        version:
          type: string
          description: The license version format.
      additionalProperties:
        type: string
        description: Entitlements granted by the license.
      example:
        version: "1.0"
        serial: "2026-3638-61333041"
        issued_to: "Toronto Office"
        issuer:
          email: "licensing@example.com"
          name: "Example Co"
        signature: "LHhbWkp+32qvi4E6bTx..."
        terms_of_service: "By using this software, you agree to the Terms of Service - https://www.netify.ai/terms-of-service"
        transfer_notice: "This license is granted solely to the original licensee and is non-transferable."
        created_at:
          unix: 1774830914
          date: "2026-03-30 00:35:14"
        expire_at:
          unix: 1780012800
          date: "2026-05-29 00:00:00"
        application-signatures: "true"

security:
  - ApiKeyAuth: []

paths:
  /applications/catalog:
    get:
      tags:
        - Applications
      summary: Application Catalog
      operationId: getApplicationCatalog
      description: Returns the list of all applications supported by the Netify Agent.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Application'
              example:
                status_code: 0
                status_message: Success.
                data:
                  - id: 156
                    tag: netify.spotify
                    label: Spotify
                    description: Spotify is a popular music streaming service available on mobile, tablets, game consoles and more.
                    home_page:
                      url: https://www.spotify.com
                      text: Spotify
                    category:
                      id: 29
                      tag: streaming-media
                      label: Streaming Media
                    active: true
                    favicon: https://static.netify.ai/logos/s/p/o/fcbgvsl/favicon.png?v=4
                    icon: https://static.netify.ai/logos/s/p/o/fcbgvsl/icon.png?v=4
                    logo: https://static.netify.ai/logos/s/p/o/fcbgvsl/logo.png?v=4
                    favicon_source: app
                    icon_source: app
                    logo_source: app
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /applications/categories:
    get:
      tags:
        - Applications
      summary: Application Categories
      operationId: getApplicationCategories
      description: Returns the list of application categories supported by the Netify Agent.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Category'
              example:
                status_code: 0
                status_message: Success.
                data:
                  - id: 9
                    tag: financial
                    label: Financial
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /applications/changelog:
    get:
      tags:
        - Applications
      summary: Application Changelog
      operationId: getApplicationChangelog
      description: Returns the log of application additions, deletions, and signature changes.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ApplicationChangelogEntry'
              example:
                status_code: 0
                status_message: Success.
                data:
                  - application:
                      id: 140
                      tag: netify.apple
                      label: Apple
                      description: Apple designs, manufactures and markets a range of consumer electronics, computer software, and online services. Products include the iPhone, iPad, Mac computers, and Apple Watch.
                      home_page:
                        url: https://www.apple.com
                        text: Apple
                      category:
                        id: 5
                        tag: business
                        label: Business
                      active: true
                      favicon: https://static.netify.ai/logos/a/p/p/nccyr/favicon.png?v=6
                      icon: https://static.netify.ai/logos/a/p/p/nccyr/icon.ico?v=6
                      logo: https://static.netify.ai/logos/a/p/p/nccyr/logo.png?v=6
                      favicon_source: app
                      icon_source: app
                      logo_source: app
                    type: updated
                    signature_updated: true
                    date: "2026-05-06"
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /intelligence/catalog:
    get:
      tags:
        - Intelligence
      summary: Intelligence Catalog
      operationId: getIntelligenceCatalog
      description: Returns the list of all intelligence drivers supported by the Netify Intelligence engine.
      parameters:
        - name: version
          in: query
          schema:
            type: string
            pattern: '^\d+(\.\d+){1,2}$'
          description: Filter results by Netify Intelligence plugin version.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Intelligence'
              example:
                status_code: 0
                status_message: Success.
                data:
                  - id: 21
                    tag: doh_scanner
                    label: DoH Scanner
                    description: Connection with detected DoH server.
                    score: 30
                    category:
                      id: 4
                      tag: encrypted_dns_detection
                      label: Encrypted DNS Detection
                    supported: "1.2.1"
                    deprecated: ""
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /intelligence/categories:
    get:
      tags:
        - Intelligence
      summary: Intelligence Categories
      operationId: getIntelligenceCategories
      description: Returns the list of categories supported by the Netify Intelligence engine.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Category'
              example:
                status_code: 0
                status_message: Success.
                data:
                  - id: 4
                    tag: encrypted_dns_detection
                    label: Encrypted DNS Detection
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /intelligence/releaselog:
    get:
      tags:
        - Intelligence
      summary: Intelligence Release Log
      operationId: getIntelligenceReleaseLog
      description: Returns the intelligence release log with additions and deletions in release order.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/IntelligenceReleaseLogEntry'
              example:
                status_code: 0
                status_message: Success.
                data:
                  - intelligence:
                      id: 21
                      tag: doh_scanner
                      label: DoH Scanner
                      description: Connection with detected DoH server.
                      category:
                        id: 4
                        tag: encrypted_dns_detection
                        label: Encrypted DNS Detection
                    type: added
                    version: "1.2.1"
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /licenses:
    get:
      tags:
        - Licenses
      summary: License List
      operationId: licenseList
      description: Returns a list of all licenses created with the API key.
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [netifyd, object]
          description: Response format.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        oneOf:
                          - type: array
                            items:
                              $ref: '#/components/schemas/LicenseObject'
                          - type: array
                            items:
                              $ref: '#/components/schemas/LicenseNetifyd'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.
    post:
      tags:
        - Licenses
      summary: License Create
      operationId: licenseCreate
      description: Creates a new license.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseCreateRequest'
      responses:
        '200':
          description: License created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/LicenseNetifyd'
              example:
                status_code: 0
                status_message: Success.
                data:
                  version: "1.0"
                  issued_to: "Toronto Office"
                  created_at:
                    date: "2026-05-07 14:35:09"
                    unix: 1778164509
                  expire_at:
                    date: "2026-06-04 00:00:00"
                    unix: 1780531200
                  serial: "2026-6027-30832256"
                  issuer:
                    name: "Example Co."
                    email: "licensing@example.com"
                  terms_of_service: "By using this software, you agree to the Terms of Service - https://www.netify.ai/terms-of-service"
                  description: "Flow Actions Policy Control"
                  netify-proc-flow-actions:
                    not_valid_after: "2026-06-04"
                  signature: "MKDm6+emMFj3wK..."
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /licenses/{serial}:
    get:
      tags:
        - Licenses
      summary: License View
      description: Returns the license for given serial number.
      operationId: licenseView
      parameters:
        - name: serial
          in: path
          required: true
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [netifyd, object]
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        oneOf:
                          - $ref: '#/components/schemas/LicenseObject'
                          - $ref: '#/components/schemas/LicenseNetifyd'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: License not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.
    delete:
      tags:
        - Licenses
      summary: License Delete
      operationId: licenseDelete
      parameters:
        - name: serial
          in: path
          required: true
          schema:
            type: string
          example: "2025-7546-23742565"
      responses:
        '200':
          description: License delete action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                status_code: 0
                status_message: Success.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: License not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /licenses/{serial}/renew:
    post:
      tags:
        - Licenses
      summary: License Renew
      operationId: licenseRenew
      parameters:
        - name: serial
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                expire_at:
                  type: string
                  format: date
                duration_days:
                  type: integer
      responses:
        '200':
          description: License renewed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: License not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /protocols/catalog:
    get:
      tags:
        - Protocols
      summary: Protocol Catalog
      operationId: getProtocolCatalog
      description: Returns the list of all protocols - past and present - supported by the Netify Agent.
      parameters:
        - name: version
          in: query
          schema:
            type: string
            pattern: '^\d+(\.\d+){1,2}$'
          description: If the Netify agent version is passed as a parameter to the endpoint, the catalog results will only include the protocols supported in the specified version.  You can specify the full version (e.g. 5.2.1), or a major version number (e.g. 5.2).
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Protocol'
              example:
                status_code: 0
                status_message: Success.
                data:
                  - id: 206
                    tag: wireguard
                    label: WireGuard
                    full_label: WireGuard
                    description: WireGuard is a simple, fast and modern VPN that utilizes state-of-the-art cryptography.
                    home_page:
                      url: https://www.wireguard.com/
                      text: WireGuard
                    category:
                      id: 21
                      tag: vpn
                      label: VPN
                    introduced: "3.00"
                    deprecated: ""
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /protocols/categories:
    get:
      tags:
        - Protocols
      summary: Protocol Categories
      operationId: getProtocolCategories
      description: Returns the list of protocol categories supported by the Netify Agent.
      parameters:
        - name: version
          in: query
          schema:
            type: string
            pattern: '^\d+(\.\d+){1,2}$'
          description: If the Netify agent version is passed as a parameter to the endpoint, the results will only include the categories supported in the specified version. You can specify the full version (e.g. 5.2.1), or a major version number (e.g. 5.2). Currently, all versions share the same categories, but this may not be true in future releases.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Category'
              example:
                status_code: 0
                status_message: Success.
                data:
                  - id: 21
                    tag: vpn
                    label: VPN
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /protocols/release-log:
    get:
      tags:
        - Protocols
      summary: Protocol Release Log
      operationId: getProtocolReleaseLog
      description: Returns the protocol release log with detailed version information.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StatusResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ProtocolReleaseLogEntry'
              example:
                status_code: 0
                status_message: Success.
                data:
                  - protocol:
                      id: 338
                      tag: ceph
                      label: Ceph
                      full_label: Ceph
                      description: The Ceph protocol is a distributed storage system protocol used by the Ceph storage platform to enable scalable, fault-tolerant object, block, and file storage.
                      home_page:
                        url: https://docs.ceph.com/en/reef/dev/network-protocol/
                        text: Ceph
                      category:
                        id: 4
                        tag: file-server
                        label: File Server
                      introduced: "5.1.7"
                      deprecated: ""
                    type: added
                    version: "5.1.7"
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /signatures/categories:
    get:
      tags:
        - Signatures
      summary: Signatures Categories
      operationId: getSignaturesCategories
      description: Returns application category signatures for the Netify Agent.
      parameters:
        - name: version
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d+(\.\d+){1,2}$'
      responses:
        '200':
          description: Successful response returning the category data file.
          headers:
            x-sha1-hash:
              description: SHA1 hash of the file (legacy).
              schema:
                type: string
            x-sha256-hash:
              description: SHA256 hash of the file.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                description: Category definitions formatted for the Netify Agent.
                additionalProperties: true
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /signatures/applications:
    get:
      tags:
        - Signatures
      summary: Signatures Applications
      operationId: getSignaturesApplications
      description: Returns application signatures for the Netify Agent.
      parameters:
        - name: version
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d+(\.\d+){1,2}$'
          description: The Netify Agent version used to determine the correct file format and signature patterns.  You can specify the full version (e.g. 5.2.1), or a major version number (e.g. 5.2).
        - name: ip_version
          in: query
          schema:
            type: integer
            enum: [4, 6]
          description: Optional. By default, signatures include both IPv4 and IPv6. Set ip_version to return only IPv4 or IPv6 data.
      responses:
        '200':
          description: Successful response returning the binary signature data file.
          headers:
            x-sha1-hash:
              description: SHA1 hash of the file (legacy).
              schema:
                type: string
            x-sha256-hash:
              description: SHA256 hash of the file.
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: Application signatures formatted for the Netify Agent.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

  /signatures/intelligence:
    get:
      tags:
        - Signatures
      summary: Signatures Intelligence
      operationId: getSignaturesIntelligence
      description: Returns intelligence signatures for the Netify Intelligence engine.
      parameters:
        - name: version
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d+(\.\d+){1,2}$'
          description: The Netify Intelligence plugin version used to determine the correct file format and signature patterns.
      responses:
        '200':
          description: Successful response returning the binary signature data file.
          headers:
            x-sha1-hash:
              description: SHA1 hash of the file (legacy).
              schema:
                type: string
            x-sha256-hash:
              description: SHA256 hash of the file.
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: Intelligence signatures formatted for the Netify Agent.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
        '500':
          description: Internal server error.

```

---

# Processor Plugins

## Aggregator Processor Plugin

### Aggregator Processor: Overview
The Aggregator Processor plugin creates structured telemetry by aggregating individual flow records from the Netify Agent's memory.
This aggregated data is typically used for high-level dashboards with bandwidth usage statistics and key network metrics.

The plugin emits several predefined summary formats (see the Telemetry section). Each format provides aggregated metrics - counts, bytes, and flow totals - plus metadata such as application, protocol, IPs, MACs, ports, VLAN, and interface statistics.

### Aggregator Processor: Configuration
The plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-proc-aggregator.json`).  The format and compressor properties define global defaults, which can be overridden per channel. See the examples below for how to apply channel-level overrides.

### Aggregator Processor: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-proc-aggregator.json",
  "title": "Netify Aggregator Plugin Configuration",
  "description": "JSON Schema for the Netify Aggregator plugin configuration.",
  "type": "object",
  "properties": {
    "aggregator": {
      "type": "integer",
      "description": "Aggregator format type.",
      "externalDocs": {
        "description": "Aggregator telemetry formats",
        "url": "https://www.netify.ai/documentation/agent/v5/processor/aggregator#telemetry"
      }
    },
    "log_interval": {
      "type": "integer",
      "default": 60,
      "description": "Interval in seconds between aggregate summary reports."
    },
    "privacy_mode": {
      "type": "boolean",
      "description": "If true, aggregation will not include breakdowns by MAC address or IP address."
    },
    "format": {
      "$ref": "#/$defs/formatType",
      "description": "Default payload format used for all outputs unless overridden in sinks."
    },
    "compressor": {
      "$ref": "#/$defs/compressorType",
      "description": "Default compression policy used for all outputs unless overridden in sinks."
    },
    "batched_rows": {
      "type": "integer",
      "default": 0,
      "description": "Limits the number of aggregate records processed in a single batch. Use 0 for unlimited."
    },
    "nested": {
      "type": "boolean",
      "default": false,
      "description": "Layout format for aggregate rows. 'true' for nested objects, 'false' for flat key-value pairs.",
      "externalDocs": {
        "description": "Flat versus nested information",
        "url": "https://www.netify.ai/documentation/agent/v5/processor/aggregator#nested"
      }
    },
    "criteria": {
      "type": "object",
      "description": "An object array of supported flow criteria expressions.",
      "externalDocs": {
        "description": "See Expression Engine documentation</a>",
        "url": "/documentation/agent/v5/integrations/expression-engine"
      }
    },
    "sinks": {
      "type": "object",
      "description": "Sink configuration.",
      "additionalProperties": {
        "type": "object",
        "description": "The specific output target (e.g., 'sink-mqtt', 'sink-http').",
        "additionalProperties": {
          "type": "object",
          "description": "The specific channel or topic for the target (e.g., 'aggregate').",
          "properties": {
            "enable": {
              "type": "boolean",
              "default": true,
              "description": "Enables or disables this specific sink channel."
            },
            "format": {
              "$ref": "#/$defs/formatType"
            },
            "compressor": {
              "$ref": "#/$defs/compressorType"
            }
          }
        }
      }
    }
  },
  "required": [
    "aggregator",
    "batched_rows",
    "compressor",
    "format",
    "log_interval",
    "nested",
    "privacy_mode",
    "sinks"
  ],
  "$defs": {
    "formatType": {
      "type": "string",
      "enum": ["json", "msgpack"],
      "description": "The serialization format for the data payload."
    },
    "compressorType": {
      "type": "string",
      "enum": ["none", "gz"],
      "description": "The compression algorithm applied to the payload."
    }
  },
  "examples": [
    {
      "aggregator": 1,
      "log_interval": 15,
      "privacy_mode": false,
      "format": "json",
      "compressor": "gz",
      "batched_rows": 0,
      "nested": false,
      "criteria": [
        "ip_nat == false;",
        "vlan_id == 10;"
      ],
      "sinks": {
        "sink-log": {
          "aggregate": {
            "format": "json",
            "compressor": "none"
          }
        }
      }
    },
    {
      "aggregator": 2,
      "log_interval": 60,
      "privacy_mode": false,
      "format": "json",
      "compressor": "gz",
      "batched_rows": 0,
      "nested": false,
      "sinks": {
        "sink-log": {
          "aggregate": {
            "format": "json",
            "compressor": "none"
          }
        },
        "sink-mqtt": {
          "aggregate": {
            "format": "msgpack",
            "compressor": "gz"
          }
        }
      }
    }
  ]
}

```

## Core Processor Plugin

### Core Processor: Overview
The Netify DPI Core Processor plugin is the telemetry engine at the center of the agent pipeline. It takes flow intelligence generated by detection,
classification, and protocol analysis, then converts it into structured event records that downstream systems can consume reliably.

In practice, this plugin separates packet inspection from telemetry delivery. You can keep capture and DPI behavior stable while independently choosing
output format, compression, and destination sinks for integration with SIEMs, data lakes, or custom analytics workflows.

### Core Processor: Configuration
The plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-proc-core.json`).  The format and compressor properties define global defaults, which can be overridden per channel. See the examples below for how to apply channel-level overrides.

### Core Processor: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-proc-core.json",
  "title": "Netify Core Processor Configuration",
  "description": "JSON Schema for the Netify Core Processor plugin configuration.",
  "type": "object",
  "properties": {
    "format": {
      "$ref": "#/$defs/formatType",
      "description": "Default payload format used for all outputs unless overridden in sinks."
    },
    "compressor": {
      "$ref": "#/$defs/compressorType",
      "description": "Default compression policy used for all outputs unless overridden in sinks."
    },
    "sinks": {
      "type": "object",
      "description": "Sink configuration.",
      "additionalProperties": {
        "type": "object",
        "description": "The specific output target (e.g., 'sink-mqtt', 'sink-http').",
        "additionalProperties": {
          "type": "object",
          "description": "The specific channel or topic for the target (e.g., 'aggregate').",
          "properties": {
            "enable": {
              "type": "boolean",
              "default": true,
              "description": "Enables or disables this specific sink channel."
            },
            "format": {
              "$ref": "#/$defs/formatType"
            },
            "compressor": {
              "$ref": "#/$defs/compressorType"
            },
            "types": {
              "type": "array",
              "description": "Telemetry type.",
              "items": { "type": "string", "enum": ["stream-flows", "stream-stats"] },
              "externalDocs": {
                "description": "Telemetry list and details",
                "url": "https://www.netify.ai/documentation/agent/v5/processor/core#telemetry"
              }
            }
          },
          "required": ["types"]
        }
      }
    }
  },
  "$defs": {
    "formatType": {
      "type": "string",
      "enum": ["json", "msgpack"],
      "description": "The serialization format for the data payload."
    },
    "compressorType": {
      "type": "string",
      "enum": ["none", "gz"],
      "description": "The compression algorithm applied to the payload."
    }
  },
  "examples": [
    {
      "format": "json",
      "compressor": "none",
      "sinks": {
        "sink-log": {
          "stats": {
            "enable": true,
            "types": [ "stream-stats" ]
          }
        }
      }
    }
  ]
}

```

## Device Discovery Processor Plugin

### Device Discovery: Overview
Netify device discovery utility identifies all devices communicating within the local network in near real-time and on a continual basis.
This lets administrators keep tabs on anything from static, mainstay devices like desktops, printers and routers, to more transient devices, like
smartphones and tablets, that regularly come and go from the network.

The plugin is responsible for collecting metadata from the host where the agent is installed and securely sending
it up to the Netify cloud for analysis. All classification is done in the cloud and the plugin receives the results of the classification from the
machine learning models.

### Device Discovery: Configuration
The plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-proc-dev-discovery.json`).

### Device Discovery: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-proc-dev-discovery.json",
  "title": "Netify Device Discovery Processor Configuration",
  "description": "JSON Schema for the Netify Device Discovery Processor plugin configuration.",
  "type": "object",
  "properties": {
    "format": {
      "$ref": "#/$defs/formatType",
      "description": "Default payload format used for all outputs unless overridden in sinks."
    },
    "compressor": {
      "$ref": "#/$defs/compressorType",
      "description": "Default compression policy used for all outputs unless overridden in sinks."
    },
    "max_confidence": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "default": 80,
      "description": "Confidence threshold (0-100) required before discovery stops for a device."
    },
    "max_devices": {
      "type": "integer",
      "default": 0,
      "description": "Maximum number of devices to track in memory. 0 for unlimited."
    },
    "max_device_age": {
      "type": "integer",
      "default": 0,
      "description": "Maximum idle time (seconds) before a device is purged from memory."
    },
    "max_ja4_clients": {
      "type": "integer",
      "default": 10,
      "description": "Maximum number of extracted JA4 client hashes to collect on any given MAC address."
    },
    "max_mdns_services": {
      "type": "integer",
      "default": 10,
      "description": "Maximum number of extracted mDNS service strings to collect on any given MAC address."
    },
    "max_http_user_agents": {
      "type": "integer",
      "default": 10,
      "description": "Maximum number of extracted HTTP user agent strings to collect on any given MAC address."
    },
    "max_ssdp_user_agents": {
      "type": "integer",
      "default": 10,
      "description": "Maximum number of extracted SSDP user agent strings to collect on any given MAC address."
    },
    "path_device_cache": {
      "type": "string",
      "description": "Filesystem path for persistent device cache."
    },
    "process_all_macs": {
      "type": "boolean",
      "default": false,
      "description": "If false, only local/unicast MAC addresses are processed."
    },
    "device_mac_ignore": {
      "type": "array",
      "description": "List of MAC addresses to exclude from discovery.",
      "items": {
        "type": "string",
        "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$"
      }
    },
    "netify_api": {
      "type": "object",
      "description": "Netify API object definition.",
      "enable": {
        "type": "boolean",
        "default": true,
        "description": "Enables or disables this Netify Clound discovery engine."
      }
    },
    "sinks": {
      "type": "object",
      "description": "Sink configuration.",
      "additionalProperties": {
        "type": "object",
        "description": "The specific output target (e.g., 'sink-mqtt', 'sink-http').",
        "additionalProperties": {
          "type": "object",
          "description": "The specific channel or topic for the target (e.g., 'aggregate').",
          "properties": {
            "enable": {
              "type": "boolean",
              "default": true,
              "description": "Enables or disables this specific sink channel."
            },
            "format": {
              "$ref": "#/$defs/formatType"
            },
            "compressor": {
              "$ref": "#/$defs/compressorType"
            },
            "flush": {
              "type": "boolean",
              "default": true,
              "description": "The flush policy."
            }
          }
        }
      }
    }
  },
  "$defs": {
    "formatType": {
      "type": "string",
      "enum": ["json", "msgpack"],
      "description": "The serialization format for the data payload."
    },
    "compressorType": {
      "type": "string",
      "enum": ["none", "gz"],
      "description": "The compression algorithm applied to the payload."
    }
  },
  "examples": [
    {
      "compressor": "gz",
      "format": "json",
      "max_confidence": 80,
      "max_devices": 1500,
      "max_device_age": 4147200,
      "path_device_cache": "${path_state_persistent}/device-discovery-cache.json",
      "device_mac_ignore": [
        "00:00:00:00:00:00",
        "ff:ff:ff:ff:ff:ff"
      ],
      "max_ja4_clients": {
        "max": 10,
        "update_min": 1,
        "update_ttl": 3600
      },
      "max_mdns_services": 10,
      "max_http_user_agents": 10,
      "max_ssdp_user_agents": 10,
      "netify_api": {
        "enable": true
      },
      "sinks": {
        "sink-log": {
          "devices": {
            "enable": true,
            "flush": true,
            "format": "json",
            "compressor": "none"
          }
        }
      }
    }
  ]
}

```

## Intelligence Plugin

### Intelligence: Overview
The Netify Intelligence Plugin adds advanced analytics to the Netify Agent and serves as a core building block for a cybersecurity dashboard. It incorporates cyber risk indicators and applies additional heuristics alongside stateful flow inspection to analyze traffic. The plugin also provides event-driven insights and supports secondary flow inspection for more context-aware network monitoring.

In addition, the plugin is designed to work hand-in-hand with firewalls and QoS via the [Flow Actions plugin](https://www.netify.ai/documentation/agent/v5/processor/flow-actions).

### Intelligence: Configuration
The Intelligence plugin configuration is flexible and able to support a wide range of environments. For example, a manufacturing facility may enforce strict cybersecurity policies where self-signed TLS certificates are never permitted. In contrast, a prosumer environment might allow self-signed certificates on the local network while blocking them on the public Internet.

### Intelligence: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-proc-intel.json",
  "title": "Netify Intelligence Processor Configuration",
  "description": "JSON Schema for the Netify Intelligence Processor plugin configuration.",
  "type": "object",
  "required": [
    "indicator_defaults",
    "indicators",
    "sink_targets"
  ],
  "properties": {
    "indicator_defaults": {
      "type": "object",
      "description": "Default settings applied to all indicators unless explicitly overridden.",
      "properties": {
        "sink": {
          "type": "object",
          "description": "Default sink settings.",
          "properties": {
            "flow_metadata": {
              "type": "string",
              "description": "Default flow metadata format for telemetry."
            }
          }
        },
        "event_filter": {
          "type": "array",
          "description": "Default event types used for analysis.",
          "items": {
            "type": "string",
            "enum": [
              "dpi_new",
              "dpi_update",
              "dpi_complete",
              "flow_new",
              "flow_stats",
              "flow_expiring",
              "flow_expired"
            ]
          }
        }
      }
    },
    "indicators": {
      "type": "object",
      "description": "Definitions of intelligence indicators and their processing logic.",
      "additionalProperties": {
        "type": "object",
        "required": [
          "enabled",
          "indicator_driver"
        ],
        "properties": {
          "enabled": {
            "type": "boolean",
            "default": true,
            "description": "Enables or disables the indicator."
          },
          "indicator_driver": {
            "type": "string",
            "description": "Identifier for the underlying intelligence driver."
          },
          "criteria": {
            "type": "object",
            "description": "Flow criteria required to trigger the indicator."
          },
          "data_feeds": {
            "type": "array",
            "description": "Intelligence data sources used by the indicator.",
            "items": {
              "type": "string"
            }
          },
          "proc_targets": {
            "type": "array",
            "description": "Processor targets, typically flow actions such as proc-nfa.",
            "items": {
              "type": "string"
            }
          },
          "sink_targets": {
            "type": "array",
            "description": "Named output targets defined in the top-level sink_targets property.",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "sink_targets": {
      "type": "object",
      "description": "Sink target definitions.",
      "additionalProperties": {
        "type": "object",
        "description": "A specific output target such as sink-mqtt or sink-http.",
        "required": [
          "sink"
        ],
        "properties": {
          "sink": {
            "type": "string",
            "description": "Sink plugin identifier."
          },
          "channels": {
            "type": "object",
            "description": "Per-channel sink configuration.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean",
                  "default": true,
                  "description": "Enables or disables the sink channel."
                },
                "dispatch_flags": {
                  "type": "array",
                  "description": "Dispatch flags applied to the channel.",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "additionalProperties": false
}

```

## Python Processor Plugin

### Python Processor: Overview
The Netify Python plugin enables direct access to live network telemetry from the Netify agent within Python scripts, making it an ideal platform for AI-driven analytics and intelligent network automation. By leveraging Python's extensive libraries for machine learning, data processing, and anomaly detection, this plugin allows developers to rapidly prototype custom AI models, predictive workflows, and advanced network intelligence features.

### Python Processor: Configuration
The plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-proc-python.json`). The configuration file provides a way to define debug mode and the location of the Python script.

### Python Processor: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-proc-python.json",
  "title": "Netify Python Processor Configuration",
  "description": "JSON Schema for the Netify Python Processor plugin configuration.",
  "type": "object",
  "properties": {
    "debug": {
      "type": "boolean",
      "description": "Specifies whether debug mode is enabled for the processor."
    },
    "script": {
      "type": "string",
      "description": "The file system path to the Python script."
    }
  },
  "required": [
    "debug",
    "script"
  ],
  "examples": [
    {
      "debug": false,
      "script": "${path_state_persistent}/netify-proc-python/netify-proc-python.python"
    }
  ]
}

```

## Lua Processor Plugin

### Lua Processor: Overview
The Netify Lua plugin enables direct integration with the Netify agent engine, allowing Lua scripts to hook into live network telemetry in real time. This plugin is an ideal option for rapid prototyping and custom applications, providing a flexible, lightweight environment for custom logic, data analysis, or experimental features without modifying the core DPI engine.

### Lua Processor: Configuration
Once enabled, the plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-proc-lua.json`). The configuration file provides a way to define the location of the Lua script.

### Lua Processor: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-proc-lua.json",
  "title": "Netify Lua Processor Configuration",
  "description": "JSON Schema for the Netify Lua Processor plugin configuration.",
  "type": "object",
  "properties": {
    "script": {
      "type": "string",
      "description": "The file system path to the Lua script."
    }
  },
  "required": [
    "script"
  ],
  "examples": [
    {
      "script": "/usr/local/bin/monitor.lua"
    }
  ]
}

```

---

# Sink Plugins

## HTTP Sink Plugin

### HTTP Sink: Overview
The Netify HTTP POST interface enables the delivery of real-time [network telemetry](https://www.netify.ai/products/netify-dpi/telemetry) and metadata from the DPI engine to external systems via standard HTTP requests. This method allows telemetry data to be pushed to web services, APIs, or automation platforms without maintaining a persistent connection.

### HTTP Sink: Configuration
The plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-sink-http.json`).

### HTTP Sink: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-sink-http.json",
  "title": "Netify Sink HTTP Configuration",
  "description": "JSON Schema for the Netify Sink HTTP Plugin configuration.",
  "type": "object",
  "properties": {
    "timeout_connect": {
      "type": "integer",
      "default": 30,
      "description": "Default connection timeout in seconds."
    },
    "timeout_transfer": {
      "type": "integer",
      "default": 300,
      "description": "Default transfer timeout in seconds."
    },
    "channels": {
      "type": "object",
      "description": "Channel configurations.",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "enable": {
            "type": "boolean",
            "default": true,
            "description": "State of the output channel."
          },
          "timeout_connect": {
            "type": "integer",
            "description": "Connection timeout override in seconds."
          },
          "timeout_transfer": {
            "type": "integer",
            "description": "Transfer timeout override in seconds."
          },
          "url": {
            "type": "string",
            "description": "The destination URL. Supports variables like ${uuid_agent}.",
            "pattern": "^https?://[a-zA-Z0-9\\.\\-_/\\${}]+$",
            "examples": ["https://api.example.com/v1/${uuid_agent}/telemetry"]
          },
          "headers": {
            "type": "object",
            "description": "HTTP headers to add to the request. Supports variables like ${uuid_agent}.",
            "additionalProperties": {
              "type": "string"
            },
            "examples": [
              {
                "X-UUID": "${uuid_agent}",
                "X-UUID-Serial": "${uuid_serial}"
              }
            ]
          }
        },
        "required": ["url", "headers"]
      },
      "examples": [
        {
          "flows": {
            "enable": true,
            "url": "https://sink.example.com/v1/flows",
            "headers": {
              "X-UUID": "${uuid_agent}",
              "X-UUID-Serial": "${uuid_serial}"
            }
          },
          "intel": {
            "enable": true,
            "url": "https://sink.example.com/v1/intel",
            "headers": {
              "X-UUID": "${uuid_agent}",
              "X-UUID-Serial": "${uuid_serial}"
            }
          }
        }
      ]
    }
  }
}

```

## Log Sink Plugin

### Log Sink: Overview
The Netify log output interface enables the export of [network telemetry](https://www.netify.ai/products/netify-dpi/telemetry) and metadata from the DPI engine to local log files, which can be consumed by monitoring systems, automation scripts, or custom tools. This method is most often used for development and debugging, providing a simple, reliable way to capture telemetry without requiring persistent network connections or additional messaging layers.

### Log Sink: Configuration
The plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-sink-log.json`). Top-level properties set global defaults, while per-channel properties override those defaults and define log prefixes. Use the global settings for shared behavior, and apply per-channel overrides when specific streams need separate files, naming, or overwrite policies.

### Log Sink: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-sink-log.json",
  "title": "Netify Sink Log Configuration",
  "description": "JSON Schema for the Netify Sink Log Plugin configuration.",
  "type": "object",
  "properties": {
    "overwrite": {
      "type": "boolean",
      "default": false,
      "description": "Default file overwrite policy."
    },
    "log_path": {
      "type": "string",
      "default": "/tmp",
      "description": "Default output folder for log files."
    },
    "channels": {
      "type": "object",
      "description": "Channel configurations.",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "enable": {
            "type": "boolean",
            "default": true,
            "description": "State of the output channel."
          },
          "overwrite": {
            "type": "boolean",
            "description": "Channel-specific overwrite policy."
          },
          "log_path": {
            "type": "string",
            "description": "Channel-specific output folder for log files."
          },
          "log_name": {
            "type": "string",
            "minLength": 1,
            "description": "Prefix prepended to generated log filenames.",
            "examples": ["netify-intel", "security-endpoints"]
          }
        },
        "required": ["log_name"]
      },
      "examples": [
        {
          "endpoints": {
            "overwrite": true,
            "log_path": "/var/log/telemetry",
            "log_name": "netify-endpoints"
          },
          "intel": {
            "log_path": "/var/log/telemetry",
            "log_name": "netify-intel-"
          }
        }
      ]
    }
  }
}

```

## MQTT Sink Plugin

### MQTT Sink: Overview
The Netify MQTT Plugin enables the publishing of real-time [network telemetry](https://www.netify.ai/products/netify-dpi/telemetry) and metadata from the DPI engine to a message queue. Using the message queue's publish/subscribe (Pub/Sub) architecture, the plugin efficiently distributes telemetry streams to multiple subscribers without requiring persistent, resource-intensive point-to-point connections.

### MQTT Sink: Configuration
The plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-sink-mqtt.json`).  You can use the built-in ${channel} variable to route different telemetry streams to separate topics. You can also append the Netify Agent’s UUID or serial number to ensure each instance publishes to a unique path.

### MQTT Sink: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-sink-mqtt.json",
  "title": "Netify Sink MQTT Configuration",
  "description": "JSON Schema for the Netify Sink MQTT Plugin configuration.",
  "type": "object",
  "required": ["host", "user", "pass", "topic"],
  "properties": {
    "host": {
      "type": "string",
      "format": "hostname",
      "description": "MQTT server hostname or IP address."
    },
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "default": 1883,
      "description": "Port used to connect to the MQTT server (typically 1883 for TCP or 8883 for SSL)."
    },
    "user": {
      "type": "string",
      "description": "Username used to authenticate with the MQTT server."
    },
    "pass": {
      "type": "string",
      "writeOnly": true,
      "description": "Password used to authenticate with the MQTT server."
    },
    "topic": {
      "type": "string",
      "description": "Topic to publish messages to. Supports template variables.",
      "pattern": "^[a-zA-Z0-9/\\._\\-${}]+$",
      "examples": ["netify/${uuid_agent}/${channel}"]
    },
    "message_qos": {
      "type": "integer",
      "enum": [0, 1, 2],
      "default": 1,
      "description": "QoS level: 0 (At most once), 1 (At least once), 2 (Exactly once)."
    },
    "message_retain": {
      "type": "boolean",
      "default": false,
      "description": "When true, the broker retains the last message on the topic for new subscribers."
    }
  }
}

```

## Socket Sink Plugin

### Socket Sink: Overview
The Netify Sockets interface enables the direct streaming of real-time [network telemetry](https://www.netify.ai/products/netify-dpi/telemetry) and metadata from the DPI engine to client applications. It supports TCP sockets, UDP sockets, WebSockets, and file sockets, providing flexible options for both persistent, low-latency connections and local inter-process communication. This approach is ideal for custom integrations, live dashboards, or systems that require streaming telemetry data.

### Socket Sink: Configuration
The plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-sink-socket.json`). The only global setting is the default port; all other options are defined per channel, allowing each telemetry stream to specify its own protocol, destination, and behavior.

### Socket Sink: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-sink-socket.json",
  "title": "Netify Sink Socket Configuration",
  "description": "JSON Schema for the Netify Sink Socket Plugin configuration.",
  "type": "object",
  "properties": {
    "default_port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "description": "Default port used for TCP, UDP, and WebSockets (1-65535)."
    },
    "channels": {
      "type": "object",
      "description": "Channel configurations.",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "enable": {
            "type": "boolean",
            "default": true,
            "description": "State of the output channel."
          },
          "bind_address": {
            "type": "string",
            "description": "Socket connection string. Supported protocols: unix, tcp, udp, ws, wss.",
            "pattern": "^(unix|tcp|udp|ws|wss)://.+$",
            "examples": [
              "unix:///var/run/netifyd/netify-sink.sock",
              "tcp://127.0.0.1:8080",
              "udp://0.0.0.0:9000",
              "ws://192.168.1.1:80"
            ]
          }
        },
        "required": ["bind_address"]
      },
      "examples": [
        {
          "flows": {
            "enable": true,
            "bind_address": "unix:///var/run/netifyd/flows.sock"
          },
          "aggregator": {
            "enable": true,
            "bind_address": "tcp://127.0.0.1:8080"
          }
        }
      ]
    }
  }
}

```

## ubus Sink Plugin

### ubus Sink: Overview
The Netify ubus interface enables the real-time export of [network telemetry](https://www.netify.ai/products/netify-dpi/telemetry) and metadata from the DPI engine to local applications via the ubus messaging system, commonly used on OpenWrt, PrplOS and other embedded Linux distributions. This method provides lightweight, low-latency inter-process communication, making it ideal for local monitoring, automation scripts, and system integration.

### ubus Sink: Configuration
The plugin is configured via the JSON file referenced by its loader (typically `/etc/netifyd/netify-sink-ubus.json`).

### ubus Sink: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-sink-ubus.json",
  "title": "Netify Sink ubus Configuration",
  "description": "JSON Schema for the Netify Sink ubus Plugin configuration.",
  "type": "object",
  "properties": {
    "channels": {
      "type": "object",
      "description": "Channel configurations.",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "The ubus object path to invoke (e.g., 'netify.metadata').",
            "pattern": "^[a-zA-Z0-9\\._\\-]+$"
          },
          "function": {
            "type": "string",
            "description": "The specific ubus method to call for published metadata.",
            "examples": [
              "notify",
              "publish",
              "set"
            ]
          }
        },
        "required": [
          "path",
          "function"
        ]
      },
      "examples": [
        {
          "flows": {
            "path": "netify.metadata",
            "function": "publish"
          },
          "intelligence": {
            "path": "netify.metadata",
            "function": "notify"
          }
        }
      ]
    }
  }
}

```

---

# Telemetry

## Agent Status Telemetry

### Agent Status: Overview
The Agent Status telemetry captures the agent's operational heartbeat, providing a clear snapshot of runtime health. It reports key metrics such as CPU utilization, memory footprint, cache performance, flow table activity, packet throughput, and overall uptime, all in a single, structured record. These metrics give you immediate insight into how the engine performs under current network conditions.

### Agent Status: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-telemetry-agent-status.json",
  "title": "Netify Agent Status Telemetry",
  "description": "JSON Schema for Netify Agent v5 status and performance statistics telemetry.",
  "type": "object",
  "properties": {
    "agent_version": {
      "type": "string",
      "description": "Semantic version of the running Netify Agent."
    },
    "build_version": {
      "type": "string",
      "description": "Full agent build string including platform and enabled feature flags."
    },
    "cpu_cores": {
      "type": "integer",
      "description": "Number of CPU cores available to the agent process."
    },
    "cpu_system": {
      "type": "number",
      "description": "Current cumulative system CPU usage reported by the agent."
    },
    "cpu_system_prev": {
      "type": "number",
      "description": "Previous system CPU usage sample."
    },
    "cpu_user": {
      "type": "number",
      "description": "Current cumulative user CPU usage reported by the agent."
    },
    "cpu_user_prev": {
      "type": "number",
      "description": "Previous user CPU usage sample."
    },
    "dhc_status": {
      "type": "boolean",
      "description": "Status flag for the DNS hint cache subsystem."
    },
    "fhc_status": {
      "type": "boolean",
      "description": "Status flag for the flow hash cache subsystem."
    },
    "flow_count": {
      "type": "integer",
      "description": "Current number of tracked flows."
    },
    "flow_count_prev": {
      "type": "integer",
      "description": "Previous tracked flow count sample."
    },
    "flows_active": {
      "type": "integer",
      "description": "Number of active flows."
    },
    "flows_expired": {
      "type": "integer",
      "description": "Number of flows that have expired."
    },
    "flows_expiring": {
      "type": "integer",
      "description": "Number of flows currently in the process of expiring."
    },
    "flows_in_use": {
      "type": "integer",
      "description": "Number of flow table entries currently in use."
    },
    "flows_purged": {
      "type": "integer",
      "description": "Number of flows purged by maintenance routines."
    },
    "maxrss_kb": {
      "type": "integer",
      "description": "Current high-water resident set size in kilobytes."
    },
    "maxrss_kb_prev": {
      "type": "integer",
      "description": "Previous high-water resident set size sample in kilobytes."
    },
    "memrss_kb": {
      "type": "integer",
      "description": "Current resident memory usage in kilobytes."
    },
    "memrss_kb_prev": {
      "type": "integer",
      "description": "Previous resident memory usage sample in kilobytes."
    },
    "tcm_kb": {
      "type": "integer",
      "description": "Current TCMalloc-managed memory in kilobytes."
    },
    "tcm_kb_prev": {
      "type": "integer",
      "description": "Previous TCMalloc-managed memory sample in kilobytes."
    },
    "timestamp": {
      "type": "integer",
      "description": "Unix epoch timestamp (seconds) when the status record was generated."
    },
    "type": {
      "type": "string",
      "const": "agent_status",
      "description": "Telemetry record type. Always agent_status."
    },
    "update_imf": {
      "type": "integer",
      "description": "Internal update indicator for incremental maintenance/metrics refresh."
    },
    "update_interval": {
      "type": "integer",
      "description": "Status publication interval in seconds."
    },
    "uptime": {
      "type": "integer",
      "description": "Agent uptime in seconds."
    }
  },
  "required": [
    "agent_version",
    "build_version",
    "cpu_cores",
    "cpu_system",
    "cpu_system_prev",
    "cpu_user",
    "cpu_user_prev",
    "dhc_status",
    "fhc_status",
    "flow_count",
    "flow_count_prev",
    "flows_active",
    "flows_expired",
    "flows_expiring",
    "flows_in_use",
    "flows_purged",
    "maxrss_kb",
    "maxrss_kb_prev",
    "memrss_kb",
    "memrss_kb_prev",
    "tcm_kb",
    "tcm_kb_prev",
    "timestamp",
    "type",
    "update_imf",
    "update_interval",
    "uptime"
  ],
  "examples": [
    {
      "agent_version": "5.2.0",
      "build_version": "Netify Agent/5.2.0-...",
      "cpu_cores": 8,
      "cpu_system": 3.148931,
      "cpu_system_prev": 3.134846,
      "cpu_user": 6.237091,
      "cpu_user_prev": 6.206476,
      "dhc_status": true,
      "fhc_status": true,
      "flow_count": 140,
      "flow_count_prev": 135,
      "flows_active": 55,
      "flows_expired": 21,
      "flows_expiring": 0,
      "flows_in_use": 120,
      "flows_purged": 11,
      "maxrss_kb": 85504,
      "maxrss_kb_prev": 85504,
      "memrss_kb": 84508,
      "memrss_kb_prev": 84380,
      "tcm_kb": 48141,
      "tcm_kb_prev": 48076,
      "timestamp": 1772661775,
      "type": "agent_status",
      "update_imf": 1,
      "update_interval": 15,
      "uptime": 1740
    }
  ]
}

```

## Endpoints Telemetry

### Endpoints: Overview
The Endpoints telemetry provides an inventory of discovered network endpoints, keyed by MAC address and mapped to observed IP addresses.  It offers a compact view of host identity at Layer 2 with associated Layer 3 addressing information.

This data is useful for endpoint visibility, asset tracking, and change detection across local segments. Monitoring the address set per MAC over time helps identify DHCP churn, dual-stack behavior, and potential identity inconsistencies in downstream analytics.

### Endpoints: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-telemetry-endpoints.json",
  "title": "Netify Endpoints Telemetry",
  "description": "JSON Schema for Netify Agent v5 endpoints telemetry.",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "const": "endpoints",
      "description": "Telemetry record type. Always endpoints."
    }
  },
  "additionalProperties": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "description": "Dynamic key for an observed endpoint MAC address. The value is a list of associated IP addresses (IPv4 and/or IPv6)."
  },
  "examples": [
    {
      "44:39:c4:8f:0d:92": [
        "fe80::4639:c4ff:fe8f:d92",
        "192.168.88.1"
      ],
      "60:e3:27:4a:a4:30": [
        "192.168.88.2"
      ],
      "9c:6b:00:30:a2:f0": [
        "192.168.88.196"
      ],
      "a4:7d:78:cb:e0:b6": [
        "fe80::a67d:78ff:fecb:e0b6",
        "192.168.88.198"
      ],
      "type": "endpoints"
    }
  ]
}

```

## Flow Telemetry

### Flow: Overview
The Flow telemetry record contains per-flow metadata produced by the DPI engine and flow tracker. Emitted at detection and during DPI updates and completion, it reports detected application and protocol identifiers, hostnames (SNI/HTTP Host), TLS certificate details, and protocol-specific metadata used for classification and enrichment.

Use the Flow record for event-driven detection, enrichment, routing decisions, and early-alerting workflows. For periodic bandwidth and KPI reporting use the [Flow Stats Telemetry](https://www.netify.ai/documentation/agent/v5/integrations/telemetry/flow-stats), and for final per-session counters and end-state details use the [Flow Purge Telemetry](https://www.netify.ai/documentation/agent/v5/integrations/telemetry/flow-purge).

### Flow: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-telemetry-flow.json",
  "title": "Netify Flow Telemetry",
  "description": "JSON Schema for Netify Agent v5 flow telemetry.",
  "type": "object",
  "properties": {
    "flow": {
      "type": "object",
      "description": "Container for per-flow network and DPI metadata.",
      "properties": {
        "app_ip_override": {
          "type": "boolean",
          "description": "Indicates whether application IP override logic was applied."
        },
        "app_proto_twins": {
          "type": "boolean",
          "description": "Indicates whether protocol twin detection metadata was applied."
        },
        "bt": {
          "type": "object",
          "description": "BitTorrent protocol metadata extracted from the flow.",
          "properties": {
            "info_hash": {
              "type": "string",
              "description": "BitTorrent info hash represented as a hexadecimal SHA-1 digest."
            }
          },
          "required": [
            "info_hash"
          ]
        },
        "category": {
          "type": "object",
          "description": "Application, domain, and protocol category identifiers.",
          "properties": {
            "application": {
              "type": "integer",
              "description": "Detected application category ID.",
              "externalDocs": {
                "description": "Application Categories",
                "url": "https://www.netify.ai/documentation/agent/applications/categories"
              }
            },
            "domain": {
              "type": "integer",
              "description": "Detected domain category ID.",
              "externalDocs": {
                "description": "Category Lists",
                "url": "https://www.netify.ai/documentation/agent/v5/configuration/category-lists"
              }
            },
            "local_network": {
              "type": "integer",
              "description": "Local network category ID.",
              "externalDocs": {
                "description": "Category Lists",
                "url": "https://www.netify.ai/documentation/agent/v5/configuration/category-lists"
              }
            },
            "other_network": {
              "type": "integer",
              "description": "Other network category ID.",
              "externalDocs": {
                "description": "Category Lists",
                "url": "https://www.netify.ai/documentation/agent/v5/configuration/category-lists"
              }
            },
            "overlay": {
              "type": "integer",
              "description": "Overlay network category ID, when applicable.",
              "externalDocs": {
                "description": "Overlay",
                "url": "https://www.netify.ai/documentation/agent/v5/configuration/overlay"
              }
            },
            "protocol": {
              "type": "integer",
              "description": "Detected protocol category ID.",
              "externalDocs": {
                "description": "Protocol Categories",
                "url": "https://www.netify.ai/documentation/agent/protocols/categories"
              }
            }
          },
          "required": [
            "application",
            "domain",
            "overlay",
            "protocol"
          ]
        },
        "conntrack": {
          "type": "object",
          "description": "Connection tracking metadata.",
          "properties": {
            "id": {
              "type": "integer",
              "description": "Conntrack flow identifier."
            },
            "mark": {
              "type": "integer",
              "description": "Conntrack mark value."
            },
            "reply_dst_ip": {
              "type": "string",
              "description": "Destination IP in the conntrack reply tuple."
            },
            "reply_dst_port": {
              "type": "integer",
              "description": "Destination port in the conntrack reply tuple."
            },
            "reply_src_ip": {
              "type": "string",
              "description": "Source IP in the conntrack reply tuple."
            },
            "reply_src_port": {
              "type": "integer",
              "description": "Source port in the conntrack reply tuple."
            }
          },
          "required": [
            "id",
            "mark",
            "reply_dst_ip",
            "reply_dst_port",
            "reply_src_ip",
            "reply_src_port"
          ]
        },
        "detected_application": {
          "type": "integer",
          "description": "Detected application ID.",
          "externalDocs": {
            "description": "Applications Catalog",
            "url": "https://www.netify.ai/documentation/agent/applications/catalog"
          }
        },
        "detected_application_name": {
          "type": "string",
          "description": "Detected application tag.",
          "externalDocs": {
            "description": "Applications Catalog",
            "url": "https://www.netify.ai/documentation/agent/applications/catalog"
          }
        },
        "detected_protocol": {
          "type": "integer",
          "description": "Detected protocol ID.",
          "externalDocs": {
            "description": "Protocols Catalog",
            "url": "https://www.netify.ai/documentation/agent/protocols/catalog"
          }
        },
        "detected_protocol_name": {
          "type": "string",
          "description": "Detected protocol name from the underlying DPI driver."
        },
        "detection_guessed": {
          "type": "boolean",
          "description": "True when protocol classification is inferred by default port rather than fully dissected."
        },
        "detection_packets": {
          "type": "integer",
          "description": "Number of packets used to complete DPI classification."
        },
        "detection_updated": {
          "type": "boolean",
          "description": "True when additional packets update an earlier classification."
        },
        "dhc_hit": {
          "type": "boolean",
          "description": "Indicates whether domain hint cache contributed to classification."
        },
        "dhcp": {
          "type": "object",
          "description": "DHCP metadata extracted from protocol payloads when available.",
          "properties": {
            "class_ident": {
              "type": "string",
              "description": "DHCP class identifier value observed in the flow."
            },
            "fingerprint": {
              "type": "string",
              "description": "DHCP fingerprint string extracted from client options."
            }
          },
          "required": [
            "class_ident",
            "fingerprint"
          ]
        },
        "digest": {
          "type": "string",
          "description": "Current unique flow digest based on known flow attributes."
        },
        "digest_prev": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of previous sibling digests associated with this flow."
        },
        "dns_host_name": {
          "type": "string",
          "description": "Hostname associated with a corresponding DNS query."
        },
        "fhc_hit": {
          "type": "boolean",
          "description": "Indicates whether flow hash cache contributed to classification."
        },
        "first_seen_at": {
          "type": "integer",
          "description": "Timestamp in Unix epoch milliseconds when the flow was first observed."
        },
        "gtp": {
          "type": "object",
          "description": "GTP tunnel metadata when encapsulated traffic is detected.",
          "properties": {
            "ip_dscp": {
              "type": "integer",
              "description": "DSCP value observed for the inner GTP payload network context."
            },
            "ip_version": {
              "type": "integer",
              "description": "IP version for the inner GTP payload network context.",
              "enum": [
                4,
                6
              ]
            },
            "local_ip": {
              "type": "string",
              "description": "Local tunnel endpoint IP for the inner GTP flow."
            },
            "local_port": {
              "type": "integer",
              "description": "Local tunnel endpoint port for the inner GTP flow."
            },
            "local_teid": {
              "type": "integer",
              "description": "Local tunnel endpoint identifier (TEID) for the inner GTP flow."
            },
            "other_ip": {
              "type": "string",
              "description": "Other tunnel endpoint IP for the inner GTP flow."
            },
            "other_port": {
              "type": "integer",
              "description": "Other tunnel endpoint port for the inner GTP flow."
            },
            "other_teid": {
              "type": "integer",
              "description": "Other tunnel endpoint identifier (TEID) for the inner GTP flow."
            },
            "other_type": {
              "type": "string",
              "description": "Other endpoint network type for the inner GTP flow.",
              "enum": [
                "local",
                "remote",
                "unsupported",
                "error"
              ]
            },
            "version": {
              "type": "integer",
              "description": "Observed GTP protocol version."
            }
          },
          "required": [
            "ip_dscp",
            "ip_version",
            "local_ip",
            "local_port",
            "local_teid",
            "other_ip",
            "other_port",
            "other_teid",
            "other_type",
            "version"
          ]
        },
        "host_server_name": {
          "type": "string",
          "description": "Hostname extracted from protocol metadata (for example TLS SNI or HTTP Host header)."
        },
        "http": {
          "type": "object",
          "description": "HTTP metadata extracted from protocol payloads when available.",
          "properties": {
            "url": {
              "type": "string",
              "description": "HTTP URL observed in the flow payload."
            },
            "user_agent": {
              "type": "string",
              "description": "HTTP User-Agent header value observed in the flow payload."
            }
          },
          "required": [
            "url",
            "user_agent"
          ]
        },
        "ip_dscp": {
          "type": "integer",
          "description": "Differentiated Services Code Point (DSCP) value."
        },
        "ip_nat": {
          "type": "boolean",
          "description": "Indicates whether Network Address Translation (NAT) was detected."
        },
        "ip_protocol": {
          "type": "integer",
          "description": "IP protocol number.",
          "externalDocs": {
            "description": "Wikipedia",
            "url": "https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers"
          }
        },
        "ip_version": {
          "type": "integer",
          "description": "IP version used by the flow.",
          "enum": [
            4,
            6
          ]
        },
        "last_seen_at": {
          "type": "integer",
          "description": "Timestamp in Unix epoch milliseconds when the flow was last observed."
        },
        "local_bytes": {
          "type": "integer",
          "description": "Bytes sent from the local endpoint in the current lifecycle."
        },
        "local_ip": {
          "type": "string",
          "description": "Local endpoint IP address."
        },
        "local_mac": {
          "type": "string",
          "description": "Local endpoint MAC address."
        },
        "local_origin": {
          "type": "boolean",
          "description": "Indicates whether the local endpoint originated the connection."
        },
        "local_packets": {
          "type": "integer",
          "description": "Packets sent from the local endpoint in the current lifecycle."
        },
        "local_port": {
          "type": "integer",
          "description": "Local endpoint port."
        },
        "local_rate": {
          "type": "number",
          "description": "Burst local rate for the flow in the current lifecycle."
        },
        "mdns": {
          "type": "object",
          "description": "mDNS metadata extracted from multicast DNS traffic when available.",
          "properties": {
            "answer": {
              "type": "string",
              "description": "mDNS answer domain name extracted from the flow."
            }
          },
          "required": [
            "answer"
          ]
        },
        "nfq": {
          "type": "object",
          "description": "NFQUEUE interface metadata when packet queue integration is enabled.",
          "properties": {
            "dst_iface": {
              "type": "string",
              "description": "Destination interface name reported by NFQUEUE for this flow."
            },
            "src_iface": {
              "type": "string",
              "description": "Source interface name reported by NFQUEUE for this flow."
            }
          },
          "required": [
            "dst_iface",
            "src_iface"
          ]
        },
        "other_bytes": {
          "type": "integer",
          "description": "Bytes sent from the other endpoint in the current lifecycle."
        },
        "other_ip": {
          "type": "string",
          "description": "Other endpoint IP address."
        },
        "other_mac": {
          "type": "string",
          "description": "Other endpoint MAC address when available."
        },
        "other_packets": {
          "type": "integer",
          "description": "Packets sent from the other endpoint in the current lifecycle."
        },
        "other_port": {
          "type": "integer",
          "description": "Other endpoint port."
        },
        "other_rate": {
          "type": "number",
          "description": "Current other transmit rate for the flow in the current lifecycle."
        },
        "other_type": {
          "type": "string",
          "description": "Other endpoint network type classification.",
          "enum": [
            "local",
            "remote",
            "broadcast",
            "multicast",
            "unsupported",
            "error",
            "unknown"
          ]
        },
        "risks": {
          "type": "object",
          "description": "Risk assessment data derived from nDPI protocol driver.",
          "properties": {
            "ndpi_risk_score": {
              "type": "integer",
              "description": "Aggregate nDPI risk score for the flow."
            },
            "ndpi_risk_score_client": {
              "type": "integer",
              "description": "nDPI risk score associated with client-side indicators."
            },
            "ndpi_risk_score_server": {
              "type": "integer",
              "description": "nDPI risk score associated with server-side indicators."
            },
            "risks": {
              "type": "array",
              "items": {
                "type": "integer"
              },
              "description": "Set of nDPI risk identifiers triggered for this flow."
            }
          },
          "required": [
            "ndpi_risk_score",
            "ndpi_risk_score_client",
            "ndpi_risk_score_server",
            "risks"
          ]
        },
        "soft_dissector": {
          "type": "boolean",
          "description": "Indicates whether a soft dissector was used."
        },
        "ssl": {
          "type": "object",
          "description": "TLS/SSL metadata extracted when encrypted traffic is detected.",
          "properties": {
            "alpn": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "List of Application-Layer Protocol Negotiation (ALPN) protocol identifiers offered or negotiated for the TLS session."
            },
            "alpn_server": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "List of Application-Layer Protocol Negotiation (ALPN) protocol identifiers provided."
            },
            "cipher_suite": {
              "type": "string",
              "description": "Hexadecimal TLS cipher suite identifier (for example 0x1303)."
            },
            "client_ja4": {
              "type": "string",
              "description": "JA4 TLS client fingerprint extracted from the handshake."
            },
            "client_sni": {
              "type": "string",
              "description": "Server Name Indication (SNI) value sent by the TLS client."
            },
            "encrypted_ch_version": {
              "type": "string",
              "description": "Encrypted client hello (ECH) version."
            },
            "fingerprint": {
              "type": "string",
              "description": "SHA-1 digest fingerprint of the observed TLS certificate."
            },
            "issuer_dn": {
              "type": "string",
              "description": "TLS server certificate issuer distinguished name, e.g. Let's Encrypt."
            },
            "server_cn": {
              "type": "string",
              "description": "TLS server common name."
            },
            "subject_dn": {
              "type": "string",
              "description": "TLS server certificate issuer distinguished name."
            },
            "version": {
              "type": "string",
              "description": "Hexadecimal TLS version value observed in handshake metadata."
            }
          }
        },
        "ssh": {
          "type": "object",
          "description": "SSH handshake metadata extracted when available.",
          "properties": {
            "client": {
              "type": "string",
              "description": "SSH client agent or software identification string."
            },
            "server": {
              "type": "string",
              "description": "SSH server agent or software identification string."
            }
          }
        },
        "ssdp": {
          "type": "object",
          "description": "SSDP metadata extracted when available.",
          "properties": {
            "user_agent": {
              "type": "string",
              "description": "SSDP User-Agent value observed in the flow."
            }
          },
          "required": [
            "user_agent"
          ]
        },
        "stun": {
          "type": "object",
          "description": "STUN address metadata extracted from STUN payloads when available.",
          "properties": {
            "mapped": {
              "type": "string",
              "description": "STUN mapped address (host:port) observed in the flow."
            },
            "other": {
              "type": "string",
              "description": "STUN other address (host:port) observed in the flow."
            },
            "peer": {
              "type": "string",
              "description": "STUN peer address (host:port) observed in the flow."
            },
            "relayed": {
              "type": "string",
              "description": "STUN relayed address (host:port) observed in the flow."
            },
            "response": {
              "type": "string",
              "description": "STUN response address (host:port) observed in the flow."
            }
          },
          "required": [
            "mapped",
            "other",
            "peer"
          ]
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of tags associated with this flow."
        },
        "tcp": {
          "type": "object",
          "description": "TCP health and error counters for TCP flows.",
          "properties": {
            "resets": {
              "type": "integer",
              "description": "Count of observed TCP reset packets for the flow."
            },
            "retrans": {
              "type": "integer",
              "description": "Count of observed TCP retransmissions for the flow."
            },
            "seq_errors": {
              "type": "integer",
              "description": "Count of TCP sequence anomalies for the flow."
            }
          },
          "required": [
            "resets",
            "retrans",
            "seq_errors"
          ]
        },
        "total_bytes": {
          "type": "integer",
          "description": "Total bytes seen for the flow in both directions."
        },
        "total_packets": {
          "type": "integer",
          "description": "Total packets seen for the flow in both directions."
        },
        "vlan_id": {
          "type": "integer",
          "description": "Observed VLAN ID."
        }
      },
      "required": [
        "app_ip_override",
        "app_proto_twins",
        "category",
        "detected_application",
        "detected_application_name",
        "detected_protocol",
        "detected_protocol_name",
        "detection_guessed",
        "detection_packets",
        "detection_updated",
        "dhc_hit",
        "digest",
        "digest_prev",
        "dns_host_name",
        "fhc_hit",
        "first_seen_at",
        "host_server_name",
        "ip_dscp",
        "ip_nat",
        "ip_protocol",
        "ip_version",
        "last_seen_at",
        "local_bytes",
        "local_ip",
        "local_mac",
        "local_origin",
        "local_packets",
        "local_port",
        "local_rate",
        "other_bytes",
        "other_ip",
        "other_mac",
        "other_packets",
        "other_port",
        "other_rate",
        "other_type",
        "soft_dissector",
        "total_bytes",
        "total_packets",
        "vlan_id"
      ]
    },
    "interface": {
      "type": "string",
      "description": "Interface name associated with this flow record."
    },
    "internal": {
      "type": "boolean",
      "description": "Indicates whether this flow is internal to the local network context."
    },
    "type": {
      "type": "string",
      "enum": [
        "flow",
        "flow_dpi_update",
        "flow_dpi_complete"
      ],
      "description": "Telemetry record type. Always flow."
    }
  },
  "required": [
    "flow",
    "interface",
    "internal",
    "type"
  ],
  "examples": [
    {
      "flow": {
        "app_ip_override": false,
        "category": {
          "application": 28,
          "domain": 0,
          "local_network": 0,
          "other_network": 0,
          "overlay": 0,
          "protocol": 22
        },
        "conntrack": {
          "id": 3603527535,
          "mark": 0,
          "reply_dst_ip": "192.168.4.44",
          "reply_dst_port": 35636,
          "reply_src_ip": "192.200.0.102",
          "reply_src_port": 443
        },
        "detected_application": 11354,
        "detected_application_name": "netify.tailscale",
        "detected_protocol": 196,
        "detected_protocol_name": "HTTP/S",
        "detection_guessed": false,
        "detection_updated": false,
        "dhc_hit": false,
        "digest": "c4c07ca55baa19a7fe3652bcd356765a7...",
        "digest_prev": [
          "463c53093403fcce8eeb01df5b5125df66a0f53b"
        ],
        "dns_host_name": "login.tailscale.com",
        "fhc_hit": false,
        "first_seen_at": 1772738467573,
        "host_server_name": "login.tailscale.com",
        "ip_dscp": 0,
        "ip_nat": false,
        "ip_protocol": 6,
        "ip_version": 4,
        "last_seen_at": 1772738467684,
        "local_ip": "192.168.4.44",
        "local_mac": "f8:e9:03:01:69:13",
        "local_origin": true,
        "local_port": 35636,
        "other_ip": "192.200.0.102",
        "other_mac": "3c:7c:3f:a1:ed:58",
        "other_port": 443,
        "other_type": "remote",
        "risks": {
          "ndpi_risk_score": 0,
          "ndpi_risk_score_client": 0,
          "ndpi_risk_score_server": 0,
          "risks": []
        },
        "soft_dissector": false,
        "ssl": {
          "alpn": [
            "h2",
            "http/1.1"
          ],
          "cipher_suite": "0x0000",
          "client_ja4": "t13d1817h2_e8a523a41297_...",
          "client_sni": "login.tailscale.com",
          "encrypted_ch_version": "0xfe0d",
          "version": "0x0303"
        },
        "vlan_id": 0
      },
      "interface": "wlp3s0",
      "internal": true,
      "type": "flow"
    }
  ]
}

```

## Flow Purge Telemetry

### Flow Purge: Overview
The Flow Purge telemetry is emitted when a tracked flow is removed from the engine, typically after normal connection closure (TCP), inactivity timeout, or internal purge conditions. It captures final flow counters and end-state details at the point the flow leaves active tracking.  

Use this record for post-session analysis, accounting, and flow lifecycle validation. Comparing purge records with periodic [Flow Stats Telemetry](https://www.netify.ai/documentation/agent/v5/integrations/telemetry/flow-stats) updates helps explain why sessions ended and whether termination behavior aligns with network expectations.

### Flow Purge: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-telemetry-flow-purge.json",
  "title": "Netify Flow Purge Telemetry",
  "description": "JSON Schema for Netify Agent v5 flow purge telemetry.",
  "type": "object",
  "properties": {
    "flow": {
      "type": "object",
      "description": "Container for final per-flow statistics at purge time.",
      "properties": {
        "detection_packets": {
          "type": "integer",
          "description": "Number of packets used for application/protocol detection."
        },
        "digest": {
          "type": "string",
          "description": "Current flow digest identifier."
        },
        "digest_prev": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of previous digest identifiers associated with the flow."
        },
        "last_seen_at": {
          "type": "integer",
          "description": "Timestamp in Unix epoch milliseconds when the flow was last observed."
        },
        "local_bytes": {
          "type": "integer",
          "description": "Bytes sent from the local endpoint."
        },
        "local_packets": {
          "type": "integer",
          "description": "Packets sent from the local endpoint."
        },
        "local_rate": {
          "type": "integer",
          "description": "Final local transmit rate for the flow."
        },
        "other_bytes": {
          "type": "integer",
          "description": "Bytes sent from the remote endpoint."
        },
        "other_packets": {
          "type": "integer",
          "description": "Packets sent from the remote endpoint."
        },
        "other_rate": {
          "type": "integer",
          "description": "Final remote transmit rate for the flow."
        },
        "tcp": {
          "type": "object",
          "description": "TCP health and error counters. Omitted for non-TCP flows.",
          "properties": {
            "resets": {
              "type": "integer",
              "description": "Count of observed TCP reset packets for the flow."
            },
            "retrans": {
              "type": "integer",
              "description": "Count of observed TCP retransmissions for the flow."
            },
            "seq_errors": {
              "type": "integer",
              "description": "Count of TCP sequence anomalies for the flow."
            }
          },
          "required": [
            "resets",
            "retrans",
            "seq_errors"
          ]
        },
        "total_bytes": {
          "type": "integer",
          "description": "Total bytes seen for the flow in both directions."
        },
        "total_packets": {
          "type": "integer",
          "description": "Total packets seen for the flow in both directions."
        }
      },
      "required": [
        "detection_packets",
        "digest",
        "digest_prev",
        "last_seen_at",
        "local_bytes",
        "local_packets",
        "local_rate",
        "other_bytes",
        "other_packets",
        "other_rate",
        "total_bytes",
        "total_packets"
      ]
    },
    "interface": {
      "type": "string",
      "description": "Interface name associated with the purged flow."
    },
    "internal": {
      "type": "boolean",
      "description": "Indicates whether the flow is internal to the local network context."
    },
    "reason": {
      "type": "string",
      "enum": ["closed", "expired"],
      "description": "Purge reason reported by the engine."
    },
    "type": {
      "type": "string",
      "const": "flow_purge",
      "description": "Telemetry record type. Always flow_purge."
    }
  },
  "required": [
    "flow",
    "interface",
    "internal",
    "reason",
    "type"
  ],
  "examples": [
    {
      "flow": {
        "detection_packets": 12,
        "digest": "fb69e87ed3b...",
        "digest_prev": [
          "d7fddd35cc27..."
        ],
        "last_seen_at": 1772665905392,
        "local_bytes": 0,
        "local_packets": 0,
        "local_rate": 387,
        "other_bytes": 0,
        "other_packets": 0,
        "other_rate": 300,
        "tcp": {
          "resets": 0,
          "retrans": 0,
          "seq_errors": 0
        },
        "total_bytes": 13968,
        "total_packets": 51
      },
      "interface": "wlp3s0",
      "internal": true,
      "reason": "closed",
      "type": "flow_purge"
    }
  ]
}

```

## Flow Stats Telemetry

### Flow Stats: Overview
The Flow Stats telemetry provides periodic runtime statistics for
active flows, especially long-lived sessions such as streaming, VPN, and
persistent service connections. It complements flow metadata by reporting
ongoing packet, byte, and rate counters while a flow remains active.

This record is most valuable for near-real-time monitoring and QoE analysis.
Tracking directional throughput and TCP health metrics over time helps detect
performance degradation, congestion, and retransmission-related issues before
a flow is closed.

### Flow Stats: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-telemetry-flow-stats.json",
  "title": "Netify Flow Stats Telemetry",
  "description": "JSON Schema for Netify Agent v5 flow stats telemetry.",
  "type": "object",
  "properties": {
    "flow": {
      "type": "object",
      "description": "Container for per-flow live statistics.",
      "properties": {
        "detection_packets": {
          "type": "integer",
          "description": "Number of packets used for application/protocol detection."
        },
        "digest": {
          "type": "string",
          "description": "Current flow digest identifier."
        },
        "digest_prev": {
          "type": "array",
          "items": { "type": "string" },
          "description": "List of previous digest identifiers associated with the flow."
        },
        "last_seen_at": {
          "type": "integer",
          "description": "Timestamp in Unix epoch milliseconds when the flow was last observed."
        },
        "local_bytes": {
          "type": "integer",
          "description": "Bytes sent from the local endpoint."
        },
        "local_packets": {
          "type": "integer",
          "description": "Packets sent from the local endpoint."
        },
        "local_rate": {
          "type": "integer",
          "description": "Current local transmit rate for the flow."
        },
        "other_bytes": {
          "type": "integer",
          "description": "Bytes sent from the remote endpoint."
        },
        "other_packets": {
          "type": "integer",
          "description": "Packets sent from the remote endpoint."
        },
        "other_rate": {
          "type": "integer",
          "description": "Current remote transmit rate for the flow."
        },
        "total_bytes": {
          "type": "integer",
          "description": "Total bytes seen for the flow in both directions."
        },
        "total_packets": {
          "type": "integer",
          "description": "Total packets seen for the flow in both directions."
        },
        "tcp": {
          "type": "object",
          "description": "TCP health and error counters. Omitted for non-TCP flows.",
          "properties": {
            "resets": {
              "type": "integer",
              "description": "Count of observed TCP reset packets for the flow."
            },
            "retrans": {
              "type": "integer",
              "description": "Count of observed TCP retransmissions for the flow."
            },
            "seq_errors": {
              "type": "integer",
              "description": "Count of TCP sequence anomalies for the flow."
            }
          },
          "required": ["resets", "retrans", "seq_errors"]
        }
      },
      "required": [
        "detection_packets",
        "digest",
        "digest_prev",
        "last_seen_at",
        "local_bytes",
        "local_packets",
        "local_rate",
        "other_bytes",
        "other_packets",
        "other_rate",
        "total_bytes",
        "total_packets"
      ]
    },
    "interface": {
      "type": "string",
      "description": "Interface name associated with the flow update."
    },
    "internal": {
      "type": "boolean",
      "description": "Indicates whether this flow is internal to the local network context."
    },
    "type": {
      "type": "string",
      "const": "flow_stats",
      "description": "Telemetry record type. Always flow_stats."
    }
  },
  "required": [
    "flow",
    "interface",
    "internal",
    "type"
  ],
  "examples": [
    {
      "flow": {
        "detection_packets": 2,
        "digest": "c3086c57745b...",
        "digest_prev": [
          "fcd1061d4c2ba844..."
        ],
        "last_seen_at": 1772665318561,
        "local_bytes": 5559,
        "local_packets": 6,
        "local_rate": 5559,
        "other_bytes": 913,
        "other_packets": 6,
        "other_rate": 913,
        "tcp": {
          "resets": 0,
          "retrans": 0,
          "seq_errors": 0
        },
        "total_bytes": 613175,
        "total_packets": 1064
      },
      "interface": "wlp3s0",
      "internal": true,
      "type": "flow_stats"
    }
  ]
}

```

## Flow Actions Telemetry

### Flow Actions: Overview
The Flow Actions telemetry record contains per-flow metadata produced when a flow action is triggered.

## Intelligence Telemetry

### Intelligence: Overview
Displaying cybersecurity incidents in a dashboard requires structured, high-quality telemetry. The Intelligence telemetry payload provides network intelligence indicators generated by the Netify Intelligence plugin.

This structure is optimized for downstream enrichment, alerting, and policy workflows. By combining indicator scores with emitted criteria values, integrators can tune thresholds, differentiate LAN/WAN trigger behavior, and maintain clear explainability across security analytics pipelines.

### Intelligence: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-telemetry-intelligence.json",
  "title": "Netify Intelligence Telemetry",
  "description": "JSON Schema for Netify Agent v5 flow intelligence telemetry.",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "const": "flow_intel",
      "description": "Telemetry record type. Always <b>flow_intel</b>."
    },
    "interface": {
      "type": "string",
      "description": "Interface name associated with the flow."
    },
    "internal": {
      "type": "boolean",
      "description": "Indicates whether the flow is internal to the local network context."
    },
    "flow": {
      "type": "object",
      "description": "Container for per-flow statistics and intelligence data.",
      "properties": {
        "digest": {
          "type": "string",
          "description": "Current flow digest identifier."
        },
        "intel": {
          "type": "array",
          "description": "Array of intelligence indicator objects associated with the flow.",
          "items": {
            "$ref": "#/$defs/intelAttributes"
          }
        }
      }
    }
  },
  "required": [
    "type"
  ],
  "$defs": {
    "intelAttributes": {
      "type": "object",
      "description": "Intelligence indicator object containing risk and detection context.",
      "properties": {
        "category": {
          "type": "string",
          "description": "Intelligence category tag associated with the indicator.",
          "externalDocs": {
            "description": "Driver categories",
            "url": "https://www.netify.ai/documentation/agent/intelligence/categories"
          }
        },
        "criteria": {
          "type": "object",
          "description": "Resolved criteria values used when evaluating the indicator."
        },
        "event": {
          "type": "string",
          "description": "Detection lifecycle event that triggered the indicator.",
          "enum": ["dpi_new", "dpi_update", "dpi_complete", "flow_new", "flow_stats", "flow_expiring", "flow_expired"]
        },
        "indicator": {
          "type": "string",
          "description": "Configured tag of the indicator that generated the detection."
        },
        "indicator_driver": {
          "type": "string",
          "description": "Tag of the driver that powered the detection.",
          "externalDocs": {
            "description": "Driver tag catalog",
            "url": "https://www.netify.ai/documentation/agent/intelligence/catalog"
          }
        },
        "score": {
          "type": "integer",
          "description": "Risk/severity score assigned to the indicator.",
          "externalDocs": {
            "description": "Scoring matrix and description",
            "url": "https://www.netify.ai/documentation/agent/v5/integrations/telemetry/intelligence#scoring"
          }
        }
      }
    }
  },
  "examples": [
    {
      "flow": {
        "digest": "5e8529b046a53bfd3787eb7272675...",
        "digest_prev": [
          "355d412cf9a8a6f1cc583bffa7da9f876603998f",
          "5e8529b046a53bfd3787eb7272675662d3865cbf"
        ],
        "intel": [
          {
            "category": "vpn_detection",
            "criteria": {
              "min_bytes": 0,
              "min_score": 0,
              "trigger_on_east_west": true,
              "trigger_on_wan": true
            },
            "data_feed": "vpn_server_consumer",
            "event": "dpi_complete",
            "indicator": "vpn_server_consumer",
            "indicator_driver": "vpn_server_consumer",
            "score": 70
          }
        ],
        "last_seen_at": 1775750510867
      },
      "interface": "eno1",
      "internal": true,
      "type": "flow_intel"
    },
    {
      "flow": {
        "detection_packets": 6,
        "digest": "731246630167090d8f9eceffbc4f1...",
        "digest_prev": [
          "5017058958a6fa49217a594de4d169a0e4e3e180",
          "731246630167090d8f9eceffbc4f15d705d616c1"
        ],
        "intel": [
          {
            "category": "tor_detection",
            "criteria": {
              "min_bytes": 0,
              "min_score": 0,
              "trigger_on_east_west": true,
              "trigger_on_wan": true
            },
            "data_feed": "tor_relay",
            "event": "dpi_complete",
            "indicator": "tor_relay",
            "indicator_driver": "tor_relay",
            "score": 70
          }
        ],
        "last_seen_at": 1775751029770,
        "local_bytes": 2076,
        "local_packets": 6,
        "local_rate": 2076.0,
        "other_bytes": 1528,
        "other_packets": 4,
        "other_rate": 1528.0,
        "tcp": {
          "resets": 0,
          "retrans": 0,
          "seq_errors": 0
        },
        "total_bytes": 3604,
        "total_packets": 10
      },
      "interface": "eno1",
      "internal": true,
      "type": "flow_intel"
    }
  ]
}

```

## Network Interfaces Telemetry

### Network Interfaces: Overview
The network Interfaces telemetry provides a live inventory of network
interfaces that the Netify Agent can observe. Each interface entry includes
addressing information, capture method, and role, making it easy to confirm
expected interface discovery and classification.

This dataset is useful for validating deployment state and troubleshooting
capture coverage. By reviewing interface role assignments alongside addresses
and MAC identifiers, you can quickly detect missing interfaces, unexpected
role changes, or source mismatches in downstream analytics.

### Network Interfaces: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-telemetry-interfaces.json",
  "title": "Netify Network Interfaces Telemetry",
  "description": "JSON Schema for Netify Agent v5 network interfaces telemetry.",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "const": "interfaces",
      "description": "Telemetry record type. Always interfaces."
    }
  },
  "required": [
    "type"
  ],
  "additionalProperties": {
    "$ref": "#/$defs/interfaceAttributes",
    "description": "Per-interface object keyed by interface name."
  },
  "$defs": {
    "interfaceAttributes": {
      "type": "object",
      "description": "Attributes for a single monitored network interface.",
      "properties": {
        "addr": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of IP addresses assigned to the interface."
        },
        "capture_type": {
          "type": "string",
          "enum": [
            "nfqueue",
            "pcap",
            "tpv3"
          ],
          "description": "Capture type in use for the interface."
        },
        "mac": {
          "type": "string",
          "description": "Interface MAC address."
        },
        "role": {
          "type": "string",
          "enum": [
            "lan",
            "wan"
          ],
          "description": "Assigned network role for the interface."
        }
      },
      "required": [
        "capture_type",
        "mac",
        "role"
      ]
    }
  },
  "examples": [
    {
      "eno1": {
        "addr": [
          "fe80::4639:c4ff:fe8f:d92",
          "fdc0:1766:43b:0:4639:c4ff:fe8f:d92",
          "11.113.88.4"
        ],
        "capture_type": "pcap",
        "mac": "44:39:c4:8f:0d:92",
        "role": "wan"
      },
      "eno2": {
        "addr": [
          "192.168.4.44",
          "fe80::901:29c0:649b:7efe"
        ],
        "capture_type": "pcap",
        "mac": "f8:e9:03:01:69:13",
        "role": "lan"
      },
      "type": "interfaces"
    }
  ]
}

```

## Network Interface Stats Telemetry

### Network Interface Stats: Overview
The network Interface Stats and Global Stats telemetry records are your primary window into the Netify DPI engine's interaction with your network hardware. By providing real-time packet and byte telemetry for every active interface, it allows you to monitor exactly how your traffic is being observed and handled. This visibility ensures that your classification engine is receiving the raw data it needs to maintain high-accuracy visibility.

The interface_stats record provides stats per network interface, while the global_stats record provides the same information summarized across all monitored network interfaces.

### Network Interface Stats: JSON Schema
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.netify.ai/developer/agent/v5/schemas/netify-telemetry-interface-stats.json",
  "title": "Netify Network Interface Stats Telemetry",
  "description": "JSON Schema for Netify Agent v5 network interface and global stats telemetry.",
  "type": "object",
  "oneOf": [
    {
      "description": "Per-interface statistics object keyed by interface name.",
      "properties": {
        "type": {
          "type": "string",
          "const": "interface_stats",
          "description": "Telemetry record type for per-interface statistics."
        }
      },
      "required": ["type"],
      "additionalProperties": {
        "$ref": "#/$defs/statsAttributes"
      }
    },
    {
      "description": "Global statistics object summarized across all monitored network interfaces.",
      "properties": {
        "type": {
          "type": "string",
          "const": "global_stats",
          "description": "Telemetry record type for summarized global statistics."
        }
      },
      "required": ["type"],
      "allOf": [
        {
          "$ref": "#/$defs/statsAttributes"
        }
      ]
    }
  ],
  "$defs": {
    "statsAttributes": {
      "type": "object",
      "description": "Common network interface statistics counters.",
      "properties": {
        "capture_dropped": {
          "type": "integer",
          "description": "Total number of packets dropped by the packet capture layer."
        },
        "capture_filtered": {
          "type": "integer",
          "description": "Total packets filtered out (removed) in the case where Berkely Packet Filters are in use."
        },
        "discarded": {
          "type": "integer",
          "description": "Total packet counts being discarded prior to entering the DPI engine for analysis."
        },
        "discarded_bytes": {
          "type": "integer",
          "description": "Total number of discarded bytes."
        },
        "ethernet": {
          "type": "integer",
          "description": "Total number of supported Ethernet header counts seen."
        },
        "flow_dropped": {
          "type": "integer",
          "description": "Total number of packets dropped during flow processing."
        },
        "fragmented": {
          "type": "integer",
          "description": "Number of fragmented IP packets observed."
        },
        "icmp": {
          "type": "integer",
          "description": "Total number of ICMP packets."
        },
        "igmp": {
          "type": "integer",
          "description": "Total number of IGMP packets."
        },
        "ip": {
          "type": "integer",
          "description": "Total number of IP packets."
        },
        "ip_bytes": {
          "type": "integer",
          "description": "Total number of bytes carried in IP packets."
        },
        "largest_bytes": {
          "type": "integer",
          "description": "Largest frame size, in bytes."
        },
        "mpls": {
          "type": "integer",
          "description": "Total number of MPLS packets."
        },
        "pppoe": {
          "type": "integer",
          "description": "Total number of PPPoE packets."
        },
        "queue_dropped": {
          "type": "integer",
          "description": "Total number of packets dropped due to internal queue limits."
        },
        "raw": {
          "type": "integer",
          "description": "Total number of raw packets captured on the interface."
        },
        "tcp": {
          "type": "integer",
          "description": "Total number of TCP packets."
        },
        "tcp_resets": {
          "type": "integer",
          "description": "Total number of TCP reset (RST) packets."
        },
        "tcp_seq_errors": {
          "type": "integer",
          "description": "Total number of TCP sequence errors."
        },
        "udp": {
          "type": "integer",
          "description": "Total number of UDP packets."
        },
        "vlan": {
          "type": "integer",
          "description": "Total number of VLAN tagged packets."
        },
        "wire_bytes": {
          "type": "integer",
          "description": "Total number of bytes observed on the wire, including frame overhead."
        }
      },
      "required": [
        "capture_dropped",
        "capture_filtered",
        "discarded",
        "discarded_bytes",
        "ethernet",
        "flow_dropped",
        "fragmented",
        "icmp",
        "igmp",
        "ip",
        "ip_bytes",
        "largest_bytes",
        "mpls",
        "pppoe",
        "queue_dropped",
        "raw",
        "tcp",
        "tcp_resets",
        "tcp_seq_errors",
        "udp",
        "vlan",
        "wire_bytes"
      ]
    }
  },
  "examples": [
    {
      "type": "interface_stats",
      "eth0": {
        "capture_dropped": 0,
        "capture_filtered": 0,
        "discarded": 12,
        "discarded_bytes": 1012,
        "ethernet": 772,
        "flow_dropped": 0,
        "fragmented": 0,
        "icmp": 3,
        "igmp": 2,
        "ip": 760,
        "ip_bytes": 261408,
        "largest_bytes": 1514,
        "mpls": 0,
        "pppoe": 0,
        "queue_dropped": 0,
        "raw": 772,
        "tcp": 648,
        "tcp_resets": 0,
        "tcp_seq_errors": 0,
        "udp": 107,
        "vlan": 0,
        "wire_bytes": 279648
      }
    },
    {
      "capture_dropped": 0,
      "capture_filtered": 0,
      "discarded": 13,
      "discarded_bytes": 1070,
      "ethernet": 2049,
      "flow_dropped": 0,
      "fragmented": 0,
      "icmp": 4,
      "igmp": 13,
      "ip": 2036,
      "ip_bytes": 1218047,
      "largest_bytes": 4369,
      "mpls": 0,
      "pppoe": 0,
      "queue_dropped": 0,
      "raw": 2049,
      "tcp": 1844,
      "tcp_resets": 4,
      "tcp_seq_errors": 0,
      "type": "global_stats",
      "udp": 175,
      "vlan": 0,
      "wire_bytes": 1266911
    }
  ]
}

```