Netify Device Discovery Plugin

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 be installed using a similar syntax that was implemented during the installation of the Netify agent. Plugins are compiled and made available for x86 on mirrors. For other architectures like ARM and MIPS, please contact us

Select your installation target for specific instructions on how to install this plugin.

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

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_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"
            }
        }
    }
}
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:
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_devices
Description The maximum devices Netify Device Discovery will track. It is permitted to not set this configuration or set it exteremely high to avoid hitting the limit above which, new devices will not be 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.
Type integer
Default 0 (unlimited)
Property max_device_age
Description 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.
Type integer
Default 0 (unlimited)
Property max_ja4_clients
Description Maximum number of extracted JA4 client hashes to collect on any given mac address.
Type integer or object
Default 10
Property max_mdns_services
Description Maximum number of extracted MDNS service strings to collect on any given mac address.
Type integer or object
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 or object
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 or object
Default 10

The four properties listed above:

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 accomodate the new value. A higher value will translate into fewer events being triggered, especially for often reoccurring 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

Property path_device_cache
Description Specifies the device cache location. This prevents a flurry of events from being created in the event the daemon is restarted.
Type string
Default $\{path_state_persistent\}/device-discovery-cache.json
Property process_all_macs
Description In the default configuration (false), the plugin will only register a new device if all the following conditions are met:
1. MAC is local to the network
2. At least one flow of the following protocols have been identified for the MAC:
  • DHCP
  • SSDP
  • MDNS
  • HTTP
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.
Type boolean
Options true, false
Default false
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.

Documentation


Netify Agent Plugins


Technical Support

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

Contact Us