Netify Netify logo Contact Us
Products Resources Documentation Blog Sign In

Netify Device Discovery Plugin

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.

License

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

Installation

Netify plugins are distributed through the same packaging workflow as the Netify Agent, allowing for a consistent installation experience using standard package manager syntax. While pre-compiled binaries are readily available for x86_64 architectures via our public mirrors, support for ARM, MIPS, and other specialized architectures is available upon request. Please contact us for details.

Step 1 - Select your installation target:

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/debian/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/debian/12/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/debian/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/debian/11/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/debian/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/debian/10/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/ubuntu/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/ubuntu/noble/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/ubuntu/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/ubuntu/jammy/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/ubuntu/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/ubuntu/focal/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/24.10/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
opkg update
opkg install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/23.05/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
opkg update
opkg install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/22.03/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
opkg update
opkg install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/21.02/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
opkg update
opkg install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/19.07/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
opkg update
opkg install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import https://download.netify.ai/5/opensuse/15.5/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/opensuse/netify.repo -o /etc/zypp/repos.d/repo-netify.repo

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo zypper update
sudo zypper install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import https://download.netify.ai/5/almalinux/9/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/almalinux/9/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import https://download.netify.ai/5/almalinux/8/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/almalinux/8/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import http://download.netify.ai/5/rockylinux/9/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/rockylinux/9/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo yum update
sudo yum install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import http://download.netify.ai/5/rockylinux/8/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/rockylinux/8/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
sudo yum update
sudo yum install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/opnsense/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/opnsense/25.7",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
pkg update
pkg install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/opnsense/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/opnsense/24.7",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
pkg update
pkg install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/freebsd/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/freebsd/15.0",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
pkg update
pkg install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/freebsd/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/freebsd/14.0",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
pkg update
pkg install netify-proc-dev-discovery

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/freebsd/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/freebsd/14.0",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Device Discovery:

Terminal - Netify
× 
pkg update
pkg install netify-proc-dev-discovery

Setup

All plugins are disabled by default, and the Netify Device Discovery Processor plugin is no different. Use the --enable-plugin and --disable-plugin parameters to enable/disable the plugin:

Terminal - Netify
× 
netifyd --enable-plugin proc-dev-discovery
netifyd --disable-plugin proc-dev-discovery

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

Terminal - Netify
× 
[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

Main 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

string

If desired, data can be compressed using a compatible library.

Options
none, gz

format

string

The device discovery data format passed to sink plugins: JSON or MessagePack.

Options
json, msgpack

max_confidence

integer

The confidence (between 0 and 100) required before a device will no longer have metadata sent to the cloud service for analysis.

Default
80

max_devices

integer

The maximum number of devices Netify Device Discovery will track. You can leave this configuration unset or set it extremely high to avoid reaching the limit at which new devices are no longer tracked. However, this is essentially a potential limitless memory 'sink'. Integrators (especially on embedded devices with less RAM) are encouraged to set this to a value that will not interfere with discovery, but will protect against memory exhaustion if an unexpected number of devices are on the network.

Default
0 (unlimited)

max_device_age

integer

Specifies the maximum time (in seconds) a device can remain in memory without activity. If a flow from this device has not been observed for longer than this period, it will be automatically purged from the tracking table. This ensures that stale or inactive devices do not consume system resources indefinitely.

Default
0 (unlimited)

max_ja4_clients

integer or object

Maximum number of extracted JA4 client hashes to collect on any given MAC address.

Default
10

max_mdns_services

integer or object

Maximum number of extracted MDNS service strings to collect on any given MAC address.

Default
10

max_http_user_agents

integer or object

Maximum number of extracted HTTP user agent strings to collect on any given MAC address.

Default
10

max_sddp_user_agents

integer or object

Maximum number of extracted SDDP user agent strings to collect on any given MAC address.

Default
10

path_device_cache

string

Specifies the device cache location. This prevents a flurry of events from being created in the event the agent is restarted.

Default
$\{path_state_persistent\}/device-discovery-cache.json

process_all_macs

boolean

MAC address collection policy. See MAC collection policy below.

Default
false
Options
true, false

netify_api

boolean

Contact us for a developer API key for proof-of-concept projects.

Options
true, false

sinks

object

An object array that determines which Netify sink plugins to send data to.

Reference
See Sink Configuration below 
{
    "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,
      "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"
            }
        }
    }
}

Sink Configuration

We need to send our telemetry to a configured output using a Sink Plugin: log, socket, message queue, etc. This sink configuration is highly flexible, but it can also be easy to misconfigure if the relationships between components are not clear. Let's get started.

Sink Tag - First Level Key

The Device Discovery Processor’s sinks object determines which sinks (outputs) receive the telemetry data and how the data should be sent to each one. A single processor can send data to multiple sinks, but in this example it is configured to send to only one.

The sink tag is the first-level key under the sinks property. This key must match the section name defined by the corresponding plugin loader. In our example, the sink tag is sink-log , which must exactly match the loader section name sink-log as shown below:

Sinks Configuration - Overview

"sinks": {
    "sink-log": {
        "devices": {
            "enable": true,
            ... other properties ...
        }
    }
}
Terminal - Netify
× 
$ cat /etc/netifyd/plugins.d/10-netify-sink-log.conf
[sink-log]
enable = yes
plugin_library = /usr/lib64/libnetify-sink-log.so.0.0.0
conf_filename = ${path_state_persistent}/netify-sink-log.json

Here we can see that the section name [sink-log] matches the sink tag used in the Device Discovery configuration. The presence of this configuration file indicates that the plugin has been installed, and the enable = yes setting confirms that it is currently enabled. The loader configuration also specifies the sink’s runtime configuration file through the conf_filename property.

This mapping is critical: if the names do not match, the processor will not be able to deliver data to the sink.

The Channel - Second Level Key

The second-level key in JSON configuration is the channel. Sink output channels provide a way to separate different types of telemetry into different output targets. For example, you can send:

  • aggregator data to /tmp/netify-aggregate-x
  • interface statistics to /tmp/netify-interface-stats-x
  • intelligence detections to /tmp/netify-intelligence-x

This channel must be configured in the target sink configuration as shown.

Refer to the relevant Sink Plugin configuration for channel configuration details.

Sink Log Config: /etc/netifyd/netify-sink-log.json

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

Channel Properties

{sink-tag}.{channel}.enable

boolean

Flag to enable/disable the channel.

{sink-tag}.{channel}.flush

boolean

The flush policy.

{sink-tag}.{channel}.format

string

The data format - overrides default.

Options
json, msgpack

{sink-tag}.{channel}.compressor

string

The compression policy - overrides default.

Options
none, gz

Example Sinks Configuration

{
    ...
    "sinks": {
        "sink-log": {
            "devices": {
                "enable": true,
                "flush": true,
                "format": "json",
                "compressor": "none"
            }
        }
    }
}

Policies

MAC Collection Policy

The device discovery system will only register a new device if the MAC is local to the network and at least one flow of the following protocols has been identified for the MAC:

If true, the Device Discovery plugin will immediately create an event and a record for any new MAC address processed by the Netify agent during flow analysis. For integrators who wish to generate an accurate inventory of devices (existing and new) that join the network, setting this option to true is the recommended configuration.

Fingerprint and Agent Policies

The four properties listed here:

  • max_ja4_clients
  • max_mdns_services
  • max_http_user_agents
  • max_sddp_user_agents

can be configured using an integer value. If a new, previously unseen value is discovered, it will be added to the table. If the maximum number of entries has been exceeded, the oldest entry will be popped off the list to accommodate the new value. A higher value will translate into fewer events being triggered, especially for often recurring values like JA4 client hashes.

For more fine-grained control, define an object in place of the integer. The object is defined with any or all of the following attributes (on a per-device basis):

  • max - same as defined above
  • update_min - will have the effect of 'squelching' any new events that occur more frequently than this minimum setting (in seconds)
  • update_ttl - will update on a set frequency (in seconds), regardless of any activity discovered

Example

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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "sinks": {
        "sink-socket": {
            "devices": {
                "enable": true,
                "flush": true,
                "format": "json",
                "compressor": "none"
            }
        }
    }
}