Netify Plugins - Device Discovery for Netify 5

Netify Device Discovery Plugin

Introduction
License
Installation

Alma Linux
Debian
OpenWRT
OPNsense
pfSense
Rocky Linux
Ubuntu

Configuration
Examples

Introduction

Netify Informatics 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.

An example of the device discovery object is provided below.

{
  "mac": "dc:d3:a2:00:00:00",
  "is_local": false,
  "is_multicast": false,
  "oui": {
    "prefix": "dc:d3:a2",
    "type": "MA-L",
    "vendor": "Apple",
    "entity": {
      "id": 140,
      "tag": "apple",
      "label": "Apple",
      "category": {
        "id": 5,
        "tag": "business",
        "label": "Business"
      },
      "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"
    }
  },
  "discovery": {
    "label": "iPad",
    "score": 100,
    "entity": {
      "id": 140,
      "tag": "apple",
      "label": "Apple",
      "category": {
        "id": 5,
        "tag": "business",
        "label": "Business"
      },
      "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": {
      "id": 200,
      "label": "Tablet/eBook"
    },
    "os": {
      "id": 700,
      "label": "Apple iOS",
      "version": "13.3.1"
    }
  }
},

License

Netify Device Discovery Plugin is a proprietary plugin requiring a license. Please contact us for details.

Installation

Netify plugins are packaged in the same workflow as the agent and can usually be installed using a similar syntax that was implemented during the installation of the Netify agent. Exceptions to this rule occur when the plugin requires a Software License Agreement or if an upgrade or downgrade to a different version of the plugin is required.

Plugins are compiled against specific Netify agent versions and require ABI compatibility. Click here for more information.

Download URLs in the commands below for example only and version specific. Use a browser to navigate to the repository to find and copy the package you wish to install.

Alma Linux

Alma Linux 9

The Netify Device Discovery plugin is a licensed (proprietary) plugin. Instructions to access this plugin will have been provided to you by a Netify representative. Typically, the package will be available via a web link with Basic authentication protection. Example:

cd /tmp/
wget https://client:secret@download.netify.ai/5/almalinux/9/stable/x86_64/netify-dev-discovery_1.0.30-1.os9.x86_64.rpm
apt install ./netify-dev-discovery_1.0.30-1.os9.x86_64.rpm

Alma Linux 8

cd /tmp/
wget https://client:secret@download.netify.ai/5/almalinux/8/stable/x86_64/netify-dev-discovery_1.0.30-1.os8.x86_64.rpm
yum install ./netify-dev-discovery_1.0.30-1.os8.x86_64.rpm

Debian

Debian 13 (Bookworm)

cd /tmp/
wget https://client:secret@download.netify.ai/5/debian/10/amd64/netify-dev-discovery_1.0.30-1_amd64.deb 
apt install ./netify-dev-discovery_1.0.30-1_amd64.deb

Debian 11 (Bullseye)

cd /tmp/
wget https://client:secret@download.netify.ai/5/debian/10/amd64/netify-dev-discovery_1.0.30-1_amd64.deb 
apt install ./netify-dev-discovery_1.0.30-1_amd64.deb

Debian 10 (Buster)

cd /tmp/
wget https://client:secret@download.netify.ai/5/debian/10/amd64/netify-dev-discovery_1.0.30-1_amd64.deb 
apt install ./netify-dev-discovery_1.0.30-1_amd64.deb

OpenWRT

OpenWRT 23.05

pkg add https://client:secret@download.netify.ai/5/openwrt/23.05/amd64/netify-dev-discovery_1.0.30-1_x86_64.ipk

OpenWRT 22.03

pkg add https://client:secret@download.netify.ai/5/openwrt/22.03/amd64/netify-dev-discovery_1.0.30-1_x86_64.ipk

OpenWRT 21.02

pkg add https://client:secret@download.netify.ai/5/openwrt/21.02/amd64/netify-dev-discovery_1.0.30-1_x86_64.ipk

OpenWRT 19.07

pkg add https://client:secret@download.netify.ai/5/openwrt/19.07/amd64/netify-dev-discovery_1.0.30-1_x86_64.ipk

OPNsense

OPNsense 24.1 - Savvy Shark

pkg add https://client:secret@download.netify.ai/5/freebsd/13.2/amd64/netify-dev-discovery_1.0.30,1.pkg

OPNsense 23.7 - Restless Roadrunner

pkg add https://client:secret@download.netify.ai/5/freebsd/13.2/amd64/netify-dev-discovery_1.0.30,1.pkg

pfSense

pfSense Plus 23.x

pkg add https://client:secret@download.netify.ai/5/freebsd/14.0/amd64/netify-dev-discovery_1.0.30,1.pkg

pfSense CE 2.7.x

pkg add https://client:secret@download.netify.ai/5/freebsd/13.2/amd64/netify-dev-discovery_1.0.30,1.pkg

Rocky Linux

Rocky Linux 9

cd /tmp/
wget https://client:secret@download.netify.ai/5/rockylinux/9/stable/x86_64/netify-dev-discovery_1.0.30-1.os9.x86_64.rpm
apt install ./netify-dev-discovery_1.0.30-1.os9.x86_64.rpm

Rocky Linux 8

cd /tmp/
wget https://client:secret@download.netify.ai/5/rockylinux/8/stable/x86_64/netify-dev-discovery_1.0.30-1.os8.x86_64.rpm
yum install ./netify-dev-discovery_1.0.30-1.os8.x86_64.rpm

Ubuntu

Ubuntu 22.04 - Jammy

cd /tmp/
wget https://client:secret@download.netify.ai/5/ubuntu/jammy/binary-amd64/netify-dev-discovery_1.0.30-1_amd64.deb 
apt install ./netify-dev-discovery_1.0.30-1_amd64.deb

Ubuntu 20.04 - Focal

cd /tmp/
wget https://client:secret@download.netify.ai/5/ubuntu/jammy/binary-amd64/netify-dev-discovery_1.0.30-1_amd64.deb 
apt install ./netify-dev-discovery_1.0.30-1_amd64.deb

Configuration

Plugin Loader Configuration

All plugins are disabled by default, and the Netify Device Discovery Processor plugin is no different. To enable:

netifyd --enable-plugin proc-dev-discovery

A plugin can also be disabled in this way by substituting --disable-plugin.

Alternatively, you can edit /etc/netifyd/plugins.d/10-netify-proc-dev-discovery.conf and set enable to yes.

# Netify Device Discovery Processor Plugin Loader
# Copyright (C) 2024 eGloo Incorporated
#
##############################################################################

[proc-dev-discovery]
enable = yes
plugin_library = /usr/lib64/libnetify-proc-dev-discovery.so.0.0.0
conf_filename = ${path_state_persistent}/netify-proc-dev-discovery.json

# vim: set ft=dosini :

Plugin Configuration

Once the plugin has been enabled, it can be configured using the JSON configuration file specified in the plugin loader configuration. Let's look at a configuration sample to review the syntax and parts of the file.

{
    "compressor": "gz",
    "format": "json",
    "max_confidence": 80,
    "max_mdns_services": 10,
    "max_http_user_agents": 10,
    "max_ssdp_user_agents": 10,
    "netify_api": {
      "enable": true,
      "url": "https://agents.netify.ai/api/v2/device_discovery",
      "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "sinks": {
        "sink-log": {
            "devices": {
                "enable": true,
                "flush": true,
                "format": "json",
                "compressor": "none"
            }
        }
    }
}

Property	compressor
Description	If desired, data can be compressed using a compatible library.
Type	string
Options	none, gzip

Property	format
Description	The Device Discovery processor passes structured data to the API for analysis. This field determines what type of data structure to output. The plugin supports: JSON MessagePack
Type	string
Options	json, msgpack

Property	max_confidence
Description	The confidence (between 0 and 100) required before a device will no longer have metadata sent to the cloud service for analysis.
Type	integer
Default	80

Property	max_mdns_services
Description	Maximum number of extracted MDNS service strings to collect on any given mac address.
Type	integer
Default	10

Property	max_http_user_agents
Description	Maximum number of extracted HTTP user agent strings to collect on any given mac address.
Type	integer
Default	10

Property	max_sddp_user_agents
Description	Maximum number of extracted SDDP user agent strings to collect on any given mac address.
Type	integer
Default	10

Property	netify_api
Description	Contact us for an integration key
Type	boolean
Options	true, false

Property	sinks
Description	An object array that determines which Netify sink plugins to send data to.
Type	object
Options	Depends on local configuration (see Sink Objects section below)

Sink Objects

The Device Discovery Processor's sink object list determines which sinks receive the device discovery processor's data and what type of data should be sent to it. A single device discovery processor can be configured to send to any number of sinks. In the example above, we are sending to only one, the sink-log. Let's take a closer look at the configuration.

The sink-log object key is critical - it must match the section name of the corresponding plugin loader. The nested key inside the sink refers to a channel as defined in the sink plugin. In this example, the keyed sink-log reference means (very likely) that we have the sink log plugin installed and enabled and that we find a section named sink-log. We should also see a channel defined in the sink-log plugin with the name stats. To verify this, we need to first look at the sink log loader configuration file:

$ cat /etc/netifyd/plugins.d/10-netify-sink-log.conf 

# Netify Agent Log Sink Plugin Loader
# Copyright (C) 2023 eGloo Incorporated
#
# This is free software, licensed under the GNU General Public License v3.
#
##############################################################################

[sink-log]
enable = yes
plugin_library = /usr/lib64/libnetify-sink-log.so.0.0.0
conf_filename = ${path_state_persistent}/netify-sink-log.json

# vim: set ft=dosini :

You can see the sink-log section name does match our device discovery processor sink target configuration. The fact that the configuration file exists, is a good indication it has been installed, and the enable = yes confirms the plugin is enabled. From this file, we can also see the JSON configuration file of the sink log from the conf_filename option.

Next, we look at the JSON configuration file for the sink-log plugin.

$ cat /etc/netifyd/netify-sink-log.json 

{
    "overwrite": false,
    "log_path": "/tmp",
    "channels": {
        "devices": {
            "overwrite": true,
            "log_path": "/tmp",
            "log_name": "netify-devices-log-"
        }
    }
}

As seen above, the devices channel exists. To further gain an understanding of the sink log configuration, please go here.

Examples

Send device discovery data to the Sink Socket plugin.

Send device discovery data to the Sink Socket plugin to a channel name devices.

{
    "compressor": "gz",
    "format": "json",
    "max_confidence": 80,
    "max_mdns_services": 10,
    "max_http_user_agents": 10,
    "max_ssdp_user_agents": 10,
    "netify_api": {
      "enable": true,
      "url": "https://agents.netify.ai/api/v2/device_discovery",
      "key": "afaf1640-8485-11ee-bd48-00163ec6aee7"
    },
    "sinks": {
        "sink-socket": {
            "devices": {
                "enable": true,
                "flush": true,
                "format": "json",
                "compressor": "none"
            }
        }
    }
}

Requires the installation and correct configuration of the Netify Sink Socket plugin.

Output Plugins

Examples

Technical Support

Haven't found the answers you're looking for?

Device Discovery Processor